基本布局

如何相对于画布和彼此定位 UI 元素。关键是 UIItem 组件，将其视为 Unity 的 RectTransform。UIContainer 是 UIItem 的 actor 包装器。

UIItem 是所有 UI 元素的基本 SceneComponent，UIItem 具有位置、旋转和缩放比例，就像常规 SceneComponent 一样，但它也具有宽度和高度，用于指定矩形的尺寸。和unity的UGUI差不多

基本组件-渲染

LGUICanvas

这是渲染的关键组件，添加了本组件才可以渲染到界面上。添加后UIContainerActor就能看到如下图所示的小太阳，同时左侧则为本画布的Drawcall计数

LGUICanvas是所有 LGUI 元素都应该位于其中的区域。LGUICanvas 是一个 UIContainerActor，上面有一个 LGUICanvas 组件，所有 UI 元素在层次结构中都必须是 LGUICanvas 的子元素。

如下图所示，在创建如下三个actor时将自动包含本组件。

所有 UI 元素都有属性 HierarchyIndex，表示它的绘制顺序。要更改哪个元素出现在其他元素之上，只需通过更改 HierarchyIndex 属性（直接设置值，或单击旁边的“+”/“-”按钮）重新排序 SceneOutliner 中的元素即可。还可以通过在 UIItem 组件上使用以下方法从脚本中控制顺序：SetAsFirstHierarchy、SetAsLastHierarchy 和 SetHierarchyIndex。

LGUICanvas 上有一个 SortOrder 属性，其优先级始终高于 HierarchyIndex。如果要更改它，只需选中 OverrideSorting 属性并设置值。还可以通过在 LGUICanvas 组件上使用以下方法从脚本中控制 SortOrder：SetSortOrderToHighestOfHierarchy、SetSortOrderToLowestOfHierarchy 和 SetSortOrder。

创建LGUICanvas

LGUICanvas 必须停留在具有 UIItem 作为 RootComponent 的 Actor 上，UIContainer actor 很好用。创建一个新的空关卡，将 UIContainerActor 拖到视口：

使用矩形剪切RectClip

可以理解为，把子物体的显示范围限制在Canvas大小上，超出Canvas范围的则被裁切掉不渲染显示。

同时，LGUICanas支持层次结构嵌套裁切，如下图所示：

RootCanvas和SubCanvas都有LGUICanvas组件，被裁切图形在SubCanvas下，将只显示两个canvas重合部分内容。

剪切还支持如下几种模式：

1. None

   1. UMETA(DisplayName = "No Clip")：显示名称为 "不裁剪"。

   2. 含义：不对画布内容进行任何裁剪，所有内容都会完整显示。

2. Rect

   1. UMETA(DisplayName = "Rect Clip")：显示名称为 "矩形裁剪"。

   2. 含义：通过矩形区域裁剪内容，支持边缘羽化效果，且允许嵌套矩形裁剪（即多个矩形裁剪区域可以叠加使用）。

3. Texture

   1. UMETA(DisplayName = "Texture Clip")：显示名称为 "纹理裁剪"。

   2. 含义：使用黑白纹理（实际使用纹理的红色通道）作为裁剪掩码，纹理中白色区域显示内容，黑色区域裁剪内容。不支持嵌套裁剪（即多个纹理裁剪不能叠加）。

4. Custom

   1. UMETA(DisplayName = "Custom Clip")：显示名称为 "自定义裁剪"。

   2. 含义：通过指定CustomClip参数（通常是一个自定义裁剪类）来实现裁剪逻辑。如果未指定CustomClip，则会回退到 "不裁剪" 模式。

详细使用，请参考对应部分源码。

渲染模式RenderMode

支持的模式如下。

enum class ELGUIRenderMode :uint8
{
    /**
     * Render in screen space. If there are multiple screen-space-ui-root in world, they will be sort by SortOrder property.
     * This mode use LGUI's custom render pipeline.
     * This mode need a LGUICanvasScaler to control the size and scale.
     */
    ScreenSpaceOverlay = 0,
    /**
     * Render in world space by UE default render pipeline.
     * This mode use engine's default render pieple, so post process will affect ui.
     */
    WorldSpace=1         UMETA(DisplayName = "World Space - UE Renderer"),
    /**
     * Render in world space by LGUI's custom render pipeline, 
     * This mode use LGUI's custom render pipeline, will not be affected by post process.
     */
    WorldSpace_LGUI = 3       UMETA(DisplayName = "World Space - LGUI Renderer"),
    /**
     * Render to a custom render target.
     */
    RenderTarget = 2      UMETA(DisplayName = "Render Target"),
    
    None = 255          UMETA(Hidden),
};

1. ScreenSpaceOverlay = 0

• 含义：在屏幕空间中渲染（UI 直接叠加在屏幕上）。

• 特点：

  • 若场景中存在多个 “屏幕空间 UI 根节点”，会根据它们的 SortOrder 属性进行排序（控制显示层级）。

  • 使用 LGUI 自定义的渲染管线，而非引擎默认管线。

  • 必须配合 LGUICanvasScaler 组件使用，以控制 UI 的大小和缩放比例（适配不同屏幕分辨率）。

• 适用场景：传统 2D UI（如游戏 HUD、菜单、按钮等），不依赖 3D 场景，始终面向屏幕显示。

2. WorldSpace = 1（显示名称："World Space - UE Renderer"）

• 含义：在 3D 世界空间中渲染，使用 Unreal Engine 的默认渲染管线；UI 元素将被视为透明网格，同时UI元素将会受到场景灯光影响。

• 特点：

  • UI 元素作为 3D 空间中的物体存在（类似场景中的模型），会受相机视角、位置影响。

  • 会被引擎的后处理效果（如模糊、色调调整等）影响，与其他 3D 物体的渲染逻辑一致。

• 适用场景：需要融入 3D 场景的 UI（如 3D 交互面板、场景中的提示牌等），希望 UI 与 3D 环境视觉风格统一时使用。

3. WorldSpace_LGUI = 3（显示名称："World Space - LGUI Renderer"）

• 含义：在 3D 世界空间中渲染，但使用 LGUI 的自定义渲染管线。

• 特点：

  • 同样作为 3D 空间中的物体存在，受相机视角影响。

  • 不使用引擎默认渲染管线，因此不会被引擎的后处理效果影响。

• 适用场景：需要放置在 3D 空间中，但希望保持 UI 自身渲染风格（不受场景后处理干扰）的元素（如需要保持清晰的 3D 交互界面）。

4. RenderTarget = 2（显示名称："Render Target"）

• 含义：将 UI 渲染到自定义的渲染目标（Render Target，本质是一张纹理）。

• 特点：

  • 渲染结果会存储在指定的纹理中，可后续将该纹理应用到其他物体（如 3D 模型表面、屏幕贴花等）。

• 适用场景：需要将 UI “烘焙” 到纹理中复用的情况（如动态生成的广告牌、通过 UI 控制的纹理显示等）。

5. None = 255（隐藏）

• 含义：无渲染模式（通常作为默认值或未初始化状态）。

• 特点：标记为 UMETA(Hidden)，不会在编辑器的下拉菜单中显示，仅用于内部逻辑判断。

ScreenSpaceOverlay、WorldSpace、WorldSpace_LGUI显示方式可以通过LGUI编辑器右键工具中的BaseSetup直接使用，如下图所示。

公共参数和World Space - UE Renderer

• Override Sorting：重写渲染顺序，未勾选根据层级渲染，勾选后将会显示sortOrder参数；顺序较大的画布将在较低顺序的顶部渲染。注意！SortOrder 值以 int16 类型存储，因此有效范围为 -32768 到 32767。

• Clip Type：剪辑内容 UI 元素。剪辑的最好方法是使用模板，LGUI作者但还没有找到方法。详细参考：LGUI组件介绍

• Dynamic Pixels Per Unit：用于在 UI 中动态创建的位图（例如 UIText）的每单位像素数。但！！！如果您已经有较大的 UIText 字体大小，请不要将此值设置得太大，因为这会导致纹理过大！

• Additional Shader Channels：启用/禁用着色器通道的标志。默认只提供位置/颜色/UV0，您可以检查正常/正切/UV1/UV2/UV3供您自己使用。

• DefaultMaterials：默认材质，用于渲染默认UI元素。

• Override Parameters：对于非根画布，继承或覆盖父画布参数。当前

ScreenSpaceOverlay

注意！一个场景只能存在一个本渲染模式的组件。存在两个及以上将会触发错问题提示。

• Pixel Perfect：像素完美，避免半像素渲染。

• Preview with LGUIRenderer：在 eidt 模式下，使用 LGUIRenderer 显示 Screen-Space-Overlay UI。LGUIRenderer 可以在最终结果时显示颜色和纹理，不受后期处理的影响

• Enable Depth Test：创建深度纹理，以便我们可以进行深度测试。这对于使用不透明材质的UIStaticMesh非常有用。仅对 ScreenSpaceOverlay 和 RenderTarget 模式有效。

World Space - LGUI Rendere

• Blend Depth：使用混合深度进行渲染，按场景深度遮挡 0，全部可见 1，半透明 0.5。“混合深度”参数可以控制 UI 元素被场景对象遮挡时的可见量。 此功能仅支持不透明对象，不适用于移动平台。

• Depth Fade：仅使用深度淡入淡出效果进行渲染。

RenderTarget

• Pixel Perfect：像素完美，避免半像素渲染。

• Enable Depth Test：创建深度纹理，以便我们可以进行深度测试。这对于使用不透明材质的UIStaticMesh非常有用。仅对 ScreenSpaceOverlay 和 RenderTarget 模式有效。

• Render Target：渲染到 RenderTarget，如果未指定，则 LGUI 将创建一个新。

• Render Target Update Mode：控制 LGUICanvas 渲染到 RenderTarget 的方式。

  • Automatic：LGUI 将自动管理更新，仅在检测到某些更改时绘制到 RenderTarget。

  • Always：每帧都绘制到 RenderTarget。

  • WhenRequest：仅在调用 RequestUpdateForRenderTarget 时绘制到 RenderTarget。

• Render Target Size Mode：RenderTarget和lguiccanvas的大小变化是如何相互依赖的。

  • None：

  • CanvasFitToRenderTarget：改变LGUI ccanvas的大小以适应RenderTarget。

  • RenderTargetFitToCanvas：更改 RenderTarget 的大小以适合 LGUICanvas。

• RenderTargetResolutionScale：RenderTarget 大小缩放。仅当 RenderTargetSizeMode 为 RenderTargetFitToCanvas 时才有效。

LGUICanvasScale

主要作用是让UI适配不同分辨率。高级部分就是UI相机的参数设置。本组件仅对根LGUICanvas组件有效。

其中有一个Fixed Size in Edit Mode，勾选后，将锁定场景内的UI显示大小，便于开发。

UIScaleMode支持的模式如下：

UENUM(BlueprintType, Category = LGUI)
enum class ELGUICanvasScaleMode:uint8
{
    /** 1 unit is 1 pixel render in screen*/
    ConstantPixelSize,
    /** scale UI with reference resolution and screen resolution*/
    ScaleWithScreenSize,
    /**
     * Assign CustomScale parameter to use a custom class calculate resolution and scale.
     */
    Custom,
};

• ConstantPixelSize：1 个单位对应屏幕上 1 个像素进行渲染。这种模式下，UI 元素的大小会严格按照像素尺寸显示，在不同分辨率的屏幕上，UI 的实际视觉大小可能会随屏幕像素密度变化。

• ScaleWithScreenSize：根据参考分辨率和实际屏幕分辨率来缩放 UI。这是自适应不同屏幕尺寸的常用模式，能保持 UI 元素在不同分辨率下的相对视觉大小一致。

• Custom：通过指定CustomScale参数，使用自定义类来计算分辨率和缩放比例。这种模式提供了最大的灵活性，允许开发者根据特殊需求实现自定义的缩放逻辑。

选择不同的缩放模式，将会有不同的设置参数。

其中，ScaleWithScreenSize勾选后将会有一个Screen Match Mode即为匹配模式，和unity很像；

UENUM(BlueprintType, Category = LGUI)
enum class ELGUICanvasScreenMatchMode :uint8
{
    /** Use "MatchFromWidthToHeight" and "ReferenceResolution" properties to control size and scale UI*/
    MatchWidthOrHeight,
    /** If viewport's aspect ratio not match "ReferenceResolution"'s aspect ratio, then expand size and scale UI*/
    Expand,
    /** if viewport's aspect ratio not match "ReferenceResolution"'s aspect ratio, then shrink size and scale UI*/
    Shrink,
};

• MatchWidthOrHeight：基于 "MatchFromWidthToHeight"（宽高匹配比例）和 "ReferenceResolution"（参考分辨率）这两个属性来控制 UI 的大小和缩放。原理是：以参考分辨率为基准，根据当前视口的宽高比，选择以宽度或高度为基准进行缩放，确保 UI 在不同比例的屏幕上保持相对一致的显示效果。

• Expand：当视口的纵横比与 "ReferenceResolution"（参考分辨率）的纵横比不匹配时，会扩大画布尺寸并相应缩放 UI。这种模式会确保参考分辨率范围内的 UI 内容完全显示，可能会在边缘出现额外的显示区域。

• Shrink：当视口的纵横比与 "ReferenceResolution"（参考分辨率）的纵横比不匹配时，会缩小画布尺寸并相应缩放 UI。这种模式会确保整个画布内容都能适配到当前视口内，可能会导致参考分辨率范围内的部分内容显示范围缩小。

UICanvasGroup

和unity的CanvasGroup很像，可用于从一个位置控制整组 UI 元素的某些方面，而无需单独处理它们。UICanvasGroup 的属性会影响它所在的 UI 元素以及所有子元素。他是一个组件。

• Alpha ：此组中 UI 元素的不透明度。该值介于 0 和 1 之间，其中 0 表示完全透明，1 表示完全不透明。请注意，元素也保留自己的透明度，因此各个 UI 元素的 UICanvasGroup alpha 和 alpha 值是相互乘以的。

• Interactable：确定此组件是否接受输入。当它设置为 false 时，将禁用交互。

• RestrictNavigationArea：使用导航输入（键盘或游戏手柄导航）时，在导航出时将导航区域限制为仅此 UI 元素的子元素。

• IgnoreParentGroup：此组是否也会受到 UI 元素层次结构中更上层的 UICanvasGroup 组件中的设置的影响，还是会忽略这些设置并因此覆盖它们？

效果

UIText：

首先先需要了解字体文件

• Font：字体文件，是LGUI的字体文件

• Text：显示的内容

• Size：显示大小

• Space：水平垂直分隔

• Alignment：水平垂直对齐方式

• UseKerning：是否使用字距调整以获得更好的文本布局

• OverflowType：溢出类型，用于处理文本太宽或太高而无法放入矩形的情况的方法。选项包括 “水平溢出” 和 “垂直溢出 ”和“ 钳制内容 ”。

• WrappingPolicy：文本换行策略

• Adjust Width： 调整宽度，当溢出类型为水平溢出时有效。将矩形的宽度设置为 real with of text content。

• Adjust Height：调整高度，当“溢出类型*为垂直溢出 ”时有效。将矩形的高度设置为文本内容的实际高度。

• Font Style：字形，应用于文本的样式。选项包括 “无 ”、“ 粗体 ”、“ 斜体”、“ 粗体”和“斜体 ”。

• Rich Text：富文本，文本中的标记元素是否应该被解释为富文本样式？

富文本支持的标签

支持的颜色名称

富文本功能支持

• richText: 启用/禁用富文本

• richTextTagFilterFlags: 控制启用哪些富文本标签

• richTextCustomStyleData: 自定义标签样式数据

• richTextImageData: 图片标签数据

• listRichTextImageObjectInOutliner：在大纲视图中列出富文本图像对象（仅编辑器下）

• createdRichTextImageObjectArray ：用于存储为富文本图片标签动态创建的 UI 对象，也就是当文本包含富文本图片标签(如 <img=smile/>)时,系统会自动创建对应的 UI 对象。

ULGUIRichTextCustomStyleData

ULGUIRichTextCustomStyleData定义富文本自定义样式的数据资源类。以自定义这个标签所控制的字体资源的显示行为。

• 字体样式: bold(粗体)、italic(斜体)、underline(下划线)、strikethrough(删除线)

• 字号控制: 支持三种模式

  • KeepOrigin: 保持原始大小

  • SizeValue: 设置为指定大小

  • SizeValueAsAdditional: 在原始大小基础上增减

• 颜色控制: 支持三种模式

  • KeepOrigin: 保持原始颜色

  • Replace: 替换为指定颜色

  • Multiply: 与指定颜色相乘混合

• 上下标: 支持上标(Superscript)和下标(Subscript),会自动缩放字号至 80%

ULGUIRichTextImageData

ULGUIRichTextImageData 用于在富文本中嵌入图片/表情的数据资源类。

ULGUIRichTextImageData继承自ULGUIRichTextImageData_BaseObject（UIText 图像渲染的基类）；ULGUIRichTextImageData_BaseObject 是一个抽象基类,用于为 UUIText 组件提供富文本图像渲染功能。，它允许在文本中嵌入图像(例如表情符号),通过 <img=tagname/> 标签实现，LGUI提供了一个基于Sprite系统渲染图像，同时也可以通过</size>控制图像大小。

一般就是在富文本中嵌入动态表情。 该类通过 imageMap 存储图片标签到图片数据的映射关系:

• 图片帧序列: 每个图片标签可以包含多个 ULGUISpriteData_BaseObject 帧,支持动画

• 动画控制: 通过 animationFps 设置全局帧率（默认为4）,也可以为单个Frames图片序列设置 overrideAnimationFps（-1则使用全局帧率）

• 动态创建对象: 自动创建 UUISprite 对象来渲染图片

Frames是一个LGUISprite图像数组， 没有则不显示，但是仍然在文本中占用空间；如果只有一个，直接设置精灵；如果有多个元素，则创建播放器（UUISpriteSequencePlayer ），然后根据两级帧率的配置配置动画效果。

UIEffect

UI效果组件，支持如下几种效果，选择 UIRenderable actor（UIText、UISprite、UITexture），添加以下组件之一。

公共参数：

• bEnable：是否启用；内部都继承于UUIGeometryModifierBase，这个专门用来修改UI几何体的一个抽象类

• Execute order：每个UIEffect组件都有执行顺序属性，这定义了当同一个actor中有多个UIEffect组件时的效果执行顺序。较低的执行命令比较高的执行命令更早生效。

UIEffectGradientColor

渐变色效果，Gradient Color 组件可以将 UIRenderable 的颜色更改为 2 种或 4 种不同的颜色。

• Direction Type ：方向类型；渐变方向类型，选项为 从下到上 BottomToTop 、从上到下 TopToBottom和从左到右 LeftToRight和从右到左RightToLeft和四个角FourCornor。注意！：如果 方向类型”设置为FourCornor，则四种颜色将用作四色，否则仅使用 Color 1和 Color 2用于两种颜色。

• Multiply Source Alpha ：将 UIRenderable 的 alpha 乘以效果的 alpha。

UIEffectShadow

影子效果，Shadow 组件向 UIRenderable 组件（如 UIText/UISprite/UITexture）添加简单的轮廓效果。它必须位于具有 UIRenderable 组件的 actor 上。

• Shadow Color：阴影的颜色。

• Multiply Source Alpha ：将 UIRenderable 的 alpha 乘以效果的 alpha。

• Shadow Offset ：阴影的偏移量表示为Vector2

UIEffectLongShadow

长影子效果，内部继承自UUIGeometryModifierBase抽象类，并不是UUIEffectShadow子类。Long Shadow 组件类似于 Shadow，但给我们更多的控制参数，我们可以制作非常平滑的阴影，或者让它看起来很厚。

• Shadow Color：阴影的开始颜色。

• Shadow Size：阴影的偏移量表示为Vector3。

• Shadow Segment ：更多的分段将渲染更平滑的阴影，但需要更多的性能成本。上限为255

• Use Gradient Color：使用渐变颜色影响阴影。

• Gradient Color ：考虑这是阴影的结束颜色。

• Multiply Source Alpha：将 UIRenderable 的 alpha 乘以效果的 alpha。

UIEffectOutline

轮廓描边，Outline 组件向 UIRenderable 组件（如 UIText/UISprite/UITexture）添加简单的大纲效果。它必须位于具有 UIRenderable 组件的 actor 上。

• Outline Color ：轮廓颜色

• Outline Size：轮廓尺寸，轮廓效果在水平和垂直方向上的距离，Vector2值

• Multiply Source Alpha ：将 UIRenderable 的 alpha 乘以效果的 alpha。

• Use8 Direction：使用8个方向，默认值是四个方向，使用8个方向会变得更好看。

UIEffectPostionAsUV

UI效果位置为UV；这将修改选定的 uv 通道，并使用 position.xy 作为 uv 数据。

？？？这么做的目的，可能是让 UI 元素能根据自己的位置来显示不同的图案效果（比如位置变了，显示的图案部分也跟着变）？？？

UIEffectTextAnimation

文本动画效果，需添加组件到一个 UIText actor上。

原理就是先通过选择器选取文字，然后在通过属性面板里面的动画信息，对本文字最动画效果（可以使用多个属性来组合我们的特定效果，效果会从上到下计算）；编辑器下可以通过拖动Selector Offset预览效果；同时本参数可以在序列中使用，以控制动画位置。下面是AI阅读源码后给出的解释。

触发条件（UI几何数据变化/属性修改）  
→ 准备阶段：CheckUIText() 验证文本对象有效性  
→ 选择阶段：selector->Select() 确定需要修改的文字范围（生成selection）  
→ 应用阶段：遍历properties，调用ApplyProperty() 修改选中文字的几何数据  
→ 刷新阶段：MarkVerticesDirty() 通知UI刷新，显示效果  

同时支持多个UIEffectTextAnimation一块使用，主要通过选择器设置选择范围，标签选择器通过富文本标签实现选择。

• Selector：选择器，选择器定义了在文本中选择字符的方法。

• Properties：性能，属性定义了哪些属性将影响以及它如何影响。

• selectorOffset：这只是选择器的偏移属性的代理，供Sequencer访问它。

基本上我们使用 Selector 来选择文本中的角色范围，并使用 Properties 来更改角色的属性，然后使用动画控制器来播放动画 。

Selector选择器

选择器可以收集有关选择哪些字符的信息，以及从头到尾的 0 到 1 插值，然后将这些信息提供给属性 。

选择器有 3 种类型：范围Range、随机Random、富文本标签RichTextTag。

范围Range

范围选择器定义 UIText 中字符的开始和结束范围，并从开始到结束提供 0 到 1 的值（用于插值）。

• Start：起始字符位置从 0 到 1,0 是文本的第一个字符，1 是最后一个字符。

• End：结束字符位置从 0 到 1,0 是文本的第一个字符，1 是最后一个字符。

• Offset：0 表示属性无效，1 表示属性完全有效，中间值为插值。我们可以设置这个“offset”属性来制作动画。

• Range：选择器可以从头到尾提供 0 到 1 的值，但有时属性效果可能看起来过于平滑，因此降低此值可以使属性效果更清晰。

• Flip Direction：翻转方向，当该值为 false 时， 选择器可以从头到尾提供 0 到 1 的值，如果该值为 true，则从头到尾提供 1 到 0。

随机Random

随机选择器将随机选择字符，并生成从 0 到 1 的随机值进行插值。

• Seed：随机数种子。

• Start：起始字符位置从 0 到 1,0 是文本的第一个字符，1 是最后一个字符。

• End：结束字符位置从 0 到 1,0 是文本的第一个字符，1 是最后一个字符。

• Offset：0 表示属性无效，1 表示属性完全有效，中间值为插值。我们可以设置这个“offset”属性来制作动画。

富文本选择器RichTextTag

富文本选择器可以通过富文本自定义标签选择字符，并从头到尾提供 0 到 1 的值（用于插值）。

• Range：就像范围选择器中的属性一样。降低此值可以使属性效果更清晰。

• Tag Name 自定义标记名称，即富文本标签。

• Flip Direction：翻转方向，与范围选择器中的属性一样，将 0-1 翻转到 1-0。

• Offset：0 表示属性无效，1 表示属性完全有效，中间值为插值。我们可以设置这个“offset”属性来制作动画。

Properties 属性

可以使用从 Selector 传递的信息，并将属性更改应用于字符。属性有多种类型：Alpha、颜色、位置、旋转、缩放、随机位置、位置波......这个名字就是它的功能。是一个数组。可以使用多个，同时修改多个参数实现复杂效果。

除了波浪效果不支持Ease参数，其他的都支持。Ease Curve 自定义缓动动画曲线，仅当 easeType = CurveFloat 时才有效。使用 CurveFloat 控制动画。

Position

移动字符到指定位置

• Position：目标位置偏移量

PositionRandom

将字符随机移动到指定范围内的位置

• Seed：随机数种子

• Min/Max：随机偏移范围

Rotation

围绕字符中心点旋转

• rotator：旋转角度

Rotation Random

将字符随机旋转到指定范围内的角度

• Seed：随机数种子

• Min/Max：随机旋转范围

Scale

围绕字符中心点缩放

• Scale：缩放比例，米认为OneVector

ScaleRandom

将字符随机缩放到指定范围内的比例

• Seed：随机数种子

• Min/Max：随机缩放范围

Alpha

可以更改字符的透明度。

• Alpha：目标 alpha 值，0-1 范围。

• Ease Type：缓动动画类型，这里用的是LTween，和unity的DoTween差不多，后续补充LTWeen文档。

Color

修改字符颜色

• Color：目标颜色，默认为绿色。

• Use HSV：是否使用HSV颜色空间进行差值

ColorRandom

随机颜色生成

• Seed：随机种子

• Min、Max：随机颜色的最小值和最大值

• Use HSV：将颜色转换为 HSV（Hue、Saturate、Value）并插值，然后将结果转换回来。在 HSV 中插值两种颜色可能看起来更好。

PositionWave

创建位置的波浪动画效果。

• Frequency：: 频率，数值越高波长越小

• Speed：波形移动速度

• FlipDirection：是否翻转波形移动方向

• Position：波形最大偏移量

RotationWave

创建旋转的波浪动画效果

• Frequency：: 频率，数值越高波长越小

• Speed：波形移动速度

• FlipDirection：是否翻转波形移动方向

• Rotator：波形最大旋转角度

ScaleWave

创建缩放的波浪动画效果

• Frequency：: 频率，数值越高波长越小

• Speed：波形移动速度

• FlipDirection：是否翻转波形移动方向

• Scale：波形最大缩放比例。

播放动画

可以使用作者提供的LGUIPlayTween组件来播放动画，关键的就是让Tween组件调用UIEffectTextAnimation上的公开的SetSelectorOffset函数。

例外的情况就是波浪效果，波浪效果在初始化时，会创建一个持续的更新器updateTweener，通过ULTweenBPLibrary::UpdateCall注册每帧调用，不需要外部调用

CreateUl Post Process

UIBackgroundBlur

UI背景模糊，和UMG的BackgroundBlur 效果一样。在ScreenSpaceUI 或 World Space LGUI 渲染器上使用它。组件继承于UUIItem

注意，当MSAA打开时可能存在一些问题。如果android OpenGL ES3.1，则需要启用“ProjectSettings/Platforms/Android/Build/Support Backbuffer Sampling on OpenGL"

测试下来有空指针崩溃，是否可用有待商搓

通过Cerate UI Post Process ->UIBackgroundBlur创建

• Blur Strength： 模糊效果强度。

• Apply Alpha to Blur：将 Alpha 应用于模糊，alpha 会影响模糊强度吗？如果为 true，则 0 alpha 表示 0 模糊强度，1 alpha 表示完全模糊强度。因此，如果你需要在模糊强度上制作动画，只需使用蓝图上的“Alpha To”节点即可。

• Strength Texture ：强度纹理：使用 strengthTexture 的红色通道控制模糊强度，0-无模糊，1-全模糊。

• MaskTexture：遮罩纹理；使用 maskTexture 的红色通道遮盖模糊结果。

  • MaskTextureType

    • Simple：简单

    • Sliced：切片

  • MaskTextureSpriteInfo：纹理的Sprite信息

  • MaskTextureUVRect：MaskTexture UV 偏移和缩放信息。仅当 MaskTextureType 为 Simple 时才能获得良好的结果

• MaxDownSampleLevel：本配置无需更改，默认配置6就可以提供良好的效果。

  

UIBackgroundPixelate

背景模糊像素化，类似于马赛克风格。 该组件可以使背景视图的图像像素化效果。参数和UIBackgroundBlur一样，少了强度纹理。

UIFrameCapture

UI 元素，可以将屏幕捕获为纹理以供进一步使用。在 ScreenSpace 或 WorldSpace-LGUIRenderer 中使用它。如果android OpenGL ES3.1，则需要启用“ProjectSettingsPlatformsAndroidBuildSupport Backbuffer Sampling on OpenGL”。

• Capture Full Screen：捕获全屏或仅捕获此 UI 的矩形区域。

• Captured Frame：捕获的屏幕纹理

事件

LGUIEventDelegate

LGUIEventDelegate 是一个回调方法（在事件触发时执行），它可以在“详细信息”面板中进行序列化和编辑。

基本上，在设置了 LGUIEventDelegate 并尝试执行它后，它会在目标 Actor 上搜索函数接收对象（函数接收对象可以是 Actor 本身，也可以是 Actor 上的组件之一），找到与函数名称和参数类型匹配的函数，然后使用参数值调用该函数。LGUIEventDelegate 具有内置缓存，这意味着它在第一次执行时只执行一次这些搜索作。

创建一个ActorComponent蓝图类，命名为“MyLGUIEventDelegateTest”，这个组件将保存LGUIEventDelegate并执行它；双击 MyLGUIEventDelegateTest 打开蓝图编辑器，然后创建一个 LGUIEventDelegateEmpty 类型的变量，将其命名为“MyEvent”，选中“InstanceEditable可编辑实例”，然后编译蓝图：

这里使用组件蓝图来存储LGUIEventDelegate，当然也可以直接使用actor蓝图

创建另一个 ActorComponent 蓝图类，将其命名为 “FunctionComponent”，该组件将提供要由 LGUIEventDelegate 调用的函数；双击打开后创建一个函数，并创建传入参数。

然后把上面组件分别挂载到两个不同的Actor上

在 Actor A 上选择 MyLGUIEventDelegateTest 组件，在 细节（Details） 面板中，你会找到刚刚创建的 LGUIEventDelegate “My Event（）”，点击 “+” 按钮添加一个事件项目，保持 MyLGUIEventDelegateTest 组件处于选中状态，然后单击 细节（Details） 面板上的锁定图标按钮将其锁定，这可以让我们在大纲视图中拖动其他 Actor；将 actor B 拖到事件参数中。

整个过程和unity的操作很像。

上述绑定回调已经完成，下一步是执行“My Event（）” LGUIEventDelegate。双击 MyLGUIEventDelegateTest 组件，在蓝图编辑器中将 “MyEvent” 变量拖到 EventGraph 中，然后从 “MyEvent” 节点中拖出一条线，然后选择 “Execute” 节点。

同时也可以通过蓝图调用执行绑定解绑。

上面的例子很简单，其实 LGUIEventDelegate 可以将参数从源事件传递给 dest 函数，只需选择 LGUIEventDelegateXXX（XXX 表示参数类型）作为你的事件类型即可。LGUIEventDelegate 支持很多基本数据类型：bool float double int8 uint8 int16 uint16 int32 uint32 int64 uint64 vector2 vector3 vector4 color linearColor quaternion string object actor pointerEvent class rotator name text，其中一些仅是 C++。

当您使用 LGUIEventDelegateXXX 时，当您从列表中选择函数时，您可能会看到一些带有“（NativeParameter）”的函数（例如。TestFunction（NativeParameter））。这意味着该函数可以接收从 LGUIEventDelegate 传递的参数。

LGUIEventSystem

LGUIEventSystem 是 LGUI 框架中负责管理输入、射线检测和事件分发的核心系统。它作为一个 UActorComponent 实现,每个 World 只能有一个实例。

所有事件接口函数都返回 bool 值,用于控制事件是否继续冒泡 UIEventTriggerComponent.cpp:153-182 。返回 true 允许事件冒泡到父级 Actor,返回 false 则阻止冒泡。UIEventTriggerComponent 通过 AllowEventBubbleUp 属性控制这一行为

系统支持多种指针事件:

• Enter/Exit: 指针进入/离开 UI 元素

• Down/Up: 指针按下/释放

• Click: 点击事件

• BeginDrag/Drag/EndDrag: 拖拽事件

• Scroll: 滚动事件

• DragDrop: 拖放事件

• Select/Deselect: 选择/取消选择事件

在UE有两种方案使用输入事件

实现 Blueprint Interface

在蓝图中添加一个需要的接口实现即可使用，

LGUI 提供了以下 Blueprint Interface:

• ILGUIPointerClickInterface - 点击事件

• ILGUIPointerEnterExitInterface - 进入/离开事件

• ILGUIPointerDownUpInterface - 按下/释放事件

• ILGUIPointerDragInterface - 拖拽事件

• ILGUIPointerScrollInterface - 滚动事件

• ILGUIPointerDragDropInterface - 拖放事件

• ILGUIPointerSelectDeselectInterface - 选择/取消选择事件

使用 UIEventTriggerComponent

更简便的方式是使用 UIEventTriggerComponent 组件，这个组件已经实现了所有事件接口,并提供了可在编辑器中直接配置的事件委托。

此外,UIEventTriggerComponent 还提供了蓝图可调用的 Register 和 Unregister 函数,用于在运行时动态注册/注销事件回调 。

使用内置交互组件

LGUI 提供了多个内置的交互组件,它们已经封装好了常用的事件处理逻辑:

• UIButtonComponent

用于按钮点击。提供 OnClick 事件委托,以及蓝图可调用的 RegisterClickEvent 和 UnregisterClickEvent 函数

• UISliderComponent

用于滑动条 。实现了 ILGUIPointerDragInterface 接口 ,处理拖拽事件。

• UIScrollbarComponent

用于滚动条。同样实现了拖拽接口 。

• UITextInputComponent

用于文本输入 。实现了点击和拖拽接口 。

冒泡机制

所有事件接口函数都返回 bool 值,用于控制事件是否继续冒泡 UIEventTriggerComponent.cpp:153-182 。返回 true 允许事件继续冒泡到父级 Actor,返回 false 则阻止冒泡，事件在当前层级停止。UIEventTriggerComponent 通过 AllowEventBubbleUp 属性控制这一行为 。

事件冒泡(Event Bubbling)是指当一个 UI 元素触发事件后,该事件会沿着 Actor 层级树向上传播到父级 Actor 的机制。

冒泡的特殊规则，根据代码注释 LGUIEventSystem.h:26 :

• 如果目标组件和 Actor 的所有接口都返回 true,事件会冒泡

• 如果目标上没有找到任何接口实现,事件也会冒泡

这意味着默认情况下,如果你不实现事件接口,事件会自动向上传播。

使用本机制，可在父级容器上统一处理所有子元素的事件,而不需要为每个子元素单独绑定处理函数。这在实现复杂 UI 交互时非常有用,比如列表项的点击、拖拽容器的处理等。

具体实现就是通过ULGUIPointerEventData对象来获取被点击的具体子元素信息。当事件触发时,所有事件接口函数都会接收一个 ULGUIPointerEventData* eventData 参数 。这个对象包含了完整的事件信息,包括被点击的组件。

ULGUIPointerEventData 提供了以下属性来追踪被点击的元素:

• pressComponent: 被按下的组件

• enterComponent: 当前指针悬停的组件

• dragComponent: 正在拖拽的组件

bool UMyParentComponent::OnPointerClick_Implementation(ULGUIPointerEventData* eventData)  
{  
    // 获取实际被点击的组件  
    USceneComponent* clickedComponent = eventData->pressComponent;  
      
    // 获取被点击组件所属的 Actor  
    AActor* clickedActor = clickedComponent->GetOwner();  
      
    // 现在你可以判断是哪个子元素被点击了  
    if (clickedActor->GetName() == "Button1")  
    {  
        // 处理按钮1的点击  
    }  
      
    return true; // 允许继续冒泡  
}

如果想获取完整的层级路径，可以使用eventData->enterComponentStack获取，这个数组包含了从最底层子元素到根元素的完整路径；

// enterComponentStack[0] 是最顶层的父元素  
// enterComponentStack[最后] 是最底层的子元素  
for (int i = 0; i < eventData->enterComponentStack.Num(); i++)  
{  
    USceneComponent* comp = eventData->enterComponentStack[i];  
    // 处理每一层  
}

需要注意的是,pressComponent 记录的是最初被按下的组件 。如果用户按下后移动鼠标再释放,pressComponent 仍然指向最初按下的位置,而不是释放时的位置。如果你需要知道释放时的位置,应该使用 enterComponent。对于拖拽操作,被拖拽的组件会存储在 dragComponent 中。

交互组件

UISelectable

UISelectable 是 LGUI 框架中用于处理 UI 元素交互和视觉反馈的核心组件

• AllowEventBubbleUp：允许事件气泡

• Transition：过渡类型，本选项有多个，具体取决于

  • None

  • ColorTint：颜色渐变模式，在此模式下,TransitionActor 必须是 UIBaseRenderable 类型的 Actor(如 UISprite、UITexture、UIText),组件会覆盖其颜色属性。实现时使用 FadeDuration 参数控制渐变时长。根据按钮所处的状态更改按钮的颜色。可以为每个单独的状态选择颜色。还可以在不同状态之间设置 淡入淡出持续时间（Fade Duration）。数字越高，颜色之间的淡入淡出越慢。

  • SpriteSwap：精灵图切换模式 。在此模式下,TransitionActor 的根组件必须是 UISpriteBase 类型的 Actor,组件会根据状态切换不同的精灵图 。切换是即时的,不使用渐变动画。允许根据按钮当前处于的状态显示不同的精灵，可以自定义精灵。

  • TransitionComponent：自定义过渡组件模式 UISelectableComponent.h:21-22 。你可以在 C++ 或蓝图中实现 UISelectableTransitionComponent 来自定义过渡效果,并将该组件添加到同一个 Actor 上 。系统会自动查找并调用该组件的相应方法。

• Navigation：导航

• Can Navigate Here：该元素是否可以被导航系统找到并导航到（仅auto下有效，如果对方设置为Explicit并指定目标为自己，仍能被导航到）

• Visualize：显示导航线

继承使用本组件的还有：

• UIButtonComponent (按钮)

• UISliderComponent (滑动条)

• UIToggleComponent (切换开关)

• UITextInputComponent (文本输入)

• UIScrollbarComponent (滚动条)

• UIDropdownComponent (下拉菜单)

过渡选项

在 UISelectable 组件中，有多个过渡选项 ，具体取决于 UISelectable 当前所处的状态。每一位继承者都会使用normal（正常）, highlighted（突出显示）, pressed（按下）和disabled（禁用），以及TransitionTarget（过渡目标），用于此 UISelectable 组件的 UIBaseRenderable Actor。；同时每一种也会有附加参数来辅佐本效果，这里不做过多赘述。

• ColorTint

  • FadeDuration：淡入淡出持续时间，从一种状态淡入另一种状态所花费的时间（以秒为单位）

UISelectableTransition component 自定义过渡效果组件

这是一个抽象类，用来自定义过渡效果；当转换状态发生变化时，将在 UISelectableTransition 组件上执行以下回调事件：

• OnNormal：当 UISelectable 的过渡状态变为正常时调用

• OnHighlighted：当 UISelectable 的过渡状态高亮显示时调用

• OnPressed：当 UISelectable 的过渡状态被按下时调用

• OnDisabled：当 UISelectable 的转换状态变为禁用时调用

• ReceiveOnStartCustomTransition：这使我们有机会在比上面提供的更多状态上进行转换，使用参数 InTransitionName 调用告诉不同的状态。例如，UIToggleComponent 使用“On”/“Off”来切换开/关。

同时以上也有对应蓝图实现的回调函数，内部在调用前会判断当前类的类型（原生 C++ 类还是蓝图编译类），并在特定条件下触发蓝图可实现的事件。

• ReceiveOnNormal

• ReceiveOnHighlighted

• ReceiveOnPressed

• ReceiveOnDisabled

• ReceiveOnStartCustomTransition

每个回调事件都会获得一个布尔参数 InImmediateSet，如果为 true，则你必须立即设置属性（主要用于初始化或编辑器使用），如果为 false，则可以使用补间动画。当 Transition 设置为 TransitionComponent 时,UISelectableComponent 会自动查找并调用此组件 。系统会在每次状态变化时调用对应的方法,并传递 immediateSet 参数来指示是立即设置还是使用动画过渡

自定义状态

OnStartCustomTransition() 是一个虚函数,用于处理超出标准四种状态(Normal/Highlighted/Pressed/Disabled)之外的自定义过渡场景

virtual void OnStartCustomTransition(FName InTransitionName, bool InImmediateSet);

• InTransitionName: 过渡名称,用于区分不同的自定义事件类型

• InImmediateSet: 是否立即设置属性(true)或使用动画过渡(false)

OnStartCustomTransition() 的存在是为了解决一个问题:有些 UI 组件需要的过渡效果不仅仅是 Normal/Highlighted/Pressed/Disabled 这四种标准状态，这个方法本质上是一个扩展点,让你可以为任何自定义状态添加过渡效果,而不局限于标准的四种鼠标交互状态。InTransitionName 就像一个"开关",让你在同一个组件中处理多种不同的过渡场景；即通过约定的InTransitionName传递的消息来执行不同动画。

Tweener管理

组件提供了 TweenerCollection 数组来收集和管理动画对象，这个系统用于管理过渡动画对象的生命周期,确保动画能够正确启动和停止。

• CollectTweener(): 添加单个

• CollectTweeners(): 批量添加

• StopTransition(): 停止所有收集的动画

在 UISelectableComponent 的 ColorTint 模式中可以看到典型用法:

1. 检查并停止旧动画: 使用 ULTweenManager::IsTweening() 检查动画是否在播放,如果是则调用 Kill() 停止

2. 创建新动画: 通过 ULTweenManager::To() 创建新的 tweener

3. 配置动画: 设置游戏暂停和时间膨胀影响

所以在自定义过渡组件中,应该遵循以下模式:

1. 开始新过渡前先停止: 在任何状态回调(如 OnNormal、OnHighlighted)开始时调用 StopTransition()

2. 收集新创建的动画: 使用 CollectTweener() 将新创建的 tweener 添加到集合

3. 让系统自动管理: 不需要手动清理,StopTransition() 会处理一切

导航

这个系统允许用户通过键盘或手柄在 UI 元素之间进行方向导航；导航系统基于三种模式：

1. None: 禁用该方向的导航

2. Auto: 由 LGUI 自动根据位置计算最近的可选元素 （内部会FindSelectable()寻找下一目标）

3. Explicit: 手动指定导航目标（目标必须能转换为UUISelectableComponent即必须继承）

共定义了六个导航方向：

• Left/Right/Up/Down: 四个基本方向

• Prev/Next: 前后导航(通常用于 Tab 键切换)

每个方向都有:

• 一个 NavigationMode 属性(如 NavigationLeft)，其可以设置前面说过的三种模式。

• 一个 Specific 属性(如 NavigationLeftSpecific),用于 Explicit 模式时指定目标。

Auto时会对每一个候选元素做多次检查：

• 排除自身

• 检查是否可交互(IsInteractable())

• 检查是否允许导航到此(bCanNavigateHere)

• 检查 UI 是否激活

• 检查导航限制区域(RestrictNavigationAreaCanvasGroup)

• 检查裁剪可见性

• 评分系统: 使用点积和距离计算最佳匹配

float dot = FVector::DotProduct(InDirection, myVector);  
if (dot <= 0.0f) continue; // 必须在正确方向  
float score = dot / myVector.SizeSquared(); // 距离越近分数越高

特殊导航:Prev 和 Next

• Next 导航: 优先尝试向右,如果失败则向下

• Prev 导航: 优先尝试向左,如果失败则向上

当用户首次使用键盘/手柄导航 UI 时,系统需要知道从哪个元素开始（在没有当前选中元素时,自动找到一个合适的起始导航元素），本组件也提供了FindDefaultSelectable()静态方法查找“最左上”可选元素（符合大部分交互导航逻辑）

数据蓝图（应该这么叫）

Font字体

LGUI 字体系统是一个用于在 UI 中渲染文本的完整解决方案,主要由以下几个核心类组成以及继承关系:

• ULGUIFontData_BaseObject - 字体基类,定义了所有字体实现必须遵循的接口

  • ULGUIFreeTypeRenderFontData - 使用 FreeType 库渲染字体的抽象基类

    • ULGUIFontData - 标准字体实现,支持粗体和斜体样式

    • ULGUISDFFontData - SDF(有向距离场)字体实现,用于高质量缩放

公共参数（继承的基类参数）：

• ReloadFont：编辑器专有方法，用于重载字体数据，并且引用他的UText也会刷新。

• Font Type：字体数据类型

  • CustomFontFiel：自定义字体文件

    • FontSourceFile：字体路径（绝对或相对）（字体文件使用相对路径（相对于ProjectDir）或绝对路径。在构建游戏后，记得将字体文件复制到目标路径，除非“useExternalFileOrEmbedInToUAsset”为假）

    • UseRelativeFilePath:是否使用相对路径（相对于项目目录）

    • UseExternalFileOrEmbedInToUAsset：使用外部文件或嵌入到 uasset 中（在构建时，使用外部文件或嵌入到uasset。但在编辑器中，总是从fontFilePath加载。）

  • UnrealFont：虚幻字体文件

• FontFace：字体面索引，某些字体文件(如 .ttc 格式)可以包含多个字体面(font face)。每个字体面代表一个独立的字体样式,例如同一字体家族的不同变体(常规、粗体、斜体等)。fontFace 参数允许您选择使用哪个字体面。

• LineHeightType：行高类型

  • FromFontFace：从字体数据获取。

  • FontSizeAsLineHeight：使用字面大小作为行高。

• InitialSize：初始纹理图集大小：1024×1024

• RectPackCellSize：矩形打包的单元格大小，默认为256，必须是2的幂且不大于Initialsize

• FallBackFontArray：后备字体数组,当当前字体找不到字符时会在这些字体中搜索。

• RenderTextArray：使用此字体进行渲染的 UIText 集合。可在这快速扎到谁引用了哪些组件引用了本字体。

在高级页：

• HasKerning：当前加载的字体面是否支持字距调整

• SubFaces：编辑器下专用，存储字体文件中所有可用的字体面（FontFace）名称

在参数页能看到如下两个参数显示位置不同，这是因为两个实现方式有些区别，为了避免混淆。

• ItalicAngle： (float, 默认 15.0) - 斜体样式的倾斜角度(度数)

• BoldRatio ：(float, 默认 0.1, 范围 0.0-1.0) - 粗体样式的大小比例,此参数与 SDFRadius 和 FontSize 相关,较小的 SDFRadius 和 FontSize 需要更大的 BoldRatio 才能渲染

文化字参数

主要用于需要支持多语言的游戏，特别是当不同语言需要使用不同字体时，通过 bCultureFont 和 CultureFontMap,您可以为每种语言配置专门的字体,系统会在语言切换时自动加载对应的字体。

当 CultureFont 设置为 true 时,系统会启用本地化字体支持，此时CultureFontMap才可用，同时，根据代码分析，只有 fontType 设置为 UnrealFont时才生效；也能看到文化字参数用的是UnrealFont字体资源；所以即使在CustomFontFile下打开了本功能，最终也会使用FontFilePatch的资源，所以不修改代码情况下，CutsomFontFile这FFontType这个功能将不可用，这点要注意

总结就是,CultureFontMap 的字体覆盖功能仅在以下条件同时满足时生效:

1. bCultureFont 必须设置为 true

2. fontType 必须为 UnrealFont(因为它依赖 unrealFont 参数)

3. CultureFontMap 中必须包含当前文化的键值对

如果 CultureFontMap 中没有当前文化的条目,系统会保持使用原有的 unrealFont 值,不会进行覆盖。

• 键(FString) - 文化名称,遵循 ISO 639-1 和 ISO 3166-1 标准,例如 "zh-CN"(简体中文)、"ja-JP"(日语)、"ko-KR"(韩语)等。

• 值(TSoftObjectPtr) - 软引用的字体资源,使用软引用可以避免在不需要时加载所有字体,节省内存。

当游戏语言切换时，触发回调，然后LGUI会获取新的本地化文化名，然后查找Map，找到后将UnrealFont赋值到主的UnrealFont，同时触发字体刷新，以更新显示的字体。

ULGUISDFFontData参数

ULGUISDFFontData 是 SDF(有向距离场)字体实现,同样继承自 ULGUIFreeTypeRenderFontData，与 ULGUIFontData 相同,继承所有 ULGUIFreeTypeRenderFontData 的参数。也有自己的自身参数

• SDFDefaultMaterials ：SDF 字体的渲染材质数组,包含不同裁剪类型的材质

• FontSize： (int, 默认 64, 范围 16-100) - 渲染字形时的字体大小

• SDFRadius ：(int, 只读, 默认 16) - 距离场的半径(像素),从 LGUI 3.4.11 开始自动设置为 FontSize 的四分之一