动画文本控件

Texturge 提供两个 UMG 控件，分别对应纯文本和多格式文本两种使用路径，均继承自引擎内置控件并扩展逐字动画能力。

控件对比

	UAnimatedTextBlock	UAnimatedRichTextBlock
继承	UTextBlock	URichTextBlock
动画配置	TextAnimationBlueprint	AnimationData (DataAsset)
文本类型	纯文本	多格式文本（含内联动画标签）
动画数量	单一动画	多动画混合（按标签匹配）
样式系统	UTextBlock 样式属性	URichTextBlock 样式集 + 装饰器
适用场景	简单打字机、标题入场	RPG 对话、多效果混合文本

UAnimatedTextBlock

属性

属性	类型	说明
TextAnimationBlueprint	UTextAnimationBlueprint*	驱动逐字动画的动画蓝图资产
bAutoPlay	bool	构建时自动播放（默认 false）
bLoopPlayback	bool	动画结束后自动从头循环（默认 false）

蓝图可绑定委托

委托	签名	说明
OnCharacterRevealedBP	(int32 RevealedCount)	每揭示一个字符时广播，参数为当前已揭示字符数
OnAnimationCompleteBP	()	动画完全结束时广播

播放控制 API

UFUNCTION(BlueprintCallable)
void Play();        // 播放逐字揭示动画
void Pause();      // 暂停
void Resume();     // 恢复
void Stop();       // 停止并重置
void SkipToEnd();  // 跳过动画，直接显示全部文本
bool IsAnimating(); // 是否正在播放

内部架构

UAnimatedTextBlock 内部持有 UTextAnimator 实例（Animator），在 RebuildWidget() 中创建自定义 Slate 控件 SAnimatedTextBlock。该 Slate 控件重写 OnPaint() 方法，从 Animator->GetCurrentFrameDataArray() 读取每字符帧数据，对每个字形独立应用变换后渲染。

控件还监听以下外部事件：

• 语言切换：监听到 ULocalizationSubsystem::OnLanguageChanged 时，重新执行管线以适配新语言文本长度。
• 蓝图编译：监听到 TextAnimationBlueprint 重新编译时，刷新 Animator 的内置 AnimInstance。

UAnimatedRichTextBlock

属性

属性	类型	说明
AnimationData	UTextAnimationDataAsset*	动画数据资产，定义标签名到动画蓝图的映射
bAutoPlay	bool	构建时自动播放
bLoopPlayback	bool	循环播放

工作流

1. 创建 UTextAnimationDataAsset 资产，在 Entries 数组中添加动画条目（FAnimationEntry）
2. 每个条目包含 TagName（标签名）和 Type（对应的 UTextAnimationBlueprint）
3. 在多格式文本中使用 <TagName>文本内容</> 标签包裹需要应用动画的文本段
4. 将 AnimationData 赋值给 UAnimatedRichTextBlock，设置文本并播放

标签语法

Texturge 使用自定义标签解析器 FTagParser，支持两种标签格式：

<!-- 格式 1：使用 TagName 直接匹配（兼容旧格式） -->
<Wave>这段文字将应用 Wave 动画</>

<!-- 格式 2：使用 id 属性匹配（推荐） -->
<anim id="Wave">这段文字也将应用 Wave 动画</>

• </> 自动关闭最近打开的标签
• <img id="..." /> 自闭合标签（装饰器），id 对应 URichTextBlockImageDecorator 中 RichImageRow 数据表的 RowName

文本中可以混合使用引擎富文本样式数据表（RichTextStyleSheet）中定义的样式标签（如 <b>、<i> 等，需在 DataTable 的 RichTextStyleRow 中注册）和 Texturge 动画标签，互不干扰。

NOTE

UE5 富文本的关闭标签固定为 </>，不支持 </TagName> 形式的显式命名关闭。颜色通过样式表定义而非内联 <color> 属性。

播放控制 API

与 UAnimatedTextBlock 相同：Play() / Pause() / Resume() / Stop() / SkipToEnd() / IsAnimating()。

内部架构

UAnimatedRichTextBlock 内部使用 SAnimatedRichTextBlock Slate 控件。RichText 路径的核心区别在于渲染树驱动的多层动画系统——每个动画标签对应独立的 UTextAnimInstance。FRichTextMarshaller 在构建文本布局时用 FTextRun 替换标准 FSlateTextRun，使每个文字运行块都能读取动画器的帧数据并逐字符应用变换。

装饰器代理

Texturge 在 RichText 路径中为内嵌装饰器（如图片）提供了 FDecoratorProxyRun，确保装饰器占位符不影响纯文本索引映射。这使得动画帧数据数组的正确索引得以保持——文本中的装饰器（如图片字符）不消耗帧数据索引。