03 · 对话框模板

灵泛引擎支持同场景内不同对话使用不同风格的对话框。本章讲解模板注册系统和三级优先级。

为什么需要模板

想象这些场景：

• 角色对话用底部条状对话框
• 内心独白用中央气泡对话框
• 重要叙事用全屏 NVL对话框

如果只有一个全局对话框，很难兼顾。模板系统让你按需切换，甚至逐句指定。

三级优先级

模板选择遵循三级优先级：

say template="xxx"        ← 最高优先级（只影响这一句）
    ↓ 未指定
character screen="xxx"    ← 角色级（该角色所有对话）
    ↓ 未指定
全局默认                   ← 最低（SetDefault 设置）

say 单句指定

say "这是内心独白。" speaker="旁白" template="center"
say "这句回到默认模板。" speaker="旁白"

character 角色级绑定

character "narrator" name="旁白" color="#AAAAAA" screen="center"
character "hero" name="勇者" color="#FFD700" screen="bottom"

say "我是旁白，自动用 center 模板。" speaker="narrator"
say "我是勇者，自动用 bottom 模板。" speaker="hero"

全局默认

在 UI 层注册时设置：

services.AddDialogTemplates();  // 内部调用 registry.SetDefault("bottom")

内置模板

引擎内置三个模板：

模板名	类	外观	适用场景
bottom	DialogBox	底部条状 + 左侧脸图 + 说话者名	标准对话（默认）
center	CenterBubbleDialogBox	居中圆角气泡，MaxWidth=600	内心独白 / 旁白 / OS
fullscreen	FullScreenNvlDialogBox	全屏半透明 + 滚动文本	NVL 模式 / 重要叙事

bottom（默认）

say "标准底部条对话框。" speaker="系统"
say "带侧脸图和说话者名。" speaker="老张"

center（中央气泡）

say "这是内心独白。" speaker="旁白" template="center"
say "圆角半透明背景，居中显示。" speaker="旁白" template="center"

fullscreen（全屏 NVL）

say "这是全屏对话框。" speaker="旁白" template="fullscreen"
say "支持滚动，适合长段叙事。" speaker="旁白" template="fullscreen"

混合切换

同一场景内可以自由切换模板，每句对话可以不同：

say "旁白用默认底部条。" speaker="旁白"
say "这句切到中央气泡。" speaker="旁白" template="center"
say "这句用全屏。" speaker="旁白" template="fullscreen"
say "又回到默认。" speaker="旁白"

模板缓存

模板实例会被缓存，切换时无额外创建开销。第一次使用某模板时创建，之后复用。

模板与 NVL 模式

fullscreen 模板天然支持 NVL 累积模式。当 NVL 模式激活时，文本会累积显示：

nvl
say "第一句。" speaker="诗人" template="fullscreen"
say "第二句追加到后面。" speaker="诗人" template="fullscreen"
nvl clear
say "清空后重新开始。" speaker="诗人" template="fullscreen"
nvl exit

NVL 与模板的关系

NVL 是一种文本累积模式，fullscreen 是一种对话框外观。两者可以组合使用，但也可以分开。详见第 09 章 NVL 模式。

注册模板

模板在 UI 层注册。在你的 ServiceExtensions.cs 中：

public static IServiceCollection AddDialogTemplates(this IServiceCollection services)
{
    services.AddSingleton(sp =>
    {
        var registry = sp.GetRequiredService<IDialogTemplateRegistry>();

        // 注册三个内置模板
        registry.Register("bottom", new DefaultDialogBoxFactory());
        registry.Register("center", new CenterBubbleDialogBoxFactory());
        registry.Register("fullscreen", new FullScreenNvlDialogBoxFactory());

        // 设置全局默认
        registry.SetDefault("bottom");
        return registry;
    });
    return services;
}

自定义模板

你可以实现 IDialogBox 接口创建完全自定义的对话框模板，详见第 14 章。

场景切换时的行为

场景切换时，所有缓存模板的 NVL 状态会被重置，对话框被隐藏。下一个场景从干净状态开始。

动手练习

体验三级优先级和模板切换：

character "narrator" name="旁白" color="#AAAAAA" screen="center"
character "hero" name="勇者" color="#FFD700" screen="bottom"

label template_practice:
  // 角色级：narrator 自动用 center
  say "我是旁白，character 定义了 screen=center。" speaker="narrator"
  say "不需要每句都写 template=。" speaker="narrator"

  // 角色级：hero 自动用 bottom
  say "我是勇者，用默认底部条。" speaker="hero"

  // say 显式 template= 覆盖角色 screen=
  say "这句虽然是勇者说的，但显式指定了 template=center。" speaker="hero" template="center"

  // 混合切换
  say "底部条。" speaker="系统"
  say "中央气泡。" speaker="系统" template="center"
  say "全屏。" speaker="系统" template="fullscreen"
  say "回到默认。" speaker="系统"

下一步

对话框样式掌握了！下一章学习分支与导航——控制剧情走向。