GameUI.Control

Control 仅客户端

命名空间 GameUI.Control

public abstract class Control : DisposableObject, IGameObject<GameDataControl>, IGameObject, INodeChild, INode

Represents a base class for UI controls in the game UI system. Provides core logic for managing control hierarchy, data context, and interaction with the underlying game data.

备注

This class implements IGameObject1andINodeChild` interfaces, enabling integration with the game data layer and UI tree structure.

属性

Behaviors 仅客户端

public IReadOnlyList<IControlBehavior>? Behaviors { get; }

获取控件的行为集合（只读）

Link 仅客户端

public IGameLink<GameDataControl> Link { get; set; }

Gets the link to the game data control.

Cache 仅客户端

public GameDataControl Cache { get; set; }

Gets the cached game data control.

Id 仅客户端

protected internal long Id { get; set; }

Gets or sets the unique identifier for this control.

Children 仅客户端

public IReadOnlyList<Control>? Children { get; init; }

Gets or initializes the read-only list of child controls.

Parent 仅客户端

public INode? Parent { get; set; }

Gets the parent node of this control.

DataContext 仅客户端

public object? DataContext { get; set; }

ItemIndex 仅客户端

public int ItemIndex { get; set; }

当前项在 ItemsSource 中的索引，未设置时为 -1。

ItemsSource 仅客户端

public virtual IEnumerable<object>? ItemsSource { get; set; }

控件的数据源集合。

ItemTemplate 仅客户端

public IGameLink<GameDataControl>? ItemTemplate { get; set; }

控件的项模板。

ItemTemplateSelector 仅客户端

public ItemTemplateSelector? ItemTemplateSelector { get; set; }

控件的项模板选择器。

GeneratedChildren 仅客户端

public IReadOnlyList<Control>? GeneratedChildren { get; }

获取由数据源自动生成的子控件集合（只读）。

KeyboardAccelerators 仅客户端

public IList<KeyboardAccelerator>? KeyboardAccelerators { get; set; }

Gets or sets the collection of keyboard accelerators associated with this control.

备注

Keyboard accelerators are keys (such as A) or key combinations (such as Ctrl+S or Alt+Enter) that allow users to quickly invoke specific actions on the control. When a registered accelerator is triggered and the control is functional, the corresponding action or event handler is executed. Controls like Button may have default actions (such as click) that are invoked by accelerators. Modifying this collection will automatically register or unregister the control for accelerator handling.

ActualSizePx 仅客户端

public Size ActualSizePx { get; }

获取控件在设备像素（Device Pixel）下的实际尺寸。只读属性。

备注

The size is calculated dynamically and reflects the current dimensions of the element. Ensure that the element is in a valid state before accessing this property. 通常控件在创建并添加到布局后，会等到该帧末才能获取到实际尺寸。

ActualSize 仅客户端

public SizeF ActualSize { get; }

获取控件在设备无关像素（DIP）下的实际尺寸。只读属性。

备注

This property retrieves the current size of the element by ensuring its state is valid and querying the underlying system. 通常控件在创建并添加到布局后，会等到该帧末才能获取到实际尺寸。

ScreenPositionPx 仅客户端

public (int x, int y) ScreenPositionPx { get; }

获取控件在屏幕上的像素坐标（设备像素，Device Pixel）。只读属性。

ScreenPosition 仅客户端

public UIPosition ScreenPosition { get; }

获取控件在屏幕上的坐标（设备无关像素，DIP）。只读属性。

备注

The returned position is calculated based on the primary viewport's device pixel ratio to ensure consistency across devices with varying display densities.

Position 仅客户端

public UIPosition Position { get; set; }

控件的布局位置。

PositionType 仅客户端

public UIPositionType PositionType { get; set; }

控件的布局定位类型，决定 Position 属性的含义。

备注

Relative：控件位置基于自身排版后的位置进行偏移。 Absolute：控件位置基于父容器的左上角进行偏移。其余排版失效。

Margin 仅客户端

public Thickness Margin { get; set; }

控件的外边距。

Padding 仅客户端

public Thickness Padding { get; set; }

控件的内边距。

Width 仅客户端

public Auto<float> Width { get; set; }

控件的宽度（支持 Auto）。设为 Auto 时，控件宽度将根据内容和其它属性自动调整。 当前属性仅仅反映用户设置的宽度值。在尝试获取控件实际宽度尺寸时，应当使用 ActualSize 属性。

Height 仅客户端

public Auto<float> Height { get; set; }

控件的高度（支持 Auto）。设为 Auto 时，控件高度将根据内容和其它属性自动调整。 当前属性仅仅反映用户设置的高度值。在尝试获取控件实际高度尺寸时，应当使用 ActualSize 属性。

WidthStretchRatio 仅客户端

public float WidthStretchRatio { get; set; }

控件在父容器中的宽度拉伸比例。当父控件拥有足够空间时，控件将根据此比例扩展其宽度。0.5代表占用父容器剩余宽度的50%，1.0代表占用100%。 控件的宽度拉伸比例决定了在父容器空间充足时，控件将如何扩展其宽度。

备注

百分比尺寸设置： 若要将控件宽度设置为父容器宽度的特定百分比，需同时将 Width 设置为 0， 然后设置此属性为目标百分比值。例如，要让控件宽度占父容器的 50%： control.Width = 0; control.WidthStretchRatio = 0.5f; 如果使用流式扩展方法，可以更简洁地调用 control.WidthPercent(0.5f)。

HeightStretchRatio 仅客户端

public float HeightStretchRatio { get; set; }

控件在父容器中的高度拉伸比例。当父控件拥有足够空间时，控件将根据此比例扩展其高度。0.5代表占用父容器剩余高度的50%，1.0代表占用100%。 控件的高度拉伸比例决定了在父容器空间充足时，控件将如何扩展其高度。

备注

百分比尺寸设置： 若要将控件高度设置为父容器高度的特定百分比，需同时将 Height 设置为 0， 然后设置此属性为目标百分比值。例如，要让控件高度占父容器的 50%： control.Height = 0; control.HeightStretchRatio = 0.5f; 如果使用流式扩展方法，可以更简洁地调用 control.HeightPercent(0.5f)。

WidthCompactRatio 仅客户端

public float WidthCompactRatio { get; set; }

控件在父容器中的宽度收缩比例。当父控件空间不足时，控件将根据此比例收缩其宽度。0.5代表占用父容器剩余宽度的50%，1.0代表占用100%。 控件的宽度收缩比例决定了在父容器空间不足时，控件将如何收缩其宽度。

HeightCompactRatio 仅客户端

public float HeightCompactRatio { get; set; }

控件在父容器中的高度收缩比例。当父控件空间不足时，控件将根据此比例收缩其高度。0.5代表占用父容器剩余高度的50%， 1.0代表占用100%。 控件的高度收缩比例决定了在父容器空间不足时，控件将如何收缩其高度。

FlowOrientation 仅客户端

public virtual Orientation? FlowOrientation { get; set; }

控件的流式布局方向。Horizontal代表水平布局， Vertical代表垂直布局， None代表不使用流式布局。

HorizontalAlignment 仅客户端

public HorizontalAlignment? HorizontalAlignment { get; set; }

控件的水平对齐方式。

备注

若父控件启用了水平流式布局（FlowOrientation为Horizontal）， 且设置了属性，则此属性将被忽略。

VerticalAlignment 仅客户端

public VerticalAlignment? VerticalAlignment { get; set; }

控件的垂直对齐方式。

备注

若父控件启用了垂直流式布局（FlowOrientation为Vertical）， 且设置了属性，则此属性将被忽略。

HorizontalContentAlignment 仅客户端

public HorizontalContentAlignment? HorizontalContentAlignment { get; set; }

子控件的水平对齐方式。历史默认值为Center； 当前 GameDataGameUI 开启左上默认后为Left。

备注

兼容默认值： 旧项目未开启左上内容对齐时，默认值为 Center。当子控件未设置 HorizontalAlignment 时， 子控件会被水平居中放置。如果此时用 Margin.Left 定位子控件，偏移量将从中心而非左边缘计算， 导致子控件位置偏右。用 Margin 做绝对定位时，务必在子控件上设置 HorizontalAlignment = HorizontalAlignment.Left。 常规容器控件： 若启用了水平流式布局（FlowOrientation为Horizontal），且设置了此属性，则子控件的 HorizontalAlignment属性将被忽略，改为使用此属性进行对齐。 若未启用水平流式布局，且此属性和子控件的HorizontalAlignment属性均被设置，则优先使用子控件的 HorizontalAlignment属性进行对齐。 Label 文本控件： 对于 Label 控件，此属性控制文字在 Label 内部的水平对齐方式（左对齐、居中、右对齐）。 这是设置 Label 文字水平对齐的正确方法，而 HorizontalAlignment 则控制 Label 控件本身在父容器中的位置。

VerticalContentAlignment 仅客户端

public VerticalContentAlignment? VerticalContentAlignment { get; set; }

子控件的垂直对齐方式。历史默认值为Center； 当前 GameDataGameUI 开启左上默认后为Top。

备注

兼容默认值： 旧项目未开启左上内容对齐时，默认值为 Center。当子控件未设置 VerticalAlignment 时， 子控件会被垂直居中放置。如果此时用 Margin.Top 定位子控件，偏移量将从中心而非顶边缘计算， 导致子控件位置偏下。用 Margin 做绝对定位时，务必在子控件上设置 VerticalAlignment = VerticalAlignment.Top。 常规容器控件： 若启用了垂直流式布局（FlowOrientation为Vertical），且设置了此属性，则子控件的 VerticalAlignment属性将被忽略，改为使用此属性进行对齐。 若未启用垂直流式布局，且此属性和子控件的VerticalAlignment属性均被设置，则优先使用子控件的 VerticalAlignment属性进行对齐。 Label 文本控件： 对于 Label 控件，此属性控制文字在 Label 内部的垂直对齐方式（顶部对齐、居中、底部对齐）。 这是设置 Label 文字垂直对齐的正确方法，而 VerticalAlignment 则控制 Label 控件本身在父容器中的位置。

AspectRatio 仅客户端

public Auto<float>? AspectRatio { get; set; }

控件的宽高比设置，仅在宽或高为 Auto 时生效。

Name 仅客户端

public string? Name { get; set; }

控件的名称。父控件可以通过此名称来查找子控件。

IsStatic 仅客户端

public bool IsStatic { get; set; }

控件是否为静态（不可交互，且不会接受任何事件）。静态控件通常用于显示信息或作为布局容器，不会响应用户输入。 静态控件依然处于事件链路中，子控件仍然可以响应事件，并可能通过静态控件的父控件来传递事件。

IsActuallyDisabled 仅客户端

public bool IsActuallyDisabled { get; }

Gets a value indicating whether the control is disabled, either directly or indirectly through its parent hierarchy.

Disabled 仅客户端

public bool Disabled { get; set; }

控件是否禁用，即不可交互。禁用的控件会使其子控件也变为禁用状态。

备注

由于控件禁用后会影响其子控件，因此在判断一个控件是否可以交互时，应检查IsActuallyDisabled属性， 而不是直接检查此属性。

IsActuallyFunctional 仅客户端

public bool IsActuallyFunctional { get; }

Gets a value indicating whether the component is functional based on its visibility and disabled state. The component is considered functional if it is visible, not disabled, and all its parent controls are also valid and visible, and is linked to the visual tree.

RoutedEvents 仅客户端

public RoutedEvents RoutedEvents { get; set; }

控件的路由事件设置。决定控件是否会将某些事件传递给父控件。

IsLinkedToVisualTree 仅客户端

public bool IsLinkedToVisualTree { get; }

Gets a value indicating whether the current node is linked to a visual tree.

备注

A node is considered linked to a visual tree if it has a valid parent chain that ultimately connects to a UIRoot. If the node is invalid or the parent chain does not lead to a UIRoot, the property returns false.

IsActuallyVisible 仅客户端

public bool IsActuallyVisible { get; }

Gets a value indicating whether the control is visible, taking into account its visibility, linkage to the visual tree, and the visibility of its parent controls.

备注

This property evaluates the control's visibility by checking its own Visible property, its linkage to the visual tree, and the Visible property of all parent controls in its hierarchy. If any parent control is not visible, this property returns false.

Visible 仅客户端

public bool Visible { get; set; }

控件是否可见。不可见的控件会使其子控件也变为不可见状态。

备注

由于控件不可见后会影响其子控件，而且只有当控件直接或间接地链接到视觉树时才会被渲染， 因此在判断一个控件是否可见时，应检查IsActuallyVisible属性，

AllowDrag 仅客户端

public bool AllowDrag { get; set; }

控件是否允许拖拽。

AllowDrop 仅客户端

public bool AllowDrop { get; set; }

控件是否允许作为拖放目标。

ZIndex 仅客户端

public int ZIndex { get; set; }

控件的 Z 轴顺序。这决定了控件在同一父容器中的绘制顺序，数值越大，控件越靠前显示。

Background 仅客户端

public ColorBrush Background { get; set; }

控件的背景颜色画刷。可以是单色或是渐变色。

Desaturated 仅客户端

public bool Desaturated { get; set; }

控件是否为灰度（去色）显示。去色显示通常用于禁用状态或视觉效果处理。

CornerRadius 仅客户端

public float CornerRadius { get; set; }

控件的圆角半径。

Image 仅客户端

public UTF8String Image { get; set; }

控件的图片资源。

ImageMask 仅客户端

public UTF8String ImageMask { get; set; }

控件的图片遮罩资源。

ImageFlipX 仅客户端

public bool ImageFlipX { get; set; }

控件的图片是否水平翻转。 仅对支持图片渲染的控件生效。PanelScrollable 的底层滚动控件不支持图片翻转， 请改用普通 Panel。

ImageFlipY 仅客户端

public bool ImageFlipY { get; set; }

控件的图片是否垂直翻转。 仅对支持图片渲染的控件生效。PanelScrollable 的底层滚动控件不支持图片翻转， 请改用普通 Panel。

ImageBlurLevel 仅客户端

public uint ImageBlurLevel { get; set; }

控件的图片模糊等级。

SlicedEdges 仅客户端

public Thickness SlicedEdges { get; set; }

控件的九宫格切片边距。

Opacity 仅客户端

public float Opacity { get; set; }

控件的不透明度。

Rotation 仅客户端

public float Rotation { get; set; }

控件的旋转角度。

Scale 仅客户端

public Vector2 Scale { get; set; }

控件的缩放比例。

ClipContent 仅客户端

public bool ClipContent { get; set; }

控件是否会裁剪其子控件。

ClickLockedPointerButtons 仅客户端

public PointerButtons ClickLockedPointerButtons { get; }

获取控件的点击锁定指针按钮。 如果控件有行为，则返回所有行为中点击锁定指针按钮的并集。 否则返回None。

方法

AddBehavior 仅客户端

public bool AddBehavior(IControlBehavior behavior)

为控件添加行为

• behavior — 要添加的行为

返回： 是否成功添加

RemoveBehavior 仅客户端

public bool RemoveBehavior(IControlBehavior behavior)

从控件移除指定行为

• behavior — 要移除的行为

返回： 是否成功移除

RemoveBehavior 仅客户端

public bool RemoveBehavior<T>() where T : IControlBehavior

从控件移除指定类型的行为

返回： 是否成功移除

GetBehavior 仅客户端

public T? GetBehavior<T>() where T : class, IControlBehavior

获取指定类型的行为

返回： 找到的行为，如果不存在则为null

HasBehavior 仅客户端

public bool HasBehavior<T>() where T : IControlBehavior

检查控件是否具有指定类型的行为

返回： 如果存在指定类型的行为则为true

ClearBehaviors 仅客户端

public void ClearBehaviors()

清除控件的所有行为

CapturePointer 仅客户端

public void CapturePointer(PointerButtons pointerButtons)

捕获指针输入。捕获后控件将接收 OnPointerCapturedMove 事件，直到释放捕获或抬起指针。

• pointerButtons — 要捕获的指针按钮

备注

通常在 OnPointerPressed 事件中调用此方法，并在 OnPointerReleased 中调用 PointerButtons)。 推荐：对于常见场景，建议使用 PointerCapturedMoveEventArgs}) 扩展方法，它会自动处理捕获和释放。

ReleasePointer 仅客户端

public void ReleasePointer(PointerButtons pointerButtons)

释放捕获的指针输入。

• pointerButtons — 要释放的指针按钮

备注

通常在 OnPointerReleased 事件中调用此方法，与 PointerButtons) 配对使用。

AddChild 仅客户端

public virtual bool AddChild(Control child)

Adds a child control to this control.

• child — The child control to add.

返回： True if the child was added successfully; otherwise, false.

SetMarginInternal 仅客户端

protected internal void SetMarginInternal(Thickness margin)

内部方法：设置控件的Margin值，用于布局系统内部使用 此方法不会影响控件的原始Margin值，适合用于临时布局调整

• margin — 新的Margin值

AddToVisualTree 仅客户端

public bool AddToVisualTree()

Adds this control to the visual tree root, making it and its children visible in the UI.

返回： True if added successfully; otherwise, false.

AddToParent 仅客户端

public Control AddToParent(INode parent)

Adds this control to the specified parent node.

• parent — The parent node.

返回： This control instance for fluent chaining.

AddToParent 仅客户端

public virtual Control AddToParent(INode parent, int index)

Adds this control to the specified parent node at the given index.

• parent — The parent node.
• index — The index at which to insert the control.

返回： This control instance for fluent chaining.

RemoveChild 仅客户端

public virtual bool RemoveChild(Control child)

Removes a child control from this control.

• child — The child control to remove.

返回： True if removed successfully; otherwise, false.

RemoveChild 仅客户端

public bool RemoveChild(INodeChild child)

Removes the specified child from this control.

• child — The child to remove.

返回： True if removed successfully; otherwise, false.

RemoveChild 仅客户端

public bool RemoveChild(int index)

Removes the child at the specified index from this control.

• index — The index of the child to remove.

返回： True if removed successfully; otherwise, false.

RemoveFromParent 仅客户端

public bool RemoveFromParent()

将当前控件从父控件和可视树中移除。

返回： 如果成功移除则为 true；否则为 false。

备注

此方法只摘除父子关系和可视树节点，不会释放控件资源，也不会递归销毁子控件。 如果控件永久不再使用，应调用 Destroy；只有临时隐藏、换父节点或对象池复用时才使用此方法。 对 Canvas 和 CanvasAnimated 等持有渲染资源或回调的控件，长期只调用此方法而不销毁，可能导致资源持续占用。

RemoveFromVisualTree 仅客户端

public bool RemoveFromVisualTree()

将直接挂在可视树根节点下的控件移出可视树。

返回： 如果成功从可视树移除则为 true；否则为 false。

备注

移除后会清空父级引用；如果控件未直接挂在可视树根节点下，则返回 false 且不做修改。 此方法不释放控件资源。永久不用的控件应调用 Destroy。

RemoveFromVisualTreeAndParent 仅客户端

public bool RemoveFromVisualTreeAndParent()

将当前控件从可视树和父控件中移除。

返回： 如果成功移除则为 true；否则为 false。

备注

与 RemoveFromParent 等效，只是命名更强调可视树语义。此方法不释放控件资源。

RemoveFromVisualTreeOnly 仅客户端

protected internal void RemoveFromVisualTreeOnly()

Removes this control from the visual tree only, without affecting the parent relationship.

FindChild 仅客户端

public Control? FindChild(Func<Control, bool> condition)

Finds the first child control that matches the specified condition.

• condition — The condition to match.

返回： The first matching child control, or null if none found.

FindChild 仅客户端

public Control? FindChild(string name)

Finds the first child control with the specified name.

• name — The name of the child control.

返回： The first matching child control, or null if none found.

FindChildren 仅客户端

public IEnumerable<Control>? FindChildren(string name)

Finds all child controls with the specified name.

• name — The name of the child controls.

返回： An enumerable of matching child controls, or null if none found.

ClearBindings 仅客户端

public void ClearBindings()

清除控件的所有绑定

GetById 仅客户端

protected static Control? GetById(long id)

根据控件 Id 获取 Control 实例。

• id — 控件的唯一标识符。

返回： 对应的 Control 实例，如果不存在则为 null。

EnsureValid 仅客户端

protected void EnsureValid()

确保控件处于有效状态（未被摧毁），否则抛出异常。

DisposeManaged 仅客户端

protected override void DisposeManaged()

释放托管资源，包括移除父子关系、销毁子控件、注销事件等。

DisposeUnmanaged 仅客户端

protected override void DisposeUnmanaged(bool finalizing)

释放非托管资源，销毁底层控件句柄。

• finalizing — 指示是否为终结器调用。

GenerateChild 仅客户端

protected virtual Control? GenerateChild(object item, GameDataControl template, bool addToParent = true)

根据数据项和模板生成子控件。

• item — 数据项。
• template — 模板。
• addToParent — 是否自动添加到父控件。

返回： 生成的子控件。

GenerateChild 仅客户端

protected virtual Control? GenerateChild(object item, ItemTemplateSelector templateSelector, bool addToParent = true)

根据数据项和模板选择器生成子控件。

• item — 数据项。
• templateSelector — 模板选择器。
• addToParent — 是否自动添加到父控件。

返回： 生成的子控件。

Template 仅客户端

protected virtual GameDataControl? Template(object item)

根据数据项获取模板。

• item — 数据项。

返回： 对应的数据模板。

GenerateChild 仅客户端

protected virtual Control? GenerateChild(object item, bool addToParent = true)

根据数据项自动选择模板并生成子控件。

• item — 数据项。
• addToParent — 是否自动添加到父控件。

返回： 生成的子控件。

GenerateChildren 仅客户端

public virtual void GenerateChildren()

根据 ItemsSource 生成所有子控件。

GetChildByItem 仅客户端

public virtual Control? GetChildByItem(int itemIndex)

根据数据项索引获取对应的子控件。

• itemIndex — 数据项索引。

返回： 对应的子控件，如果不存在则为 null。

OnKeyboardAcceleratorReleaseInternal 仅客户端

protected virtual bool OnKeyboardAcceleratorReleaseInternal(KeyboardAccelerator accelerator)

OnKeyboardAcceleratorInvokedInternal 仅客户端

protected virtual bool OnKeyboardAcceleratorInvokedInternal(KeyboardAccelerator accelerator)

OnDisplayOrientationChanged 仅客户端

protected internal void OnDisplayOrientationChanged(DisplayOrientations orientations)

响应屏幕方向变化的回调，通常用于基于屏幕方向和控件模版数据调整布局或样式。

• orientations — 当前屏幕方向。

事件

OnPointerClicked 仅客户端

public event EventHandler<PointerEventArgs>? OnPointerClicked

当控件被点击时触发。

备注

点击的精确定义为：在当前控件上按下指针，然后在当前控件上释放指针。 这个事件与和OnPointerReleased不同，尽管两者都在指针释放时触发， 点击事件要求指针在同一个控件上按下和释放。而OnPointerReleased则是只要求当前控件上按下， 在任何地方释放都会触发。

OnPointerDoubleClicked 仅客户端

public event EventHandler<PointerEventArgs>? OnPointerDoubleClicked

当控件被双击时触发。

OnPointerEntered 仅客户端

public event EventHandler? OnPointerEntered

当指针进入控件区域时触发。

OnPointerExited 仅客户端

public event EventHandler? OnPointerExited

当指针离开控件区域时触发。

OnPointerPressed 仅客户端

public event EventHandler<PointerEventArgs>? OnPointerPressed

当指针在控件上按下时触发。

OnPointerReleased 仅客户端

public event EventHandler<PointerEventArgs>? OnPointerReleased

当控件上的指针释放时触发。

备注

这个事件与OnPointerClicked不同，尽管两者都在指针释放时触发， 点击事件要求指针在同一个控件上按下和释放。而OnPointerReleased则是只要求当前控件上按下， 在任何地方释放都会触发。

OnPointerCapturedMove 仅客户端

public event EventHandler<PointerCapturedMoveEventArgs>? OnPointerCapturedMove

当捕获的指针移动时触发。无论 AllowDrag 设置为 true 还是 false 都会触发。

备注

重要：此事件仅在调用 PointerButtons) 捕获指针后才会触发。 通常需要在 OnPointerPressed 中调用 PointerButtons)， 并在 OnPointerReleased 中调用 PointerButtons)。 推荐：对于常见的指针追踪场景，建议使用 PointerCapturedMoveEventArgs}) 扩展方法，它会自动处理捕获和释放逻辑。 手动方式： control.OnPointerPressed += (s, e) => control.CapturePointer(e.PointerButtons); control.OnPointerCapturedMove += (s, e) => { /* 处理移动 / }; control.OnPointerReleased += (s, e) => control.ReleasePointer(e.PointerButtons); 推荐方式： control.TrackPointer(e => { / 处理移动 */ });

OnDrag 仅客户端

public event EventHandler? OnDrag

当控件被拖动时触发。

OnDrop 仅客户端

public event EventHandler<DropEventArgs>? OnDrop

当控件发生拖放操作时触发。

OnSizeChanged 仅客户端

public event EventHandler<SizeChangedEventArgs>? OnSizeChanged

OnChildPostInitialization 仅客户端

public event EventHandler<ApplyControlTemplateEventArgs>? OnChildPostInitialization

Occurs after a child control has been initialized, allowing for additional customization or setup.

备注

This event is raised after the control initialization process is complete. Subscribers can use this event to perform post-initialization tasks, such as applying additional configurations or modifying the control.

OnKeyboardAcceleratorInvoked 仅客户端

public event EventHandler<KeyboardAcceleratorEventArgs>? OnKeyboardAcceleratorInvoked

OnKeyboardAcceleratorReleased 仅客户端

public event EventHandler<KeyboardAcceleratorEventArgs>? OnKeyboardAcceleratorReleased

字段

DefaultFontSize 仅客户端

public const int DefaultFontSize

控件兼容默认字号，单位是 UI 设计坐标；项目应按目标窗口选择可读字号。

children 仅客户端

protected List<Control>? children

The list of child controls.

OnPointerClickedHandler 仅客户端

protected EventHandler<PointerEventArgs>? OnPointerClickedHandler

generatedChildren 仅客户端

protected List<Control>? generatedChildren

RegisteredKeyboardAccelerators 仅客户端

protected static readonly HashSet<Control> RegisteredKeyboardAccelerators

GameEntryLoadingSystem 仅客户端

命名空间 GameUI.Control

public class GameEntryLoadingSystem : IGameClass

GameEntry Loading系统，在游戏初始化时自动显示Loading界面

备注

这个系统实现了IGameClass接口，会在游戏启动时自动注册， 并在适当的时机显示Loading界面，提供更好的用户体验。

构造函数

GameEntryLoadingSystem 仅客户端

public GameEntryLoadingSystem()

方法

OnRegisterGameClass 仅客户端

public static void OnRegisterGameClass()

ShowLoading 仅客户端

public static LoadingUI ShowLoading(string message = "加载中...", bool showProgress = true, bool showCancel = false)

手动显示Loading界面（用于其他系统）

HideAllLoading 仅客户端

public static void HideAllLoading()

隐藏所有Loading界面

IValueBinding 仅客户端

命名空间 GameUI.Control

public interface IValueBinding

值绑定的基接口

方法

Update 仅客户端

void Update(Control control)

更新绑定的目标控件

• control — 目标控件

LoadingUI 仅客户端

命名空间 GameUI.Control

public class LoadingUI

现代化的加载界面控件，提供进度显示、加载文本和动画效果

构造函数

LoadingUI 仅客户端

public LoadingUI()

创建LoadingUI实例

LoadingUI 仅客户端

public LoadingUI(GameDataLoadingUI configuration)

使用指定 GameData 配置创建 LoadingUI 实例。

• configuration — Loading 界面的数据配置。

属性

Configuration 仅客户端

public GameDataLoadingUI Configuration { get; }

当前 Loading 界面使用的数据配置。

Progress 仅客户端

public float Progress { get; set; }

当前加载进度 (0.0 - 1.0)

LoadingMessage 仅客户端

public string LoadingMessage { get; set; }

加载文本消息

ShowCancelButton 仅客户端

public bool ShowCancelButton { get; set; }

是否显示取消按钮

ShowProgress 仅客户端

public bool ShowProgress { get; set; }

是否显示进度条

ShowProgressText 仅客户端

public bool ShowProgressText { get; set; }

是否显示进度文本

方法

Show 仅客户端

public void Show(string? message = null, float progress = 0f)

显示加载界面

Hide 仅客户端

public void Hide()

隐藏加载界面

UpdateProgress 仅客户端

public void UpdateProgress(float progress, string? message = null)

更新加载进度

SetComplete 仅客户端

public void SetComplete(string message = "加载完成")

设置加载完成状态

SetFailed 仅客户端

public void SetFailed(string message = "加载失败")

设置加载失败状态

CreateSimple 仅客户端

public static LoadingUI CreateSimple(string message = "加载中...")

创建简单的加载界面

CreateWithProgress 仅客户端

public static LoadingUI CreateWithProgress(string message = "加载中...", bool showCancel = true)

创建带进度的加载界面

CreateFull 仅客户端

public static LoadingUI CreateFull(string message = "加载中...")

创建全功能加载界面

事件

CancelRequested 仅客户端

public event EventHandler? CancelRequested

取消按钮点击事件

LoadingUIExtensions 仅客户端

命名空间 GameUI.Control

public static class LoadingUIExtensions

LoadingUI的扩展方法，提供便捷的链式调用

方法

Message 仅客户端

public static LoadingUI Message(this LoadingUI loadingUI, string message)

设置加载消息

Progress 仅客户端

public static LoadingUI Progress(this LoadingUI loadingUI, float progress)

设置进度值

WithCancel 仅客户端

public static LoadingUI WithCancel(this LoadingUI loadingUI)

显示取消按钮

WithoutProgress 仅客户端

public static LoadingUI WithoutProgress(this LoadingUI loadingUI)

隐藏进度条

Show 仅客户端

public static LoadingUI Show(this LoadingUI loadingUI, string? message = null)

显示并返回自身

UIRoot 仅客户端

命名空间 GameUI.Control

public sealed class UIRoot : INode

属性

Instance 仅客户端

public static UIRoot Instance { get; }

Children 仅客户端

public IReadOnlyList<Control> Children { get; }

DataContext 仅客户端

public object? DataContext { get; set; }

方法

AddChild 仅客户端

public Control AddChild(Control child)

ValueBinding 仅客户端

命名空间 GameUI.Control

public class ValueBinding<TControl, TValue> : IValueBinding where TControl : Control

泛型值绑定实现

构造函数

ValueBinding 仅客户端

public ValueBinding(Func<TValue> getter, Action<TValue, TControl> updater)

创建值绑定

• getter — 获取值的函数
• updater — 更新控件的函数

方法

Update 仅客户端

public void Update(TControl control)

更新绑定

• control — 目标控件

JoystickActivatedEventArgs 仅客户端

命名空间 GameUI.Control.Advanced

public class JoystickActivatedEventArgs : EventArgs

摇杆激活事件参数

构造函数

JoystickActivatedEventArgs 仅客户端

public JoystickActivatedEventArgs(Vector2 position)

属性

Position 仅客户端

public Vector2 Position { get; }

JoystickCenterChangedEventArgs 仅客户端

命名空间 GameUI.Control.Advanced

public class JoystickCenterChangedEventArgs : EventArgs

摇杆中心位置改变事件参数

构造函数

JoystickCenterChangedEventArgs 仅客户端

public JoystickCenterChangedEventArgs(Vector2 oldCenter, Vector2 newCenter)

属性

OldCenter 仅客户端

public Vector2 OldCenter { get; }

NewCenter 仅客户端

public Vector2 NewCenter { get; }

JoystickDynamic 仅客户端

命名空间 GameUI.Control.Advanced

public class JoystickDynamic : Control, IGameObject<GameDataControlJoystickDynamic>, IGameObject

动态游戏摇杆控件。跟随手指/鼠标移动，没有固定中心点，中心点会随着手指移动而调整。

构造函数

JoystickDynamic 仅客户端

public JoystickDynamic(IGameLink<GameDataControlJoystickDynamic> link)

使用指定模板链接初始化摇杆实例。

• link — 摇杆模板数据链接。

JoystickDynamic 仅客户端

public JoystickDynamic()

使用默认模板初始化摇杆实例。

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlJoystickDynamic> DefaultTemplate { get; }

获取摇杆的默认模板链接。

InputValue 仅客户端

public Vector2 InputValue { get; }

摇杆的当前输入值，范围为 (-1, -1) 到 (1, 1)

Radius 仅客户端

public float Radius { get; set; }

摇杆操作半径（像素）

KnobSize 仅客户端

public float KnobSize { get; set; }

摇杆头的大小（像素）

IsEnabled 仅客户端

public bool IsEnabled { get; set; }

是否启用摇杆功能

IsActive 仅客户端

public bool IsActive { get; }

摇杆是否当前激活

FollowSensitivity 仅客户端

public float FollowSensitivity { get; set; }

中心点跟随的敏感度（0-1），越大跟随越快

CurrentCenterPosition 仅客户端

public Vector2 CurrentCenterPosition { get; }

获取当前动态中心位置

Link 仅客户端

public new IGameLink<GameDataControlJoystickDynamic> Link { get; }

Cache 仅客户端

public new GameDataControlJoystickDynamic Cache { get; }

方法

GenerateChildren 仅客户端

public override void GenerateChildren()

UpdateAppearance 仅客户端

public void UpdateAppearance()

更新摇杆的外观设置

ForceDeactivate 仅客户端

public void ForceDeactivate()

手动停用摇杆

事件

ValueChanged 仅客户端

public event EventHandler<JoystickValueChangedEventArgs>? ValueChanged

摇杆值改变时触发的事件

Activated 仅客户端

public event EventHandler<JoystickActivatedEventArgs>? Activated

摇杆激活时触发的事件

Deactivated 仅客户端

public event EventHandler? Deactivated

摇杆停用时触发的事件

CenterChanged 仅客户端

public event EventHandler<JoystickCenterChangedEventArgs>? CenterChanged

摇杆中心位置改变时触发的事件

JoystickFloat 仅客户端

命名空间 GameUI.Control.Advanced

public class JoystickFloat : Control, IGameObject<GameDataControlJoystickFloat>, IGameObject

浮动游戏摇杆控件。在用户触摸/点击位置动态出现，位置固定直到操作结束。

构造函数

JoystickFloat 仅客户端

public JoystickFloat(IGameLink<GameDataControlJoystickFloat> link)

使用指定模板链接初始化摇杆实例。

• link — 摇杆模板数据链接。

JoystickFloat 仅客户端

public JoystickFloat()

使用默认模板初始化摇杆实例。

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlJoystickFloat> DefaultTemplate { get; }

获取摇杆的默认模板链接。

InputValue 仅客户端

public Vector2 InputValue { get; }

摇杆的当前输入值，范围为 (-1, -1) 到 (1, 1)

Radius 仅客户端

public float Radius { get; set; }

摇杆操作半径（像素）

KnobSize 仅客户端

public float KnobSize { get; set; }

摇杆头的大小（像素）

IsEnabled 仅客户端

public bool IsEnabled { get; set; }

是否启用摇杆功能

IsActive 仅客户端

public bool IsActive { get; }

摇杆是否当前可见/激活

Link 仅客户端

public new IGameLink<GameDataControlJoystickFloat> Link { get; }

Cache 仅客户端

public new GameDataControlJoystickFloat Cache { get; }

方法

GenerateChildren 仅客户端

public override void GenerateChildren()

UpdateAppearance 仅客户端

public void UpdateAppearance()

更新摇杆的外观设置

ForceDeactivate 仅客户端

public void ForceDeactivate()

手动停用摇杆

事件

ValueChanged 仅客户端

public event EventHandler<JoystickValueChangedEventArgs>? ValueChanged

摇杆值改变时触发的事件

Activated 仅客户端

public event EventHandler<JoystickActivatedEventArgs>? Activated

摇杆激活时触发的事件

Deactivated 仅客户端

public event EventHandler? Deactivated

摇杆停用时触发的事件

JoystickNormal 仅客户端

命名空间 GameUI.Control.Advanced

public class JoystickNormal : Panel, IGameObject<GameDataControlJoystickNormal>, IGameObject

普通游戏摇杆控件。具有固定的中心位置，摇杆头可以在固定半径内拖动。

构造函数

JoystickNormal 仅客户端

public JoystickNormal(IGameLink<GameDataControlJoystickNormal> link)

使用指定模板链接初始化摇杆实例。

• link — 摇杆模板数据链接。

JoystickNormal 仅客户端

public JoystickNormal()

使用默认模板初始化摇杆实例。

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlJoystickNormal> DefaultTemplate { get; }

获取摇杆的默认模板链接。

InputValue 仅客户端

public Vector2 InputValue { get; }

摇杆的当前输入值，范围为 (-1, -1) 到 (1, 1)

Radius 仅客户端

public float Radius { get; set; }

摇杆操作半径（像素）

KnobSize 仅客户端

public float KnobSize { get; set; }

摇杆头的大小（像素）

IsEnabled 仅客户端

public bool IsEnabled { get; set; }

是否启用摇杆功能

BackgroundPanel 仅客户端

public Panel? BackgroundPanel { get; }

获取摇杆背景控件

KnobPanel 仅客户端

public Panel? KnobPanel { get; }

获取摇杆头控件

IsDragging 仅客户端

public bool IsDragging { get; }

摇杆是否正在被拖动

Link 仅客户端

public new IGameLink<GameDataControlJoystickNormal> Link { get; }

Cache 仅客户端

public new GameDataControlJoystickNormal Cache { get; }

方法

GenerateChildren 仅客户端

public override void GenerateChildren()

UpdateAppearance 仅客户端

public void UpdateAppearance()

更新摇杆的外观设置

SetBackgroundStyle 仅客户端

public void SetBackgroundStyle(ColorBrush background)

设置摇杆背景样式

• background — 背景画刷

SetKnobStyle 仅客户端

public void SetKnobStyle(ColorBrush background)

设置摇杆头样式

• background — 背景画刷

SetBackgroundImage 仅客户端

public void SetBackgroundImage(string imagePath)

设置摇杆背景图像

• imagePath — 图像路径

SetKnobImage 仅客户端

public void SetKnobImage(string imagePath)

设置摇杆头图像

• imagePath — 图像路径

事件

ValueChanged 仅客户端

public event EventHandler<JoystickValueChangedEventArgs>? ValueChanged

摇杆值改变时触发的事件

DragStarted 仅客户端

public event EventHandler? DragStarted

摇杆开始拖动时触发的事件

DragEnded 仅客户端

public event EventHandler? DragEnded

摇杆结束拖动时触发的事件

JoystickValueChangedEventArgs 仅客户端

命名空间 GameUI.Control.Advanced

public class JoystickValueChangedEventArgs : EventArgs

摇杆值改变事件参数

构造函数

JoystickValueChangedEventArgs 仅客户端

public JoystickValueChangedEventArgs(Vector2 oldValue, Vector2 newValue)

属性

OldValue 仅客户端

public Vector2 OldValue { get; }

NewValue 仅客户端

public Vector2 NewValue { get; }

TextButton 仅客户端

命名空间 GameUI.Control.Advanced

public class TextButton : Button, ITextControl, IGameObject<GameDataControlTextButton>, IGameObject

表示带有内置文本支持的高级按钮控件

备注

TextButton是对Button的封装，内部管理一个Label子控件来显示文本。 它提供了更简洁的API来处理带文本的按钮，避免手动管理Label子控件。 相比传统的Button + Label组合，TextButton提供了统一的文本设置接口。

构造函数

TextButton 仅客户端

public TextButton(IGameLink<GameDataControlTextButton> link)

使用指定模板链接初始化TextButton实例

• link — 按钮模板数据链接

TextButton 仅客户端

public TextButton()

使用默认模板初始化TextButton实例

TextButton 仅客户端

public TextButton(string text)

使用指定文本初始化TextButton实例

• text — 按钮文本

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlTextButton> DefaultTemplate { get; }

获取TextButton的默认模板链接

Text 仅客户端

public string? Text { get; set; }

获取或设置按钮显示的文本内容

Font 仅客户端

public UTF8String Font { get; set; }

获取或设置文本字体

FontSize 仅客户端

public float FontSize { get; set; }

获取或设置文本字体大小

TextColor 仅客户端

public Color TextColor { get; set; }

获取或设置文本颜色

Bold 仅客户端

public bool Bold { get; set; }

获取或设置文本是否为粗体

Italic 仅客户端

public bool Italic { get; set; }

获取或设置文本是否为斜体

TextWrap 仅客户端

public bool TextWrap { get; set; }

获取或设置文本是否自动换行

LineSpacingRatio 仅客户端

public float LineSpacingRatio { get; set; }

获取或设置行间距比例

TextHorizontalAlignment 仅客户端

public HorizontalContentAlignment TextHorizontalAlignment { get; set; }

获取或设置文本的水平内容对齐方式

TextVerticalAlignment 仅客户端

public VerticalContentAlignment TextVerticalAlignment { get; set; }

获取或设置文本的垂直内容对齐方式

StrokeSize 仅客户端

public float StrokeSize { get; set; }

获取或设置文本描边大小

StrokeColor 仅客户端

public Color StrokeColor { get; set; }

获取或设置文本描边颜色

ShadowOffset 仅客户端

public Vector2 ShadowOffset { get; set; }

获取或设置文本阴影偏移

ShadowColor 仅客户端

public Color ShadowColor { get; set; }

获取或设置文本阴影颜色

Link 仅客户端

public new IGameLink<GameDataControlTextButton> Link { get; }

Cache 仅客户端

public new GameDataControlTextButton Cache { get; }

方法

Dispose 仅客户端

protected override void Dispose(bool disposing)

重写Dispose方法，确保正确清理内部Label

VirtualizingDebugPanel 仅客户端

命名空间 GameUI.Control.Advanced

public class VirtualizingDebugPanel : PanelScrollable, IVirtualizingDebugPanel

虚拟化列表调试信息面板 显示虚拟化列表控件的详细调试信息，包括虚拟化状态、缓存信息、子控件信息等

构造函数

VirtualizingDebugPanel 仅客户端

public VirtualizingDebugPanel()

构造函数

属性

Title 仅客户端

public string Title { get; set; }

获取或设置面板标题

方法

AttachTo 仅客户端

public void AttachTo(VirtualizingPanel panel)

附加到指定的虚拟化面板

• panel — 要调试的虚拟化面板

Detach 仅客户端

public void Detach()

从虚拟化面板分离

UpdateVirtualizationState 仅客户端

public void UpdateVirtualizationState(bool isVirtualizing, int cacheStartIndex, int cachedChildrenCount, SizeF viewportSize, float scrollBarValue, int viewportFirstItemIndex)

UpdateCacheInfo 仅客户端

public void UpdateCacheInfo(int cacheBeforeViewportItemCount, int cacheAfterViewportItemCount, int pageItemCount, float logicItemsTotalSize, Dictionary<string, int> recyclePoolCounts)

UpdateChildrenInfo 仅客户端

public void UpdateChildrenInfo(IReadOnlyList<Control> children, IEnumerable<object>? itemsSource)

ClearDebugInfo 仅客户端

public void ClearDebugInfo()

SetDebugEnabled 仅客户端

public void SetDebugEnabled(bool enabled)

Cleanup 仅客户端

public void Cleanup()

销毁时清理资源

BehaviorExtensions 仅客户端

命名空间 GameUI.Control.Behavior

public static class BehaviorExtensions

控件行为的扩展方法，提供便捷的行为添加接口

方法

AddTouchBehavior 仅客户端

public static TouchBehavior AddTouchBehavior(this Control control, float scaleFactor = 0.95f, bool enablePressAnimation = true, bool enableLongPress = true)

为控件添加触摸行为（包含按下动画和长按检测）

• control — 目标控件
• scaleFactor — 按下时的缩放因子，默认为0.95
• enablePressAnimation — 是否启用按下动画，默认为true
• enableLongPress — 是否启用长按检测，默认为true

返回： 添加的行为实例

AddTouchBehaviorWithDuration 仅客户端

public static TouchBehavior AddTouchBehaviorWithDuration(this Control control, float scaleFactor, int pressAnimationDurationMs, int longPressDurationMs, bool enablePressAnimation = true, bool enableLongPress = true)

为控件添加触摸行为（包含按下动画和长按检测），并自定义时长参数

• control — 目标控件
• scaleFactor — 按下时的缩放因子
• pressAnimationDurationMs — 按下动画时长（毫秒）
• longPressDurationMs — 长按触发时长（毫秒）
• enablePressAnimation — 是否启用按下动画
• enableLongPress — 是否启用长按检测

返回： 添加的行为实例

ControlBehavior 仅客户端

命名空间 GameUI.Control.Behavior

public abstract class ControlBehavior : IControlBehavior

控件行为基类，提供通用的行为管理功能

备注

继承此类可以简化行为实现，提供通用的附加/分离逻辑和状态管理。

构造函数

ControlBehavior 仅客户端

protected ControlBehavior()

属性

IsAttached 仅客户端

public bool IsAttached { get; }

获取行为是否已附加到控件上

AttachedControl 仅客户端

public Control? AttachedControl { get; }

获取行为附加的控件

方法

Attach 仅客户端

public virtual void Attach(Control control)

将行为附加到指定控件上

• control — 要附加行为的控件

Detach 仅客户端

public virtual void Detach(Control control)

从指定控件上分离行为

• control — 要分离行为的控件

OnAttached 仅客户端

protected abstract void OnAttached(Control control)

当行为被附加到控件时调用

• control — 被附加的控件

OnDetached 仅客户端

protected abstract void OnDetached(Control control)

当行为从控件分离时调用

• control — 被分离的控件

IControlBehavior 仅客户端

命名空间 GameUI.Control.Behavior

public interface IControlBehavior

控件行为接口，定义控件行为的标准契约

备注

行为模式允许为控件动态添加功能，而不需要修改控件基类。 每个行为负责特定的交互逻辑，如动画、手势识别等。

属性

ClickLockedPointerButtons 仅客户端

public PointerButtons ClickLockedPointerButtons { get; }

点击锁定指针按钮。指定的指针按钮被锁定后，点击控件不会触发OnPointerClicked事件。

IsAttached 仅客户端

public bool IsAttached { get; }

获取行为是否已附加到控件上

AttachedControl 仅客户端

public Control? AttachedControl { get; }

获取行为附加的控件

方法

Attach 仅客户端

void Attach(Control control)

将行为附加到指定控件上

• control — 要附加行为的控件

Detach 仅客户端

void Detach(Control control)

从指定控件上分离行为

• control — 要分离行为的控件

TouchBehavior 仅客户端

命名空间 GameUI.Control.Behavior

public class TouchBehavior : ControlBehavior, IControlBehavior

触摸行为，提供按下动画和长按检测功能

备注

该行为支持平滑按下缩放和透明度动画，还支持长按事件检测。 使用内部ScaleAndOpacity类型实现统一的缩放和透明度动画。

构造函数

TouchBehavior 仅客户端

public TouchBehavior()

属性

PressedScale 仅客户端

public float PressedScale { get; set; }

按下时的缩放因子，默认为0.95

PressedOpacity 仅客户端

public float PressedOpacity { get; set; }

按下时的透明度因子，默认为0.9

PressAnimationDuration 仅客户端

public TimeSpan PressAnimationDuration { get; set; }

按下动画时长，默认为150毫秒

PressAnimationEasing 仅客户端

public IEasingFunction? PressAnimationEasing { get; set; }

按下动画的缓动函数，默认为null（线性插值）

LongPressDuration 仅客户端

public TimeSpan LongPressDuration { get; set; }

长按触发时长，默认为500毫秒

EnablePressAnimation 仅客户端

public bool EnablePressAnimation { get; set; }

是否启用按下动画，默认为true

EnableLongPress 仅客户端

public bool EnableLongPress { get; set; }

是否启用长按检测，默认为true

IsLongPressed 仅客户端

public bool IsLongPressed { get; }

获取当前是否处于长按状态

IsPressed 仅客户端

public bool IsPressed { get; }

获取当前是否处于按下状态

ClickLockedPointerButtons 仅客户端

public PointerButtons ClickLockedPointerButtons { get; }

获取当前点击锁定指针按钮。 如果当前处于长按状态，并且有长按事件订阅，则返回长按事件的指针按钮。 否则返回None。 该逻辑的目的是为了防止长按事件触发时，点击控件会触发OnPointerClicked事件。

方法

OnAttached 仅客户端

protected override void OnAttached(Control control)

OnDetached 仅客户端

protected override void OnDetached(Control control)

事件

LongPressTriggered 仅客户端

public event EventHandler<PointerEventArgs>? LongPressTriggered

长按触发事件

LongPressStarted 仅客户端

public event EventHandler<PointerEventArgs>? LongPressStarted

长按开始事件

LongPressEnded 仅客户端

public event EventHandler<PointerEventArgs>? LongPressEnded

GameDataControl 仅客户端

命名空间 GameUI.Control.Data

public abstract class GameDataControl : GameDataCategory<GameDataControl>, IGameDataCategory<GameDataControl>, IGameData<GameDataControl>, IGameData

UI 控件的数据模板基类，用于在游戏数据层定义控件的属性和行为。 该类是数据驱动 UI 系统的核心，允许通过配置数据动态生成和更新 UI 控件。

备注

GameDataControl 采用可空属性设计，只有非空值才会在 ApplyTo 时应用到控件上， 这样可以实现部分更新和模板继承。所有具体的控件数据类（如 GameDataControlButton、 GameDataControlLabel 等）都继承自此类。

构造函数

GameDataControl 仅客户端

public GameDataControl(GameLink<GameDataControl, GameDataControl> link)

GameDataControl 仅客户端

public GameDataControl(IGameLink<GameDataControl> link)

属性

Layout 仅客户端

public Layout? Layout { get; set; }

控件的布局配置，包含位置、大小、对齐方式等布局相关属性。 当设置时，会批量应用所有非空的布局属性到目标控件。

Event 仅客户端

public Event? Event { get; set; }

控件的事件处理器配置，定义了控件响应的各种用户交互事件。 包括鼠标点击、双击、进入、离开、拖放等事件的处理函数。

IsStatic 仅客户端

public bool? IsStatic { get; set; }

指定控件是否为静态控件。静态控件不接收交互事件，但不影响其子控件的事件处理。 通常用于纯展示的背景元素或布局容器。

Disabled 仅客户端

public bool? Disabled { get; set; }

控件的禁用状态。禁用的控件及其所有子控件都不能接收用户输入。 通常会配合视觉样式变化（如变灰）来提示用户。

KeyboardAccelerators 仅客户端

public List<KeyboardAccelerator>? KeyboardAccelerators { get; set; }

Gets or sets the collection of keyboard accelerators associated with the control.

Behaviors 仅客户端

public List<IGameLink<GameDataControlBehavior>>? Behaviors { get; set; }

控件的行为配置列表，用于动态添加交互行为

备注

行为包括触摸交互等效果。 每个行为都可以独立配置参数，如动画时长、缩放比例等。

RoutedEvents 仅客户端

public RoutedEvents? RoutedEvents { get; set; }

控件的事件路由配置，决定哪些事件会被控件消费，哪些会继续向父控件冒泡。 用于实现复杂的事件传播逻辑，比如按钮的点击事件是否会冒泡到父控件。 这个属性也影响到全局鼠标事件。如果控件吞噬了鼠标事件，则全局鼠标事件不会触发。

Visible 仅客户端

public bool? Visible { get; set; }

控件的可见性。不可见的控件及其子控件不会被渲染和参与布局计算。 与 Opacity 为 0 不同，不可见的控件完全不占用空间。

AllowDrag 仅客户端

public bool? AllowDrag { get; set; }

是否允许该控件被拖拽。启用后，用户可以通过鼠标或触摸拖动该控件。 需要配合拖拽事件处理来实现完整的拖拽功能。

AllowDrop 仅客户端

public bool? AllowDrop { get; set; }

是否允许其他控件拖放到该控件上。启用后，该控件可以作为拖放操作的目标。 通常用于实现物品栏、装备槽等功能。

ZIndex 仅客户端

public int? ZIndex { get; set; }

控件在同级兄弟控件中的 Z 轴排序顺序。数值越大，控件越靠前显示。 用于控制重叠控件的显示层级，如弹出菜单、提示框等。

Background 仅客户端

public ColorBrush? Background { get; set; }

控件的背景画刷，可以是纯色或渐变色。 支持 SolidColorBrush、GradientBrush 等多种画刷类型。

Desaturated 仅客户端

public bool? Desaturated { get; set; }

是否对控件进行去色（灰度）处理。通常用于表示禁用状态或特殊的视觉效果。 去色会将控件的所有颜色转换为灰度显示。

CornerRadius 仅客户端

public float? CornerRadius { get; set; }

控件的圆角半径（像素）。设置后，控件的四个角会变为圆角。 常用于按钮、面板等控件的美化。值为 0 表示直角。

Image 仅客户端

public UTF8String? Image { get; set; }

控件的主图像资源路径。支持各种图片格式，路径相对于游戏资源目录。 图像会根据控件大小和 SlicedEdges 设置进行缩放或九宫格拉伸。

ImageMask 仅客户端

public UTF8String? ImageMask { get; set; }

控件的遮罩图像资源路径。遮罩图像的 Alpha 通道将用于裁剪主图像。 常用于实现特殊形状的控件或图像效果。

ImageBlurLevel 仅客户端

public uint? ImageBlurLevel { get; set; }

图像的模糊等级（0-10）。0 表示不模糊，数值越大模糊程度越高。 常用于背景虚化效果或创建毛玻璃效果。

ImageFlipX 仅客户端

public bool? ImageFlipX { get; set; }

是否水平翻转图像。启用后，图像会沿垂直轴镜像翻转。 常用于创建对称的 UI 元素或调整图像方向。

ImageFlipY 仅客户端

public bool? ImageFlipY { get; set; }

是否垂直翻转图像。启用后，图像会沿水平轴镜像翻转。 可与 ImageFlipX 组合使用实现 180 度旋转效果。

SlicedEdges 仅客户端

public Thickness? SlicedEdges { get; set; }

九宫格切片的边距设置。定义图像哪些部分在缩放时保持原始大小（边角）， 哪些部分可以拉伸（边缘和中心）。用于制作可缩放的 UI 元素如按钮、面板边框。

Opacity 仅客户端

public float? Opacity { get; set; }

控件的不透明度（0.0-1.0）。0 表示完全透明，1 表示完全不透明。 会影响控件及其所有子控件的透明度，可用于淡入淡出效果。

Rotation 仅客户端

public float? Rotation { get; set; }

控件的旋转角度（度）。正值表示顺时针旋转，负值表示逆时针旋转。 旋转中心为控件的中心点，会影响控件的布局边界。

Scale 仅客户端

public Vector2? Scale { get; set; }

控件的缩放比例。X 和 Y 可以独立设置，实现非等比缩放。 值为 1.0 表示原始大小，大于 1.0 表示放大，小于 1.0 表示缩小。

ClipContent 仅客户端

public bool? ClipContent { get; set; }

是否裁剪超出控件边界的内容。启用后，子控件超出父控件边界的部分将被裁剪。 常用于滚动面板、列表框等需要限制内容显示区域的控件。

ItemTemplate 仅客户端

public IGameLink<GameDataControl>? ItemTemplate { get; set; }

数据绑定的项模板。当控件设置了 ItemsSource 后，会使用此模板为每个数据项 生成对应的子控件。用于实现列表、网格等数据驱动的 UI。

ItemTemplateSelector 仅客户端

public ItemTemplateSelector? ItemTemplateSelector { get; set; }

项模板选择器函数。根据不同的数据项返回不同的模板，实现异构列表。 比如聊天列表中系统消息和玩家消息使用不同的显示模板。

OnPostInitialization 仅客户端

public Action<Control>? OnPostInitialization { get; set; }

控件初始化完成后的回调函数。在控件创建并应用模板后异步调用。 用于执行需要控件完全初始化后才能进行的操作，如动画播放、数据加载等。

OnVirtualizationPhase 仅客户端

public List<Action<Control>>? OnVirtualizationPhase { get; set; }

虚拟化回调函数列表。当控件在虚拟化面板中被重用时调用。 用于更新控件状态、重新绑定数据等，确保回收的控件正确显示新内容。

Children 仅客户端

public List<IGameLink<GameDataControl>?>? Children { get; set; }

子控件定义列表。仅在控件初始构造时使用，用于定义控件的静态子控件树。 后续对此属性的修改不会影响已创建的控件实例。

备注

与 ItemTemplate 不同，Children 定义的是静态的、预定义的子控件， 而 ItemTemplate 用于动态生成数据绑定的子控件。

OverrideByTheme 仅客户端

public ValueKeyDictionary<Theme, IGameLink<GameDataControl>>? OverrideByTheme { get; set; }

基于主题的模板覆盖字典。为不同的 UI 主题提供不同的视觉样式。 键为主题枚举，值为该主题下的覆盖模板。

备注

当前版本暂未启用，预留给未来的主题系统使用。 覆盖范围：仅覆盖当前控件的属性，不影响子控件，也无法创建新的子控件。 与 ChildOverrideByPlatform 的区别： 本属性只覆盖控件的视觉和行为属性（如颜色、大小、布局等）， 而 ChildOverrideByPlatform 用于根据平台替换整个子控件树结构。

OverrideByOrientation 仅客户端

public ValueKeyDictionary<DisplayOrientations, IGameLink<GameDataControl>>? OverrideByOrientation { get; set; }

基于屏幕方向的属性覆盖字典。为横屏、竖屏等不同方向提供优化的布局和属性。 实现响应式 UI，自动适配不同的设备方向。

备注

应用机制：覆盖模板会在基础模板之上应用，只需定义需要改变的属性。 支持的方向：横屏(Landscape)、竖屏(Portrait)等。 覆盖范围：仅覆盖当前控件的属性，不影响子控件，也无法创建新的子控件。 与 ChildOverrideByPlatform 的区别： 本属性只覆盖控件的视觉和行为属性（如位置、大小、可见性等）， 而 ChildOverrideByPlatform 用于根据平台替换整个子控件树结构。

OverrideByPlatform 仅客户端

public ValueKeyDictionary<Platform, IGameLink<GameDataControl>>? OverrideByPlatform { get; set; }

基于平台的属性覆盖字典。为不同的运行平台（iOS、Android、Windows等）提供微调的布局和属性。 用于解决平台差异带来的 UI 细节问题。

备注

应用场景：适用于需要针对不同平台微调的场景，如： iOS 和 Android 的安全区域适配差异 不同平台的字体渲染差异 平台特定的 UI 规范调整（如按钮大小、间距等） 应用机制：覆盖模板会在基础模板之上应用，只需定义需要改变的属性。 覆盖范围：仅覆盖当前控件的属性，不影响子控件，也无法创建新的子控件。 与 ChildOverrideByPlatform 的区别： 本属性用于属性微调，只覆盖控件的视觉和行为属性； 而 ChildOverrideByPlatform 用于结构替换， 可以根据平台提供完全不同的子控件树结构（如 iOS 使用一套控件，Android 使用另一套控件）。

方法

ApplyTo 仅客户端

public virtual void ApplyTo(Control control)

将模板的所有非空属性应用到指定的控件实例。 这是模板系统的核心方法，实现了数据到 UI 的映射。

• control — 要应用模板的目标控件。

备注

该方法只会应用非空属性，这样可以实现：

1. 部分更新 - 只修改需要改变的属性
2. 模板继承 - 子模板可以选择性覆盖父模板的属性
3. 增量配置 - 可以多次调用来逐步配置控件

OverrideByPlatformApply 仅客户端

protected void OverrideByPlatformApply(Control control)

根据当前运行平台应用相应的属性覆盖模板。 用于解决平台差异，为不同平台提供微调的布局和属性。

• control — 要应用平台覆盖的控件。

备注

如果当前平台有对应的覆盖模板，会在基础模板之上再应用覆盖模板的属性。 注意：这只是属性覆盖，不会替换子控件。 如需根据平台替换整个子控件树，请使用 ChildOverrideByPlatform。

OverrideByOrientationApply 仅客户端

protected void OverrideByOrientationApply(Control control)

根据当前设备的屏幕方向应用相应的属性覆盖模板。 支持响应式 UI 设计，为不同屏幕方向提供优化的布局。

• control — 要应用方向覆盖的控件。

备注

如果当前方向有对应的覆盖模板，会在基础模板之上再应用覆盖模板的属性。 同时会注册方向变化事件，以便在设备旋转时自动更新布局。 注意：这只是属性覆盖，不会替换子控件。 如需根据平台替换整个子控件树，请使用 ChildOverrideByPlatform。

CreateControl 仅客户端

public abstract Control CreateControl()

创建该模板对应的控件实例。由具体的控件数据类实现。 这是工厂方法模式的应用，每种控件类型都知道如何创建自己。

返回： 新创建的控件实例，其类型与数据模板类型对应。

备注

例如：GameDataControlButton.CreateControl() 返回 Button 实例， GameDataControlLabel.CreateControl() 返回 Label 实例。

GameDataControlBehavior 仅客户端

命名空间 GameUI.Control.Data

public abstract class GameDataControlBehavior : GameDataCategory<GameDataControlBehavior>, IGameDataCategory<GameDataControlBehavior>, IGameData<GameDataControlBehavior>, IGameData

控件行为配置基类，用于在GameDataControl中配置控件行为

备注

该基类定义了行为配置的通用属性，具体的行为配置类继承此类。 支持通过游戏数据配置来动态添加控件行为。

构造函数

GameDataControlBehavior 仅客户端

public GameDataControlBehavior(GameLink<GameDataControlBehavior, GameDataControlBehavior> link)

GameDataControlBehavior 仅客户端

public GameDataControlBehavior(IGameLink<GameDataControlBehavior> link)

属性

Enabled 仅客户端

public bool? Enabled { get; set; }

是否启用该行为，默认为 true

方法

CreateBehavior 仅客户端

public abstract ControlBehavior CreateBehavior()

创建行为实例

返回： 创建的行为实例

GameDataControlBehaviorTouch 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlBehaviorTouch : GameDataControlBehavior, IGameData<GameDataControlBehaviorTouch>, IGameData

触摸行为配置，包含按下动画和长按检测功能

备注

配置触摸行为的参数，如缩放比例、透明度、动画时长、长按触发时长等

构造函数

GameDataControlBehaviorTouch 仅客户端

public GameDataControlBehaviorTouch(GameLink<GameDataControlBehavior, GameDataControlBehaviorTouch> link)

GameDataControlBehaviorTouch 仅客户端

public GameDataControlBehaviorTouch(IGameLink<GameDataControlBehaviorTouch> link)

属性

PressedScale 仅客户端

public float? PressedScale { get; set; }

按下时的缩放因子，默认为0.8

PressedOpacity 仅客户端

public float? PressedOpacity { get; set; }

按下时的透明度因子，默认为0.9

PressAnimationDuration 仅客户端

public TimeSpan? PressAnimationDuration { get; set; }

按下动画时长，默认为250毫秒

PressAnimationEasingType 仅客户端

public EasingType? PressAnimationEasingType { get; set; }

按下动画的缓动函数类型，默认为None（线性插值）

PressAnimationEasingMode 仅客户端

public EasingMode? PressAnimationEasingMode { get; set; }

按下动画的缓动模式，默认为EaseOut

LongPressDuration 仅客户端

public TimeSpan? LongPressDuration { get; set; }

长按触发时长，默认为500毫秒

EnablePressAnimation 仅客户端

public bool? EnablePressAnimation { get; set; }

是否启用按下动画，默认为true

EnableLongPress 仅客户端

public bool? EnableLongPress { get; set; }

是否启用长按检测，默认为true

Link 仅客户端

public new IGameLink<GameDataControlBehaviorTouch> Link { get; }

方法

CreateBehavior 仅客户端

public override ControlBehavior CreateBehavior()

创建行为实例

返回： 创建的行为实例

GameDataControlButton 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlButton : GameDataControl, IGameData<GameDataControlButton>, IGameData

按钮控件的游戏数据类，用于配置可点击的 UI 按钮。

构造函数

GameDataControlButton 仅客户端

public GameDataControlButton(GameLink<GameDataControl, GameDataControlButton> link)

GameDataControlButton 仅客户端

public GameDataControlButton(IGameLink<GameDataControlButton> link)

属性

ImageHover 仅客户端

public UTF8String? ImageHover { get; set; }

鼠标悬停时显示的图像路径，用于按钮的悬停反馈效果。

ImagePressed 仅客户端

public UTF8String? ImagePressed { get; set; }

按下时显示的图像路径，用于按钮的按下反馈效果。

Link 仅客户端

public new IGameLink<GameDataControlButton> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateButton 仅客户端

public Button CreateButton()

GameDataControlCanvas 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlCanvas : GameDataControl, IGameData<GameDataControlCanvas>, IGameData

Canvas控件的游戏数据类

备注

此类继承自GameDataControl，专门用于Canvas控件的数据管理和控件创建。 它作为Canvas控件与游戏数据系统之间的桥梁，负责： Canvas控件实例的创建和初始化 Canvas相关游戏数据的存储和管理 与游戏数据链接系统的集成

构造函数

GameDataControlCanvas 仅客户端

public GameDataControlCanvas(GameLink<GameDataControl, GameDataControlCanvas> link)

GameDataControlCanvas 仅客户端

public GameDataControlCanvas(IGameLink<GameDataControlCanvas> link)

属性

DefaultPathWinding 仅客户端

public WindingMode? DefaultPathWinding { get; set; }

路径的缠绕规则，决定复杂路径的填充区域判定（如环形、自相交图形）。

FillPaint 仅客户端

public Paint? FillPaint { get; set; }

路径内部的填充画刷，支持纯色、渐变等。

StrokePaint 仅客户端

public Paint? StrokePaint { get; set; }

路径轮廓的描边画刷。

StrokeSize 仅客户端

public float? StrokeSize { get; set; }

路径轮廓的描边宽度（像素）。

Link 仅客户端

public new IGameLink<GameDataControlCanvas> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

创建Canvas控件实例

返回： 基于当前数据链接创建的Canvas控件实例

备注

此方法重写基类的CreateControl方法，返回Canvas类型的具体实例。 创建的控件会自动绑定到当前的数据链接(Link)。

CreateCanvas 仅客户端

public Canvas CreateCanvas()

创建Canvas控件的强类型版本

返回： 基于当前数据链接创建的Canvas控件实例

备注

此方法提供了创建Canvas控件的强类型接口，避免了类型转换的需要。 功能上等同于CreateControl()方法，但返回类型直接是Canvas而不是Control。

GameDataControlCanvasAnimated 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlCanvasAnimated : GameDataControlCanvas, IGameData<GameDataControlCanvasAnimated>, IGameData

CanvasAnimated控件的游戏数据类

备注

此类继承自GameDataControlCanvas，专门用于CanvasAnimated控件的数据管理和控件创建。 它作为CanvasAnimated控件与游戏数据系统之间的桥梁，负责： CanvasAnimated控件实例的创建和初始化 CanvasAnimated相关游戏数据的存储和管理 与游戏数据链接系统的集成

构造函数

GameDataControlCanvasAnimated 仅客户端

public GameDataControlCanvasAnimated(GameLink<GameDataControl, GameDataControlCanvasAnimated> link)

GameDataControlCanvasAnimated 仅客户端

public GameDataControlCanvasAnimated(IGameLink<GameDataControlCanvasAnimated> link)

属性

Link 仅客户端

public new IGameLink<GameDataControlCanvasAnimated> Link { get; }

方法

CreateControl 仅客户端

public override Control CreateControl()

创建CanvasAnimated控件实例

返回： 基于当前数据链接创建的CanvasAnimated控件实例

备注

此方法重写基类的CreateControl方法，返回CanvasAnimated类型的具体实例。 创建的控件会自动绑定到当前的数据链接(Link)。

CreateCanvasAnimated 仅客户端

public CanvasAnimated CreateCanvasAnimated()

创建CanvasAnimated控件的强类型版本

返回： 基于当前数据链接创建的CanvasAnimated控件实例

备注

此方法提供了创建CanvasAnimated控件的强类型接口，避免了类型转换的需要。 功能上等同于CreateControl()方法，但返回类型直接是CanvasAnimated而不是Control。

GameDataControlInput 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlInput : GameDataControl, IGameData<GameDataControlInput>, IGameData

文本输入框控件的游戏数据类，用于配置可编辑的文本输入区域。

构造函数

GameDataControlInput 仅客户端

public GameDataControlInput(GameLink<GameDataControl, GameDataControlInput> link)

GameDataControlInput 仅客户端

public GameDataControlInput(IGameLink<GameDataControlInput> link)

属性

InputEvents 仅客户端

public InputEvents? InputEvents { get; set; }

输入框的事件配置，包括文本变化、获得/失去焦点、按键等回调。

Text 仅客户端

public string? Text { get; set; }

Font 仅客户端

public UTF8String? Font { get; set; }

FontSize 仅客户端

public float? FontSize { get; set; }

TextColor 仅客户端

public Color? TextColor { get; set; }

Bold 仅客户端

public bool? Bold { get; set; }

是否使用粗体。

Italic 仅客户端

public bool? Italic { get; set; }

是否使用斜体。

Link 仅客户端

public new IGameLink<GameDataControlInput> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateInput 仅客户端

public Input CreateInput()

GameDataControlJoystickDynamic 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlJoystickDynamic : GameDataControl, IGameData<GameDataControlJoystickDynamic>, IGameData

动态游戏摇杆控件的数据模板类

构造函数

GameDataControlJoystickDynamic 仅客户端

public GameDataControlJoystickDynamic(GameLink<GameDataControl, GameDataControlJoystickDynamic> link)

GameDataControlJoystickDynamic 仅客户端

public GameDataControlJoystickDynamic(IGameLink<GameDataControlJoystickDynamic> link)

属性

Radius 仅客户端

public float? Radius { get; set; }

摇杆操作半径（像素）

KnobSize 仅客户端

public float? KnobSize { get; set; }

摇杆头的大小（像素）

IsEnabled 仅客户端

public bool? IsEnabled { get; set; }

是否启用摇杆功能

FollowSensitivity 仅客户端

public float? FollowSensitivity { get; set; }

中心点跟随的敏感度（0-1），越大跟随越快

JoystickBackground 仅客户端

public ColorBrush? JoystickBackground { get; set; }

摇杆背景颜色

KnobBackground 仅客户端

public ColorBrush? KnobBackground { get; set; }

摇杆头颜色

JoystickBackgroundImage 仅客户端

public UTF8String? JoystickBackgroundImage { get; set; }

摇杆背景图像

KnobImage 仅客户端

public UTF8String? KnobImage { get; set; }

摇杆头图像

ActivationAreaBackground 仅客户端

public ColorBrush? ActivationAreaBackground { get; set; }

激活区域背景颜色（用于调试）

Link 仅客户端

public new IGameLink<GameDataControlJoystickDynamic> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateJoystickDynamic 仅客户端

public JoystickDynamic CreateJoystickDynamic()

GameDataControlJoystickFloat 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlJoystickFloat : GameDataControl, IGameData<GameDataControlJoystickFloat>, IGameData

浮动游戏摇杆控件的数据模板类

构造函数

GameDataControlJoystickFloat 仅客户端

public GameDataControlJoystickFloat(GameLink<GameDataControl, GameDataControlJoystickFloat> link)

GameDataControlJoystickFloat 仅客户端

public GameDataControlJoystickFloat(IGameLink<GameDataControlJoystickFloat> link)

属性

Radius 仅客户端

public float? Radius { get; set; }

摇杆操作半径（像素）

KnobSize 仅客户端

public float? KnobSize { get; set; }

摇杆头的大小（像素）

IsEnabled 仅客户端

public bool? IsEnabled { get; set; }

是否启用摇杆功能

JoystickBackground 仅客户端

public ColorBrush? JoystickBackground { get; set; }

摇杆背景颜色

KnobBackground 仅客户端

public ColorBrush? KnobBackground { get; set; }

摇杆头颜色

JoystickBackgroundImage 仅客户端

public UTF8String? JoystickBackgroundImage { get; set; }

摇杆背景图像

KnobImage 仅客户端

public UTF8String? KnobImage { get; set; }

摇杆头图像

ActivationAreaBackground 仅客户端

public ColorBrush? ActivationAreaBackground { get; set; }

激活区域背景颜色（用于调试）

Link 仅客户端

public new IGameLink<GameDataControlJoystickFloat> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateJoystickFloat 仅客户端

public JoystickFloat CreateJoystickFloat()

GameDataControlJoystickNormal 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlJoystickNormal : GameDataControlPanel, IGameData<GameDataControlJoystickNormal>, IGameData

普通游戏摇杆控件的数据模板类

构造函数

GameDataControlJoystickNormal 仅客户端

public GameDataControlJoystickNormal(GameLink<GameDataControl, GameDataControlJoystickNormal> link)

GameDataControlJoystickNormal 仅客户端

public GameDataControlJoystickNormal(IGameLink<GameDataControlJoystickNormal> link)

属性

Radius 仅客户端

public float? Radius { get; set; }

摇杆操作半径（像素）

KnobSize 仅客户端

public float? KnobSize { get; set; }

摇杆头的大小（像素）

IsEnabled 仅客户端

public bool? IsEnabled { get; set; }

是否启用摇杆功能

JoystickBackground 仅客户端

public ColorBrush? JoystickBackground { get; set; }

摇杆背景颜色

KnobBackground 仅客户端

public ColorBrush? KnobBackground { get; set; }

摇杆头颜色

JoystickBackgroundImage 仅客户端

public UTF8String? JoystickBackgroundImage { get; set; }

摇杆背景图像

KnobImage 仅客户端

public UTF8String? KnobImage { get; set; }

摇杆头图像

Link 仅客户端

public new IGameLink<GameDataControlJoystickNormal> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateJoystickNormal 仅客户端

public JoystickNormal CreateJoystickNormal()

GameDataControlLabel 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlLabel : GameDataControl, IGameData<GameDataControlLabel>, IGameData

文本标签控件的游戏数据类，用于配置静态或动态显示的文本。

构造函数

GameDataControlLabel 仅客户端

public GameDataControlLabel(GameLink<GameDataControl, GameDataControlLabel> link)

GameDataControlLabel 仅客户端

public GameDataControlLabel(IGameLink<GameDataControlLabel> link)

属性

Text 仅客户端

public string? Text { get; set; }

获取或设置标签文本。富文本语法请参阅 Label.Text。

Font 仅客户端

public UTF8String? Font { get; set; }

FontSize 仅客户端

public float? FontSize { get; set; }

TextColor 仅客户端

public Color? TextColor { get; set; }

LineSpacingRatio 仅客户端

public float? LineSpacingRatio { get; set; }

相对于字体默认行高额外增加的行距比例。 0 表示默认行高；0.5 表示 1.5 倍默认行高；1.0 表示 2 倍默认行高。

TextWrap 仅客户端

public bool? TextWrap { get; set; }

是否自动换行，超出宽度时换到下一行。

Bold 仅客户端

public bool? Bold { get; set; }

是否使用粗体。

Italic 仅客户端

public bool? Italic { get; set; }

是否使用斜体。

StrokeSize 仅客户端

public float? StrokeSize { get; set; }

文字描边宽度（像素），用于增强可读性或装饰效果。

StrokeColor 仅客户端

public Color? StrokeColor { get; set; }

文字描边颜色。

ShadowOffset 仅客户端

public Vector2? ShadowOffset { get; set; }

文字阴影的偏移量（像素），X/Y 分别表示水平和垂直偏移。

ShadowColor 仅客户端

public Color? ShadowColor { get; set; }

文字阴影的颜色。

TextTrimming 仅客户端

public TextTrimming? TextTrimming { get; set; }

文本超出边界时的裁剪方式（如省略号、字符裁剪等）。

Link 仅客户端

public new IGameLink<GameDataControlLabel> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateLabel 仅客户端

public Label CreateLabel()

GameDataControlPage 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlPage : GameDataControlPanel, IGameData<GameDataControlPage>, IGameData

Formal UI Authoring page definition. Unlike a regular panel, this type is materialized as the viewport-sized Page root.

构造函数

GameDataControlPage 仅客户端

public GameDataControlPage(GameLink<GameDataControl, GameDataControlPage> link)

GameDataControlPage 仅客户端

public GameDataControlPage(IGameLink<GameDataControlPage> link)

属性

Link 仅客户端

public new IGameLink<GameDataControlPage> Link { get; }

方法

CreateControl 仅客户端

public override Control CreateControl()

CreatePage 仅客户端

public Page CreatePage()

GameDataControlPanel 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlPanel : GameDataControl, IGameData<GameDataControlPanel>, IGameData

构造函数

GameDataControlPanel 仅客户端

public GameDataControlPanel(GameLink<GameDataControl, GameDataControlPanel> link)

GameDataControlPanel 仅客户端

public GameDataControlPanel(IGameLink<GameDataControlPanel> link)

属性

Link 仅客户端

public new IGameLink<GameDataControlPanel> Link { get; }

方法

CreateControl 仅客户端

public override Control CreateControl()

CreatePanel 仅客户端

public Panel CreatePanel()

GameDataControlPanelScrollable 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlPanelScrollable : GameDataControlPanel, IGameData<GameDataControlPanelScrollable>, IGameData

可滚动面板控件的游戏数据类，用于配置带滚动条的内容容器。

构造函数

GameDataControlPanelScrollable 仅客户端

public GameDataControlPanelScrollable(GameLink<GameDataControl, GameDataControlPanelScrollable> link)

GameDataControlPanelScrollable 仅客户端

public GameDataControlPanelScrollable(IGameLink<GameDataControlPanelScrollable> link)

属性

ScrollEvents 仅客户端

public PanelScrollableEvents? ScrollEvents { get; set; }

滚动相关事件配置，如滚动位置变化回调。

ScrollEnabled 仅客户端

public bool? ScrollEnabled { get; set; }

是否启用滚动，禁用时内容不可滚动。

ScrollOrientation 仅客户端

public Orientation? ScrollOrientation { get; set; }

滚动方向：垂直或水平。

ScrollBarSize 仅客户端

public int? ScrollBarSize { get; set; }

滚动条宽度或高度（像素）。

ScrollBarColor 仅客户端

public ColorBrush? ScrollBarColor { get; set; }

滚动条的颜色画刷。

ScrollBarValue 仅客户端

public float? ScrollBarValue { get; set; }

滚动条初始位置（0.0-1.0），0 为顶部/左侧，1 为底部/右侧。

Link 仅客户端

public new IGameLink<GameDataControlPanelScrollable> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreatePanelScrollable 仅客户端

public PanelScrollable CreatePanelScrollable()

GameDataControlParticle 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlParticle : GameDataControl, IGameData<GameDataControlParticle>, IGameData

粒子特效控件的游戏数据类，用于配置粒子系统的显示与播放。

构造函数

GameDataControlParticle 仅客户端

public GameDataControlParticle(GameLink<GameDataControl, GameDataControlParticle> link)

GameDataControlParticle 仅客户端

public GameDataControlParticle(IGameLink<GameDataControlParticle> link)

属性

Resource 仅客户端

public UTF8String? Resource { get; set; }

粒子特效资源路径，指向粒子配置文件。

IsPlaying 仅客户端

public bool? IsPlaying { get; set; }

是否自动播放，false 时需代码手动触发播放。

Speed 仅客户端

public float? Speed { get; set; }

粒子播放速度倍率，1.0 为正常速度。

ParticleOffset 仅客户端

public PointF? ParticleOffset { get; set; }

粒子显示偏移，取值范围 0-1。(0, 0) 为左上角，(0.5, 0.5) 为居中。

ParticleAutoScale 仅客户端

public bool? ParticleAutoScale { get; set; }

是否按参考尺寸自动缩放。启用后根据 ParticleReferenceSize 和控件实际尺寸计算缩放；关闭后使用 ParticleScale。

ParticleReferenceSize 仅客户端

public SizeF? ParticleReferenceSize { get; set; }

自动缩放的参考画布尺寸，仅在 ParticleAutoScale 为 true 时生效。表示粒子在 100% 缩放下占据的画布尺寸。

ParticleScale 仅客户端

public Size? ParticleScale { get; set; }

粒子整体缩放，用于适配不同尺寸的显示区域。仅在 ParticleAutoScale 为 false 时生效。

ParticleView 仅客户端

public ParticleView? ParticleView { get; set; }

粒子视图模式，决定粒子在 2D/3D 空间中的朝向（如俯视、前向等）。

Link 仅客户端

public new IGameLink<GameDataControlParticle> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateParticle 仅客户端

public Particle CreateParticle()

GameDataControlPlatformAdaptivePanel 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlPlatformAdaptivePanel : GameDataControlPanel, IGameData<GameDataControlPlatformAdaptivePanel>, IGameData

平台自适应面板控件的数据模板类。 根据当前运行平台自动选择并显示对应的子控件树结构，实现平台特定的 UI 布局。

备注

典型应用场景： iOS 和 Android 采用完全不同的导航结构 移动端和桌面端显示不同的操作界面 不同平台的交互模式差异（如手势 vs 键鼠） 与 OverrideByPlatform 的区别： ChildOverrideByPlatform：结构替换，用于根据平台提供完全不同的子控件树 OverrideByPlatform：属性微调，只覆盖控件的视觉和行为属性

构造函数

GameDataControlPlatformAdaptivePanel 仅客户端

public GameDataControlPlatformAdaptivePanel(GameLink<GameDataControl, GameDataControlPlatformAdaptivePanel> link)

GameDataControlPlatformAdaptivePanel 仅客户端

public GameDataControlPlatformAdaptivePanel(IGameLink<GameDataControlPlatformAdaptivePanel> link)

属性

ChildOverrideByPlatform 仅客户端

public ValueKeyDictionary<Platform, IGameLink<GameDataControl>>? ChildOverrideByPlatform { get; set; }

平台子控件覆盖字典。为不同的平台提供完全不同的子控件树结构。 键为平台枚举（iOS、Android、Windows等），值为该平台下的子控件定义。

备注

工作原理：在控件构造时，根据当前运行平台从字典中选择对应的子控件进行创建。 使用场景：适用于需要根据平台提供完全不同 UI 结构的场景。 与 OverrideByPlatform 的本质区别： 本属性：替换整个子控件树结构，适合大范围的平台差异 OverrideByPlatform：只覆盖控件属性（如大小、颜色、位置），适合细节微调 示例：移动端显示滑动手势控件，桌面端显示鼠标按钮控件。

Link 仅客户端

public new IGameLink<GameDataControlPlatformAdaptivePanel> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreatePlatformAdaptivePanel 仅客户端

public PlatformAdaptivePanel CreatePlatformAdaptivePanel()

GameDataControlProgress 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlProgress : GameDataControl, IGameData<GameDataControlProgress>, IGameData

进度条控件的游戏数据类，用于配置血量条、经验条等进度显示。

构造函数

GameDataControlProgress 仅客户端

public GameDataControlProgress(GameLink<GameDataControl, GameDataControlProgress> link)

GameDataControlProgress 仅客户端

public GameDataControlProgress(IGameLink<GameDataControlProgress> link)

属性

Value 仅客户端

public float? Value { get; set; }

当前进度值（0.0-1.0），1.0 表示满进度。

ProgressionMode 仅客户端

public ProgressionMode? ProgressionMode { get; set; }

进度填充方向：从左到右、从上到下、顺时针等。

ProgressRotation 仅客户端

public float? ProgressRotation { get; set; }

进度条填充的旋转角度（度），仅对顺时针/逆时针模式有效。

Link 仅客户端

public new IGameLink<GameDataControlProgress> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateProgress 仅客户端

public Progress CreateProgress()

GameDataControlSpine 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlSpine : GameDataControl, IGameData<GameDataControlSpine>, IGameData

Spine 骨骼动画控件的游戏数据类，用于配置 Spine 格式的角色或特效动画。 当前运行时支持 Spine 4.2 资源格式，兼容 Spine 4.1 导出的资源，并额外支持 Spine 3.8 导出的 .skel 二进制资源；旧版本 .json 不在兼容范围内。

构造函数

GameDataControlSpine 仅客户端

public GameDataControlSpine(GameLink<GameDataControl, GameDataControlSpine> link)

GameDataControlSpine 仅客户端

public GameDataControlSpine(IGameLink<GameDataControlSpine> link)

属性

IsLooping 仅客户端

public bool? IsLooping { get; set; }

是否循环播放动画。

Resource 仅客户端

public UTF8String? Resource { get; set; }

Spine 资源路径（不含后缀）。当前运行时支持 Spine 4.2，兼容 Spine 4.1，并额外支持 Spine 3.8 .skel；旧版本 .json 不在兼容范围内。

Animation 仅客户端

public UTF8String? Animation { get; set; }

要播放的动画名称，需与 Spine 资源中定义的动画名一致。

Skin 仅客户端

public UTF8String? Skin { get; set; }

皮肤名称，需与 Spine 资源中定义的皮肤名一致。

Link 仅客户端

public new IGameLink<GameDataControlSpine> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateSpine 仅客户端

public Spine CreateSpine()

GameDataControlSprites 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlSprites : GameDataControl, IGameData<GameDataControlSprites>, IGameData

序列帧动画控件的游戏数据类，用于配置多张图片切换的动画效果。

备注

所有可空属性为 null 时表示不覆盖控件默认值。 普通图片文件模式需要配置 SpriteSize、FrameCount 和 RowFrameCount； 文件夹序列模式会从子图列表推导帧区域，FrameCount 仅作为播放上限。

构造函数

GameDataControlSprites 仅客户端

public GameDataControlSprites(GameLink<GameDataControl, GameDataControlSprites> link)

GameDataControlSprites 仅客户端

public GameDataControlSprites(IGameLink<GameDataControlSprites> link)

属性

IsLooping 仅客户端

public bool? IsLooping { get; set; }

获取或设置是否循环播放序列帧。

备注

为 false 时，动画推进到 EndFrame 后停止。

IsPlaying 仅客户端

public bool? IsPlaying { get; set; }

获取或设置是否在数据应用完成后播放动画。

备注

该属性会在尺寸、帧数、播放范围和速度配置之后最后应用，避免控件在参数未配置完整时提前开始播放。

IntervalMillisecond 仅客户端

public float? IntervalMillisecond { get; set; }

获取或设置每帧间隔时间，单位为毫秒。

备注

与 FramePerSecond 表达同一份速度配置。两者同时设置时，当前应用顺序下 FramePerSecond 最后生效。

FramePerSecond 仅客户端

public float? FramePerSecond { get; set; }

获取或设置播放帧率，单位为 FPS。

备注

与 IntervalMillisecond 表达同一份速度配置。两者同时设置时，该属性最后生效。

FrameCount 仅客户端

public int? FrameCount { get; set; }

获取或设置动画总帧数。

备注

普通单图 sprite sheet 模式下表示从图片中切出的总帧数。 文件夹序列模式下表示最多播放的子图数量，native 侧实际值不会超过真实子图数量。

RowFrameCount 仅客户端

public int? RowFrameCount { get; set; }

获取或设置普通单图 sprite sheet 中每一行包含的帧数。

备注

只对普通图片文件模式有意义。文件夹序列模式会忽略该值。

SpriteSize 仅客户端

public Size? SpriteSize { get; set; }

获取或设置普通单图 sprite sheet 中单帧的像素尺寸。

备注

只对普通图片文件模式有意义。文件夹序列模式使用子图自身记录的区域。

StartFrame 仅客户端

public int? StartFrame { get; set; }

获取或设置播放起始帧，下标从 0 开始。

EndFrame 仅客户端

public int? EndFrame { get; set; }

获取或设置播放结束帧，下标从 0 开始。

备注

不设置时控件默认使用 FrameCount - 1。

Link 仅客户端

public new IGameLink<GameDataControlSprites> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

将游戏数据配置应用到运行时控件实例。

• control — 目标控件实例。

备注

图片路径由基类先应用。本方法随后应用帧参数、播放速度，最后应用 IsPlaying。

CreateControl 仅客户端

public override Control CreateControl()

创建序列帧动画控件实例。

返回： 新建的 Sprites 控件。

CreateSprites 仅客户端

public Sprites CreateSprites()

创建强类型的序列帧动画控件实例。

返回： 新建的 Sprites 控件。

GameDataControlTextButton 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlTextButton : GameDataControlButton, IGameData<GameDataControlTextButton>, IGameData

带文本标签的按钮控件，支持文本样式、描边和阴影效果

构造函数

GameDataControlTextButton 仅客户端

public GameDataControlTextButton(GameLink<GameDataControl, GameDataControlTextButton> link)

GameDataControlTextButton 仅客户端

public GameDataControlTextButton(IGameLink<GameDataControlTextButton> link)

属性

Text 仅客户端

public string? Text { get; set; }

按钮默认文本内容

Font 仅客户端

public UTF8String? Font { get; set; }

文本字体

FontSize 仅客户端

public int? FontSize { get; set; }

文本字体大小

TextColor 仅客户端

public Color? TextColor { get; set; }

文本颜色

Bold 仅客户端

public bool? Bold { get; set; }

文本是否粗体

Italic 仅客户端

public bool? Italic { get; set; }

文本是否斜体

TextWrap 仅客户端

public bool? TextWrap { get; set; }

文本是否自动换行

LineSpacingRatio 仅客户端

public float? LineSpacingRatio { get; set; }

行间距比例

TextHorizontalAlignment 仅客户端

public HorizontalContentAlignment? TextHorizontalAlignment { get; set; }

文本水平对齐方式

TextVerticalAlignment 仅客户端

public VerticalContentAlignment? TextVerticalAlignment { get; set; }

文本垂直对齐方式

StrokeSize 仅客户端

public int? StrokeSize { get; set; }

文本描边大小

StrokeColor 仅客户端

public Color? StrokeColor { get; set; }

文本描边颜色

ShadowOffset 仅客户端

public Vector2? ShadowOffset { get; set; }

文本阴影偏移

ShadowColor 仅客户端

public Color? ShadowColor { get; set; }

文本阴影颜色

Link 仅客户端

public new IGameLink<GameDataControlTextButton> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateTextButton 仅客户端

public TextButton CreateTextButton()

GameDataControlVideo 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlVideo : GameDataControlCanvas, IGameData<GameDataControlVideo>, IGameData

Data definition for a project-video control. Null fields retain control defaults.

构造函数

GameDataControlVideo 仅客户端

public GameDataControlVideo(GameLink<GameDataControl, GameDataControlVideo> link)

GameDataControlVideo 仅客户端

public GameDataControlVideo(IGameLink<GameDataControlVideo> link)

属性

Source 仅客户端

public string? Source { get; set; }

Video path below the project's res directory. Empty unloads the video.

AutoPlay 仅客户端

public bool? AutoPlay { get; set; }

IsLooping 仅客户端

public bool? IsLooping { get; set; }

IsMuted 仅客户端

public bool? IsMuted { get; set; }

Volume 仅客户端

public float? Volume { get; set; }

PlaybackRate 仅客户端

public float? PlaybackRate { get; set; }

PauseWhenHidden 仅客户端

public bool? PauseWhenHidden { get; set; }

Stretch 仅客户端

public VideoStretch? Stretch { get; set; }

Link 仅客户端

public new IGameLink<GameDataControlVideo> Link { get; }

方法

ApplyTo 仅客户端

public override void ApplyTo(Control control)

CreateControl 仅客户端

public override Control CreateControl()

CreateVideo 仅客户端

public Video CreateVideo()

GameDataControlVirtualizingPanel 仅客户端

命名空间 GameUI.Control.Data

public class GameDataControlVirtualizingPanel : GameDataControlPanelScrollable, IGameData<GameDataControlVirtualizingPanel>, IGameData

虚拟化列表控件的游戏数据类，用于长列表的按需渲染以提升性能。

构造函数

GameDataControlVirtualizingPanel 仅客户端

public GameDataControlVirtualizingPanel(GameLink<GameDataControl, GameDataControlVirtualizingPanel> link)

GameDataControlVirtualizingPanel 仅客户端

public GameDataControlVirtualizingPanel(IGameLink<GameDataControlVirtualizingPanel> link)

属性

CacheLength 仅客户端

public VirtualizationCacheLength? CacheLength { get; set; }

可视区域外的缓存项数量，提前创建/保留控件以减少滚动时的卡顿。

CacheLengthUnit 仅客户端

public VirtualizationCacheLengthUnit? CacheLengthUnit { get; set; }

缓存长度的单位：像素或项数量。

ItemSize 仅客户端

public SizeF? ItemSize { get; set; }

每个列表项的固定尺寸，虚拟化需要已知项大小以计算滚动范围。

ArrangeOnScroll 仅客户端

public bool? ArrangeOnScroll { get; set; }

是否在滚动时重新排列子控件，可改善滚动流畅度。

Link 仅客户端

public new IGameLink<GameDataControlVirtualizingPanel> Link { get; }

方法

CreateControl 仅客户端

public override Control CreateControl()

创建与当前数据定义对应的 VirtualizingPanel 控件。

CreateVirtualizingPanel 仅客户端

public VirtualizingPanel CreateVirtualizingPanel()

创建 VirtualizingPanel 控件的强类型版本。

ApplyTo 仅客户端

public override void ApplyTo(Control control)

GameDataSpacingPanel 仅客户端

命名空间 GameUI.Control.Data

public class GameDataSpacingPanel : GameDataControlPanelScrollable, IGameData<GameDataSpacingPanel>, IGameData

SpacingPanel控件的数据模板类 用于配置带间距管理的Panel控件的属性

构造函数

GameDataSpacingPanel 仅客户端

public GameDataSpacingPanel(GameLink<GameDataControl, GameDataSpacingPanel> link)

GameDataSpacingPanel 仅客户端

public GameDataSpacingPanel(IGameLink<GameDataSpacingPanel> link)

属性

Spacing 仅客户端

public float? Spacing { get; set; }

间距大小（像素）

SpacingOrientation 仅客户端

public Orientation? SpacingOrientation { get; set; }

间距方向

Link 仅客户端

public new IGameLink<GameDataSpacingPanel> Link { get; }

方法

CreateControl 仅客户端

public override Control CreateControl()

创建SpacingPanel控件实例

CreateSpacingPanel 仅客户端

public SpacingPanel CreateSpacingPanel()

创建SpacingPanel控件实例

UIAuthoringGameDataMaterializerRegistry 仅客户端

命名空间 GameUI.Control.Data

public static class UIAuthoringGameDataMaterializerRegistry

Generated-code registration surface for UI Authoring materializers declared by dependent assemblies.

方法

Register 仅客户端

public static void Register<T>(string controlType, Func<GameLink<GameDataControl, T>, JsonObject, T> factory) where T : GameDataControl, IGameData<T>

DeserializeProperty 仅客户端

public static T DeserializeProperty<T>(JsonNode? source, string controlType, string propertyName)

DeserializeUtf8StringProperty 仅客户端

public static UTF8String? DeserializeUtf8StringProperty(JsonNode? source, string controlType, string propertyName)

InvalidProperty 仅客户端

public static Exception InvalidProperty(string controlType, string propertyName)

EasingType 仅客户端

命名空间 GameUI.Control.Data.Enum

public enum EasingType

缓动函数类型枚举

枚举值

• None — 无缓动函数，使用线性插值
• Quadratic — 二次方缓动函数
• Cubic — 三次方缓动函数
• Sine — 正弦缓动函数
• Bounce — 弹跳缓动函数

Event 仅客户端

命名空间 GameUI.Control.Data.Struct

public class Event

构造函数

Event 仅客户端

public Event()

属性

OnPointerClicked 仅客户端

public EventHandler<PointerEventArgs>? OnPointerClicked { get; set; }

OnPointerDoubleClicked 仅客户端

public EventHandler<PointerEventArgs>? OnPointerDoubleClicked { get; set; }

OnPointerEntered 仅客户端

public EventHandler? OnPointerEntered { get; set; }

OnPointerExited 仅客户端

public EventHandler? OnPointerExited { get; set; }

OnPointerPressed 仅客户端

public EventHandler<PointerEventArgs>? OnPointerPressed { get; set; }

OnPointerReleased 仅客户端

public EventHandler<PointerEventArgs>? OnPointerReleased { get; set; }

OnPointerCapturedMove 仅客户端

public EventHandler<PointerCapturedMoveEventArgs>? OnPointerCapturedMove { get; set; }

OnDrag 仅客户端

public EventHandler? OnDrag { get; set; }

OnDrop 仅客户端

public EventHandler<DropEventArgs>? OnDrop { get; set; }

OnSizeChanged 仅客户端

public EventHandler<SizeChangedEventArgs>? OnSizeChanged { get; set; }

方法

ApplyTo 仅客户端

public void ApplyTo(Control control)

InputEvents 仅客户端

命名空间 GameUI.Control.Data.Struct

public class InputEvents

构造函数

InputEvents 仅客户端

public InputEvents()

方法

ApplyTo 仅客户端

public void ApplyTo(Input control)

字段

OnInputTextChanged 仅客户端

public EventHandler<InputEventArgs>? OnInputTextChanged

OnGotFocus 仅客户端

public EventHandler? OnGotFocus

OnLostFocus 仅客户端

public EventHandler? OnLostFocus

OnInputKeyDown 仅客户端

public EventHandler<InputKeyEventArgs>? OnInputKeyDown

OnInputKeyUp 仅客户端

public EventHandler<InputKeyEventArgs>? OnInputKeyUp

Layout 仅客户端

命名空间 GameUI.Control.Data.Struct

public class Layout

表示控件的布局属性集合，可用于批量设置控件的布局相关属性。

构造函数

Layout 仅客户端

public Layout()

属性

Position 仅客户端

public UIPosition? Position { get; set; }

控件的布局位置。

PositionType 仅客户端

public UIPositionType? PositionType { get; set; }

控件的布局定位类型，决定 Position 的含义。

Margin 仅客户端

public Thickness? Margin { get; set; }

控件的外边距。

Padding 仅客户端

public Thickness? Padding { get; set; }

控件的内边距。

Width 仅客户端

public Auto<float>? Width { get; set; }

控件的宽度（支持 Auto）。

备注

若要设置控件宽度为父容器的特定百分比，需将此属性设置为 0， 并同时设置 WidthStretchRatio 为目标百分比值。

Height 仅客户端

public Auto<float>? Height { get; set; }

控件的高度（支持 Auto）。

备注

若要设置控件高度为父容器的特定百分比，需将此属性设置为 0， 并同时设置 HeightStretchRatio 为目标百分比值。

WidthStretchRatio 仅客户端

public float? WidthStretchRatio { get; set; }

控件在父容器中的宽度拉伸比例。0.5 代表占用父容器剩余宽度的 50%，1.0 代表占用 100%。

备注

百分比尺寸设置： 若要将控件宽度设置为父容器宽度的特定百分比，需同时将 Width 设置为 0， 然后设置此属性为目标百分比值。 示例：设置控件宽度为父容器的 50%： Layout = new Layout

HeightStretchRatio 仅客户端

public float? HeightStretchRatio { get; set; }

控件在父容器中的高度拉伸比例。0.5 代表占用父容器剩余高度的 50%，1.0 代表占用 100%。

备注

百分比尺寸设置： 若要将控件高度设置为父容器高度的特定百分比，需同时将 Height 设置为 0， 然后设置此属性为目标百分比值。 示例：设置控件高度为父容器的 50%： Layout = new Layout

WidthCompactRatio 仅客户端

public float? WidthCompactRatio { get; set; }

控件在父容器中的宽度收缩比例。

HeightCompactRatio 仅客户端

public float? HeightCompactRatio { get; set; }

控件在父容器中的高度收缩比例。

FlowOrientation 仅客户端

public Orientation? FlowOrientation { get; set; }

控件的流式布局方向。

HorizontalAlignment 仅客户端

public HorizontalAlignment? HorizontalAlignment { get; set; }

控件的水平对齐方式。

VerticalAlignment 仅客户端

public VerticalAlignment? VerticalAlignment { get; set; }

控件的垂直对齐方式。

HorizontalContentAlignment 仅客户端

public HorizontalContentAlignment? HorizontalContentAlignment { get; set; }

子控件的水平对齐方式。

VerticalContentAlignment 仅客户端

public VerticalContentAlignment? VerticalContentAlignment { get; set; }

子控件的垂直对齐方式。

AspectRatio 仅客户端

public Auto<float>? AspectRatio { get; set; }

控件的宽高比设置，仅在宽或高为 Auto 时生效。

方法

ApplyTo 仅客户端

public void ApplyTo(Control control)

批量应用布局属性到指定控件。

• control — 要应用布局的控件。

PanelScrollableEvents 仅客户端

命名空间 GameUI.Control.Data.Struct

public class PanelScrollableEvents

构造函数

PanelScrollableEvents 仅客户端

public PanelScrollableEvents()

方法

ApplyTo 仅客户端

public void ApplyTo(PanelScrollable panelScrollable)

字段

OnScrollChangedHandler 仅客户端

public EventHandler<ScrollChangedEventArgs>? OnScrollChangedHandler

TemplateOverride 仅客户端

命名空间 GameUI.Control.Data.Struct

public class TemplateOverride

构造函数

TemplateOverride 仅客户端

public TemplateOverride()

属性

ThemeOverride 仅客户端

public ValueKeyDictionary<Theme, IGameLink<GameDataControl>>? ThemeOverride { get; set; }

OrientationOverride 仅客户端

public ValueKeyDictionary<DisplayOrientations, IGameLink<GameDataControl>>? OrientationOverride { get; set; }

Auto 仅客户端

命名空间 GameUI.Control.Enum

public readonly struct Auto<T> : IEquatable<Auto<T>> where T : IEquatable<T>

构造函数

Auto 仅客户端

public Auto(AutoMode mode, T value)

属性

IsAuto 仅客户端

public bool IsAuto { get; }

Mode 仅客户端

public AutoMode Mode { get; init; }

Value 仅客户端

public T? Value { get; init; }

方法

Equals 仅客户端

public override bool Equals(object? obj)

Equals 仅客户端

public bool Equals(Auto<T> other)

operator == 仅客户端

public static bool operator ==(Auto<T> left, Auto<T> right)

operator != 仅客户端

public static bool operator !=(Auto<T> left, Auto<T> right)

operator == 仅客户端

public static bool operator ==(Auto<T> left, T right)

operator != 仅客户端

public static bool operator !=(Auto<T> left, T right)

operator == 仅客户端

public static bool operator ==(T left, Auto<T> right)

operator != 仅客户端

public static bool operator !=(T left, Auto<T> right)

operator == 仅客户端

public static bool operator ==(Auto<T> left, AutoMode right)

operator != 仅客户端

public static bool operator !=(Auto<T> left, AutoMode right)

operator == 仅客户端

public static bool operator ==(AutoMode left, Auto<T> right)

operator != 仅客户端

public static bool operator !=(AutoMode left, Auto<T> right)

implicit operator 仅客户端

public static Auto<T> implicit operator(AutoMode mode)

implicit operator 仅客户端

public static Auto<T> implicit operator(T value)

implicit operator 仅客户端

public static T? implicit operator(Auto<T> auto)

GetHashCode 仅客户端

public override int GetHashCode()

ToString 仅客户端

public override string? ToString()

AutoMode 仅客户端

命名空间 GameUI.Control.Enum

public enum AutoMode

枚举值

• Auto
• Manual

BlendMode 仅客户端

命名空间 GameUI.Control.Enum

public enum BlendMode

定义绘制内容与已有内容的混合模式

备注

混合模式决定了新绘制的内容如何与画布上已有的内容进行混合。 不同的混合模式可以创建各种视觉效果，从简单的覆盖到复杂的颜色混合。 混合模式基于Porter-Duff合成操作和传统的图形混合算法。

枚举值

• SourceOver — 源覆盖模式（默认）
• SourceIn — 源内部模式
• SourceOut — 源外部模式
• SourceAtop — 源顶部模式
• DestinationOver — 目标覆盖模式
• DestinationIn — 目标内部模式
• DestinationOut — 目标外部模式
• DestinationAtop — 目标顶部模式
• Lighten — 变亮模式
• Copy — 复制模式
• Xor — 异或模式

CanvasCoordinateMode 仅客户端

命名空间 GameUI.Control.Enum

public enum CanvasCoordinateMode

Canvas坐标系统模式

备注

坐标系统模式决定了Canvas如何处理绘制坐标和设备像素的映射关系。 不同的坐标模式适用于不同的使用场景： DesignResolution: 适用于一般UI开发，与其他控件保持一致 CanvasResolution: 适用于像素级精确绘制，如图像处理或精密图形 选择合适的坐标模式对于确保在不同设备上的正确显示效果至关重要。

枚举值

• DesignResolution — 使用设计分辨率坐标系统（与框架其他控件一致，AI友好）
• CanvasResolution — 使用Canvas原始分辨率坐标系统，当用户期望实现像素级精确绘制时使用

ETheme 仅客户端

命名空间 GameUI.Control.Enum

public enum ETheme

枚举值

• ProjectEcho
• FuJian

ParticleView 仅客户端

命名空间 GameUI.Control.Enum

public enum ParticleView

粒子特效的视图模式枚举

枚举值

• Legacy — 传统视图模式
• Forward — 前向视图模式
• TopDown — 俯视视图模式
• Left — 左侧视图模式
• Right — 右侧视图模式

ProgressionMode 仅客户端

命名空间 GameUI.Control.Enum

public enum ProgressionMode

枚举值

• RightToLeft
• LeftToRight
• BottomToTop
• TopToBottom
• Clockwise
• CounterClockwise

RoutedEvents 仅客户端

命名空间 GameUI.Control.Enum

public enum RoutedEvents

枚举值

• None = 0
• PointerClicked = 2
• PointerDoubleClicked = 4
• PointerPressed = 8
• PointerReleased = 0x10
• PointerEntered = 0x20
• PointerExited = 0x40
• AllPointerEvents = 0x7E
• Drag = 0x80
• Drop = 0x100
• All = 0x1FE

RoutedEventsExtensions 仅客户端

命名空间 GameUI.Control.Enum

public static class RoutedEventsExtensions

方法

HasAll 仅客户端

public static bool HasAll(this RoutedEvents value, RoutedEvents flag)

HasAny 仅客户端

public static bool HasAny(this RoutedEvents value, RoutedEvents flag)

HasNone 仅客户端

public static bool HasNone(this RoutedEvents value, RoutedEvents flag)

Except 仅客户端

public static RoutedEvents Except(this RoutedEvents value, RoutedEvents except)

Returns a new RoutedEvents value with the specified events removed.

• value — The original RoutedEvents value.
• except — The events to remove from the original value.

返回： A new RoutedEvents value with the specified events removed.

ScrollUnit 仅客户端

命名空间 GameUI.Control.Enum

public enum ScrollUnit

Enumeration that specifies the scrollUnit of the VirtualizingStackPanel. Used by VirtualizingPanel.ScrollUnit.

枚举值

• Pixel
• Item

TextAlign 仅客户端

命名空间 GameUI.Control.Enum

public enum TextAlign

Text alignment flags for Canvas text rendering.

备注

The numeric values are aligned with the underlying NanoVG text align bit flags: Left(1), Center(2), Right(4), Top(8), Middle(16), Bottom(32), Baseline(64).

枚举值

• None = 0
• Left = 1 — Default, align text horizontally to left.
• Center = 2 — Align text horizontally to center.
• Right = 4 — Align text horizontally to right.
• Top = 8 — Align text vertically to top.
• Middle = 0x10 — Align text vertically to center.
• Bottom = 0x20 — Align text vertically to bottom.
• Baseline = 0x40 — Default, align text vertically to baseline.

TextTrimming 仅客户端

命名空间 GameUI.Control.Enum

public enum TextTrimming

枚举值

• None
• Clip
• Ellipsis
• Shrink

Theme 仅客户端

命名空间 GameUI.Control.Enum

public readonly struct Theme : IGameClass, IExtendableEnum<Theme>, IExtendableEnum, IExtendedEnum, ISyncIdOwner

方法

ToString 仅客户端

public override string? ToString()

operator == 仅客户端

public static bool operator ==(Theme left, Theme right)

operator != 仅客户端

public static bool operator !=(Theme left, Theme right)

Equals 仅客户端

public override bool Equals(object? obj)

GetHashCode 仅客户端

public override int GetHashCode()

OnRegisterGameClass 仅客户端

public static void OnRegisterGameClass()

字段

InnerValue 仅客户端

public readonly System.Enum InnerValue

ProjectEcho 仅客户端

public static readonly Theme ProjectEcho

FuJian 仅客户端

public static readonly Theme FuJian

TouchStatus 仅客户端

命名空间 GameUI.Control.Enum

public enum TouchStatus

枚举值

• Started — The touch interaction has started.
• Completed — The touch interaction has completed.
• Canceled — The touch interaction has been canceled.

UpdateSourceTrigger 仅客户端

命名空间 GameUI.Control.Enum

public enum UpdateSourceTrigger

枚举值

• Default
• PropertyChanged
• LostFocus

VideoStretch 仅客户端

命名空间 GameUI.Control.Enum

public enum VideoStretch

How a video frame fits the control's bounds.

枚举值

• Uniform — Preserve aspect ratio and show the complete frame, centered.
• UniformToFill — Preserve aspect ratio, fill the bounds, and crop the centered frame.
• Fill — Fill the bounds without preserving aspect ratio.

VideoViewState 仅客户端

命名空间 GameUI.Control.Enum

public enum VideoViewState

Loading and playback state of a Video control.

枚举值

• Empty
• Loading
• Ready
• Playing
• Paused
• Stopped
• Ended
• Failed

VirtualizationMode 仅客户端

命名空间 GameUI.Control.Enum

public enum VirtualizationMode

Enumeration that specifies the virtualization mode of the VirtualizingPanel. Used by VirtualizingPanel.VirtualizationMode.

枚举值

• Standard — Standard virtualization mode -- containers are thrown away when offscreen.
• Recycling — Recycling virtualization mode -- containers are re-used when offscreen.

WindingMode 仅客户端

命名空间 GameUI.Control.Enum

public enum WindingMode

定义路径填充时使用的缠绕模式

备注

缠绕模式决定了在填充复杂路径（如自相交路径）时，哪些区域应该被填充。 不同的缠绕模式适用于不同的绘制需求： NonZero: 适用于大多数普通形状的填充 EvenOdd: 常用于创建镂空效果或复杂的几何图案

枚举值

• NonZero = 1 — 非零缠绕规则
• EvenOdd — 奇偶缠绕规则

BuilderExtensions 仅客户端

命名空间 GameUI.Control.Extensions

public static class BuilderExtensions

现代化的控件构建扩展，提供直观、一致的API 基于现代UI设计原则，支持AI友好的代码生成

方法

Small 仅客户端

public static T Small<T>(this T control) where T : Control

设置控件为小尺寸预设

备注

对于按钮：高度32px；对于输入框：高度32px，宽度200px

Medium 仅客户端

public static T Medium<T>(this T control) where T : Control

设置控件为中等尺寸预设（默认尺寸）

备注

对于按钮：高度40px；对于输入框：高度40px，宽度280px

Large 仅客户端

public static T Large<T>(this T control) where T : Control

设置控件为大尺寸预设

备注

对于按钮：高度48px；对于输入框：高度48px，宽度360px

XLarge 仅客户端

public static T XLarge<T>(this T control) where T : Control

设置控件为超大尺寸预设

备注

对于按钮：高度56px

Filled 仅客户端

public static T Filled<T>(this T control, ButtonIntent intent = ButtonIntent.Primary) where T : Control, ITextControl

设置按钮为填充样式（实心背景）

• control — 按钮控件
• intent — 语义意图，默认为 Primary

返回： 控件本身，支持链式调用

Outlined 仅客户端

public static Border Outlined<T>(this T control, ButtonIntent intent = ButtonIntent.Primary) where T : Control, ITextControl

设置按钮为轮廓样式（透明背景 + 边框）

• control — 按钮控件
• intent — 语义意图，默认为 Primary

返回： 包装后的Border控件

备注

注意：此方法返回 Border 类型，因为需要包装边框。

Ghost 仅客户端

public static T Ghost<T>(this T control, ButtonIntent intent = ButtonIntent.Primary) where T : Control, ITextControl

设置按钮为幽灵样式（透明背景，无边框）

TextStyle 仅客户端

public static T TextStyle<T>(this T control, ButtonIntent intent = ButtonIntent.Primary) where T : Control, ITextControl

设置按钮为文本样式（仅文字，无背景无边框）

Size 仅客户端

public static T Size<T>(this T control, ControlSize size) where T : Control

设置控件尺寸

• control — 控件
• size — 尺寸枚举

返回： 控件本身，支持链式调用

Data 仅客户端

public static T Data<T>(this T control, object? dataContext) where T : Control

设置控件的数据上下文

Show 仅客户端

public static T Show<T>(this T control) where T : Control

显示控件

Hide 仅客户端

public static T Hide<T>(this T control) where T : Control

隐藏控件

Visibility 仅客户端

public static T Visibility<T>(this T control, bool visible) where T : Control

设置控件可见性

Enable 仅客户端

public static T Enable<T>(this T control) where T : Control

启用控件

Disable 仅客户端

public static T Disable<T>(this T control) where T : Control

禁用控件

Enabled 仅客户端

public static T Enabled<T>(this T control, bool enabled) where T : Control

设置控件启用状态

Text 仅客户端

public static T Text<T>(this T control, string text) where T : Control, ITextControl

设置文本内容

Click 仅客户端

public static T Click<T>(this T control, Action action) where T : Control

设置点击事件

Click 仅客户端

public static T Click<T>(this T control, Action<object?, PointerEventArgs> action) where T : Control

设置点击事件（带参数）

DoubleClick 仅客户端

public static T DoubleClick<T>(this T control, Action action) where T : Control

设置双击事件

MouseEnter 仅客户端

public static T MouseEnter<T>(this T control, Action action) where T : Control

设置鼠标进入事件

MouseLeave 仅客户端

public static T MouseLeave<T>(this T control, Action action) where T : Control

设置鼠标离开事件

Drag 仅客户端

public static T Drag<T>(this T control, Action action) where T : Control

设置拖拽事件

• control — 控件
• action — 拖拽时的回调

返回： 控件本身，支持方法链

备注

注意：此方法只订阅拖拽事件，不会自动启用拖拽。 如需启用拖拽，请配合 Draggable 或 Boolean) 使用。

CapturedMove 仅客户端

public static T CapturedMove<T>(this T control, Action action) where T : Control

设置指针捕获移动事件（用于拖拽时跟踪指针位置）

• control — 控件
• action — 移动时的回调

返回： 控件本身，支持方法链

备注

当控件捕获了指针（如拖拽时）并且指针移动时触发此事件。 配合 Action) 使用可实现拖拽跟踪。

CapturedMove 仅客户端

public static T CapturedMove<T>(this T control, Action<PointerCapturedMoveEventArgs> action) where T : Control

设置指针捕获移动事件（带事件参数）

• control — 控件
• action — 移动时的回调，参数为事件数据

返回： 控件本身，支持方法链

TrackPointer 仅客户端

public static T TrackPointer<T>(this T control, Action<PointerCapturedMoveEventArgs> onMove) where T : Control

启用指针追踪 - 自动在按下时捕获指针，抬起时释放，并订阅移动事件

• control — 控件
• onMove — 指针移动时的回调

返回： 控件本身，支持方法链

备注

此方法封装了指针捕获的完整流程： OnPointerPressed 时自动调用 CapturePointer OnPointerCapturedMove 时触发回调 OnPointerReleased 时自动调用 ReleasePointer // 拖拽移动控件位置 control.TrackPointer(e => { if (e.PointerPosition.HasValue) control.Position = e.PointerPosition.Value; });

TrackPointer 仅客户端

public static T TrackPointer<T>(this T control, Action onMove) where T : Control

启用指针追踪（无参数版本）

• control — 控件
• onMove — 指针移动时的回调

返回： 控件本身，支持方法链

Drop 仅客户端

public static T Drop<T>(this T control, Action<Control?> action) where T : Control

设置放置事件

• control — 控件
• action — 放置时的回调，参数为放置目标控件

返回： 控件本身，支持方法链

Draggable 仅客户端

public static T Draggable<T>(this T control, Action? onDrag = null) where T : Control

启用控件拖拽并设置拖拽事件

• control — 控件
• onDrag — 可选的拖拽回调

返回： 控件本身，支持方法链

备注

此方法会自动设置 AllowDrag = true，并可选地订阅 OnDrag 事件。 var panel = UI.Panel() .Size(100, 100) .Draggable(() => UpdatePosition()) .AddToRoot();

Draggable 仅客户端

public static T Draggable<T>(this T control, bool enabled) where T : Control

设置控件是否可拖拽（用于拖放操作）

• control — 控件
• enabled — 是否启用拖拽

返回： 控件本身，支持方法链

备注

用于动态开关拖拽功能。 // 关闭拖拽 panel.Draggable(false); // 根据条件开关 panel.Draggable(isEditMode);

Droppable 仅客户端

public static T Droppable<T>(this T control, Action<Control?> onDrop) where T : Control

启用控件接收放置并设置放置事件

• control — 控件
• onDrop — 放置时的回调，参数为放置目标控件

返回： 控件本身，支持方法链

备注

此方法会自动设置 AllowDrop = true，并订阅 OnDrop 事件。 var dropZone = UI.Panel() .Size(200, 200) .Droppable(target => HandleDrop(target)) .AddToRoot();

Droppable 仅客户端

public static T Droppable<T>(this T control, bool enabled) where T : Control

设置控件是否可接收放置

• control — 控件
• enabled — 是否启用接收放置

返回： 控件本身，支持方法链

备注

用于动态开关接收放置功能。 // 关闭接收放置 dropZone.Droppable(false); // 根据条件开关 dropZone.Droppable(isEditMode);

Movable 仅客户端

public static T Movable<T>(this T control, Action? onMoved = null) where T : Control

使控件可通过拖拽移动位置

• control — 控件
• onMoved — 可选的位置变化回调

返回： 控件本身，支持方法链

备注

与 Action) 的区别： 方法 用途 Action) 拖拽改变控件自身位置（Position）。控件会跟随鼠标移动。 Action) 拖放操作（Drag & Drop）。控件可被拖拽到其他控件上触发 OnDrop 事件，但控件本身不会移动。 // 创建可移动的面板 var panel = UI.Panel() .Size(100, 100) .TopLeft(50, 50) .Movable() .AddToRoot(); // 带位置变化回调 var panel2 = UI.Panel() .Size(100, 100) .TopLeft(200, 50) .Movable(() => Console.WriteLine($"Moved to: {panel2.Position}")) .AddToRoot();

BlockPointerEvents 仅客户端

public static T BlockPointerEvents<T>(this T control) where T : Control

阻止指针事件穿透到父控件（和 Button 的默认行为一致）

• control — 控件

返回： 控件本身，支持方法链

备注

默认情况下，除 Button 外的控件会将指针事件（点击、按下、释放等）穿透到父控件。 调用此方法后，控件将拦截这些事件，不再向父级传递。 适用场景：对话框、弹窗、菜单、可拖拽控件等需要独占指针事件的控件。 var dialog = UI.Panel() .Size(400, 300) .BlockPointerEvents() // 防止点击穿透到背景 .AddToRoot();

AllowPointerPassthrough 仅客户端

public static T AllowPointerPassthrough<T>(this T control) where T : Control

允许指针事件穿透到父控件（恢复默认行为）

• control — 控件

返回： 控件本身，支持方法链

备注

将控件的 RoutedEvents 恢复为 All，允许所有事件穿透到父控件。 适用场景：装饰性 UI、HUD 叠加层等不需要阻挡交互的控件。

PointerDown 仅客户端

public static T PointerDown<T>(this T control, Action action) where T : Control

设置指针按下事件

• control — 控件
• action — 指针按下时的回调

返回： 控件本身，支持方法链

PointerDown 仅客户端

public static T PointerDown<T>(this T control, Action<PointerEventArgs> action) where T : Control

设置指针按下事件（带事件参数）

• control — 控件
• action — 指针按下时的回调，参数为事件数据

返回： 控件本身，支持方法链

PointerUp 仅客户端

public static T PointerUp<T>(this T control, Action action) where T : Control

设置指针释放事件

• control — 控件
• action — 指针释放时的回调

返回： 控件本身，支持方法链

PointerUp 仅客户端

public static T PointerUp<T>(this T control, Action<PointerEventArgs> action) where T : Control

设置指针释放事件（带事件参数）

• control — 控件
• action — 指针释放时的回调，参数为事件数据

返回： 控件本身，支持方法链

SizeChanged 仅客户端

public static T SizeChanged<T>(this T control, Action action) where T : Control

设置尺寸变化事件

• control — 控件
• action — 尺寸变化时的回调

返回： 控件本身，支持方法链

SizeChanged 仅客户端

public static T SizeChanged<T>(this T control, Action<SizeChangedEventArgs> action) where T : Control

设置尺寸变化事件（带事件参数）

• control — 控件
• action — 尺寸变化时的回调，参数为新旧尺寸

返回： 控件本身，支持方法链

Add 仅客户端

public static T Add<T>(this T control, params Control[] children) where T : Control

添加子控件

Add 仅客户端

public static T Add<T>(this T control, Control child) where T : Control

添加子控件（单个）

Remove 仅客户端

public static T Remove<T>(this T control, Control child) where T : Control

移除子控件

ClearChildren 仅客户端

public static T ClearChildren<T>(this T control) where T : Control

从当前控件移除所有直接子控件。

备注

此方法只移除父子关系和可视树节点，不会调用子控件的 Destroy()，也不会释放子控件、事件或 native control。 只有临时隐藏、换父节点或对象池复用时才使用此方法。若子控件永久不再使用，应遍历子控件并调用 Destroy()。

VScroll 仅客户端

public static PanelScrollable VScroll(this PanelScrollable panel, bool enabled = true)

启用垂直滚动

HScroll 仅客户端

public static PanelScrollable HScroll(this PanelScrollable panel, bool enabled = true)

启用水平滚动

ScrollBar 仅客户端

public static PanelScrollable ScrollBar(this PanelScrollable panel, float size = 8f, Color? color = null)

设置滚动条

ScrollTo 仅客户端

public static PanelScrollable ScrollTo(this PanelScrollable panel, float position)

设置滚动位置（0-1之间）

Scrollable 仅客户端

public static PanelScrollable Scrollable(this PanelScrollable panel, bool enabled = true)

启用滚动

SpineResource 仅客户端

public static Spine SpineResource(this Spine spine, string resource)

设置Spine动画资源路径

• spine — Spine控件
• resource — 动画资源路径

返回： Spine控件本身，支持方法链

SpineAnimation 仅客户端

public static Spine SpineAnimation(this Spine spine, string animation)

设置Spine动画名称

• spine — Spine控件
• animation — 动画名称

返回： Spine控件本身，支持方法链

SpineSkin 仅客户端

public static Spine SpineSkin(this Spine spine, string skin)

设置Spine皮肤名称

• spine — Spine控件
• skin — 皮肤名称

返回： Spine控件本身，支持方法链

SpineLoop 仅客户端

public static Spine SpineLoop(this Spine spine, bool loop = true)

设置Spine动画循环播放

• spine — Spine控件
• loop — 是否循环播放，默认为true

返回： Spine控件本身，支持方法链

Animate 仅客户端

public static T Animate<T>(this T control, AnimationType type, float duration = 0.3f) where T : Control

设置控件动画

FadeIn 仅客户端

public static T FadeIn<T>(this T control, float duration = 0.3f) where T : Control

设置淡入动画

FadeOut 仅客户端

public static T FadeOut<T>(this T control, float duration = 0.3f) where T : Control

设置淡出动画

SlideIn 仅客户端

public static T SlideIn<T>(this T control, float duration = 0.3f) where T : Control

设置滑入动画

SlideOut 仅客户端

public static T SlideOut<T>(this T control, float duration = 0.3f) where T : Control

设置滑出动画

Hover 仅客户端

public static T Hover<T>(this T control, Action<T> onEnter, Action<T> onLeave) where T : Control

设置悬停效果

HoverStyle 仅客户端

public static T HoverStyle<T>(this T control, Color hoverColor, Color normalColor) where T : Control

设置悬停样式

LongPress 仅客户端

public static T LongPress<T>(this T control, Action action, int durationMs = 500, float scaleFactor = 0.95f) where T : Control

设置长按事件（基于 TouchBehavior 实现）

• control — 目标控件。
• action — 长按触发时执行的操作
• durationMs — 长按触发时长（毫秒），默认500ms
• scaleFactor — 按压时的缩放因子，默认0.95

TouchBehavior 仅客户端

public static T TouchBehavior<T>(this T control, float scaleFactor = 0.95f, bool enablePressAnimation = true, bool enableLongPress = true) where T : Control

为控件添加触摸行为，提供按压动画和长按检测功能（流式扩展）

• control — 目标控件。
• scaleFactor — 按压时的缩放因子，默认为0.95（缩放到95%）
• enablePressAnimation — 是否启用按压动画，默认为true
• enableLongPress — 是否启用长按检测，默认为true

返回： 控件本身，支持链式调用

备注

此方法添加触摸反馈效果，包括按压时的缩放动画和长按事件检测。 使用流式语法可以与其他扩展方法链式调用。 var button = UI.Button("点击我") .Size(200, 80) .Background(Colors.Primary) .TouchBehavior(scaleFactor: 0.9f) .Click(() => DoSomething()) .AddToRoot();

TouchBehavior 仅客户端

public static T TouchBehavior<T>(this T control, float scaleFactor, int animationDurationMs, int longPressDurationMs, bool enablePressAnimation = true, bool enableLongPress = true) where T : Control

为控件添加触摸行为，并自定义动画和长按时长（流式扩展）

• control — 目标控件。
• scaleFactor — 按压时的缩放因子
• animationDurationMs — 按压动画时长（毫秒）
• longPressDurationMs — 长按触发时长（毫秒）
• enablePressAnimation — 是否启用按压动画，默认为true
• enableLongPress — 是否启用长按检测，默认为true

返回： 控件本身，支持链式调用

备注

此重载提供对动画时长的精确控制，适合需要自定义交互体验的场景。 var quickButton = UI.Button("快速响应") .TouchBehavior( scaleFactor: 0.97f, animationDurationMs: 80, longPressDurationMs: 300 ) .AddToRoot();

TouchBehavior 仅客户端

public static T TouchBehavior<T>(this T control, Action<TouchBehavior> configure, float scaleFactor = 0.95f, bool enablePressAnimation = true, bool enableLongPress = true) where T : Control

为控件添加触摸行为，并配置长按事件（流式扩展）

• control — 目标控件。
• configure — 配置回调，用于订阅 TouchBehavior 事件（LongPressStarted, LongPressTriggered, LongPressEnded）
• scaleFactor — 按压时的缩放因子，默认为0.95
• enablePressAnimation — 是否启用按压动画，默认为true
• enableLongPress — 是否启用长按检测，默认为true

返回： 控件本身，支持链式调用

备注

此重载允许通过回调函数配置 TouchBehavior 的事件，适合需要处理长按事件的场景。 var menuButton = UI.Button("菜单") .TouchBehavior( configure: tb => { tb.LongPressTriggered += (s, e) => ShowContextMenu(); tb.LongPressStarted += (s, e) => ShowHint(); }, scaleFactor: 0.95f, enableLongPress: true ) .Click(() => QuickAction()) .AddToRoot();

QuickTouch 仅客户端

public static T QuickTouch<T>(this T control) where T : Control

为控件添加快速触摸反馈（轻微缩放，快速动画）- 适用于工具栏按钮等需要快速响应的控件

返回： 控件本身，支持链式调用

备注

预设配置：scaleFactor=0.97（轻微缩放）, animationDuration=80ms（快速动画）, longPressDuration=400ms（快速长按） var toolButton = UI.Button("工具") .Size(60, 60) .QuickTouch() .AddToRoot();

EmphasizedTouch 仅客户端

public static T EmphasizedTouch<T>(this T control) where T : Control

为控件添加强调触摸反馈（明显缩放，适中动画）- 适用于主按钮等需要明显视觉反馈的控件

返回： 控件本身，支持链式调用

备注

预设配置：scaleFactor=0.90（明显缩放）, animationDuration=150ms（适中动画）, longPressDuration=500ms（标准长按） var primaryButton = UI.Button("确认") .Size(300, 60) .EmphasizedTouch() .AddToRoot();

GentleTouch 仅客户端

public static T GentleTouch<T>(this T control) where T : Control

为控件添加轻柔触摸反馈（极轻微缩放，快速动画）- 适用于列表项等需要轻微反馈的控件

返回： 控件本身，支持链式调用

备注

预设配置：scaleFactor=0.98（极轻微缩放）, animationDuration=120ms（快速动画）, longPressDuration=600ms（适中长按） var listItem = UI.Panel() .Size(400, 60) .GentleTouch() .AddToRoot();

BindValue 仅客户端

public static T BindValue<T, TValue>(this T control, Func<TValue> getter, Action<TValue, T> updater) where T : Control

绑定值到控件（响应式绑定）

• control — 控件
• getter — 获取当前值的函数
• updater — 更新控件的函数，接收值和控件

返回： 控件本身，支持链式调用

备注

此方法创建一个绑定，首次调用时会立即执行 updater。 后续可通过 Refresh``1(``0) 方法手动刷新。 var scoreLabel = UI.Label() .BindValue(() => player.Score, (score, label) => label.Text($"得分: {score}")) .AddToRoot(); // 当 player.Score 变化时，调用 Refresh 更新 scoreLabel.Refresh();

BindText 仅客户端

public static T BindText<T>(this T control, Func<string> getter) where T : Control, ITextControl

绑定文本值到控件

• control — 控件
• getter — 获取文本的函数

返回： 控件本身，支持链式调用

备注

简化的文本绑定，自动将值设置为控件的 Text 属性。 var nameLabel = UI.Label() .BindText(() => $"玩家: {player.Name}") .AddToRoot();

BindVisible 仅客户端

public static T BindVisible<T>(this T control, Func<bool> getter) where T : Control

绑定可见性到控件

• control — 控件
• getter — 获取可见性的函数

返回： 控件本身，支持链式调用

BindEnabled 仅客户端

public static T BindEnabled<T>(this T control, Func<bool> getter) where T : Control

绑定启用状态到控件

• control — 控件
• getter — 获取启用状态的函数

返回： 控件本身，支持链式调用

Refresh 仅客户端

public static T Refresh<T>(this T control) where T : Control

刷新控件的所有绑定

• control — 控件

返回： 控件本身，支持链式调用

备注

调用此方法会重新执行所有通过 BindValue 创建的绑定。 // 数据变化后刷新UI player.Score += 100; scoreLabel.Refresh();

Bind 仅客户端

public static T Bind<T>(this T control, string propertyName, object dataSource) where T : Control

设置数据绑定（占位符，保持向后兼容）

ApplyTemplate 仅客户端

public static T ApplyTemplate<T>(this T control, IGameLink<GameDataControl> template) where T : Control

应用数据模板到控件（支持链式调用）

• control — 目标控件
• template — 要应用的模板链接

返回： 控件本身，支持链式调用

备注

此方法将数据驱动模板的属性应用到控件上，同时保持类型信息以支持链式调用。 var button = UI.Button("确定") .ApplyTemplate(Control.MyButtonStyle) .Click(() => Submit()) .AddToRoot();

ApplyTemplate 仅客户端

public static T ApplyTemplate<T>(this T control, GameDataControl template) where T : Control

应用数据模板到控件（支持链式调用）

• control — 目标控件
• template — 要应用的模板数据

返回： 控件本身，支持链式调用

ApplyStyle 仅客户端

public static T ApplyStyle<T>(this T control, Action<T> template) where T : Control

应用配置函数模板到控件（支持链式调用）

• control — 目标控件
• template — 配置函数模板

返回： 控件本身，支持链式调用

备注

配置函数模板是一种轻量级模板方式，适合定义可复用的样式配置。 // 定义模板 Action<TextButton> PrimaryButtonTemplate = btn => btn .Height(48) .Background(DesignColors.Primary) .TextColor(DesignColors.OnPrimary) .CornerRadius(8); // 使用模板 var btn1 = UI.Button("确定").ApplyStyle(PrimaryButtonTemplate); var btn2 = UI.Button("提交").ApplyStyle(PrimaryButtonTemplate);

ApplyStyles 仅客户端

public static T ApplyStyles<T>(this T control, params Action<T>[] templates) where T : Control

应用多个配置函数模板到控件（模板组合）

• control — 目标控件
• templates — 配置函数模板数组

返回： 控件本身，支持链式调用

备注

允许组合多个模板，后面的模板会覆盖前面模板的相同属性。 // 定义基础模板 Action<Control> BaseCard = c => c.Padding(16).CornerRadius(8); Action<Control> Elevated = c => c.Background(DesignColors.Surface); Action<Control> Clickable = c => c.StandardTouch(); // 组合使用 var card = UI.Panel() .ApplyStyles(BaseCard, Elevated, Clickable) .Add(content);

AddToRoot 仅客户端

public static T AddToRoot<T>(this T control) where T : Control

将控件添加到可视化树根节点

AddToParent 仅客户端

public static T AddToParent<T>(this T control, Control parent) where T : Control

将控件添加到父控件

RemoveFromParent 仅客户端

public static T RemoveFromParent<T>(this T control) where T : Control

从父控件中移除控件。

备注

此扩展方法等价于从父控件调用 Control)：只移除父子关系和可视树节点，不会调用 Destroy()。 控件永久不再使用时应调用 Destroy()；只有临时隐藏、换父节点或对象池复用时才调用此方法。

字段

CardStyle 仅客户端

public static readonly Action<Control> CardStyle

卡片样式模板 - 带圆角和内边距的容器

ElevatedCardStyle 仅客户端

public static readonly Action<Control> ElevatedCardStyle

高亮卡片样式模板 - 带背景色的卡片

ListItemStyle 仅客户端

public static readonly Action<Control> ListItemStyle

列表项样式模板

ToolbarButtonStyle 仅客户端

public static readonly Action<Control> ToolbarButtonStyle

工具栏按钮样式模板

InputFieldStyle 仅客户端

public static readonly Action<Control> InputFieldStyle

输入框样式模板

DialogStyle 仅客户端

public static readonly Action<Control> DialogStyle

对话框样式模板

BadgeStyle 仅客户端

public static readonly Action<Control> BadgeStyle

徽章样式模板

CanvasTextStyleExtensions 仅客户端

命名空间 GameUI.Control.Extensions

public static class CanvasTextStyleExtensions

Canvas 文本样式的流式扩展。

备注

接收方为可空 Canvas？并以 NotNullIfNotNullAttribute 标注返回值： 入参非空则返回非空、可继续链式调用且不触发可空告警；入参为 null 则静默跳过（null-conditional 风格）。 这样在持有可空 Canvas?（如每帧渲染回调里）直接 canvas.FontSize(20).TextAlign(...) 不会冒出 CS8604/CS8602——扩展方法调用此前不传播非空流，是这些 fluent 扩展易踩的坑。 注意：Canvas 的实例属性/方法（如 FillPaint、FillRectangle）仍要求非空接收，持有可空 Canvas 时建议先取非空局部。

方法

FontSize 仅客户端

public static Canvas? FontSize(this Canvas? canvas, float size)

FontBlur 仅客户端

public static Canvas? FontBlur(this Canvas? canvas, float blur)

LetterSpacing 仅客户端

public static Canvas? LetterSpacing(this Canvas? canvas, float spacing)

LineHeight 仅客户端

public static Canvas? LineHeight(this Canvas? canvas, float lineHeight)

TextAlign 仅客户端

public static Canvas? TextAlign(this Canvas? canvas, TextAlign align)

设置文本对齐方式（推荐使用枚举版本）

• canvas — Canvas对象
• align — 文本对齐枚举，可组合水平和垂直对齐

返回： Canvas对象，支持链式调用

Colors 仅客户端

命名空间 GameUI.Control.Extensions

public static class Colors

设计系统颜色常量

字段

Primary 仅客户端

public static readonly Color Primary

Secondary 仅客户端

public static readonly Color Secondary

Tertiary 仅客户端

public static readonly Color Tertiary

Surface 仅客户端

public static readonly Color Surface

SurfaceContainer 仅客户端

public static readonly Color SurfaceContainer

SurfaceContainerHigh 仅客户端

public static readonly Color SurfaceContainerHigh

SurfaceContainerHighest 仅客户端

public static readonly Color SurfaceContainerHighest

SurfaceContainerLow 仅客户端

public static readonly Color SurfaceContainerLow

SurfaceContainerLowest 仅客户端

public static readonly Color SurfaceContainerLowest

SurfaceVariant 仅客户端

public static readonly Color SurfaceVariant

Background 仅客户端

public static readonly Color Background

OnPrimary 仅客户端

public static readonly Color OnPrimary

OnSecondary 仅客户端

public static readonly Color OnSecondary

OnSurface 仅客户端

public static readonly Color OnSurface

OnBackground 仅客户端

public static readonly Color OnBackground

OnSurfaceVariant 仅客户端

public static readonly Color OnSurfaceVariant

Success 仅客户端

public static readonly Color Success

Warning 仅客户端

public static readonly Color Warning

Error 仅客户端

public static readonly Color Error

Info 仅客户端

public static readonly Color Info

OnSuccess 仅客户端

public static readonly Color OnSuccess

OnWarning 仅客户端

public static readonly Color OnWarning

OnError 仅客户端

public static readonly Color OnError

OnInfo 仅客户端

public static readonly Color OnInfo

Outline 仅客户端

public static readonly Color Outline

OutlineVariant 仅客户端

public static readonly Color OutlineVariant

ITextControl 仅客户端

命名空间 GameUI.Control.Extensions

public interface ITextControl

文本控件的统一接口

属性

Text 仅客户端

public string? Text { get; set; }

TextColor 仅客户端

public Color TextColor { get; set; }

FontSize 仅客户端

public float FontSize { get; set; }

Bold 仅客户端

public bool Bold { get; set; }

Italic 仅客户端

public bool Italic { get; set; }

LayoutExtensions 仅客户端

命名空间 GameUI.Control.Extensions

public static class LayoutExtensions

现代化的布局扩展方法，提供直观、一致的API 基于现代UI设计原则，支持AI友好的代码生成

方法

Size 仅客户端

public static T Size<T>(this T control, float width, float height) where T : Control

设置控件的宽度和高度

Width 仅客户端

public static T Width<T>(this T control, float width) where T : Control

设置控件宽度

Height 仅客户端

public static T Height<T>(this T control, float height) where T : Control

设置控件高度

Square 仅客户端

public static T Square<T>(this T control, float size) where T : Control

设置控件为正方形

AutoWidth 仅客户端

public static T AutoWidth<T>(this T control) where T : Control

设置控件宽度为自动（根据内容自适应）

AutoHeight 仅客户端

public static T AutoHeight<T>(this T control) where T : Control

设置控件高度为自动（根据内容自适应）

AutoSize 仅客户端

public static T AutoSize<T>(this T control) where T : Control

设置控件宽度和高度都为自动（根据内容自适应）

Padding 仅客户端

public static T Padding<T>(this T control, float padding) where T : Control

设置内边距 - 统一值

Padding 仅客户端

public static T Padding<T>(this T control, float horizontal, float vertical) where T : Control

设置内边距 - 水平和垂直

Padding 仅客户端

public static T Padding<T>(this T control, float left, float top, float right, float bottom) where T : Control

设置内边距 - 四个方向

DesignPadding 仅客户端

public static T DesignPadding<T>(this T control, float multiplier = 1f) where T : Control

设置内边距 - 使用设计系统值

Margin 仅客户端

public static T Margin<T>(this T control, float margin) where T : Control

设置外边距 - 统一值

Margin 仅客户端

public static T Margin<T>(this T control, float horizontal, float vertical) where T : Control

设置外边距 - 水平和垂直

Margin 仅客户端

public static T Margin<T>(this T control, float left, float top, float right, float bottom) where T : Control

设置外边距 - 四个方向

DesignMargin 仅客户端

public static T DesignMargin<T>(this T control, float multiplier = 1f) where T : Control

设置外边距 - 使用设计系统值

AlignHorizontal 仅客户端

public static T AlignHorizontal<T>(this T control, HorizontalAlignment alignment) where T : Control

设置水平对齐

AlignVertical 仅客户端

public static T AlignVertical<T>(this T control, VerticalAlignment alignment) where T : Control

设置垂直对齐

Center 仅客户端

public static T Center<T>(this T control) where T : Control

设置居中对齐

AlignLeft 仅客户端

public static T AlignLeft<T>(this T control) where T : Control

设置左对齐

AlignRight 仅客户端

public static T AlignRight<T>(this T control) where T : Control

设置右对齐

AlignTop 仅客户端

public static T AlignTop<T>(this T control) where T : Control

设置顶部对齐

AlignBottom 仅客户端

public static T AlignBottom<T>(this T control) where T : Control

设置底部对齐

StretchHorizontal 仅客户端

public static T StretchHorizontal<T>(this T control) where T : Control

设置水平拉伸

StretchVertical 仅客户端

public static T StretchVertical<T>(this T control) where T : Control

设置垂直拉伸

Stretch 仅客户端

public static T Stretch<T>(this T control) where T : Control

设置完全拉伸

CenterHorizontal 仅客户端

public static T CenterHorizontal<T>(this T control) where T : Control

设置水平居中对齐

CenterVertical 仅客户端

public static T CenterVertical<T>(this T control) where T : Control

设置垂直居中对齐

Background 仅客户端

public static T Background<T>(this T control, Color color) where T : Control

设置背景色

Background 仅客户端

public static T Background<T>(this T control, SolidColorBrush color) where T : Control

设置背景色

Background 仅客户端

public static T Background<T>(this T control, ColorBrush color) where T : Control

设置背景色

Border 仅客户端

public static Border Border<T>(this T control, float thickness, Color? color = null) where T : Control

设置边框（通过Border控件包装实现）

• control — 控件
• thickness — 边框粗细
• color — 边框颜色，默认为DesignColors.Outline

返回： 包装后的Border控件

Border 仅客户端

public static Border Border<T>(this T control, float thickness, ColorBrush color) where T : Control

设置边框（通过Border控件包装实现）

• control — 控件
• thickness — 边框粗细
• color — 边框颜色

返回： 包装后的Border控件

Border 仅客户端

public static Border Border<T>(this T control, Thickness thickness, Color? color = null) where T : Control

设置边框（使用Thickness，通过Border控件包装实现）

• control — 控件
• thickness — 边框粗细（四边可不同）
• color — 边框颜色，默认为DesignColors.Outline

返回： 包装后的Border控件

Border 仅客户端

public static Border Border<T>(this T control, Thickness thickness, ColorBrush color) where T : Control

设置边框（使用Thickness，通过Border控件包装实现）

• control — 控件
• thickness — 边框粗细（四边可不同）
• color — 边框颜色

返回： 包装后的Border控件

TextWrap 仅客户端

public static T TextWrap<T>(this T control, bool wrap = true) where T : Control

设置文本换行

• control — 控件
• wrap — 是否换行

返回： 控件本身，支持方法链

TextTrimming 仅客户端

public static T TextTrimming<T>(this T control, TextTrimming trimming) where T : Control

设置文本修剪方式

• control — 控件
• trimming — 修剪方式

返回： 控件本身，支持方法链

ZIndex 仅客户端

public static T ZIndex<T>(this T control, int zIndex) where T : Control

设置Z轴层级

Opacity 仅客户端

public static T Opacity<T>(this T control, float opacity) where T : Control

设置透明度

• control — 控件
• opacity — 透明度值，范围为0.0到1.0，默认为1.0（完全不透明）

返回： 控件本身，支持方法链

Position 仅客户端

public static T Position<T>(this T control, float x, float y) where T : Control

设置控件在当前定位模式下的位置。

备注

此方法保留当前 PositionType。需要父容器左上角绝对坐标时使用 Single)；需要相对排版位置的偏移时使用 Single)。

Position 仅客户端

public static T Position<T>(this T control, UIPosition position) where T : Control

设置控件在当前定位模式下的位置。

备注

此方法不会修改 PositionType。

AbsolutePosition 仅客户端

public static T AbsolutePosition<T>(this T control, float left, float top) where T : Control

使用父容器左上角坐标设置控件的绝对位置。

AbsolutePosition 仅客户端

public static T AbsolutePosition<T>(this T control, UIPosition position) where T : Control

使用父容器左上角坐标设置控件的绝对位置。

RelativeOffset 仅客户端

public static T RelativeOffset<T>(this T control, float x, float y) where T : Control

相对控件正常排版后的位置设置偏移。

RelativeOffset 仅客户端

public static T RelativeOffset<T>(this T control, UIPosition offset) where T : Control

相对控件正常排版后的位置设置偏移。

WidthGrow 仅客户端

public static T WidthGrow<T>(this T control, float ratio) where T : Control

设置宽度拉伸比例

• control — 控件
• ratio — 拉伸比例，范围为0.0到1.0，代表占据父容器剩余宽度的百分比

返回： 控件本身，支持方法链

备注

注意，这只会在父容器有足够剩余空间时生效。如果当前容器已经超过了指定宽度，则不会生效。 如果只想设置百分比宽度，请使用 Single) 方法。

HeightGrow 仅客户端

public static T HeightGrow<T>(this T control, float ratio) where T : Control

设置高度拉伸比例

• control — 控件
• ratio — 拉伸比例，范围为0.0到1.0，代表占据父容器剩余高度的百分比

返回： 控件本身，支持方法链

备注

注意，这只会在父容器有足够剩余空间时生效。如果当前容器已经超过了指定高度，则不会生效。 如果只想设置百分比高度，请使用 Single) 方法。

GrowRatio 仅客户端

public static T GrowRatio<T>(this T control, float widthRatio, float heightRatio) where T : Control

设置拉伸比例（宽度和高度）

• control — 控件
• widthRatio — 宽度拉伸比例，范围为0.0到1.0，代表占据父容器剩余宽度的百分比
• heightRatio — 高度拉伸比例，范围为0.0到1.0，代表占据父容器剩余高度的百分比

返回： 控件本身，支持方法链

备注

注意，这只会在父容器有足够剩余空间时生效。如果当前容器已经超过了指定宽度或高度，则不会生效。 特别注意的是，如果当前容器没有设置过固定长宽，那么其隐含宽度/高度会随着子控件而扩展，并可能超出这里指定的的拉伸比例。 如果只想明确地设置百分比宽度或高度，请使用 Single) 方法。

WidthPercent 仅客户端

public static T WidthPercent<T>(this T control, float ratio) where T : Control

设置控件宽度为父容器宽度的指定百分比

• control — 控件
• ratio — 百分比，范围为0.0到1.0。例如：0.5表示占父容器宽度的50%

返回： 控件本身，支持方法链

备注

此方法会同时设置 Width = 0 和 WidthStretchRatio = ratio， 是设置百分比宽度的推荐方式。

SizePercent 仅客户端

public static T SizePercent<T>(this T control, float widthRatio, float heightRatio) where T : Control

设置控件宽度和高度为父容器的指定百分比

• control — 控件
• widthRatio — 宽度百分比，范围为0.0到1.0。例如：0.5表示占父容器宽度的50%
• heightRatio — 高度百分比，范围为0.0到1.0。例如：0.5表示占父容器高度的50%

返回： 控件本身，支持方法链

备注

此方法会同时设置 Width = 0 和 Height = 0 以及对应的拉伸比例， 是设置百分比尺寸的推荐方式。

HeightPercent 仅客户端

public static T HeightPercent<T>(this T control, float ratio) where T : Control

设置控件高度为父容器高度的指定百分比

• control — 控件
• ratio — 百分比，范围为0.0到1.0。例如：0.5表示占父容器高度的50%

返回： 控件本身，支持方法链

备注

此方法会同时设置 Height = 0 和 HeightStretchRatio = ratio， 是设置百分比高度的推荐方式。

WidthShrink 仅客户端

public static T WidthShrink<T>(this T control, float ratio) where T : Control

设置宽度收缩比例

• control — 控件
• ratio — 收缩比例，范围为0.0到1.0，代表占据父容器剩余宽度的百分比

返回： 控件本身，支持方法链

HeightShrink 仅客户端

public static T HeightShrink<T>(this T control, float ratio) where T : Control

设置高度收缩比例

• control — 控件
• ratio — 收缩比例，范围为0.0到1.0，代表占据父容器剩余高度的百分比

返回： 控件本身，支持方法链

ShrinkRatio 仅客户端

public static T ShrinkRatio<T>(this T control, float widthRatio, float heightRatio) where T : Control

设置收缩比例（宽度和高度）

• control — 控件
• widthRatio — 宽度收缩比例，范围为0.0到1.0，代表占据父容器剩余宽度的百分比
• heightRatio — 高度收缩比例，范围为0.0到1.0，代表占据父容器剩余高度的百分比

返回： 控件本身，支持方法链

FullScreen 仅客户端

public static T FullScreen<T>(this T control) where T : Control

设置控件为全屏模式（填满整个屏幕）

• control — 目标控件

返回： 控件本身，支持方法链

备注

此方法设置控件的增长比例和收缩比例为 1.0，使其占满视口的全部空间。 ⚠️ 注意：此方法会检查控件的父级。如果控件存在父级，且父级并非视觉树根节点， 将输出警告日志，因为 FullScreen 通常仅对根级控件有意义。 如果需要让控件填满任意父容器而不进行检查，请使用 FillParent``1(``0) 方法。

FillParent 仅客户端

public static T FillParent<T>(this T control) where T : Control

设置控件填满其父容器

• control — 目标控件

返回： 控件本身，支持方法链

备注

此方法设置控件的增长比例和收缩比例为 1.0，使其占满父容器的全部空间。 与 FullScreen``1(``0) 不同，此方法不会检查父级类型，适用于任何需要填满父容器的场景。 常见使用场景：

• 在嵌套容器中填满空间
• 在弹出框或对话框中填充内容区域
• 在布局面板中创建可伸缩的区域

FlexBasisWidth 仅客户端

public static T FlexBasisWidth<T>(this T control, float basis) where T : Control

设置Flex基础尺寸（宽度）

FlexBasisHeight 仅客户端

public static T FlexBasisHeight<T>(this T control, float basis) where T : Control

设置Flex基础尺寸（高度）

FlexBasis 仅客户端

public static T FlexBasis<T>(this T control, float widthBasis, float heightBasis) where T : Control

设置Flex基础尺寸（宽度和高度）

MinWidth 仅客户端

public static T MinWidth<T>(this T control, float minWidth) where T : Control

设置最小宽度

MinHeight 仅客户端

public static T MinHeight<T>(this T control, float minHeight) where T : Control

设置最小高度

CornerRadius 仅客户端

public static T CornerRadius<T>(this T control, float radius) where T : Control

设置圆角半径

DesignRadius 仅客户端

public static T DesignRadius<T>(this T control, float multiplier = 1f) where T : Control

设置圆角半径 - 使用设计系统值

FontSize 仅客户端

public static T FontSize<T>(this T control, float size) where T : Control, ITextControl

设置字体大小

FontStrokeSize 仅客户端

public static T FontStrokeSize<T>(this T control, float size) where T : Label

TextColor 仅客户端

public static T TextColor<T>(this T control, Color color) where T : Control, ITextControl

设置文字颜色

Bold 仅客户端

public static T Bold<T>(this T control) where T : Control, ITextControl

设置粗体

Italic 仅客户端

public static T Italic<T>(this T control) where T : Control, ITextControl

设置斜体

ResponsiveFontSize 仅客户端

public static T ResponsiveFontSize<T>(this T control, float multiplier = 1f) where T : Control, ITextControl

设置响应式字体大小

VStack 仅客户端

public static SpacingPanel VStack(float spacing = 0f, params Control[] children)

创建垂直堆叠布局

HStack 仅客户端

public static SpacingPanel HStack(float spacing = 0f, params Control[] children)

创建水平堆叠布局

Grid 仅客户端

public static SpacingPanel Grid(float rowSpacing = 0f, float columnSpacing = 0f, params Control[] children)

创建网格布局

FlowVertical 仅客户端

public static T FlowVertical<T>(this T control) where T : Control

设置控件为垂直流式布局

• control — 目标控件

返回： 控件本身，支持链式调用

FlowHorizontal 仅客户端

public static T FlowHorizontal<T>(this T control) where T : Control

设置控件为水平流式布局

• control — 目标控件

返回： 控件本身，支持链式调用

TrueGrid 仅客户端

public static SpacingPanel TrueGrid(int columns, float rowSpacing = 0f, float columnSpacing = 0f, params Control[] children)

创建真正的网格布局 - 支持多列布局

SimpleGrid 仅客户端

public static SpacingPanel SimpleGrid(float spacing, params Control[] children)

创建简单网格布局 - 自动计算列数

ResponsiveWidth 仅客户端

public static T ResponsiveWidth<T>(this T control, float minWidth, float maxWidth) where T : Control

设置响应式宽度 - 基于屏幕尺寸和断点系统

ResponsiveHeight 仅客户端

public static T ResponsiveHeight<T>(this T control, float minHeight, float maxHeight) where T : Control

设置响应式高度 - 基于屏幕尺寸和断点系统

ResponsiveSize 仅客户端

public static T ResponsiveSize<T>(this T control, float minWidth, float maxWidth, float minHeight, float maxHeight) where T : Control

设置响应式尺寸 - 基于屏幕尺寸和断点系统

ResponsiveFontSize 仅客户端

public static T ResponsiveFontSize<T>(this T control, float minSize, float maxSize, float multiplier = 1f) where T : Control, ITextControl

设置响应式字体大小 - 基于屏幕尺寸和断点系统

ResponsiveSpacing 仅客户端

public static T ResponsiveSpacing<T>(this T control, float minSpacing, float maxSpacing, float multiplier = 1f) where T : Control

设置响应式间距 - 基于屏幕尺寸和断点系统

ResponsivePadding 仅客户端

public static T ResponsivePadding<T>(this T control, float minPadding, float maxPadding, float multiplier = 1f) where T : Control

设置响应式内边距 - 基于屏幕尺寸和断点系统

ResponsiveRadius 仅客户端

public static T ResponsiveRadius<T>(this T control, float minRadius, float maxRadius, float multiplier = 1f) where T : Control

设置响应式圆角半径 - 基于屏幕尺寸和断点系统

ResponsiveContainer 仅客户端

public static T ResponsiveContainer<T>(this T control, ResponsiveContainerSize size) where T : Control

设置响应式容器宽度 - 基于断点系统

ResponsiveButton 仅客户端

public static T ResponsiveButton<T>(this T control, ResponsiveButtonSize size) where T : Control, ITextControl

设置响应式按钮尺寸 - 基于断点系统

ResponsiveInput 仅客户端

public static T ResponsiveInput<T>(this T control, ResponsiveInputSize size) where T : Control, ITextControl

设置响应式输入框尺寸 - 基于断点系统

ResponsiveGrid 仅客户端

public static SpacingPanel ResponsiveGrid(params Control[] children)

创建响应式网格布局 - 基于断点系统自动计算列数

ResponsiveOrientation 仅客户端

public static T ResponsiveOrientation<T>(this T control, Orientation landscapeOrientation, Orientation portraitOrientation) where T : Control

设置响应式布局方向 - 基于屏幕方向

ResponsiveVisibility 仅客户端

public static T ResponsiveVisibility<T>(this T control, ResponsiveVisibility visibility) where T : Control

设置响应式可见性 - 基于断点系统

Card 仅客户端

public static T Card<T>(this T control, float padding = 16f, float radius = 8f, int elevation = 2) where T : Control

创建卡片组件

Button 仅客户端

public static T Button<T>(this T control, float height = 40f, float padding = 16f, float radius = 4f) where T : Control, ITextControl

创建按钮样式

Input 仅客户端

public static T Input<T>(this T control, float height = 40f, float width = 280f, float padding = 16f, float radius = 4f) where T : Control, ITextControl

创建输入框样式

ListItem 仅客户端

public static T ListItem<T>(this T control, float height = 48f, float padding = 16f) where T : Control

创建列表项样式

Title 仅客户端

public static T Title<T>(this T control, float fontSize = 24f, float margin = 16f) where T : Control, ITextControl

创建标题样式

Subtitle 仅客户端

public static T Subtitle<T>(this T control, float fontSize = 18f, float margin = 12f) where T : Control, ITextControl

创建副标题样式

Body 仅客户端

public static T Body<T>(this T control, float fontSize = 16f, float margin = 8f) where T : Control, ITextControl

创建正文样式

Caption 仅客户端

public static T Caption<T>(this T control, float fontSize = 12f, float margin = 4f) where T : Control, ITextControl

创建说明文字样式

Label 仅客户端

public static T Label<T>(this T control, float fontSize = 16f, float margin = 8f) where T : Control, ITextControl

创建标签样式 - 透明背景

SpacingTop 仅客户端

public static T SpacingTop<T>(this T control, float spacing) where T : Control

添加上边距

SpacingBottom 仅客户端

public static T SpacingBottom<T>(this T control, float spacing) where T : Control

添加下边距

SpacingLeft 仅客户端

public static T SpacingLeft<T>(this T control, float spacing) where T : Control

添加左边距

SpacingRight 仅客户端

public static T SpacingRight<T>(this T control, float spacing) where T : Control

添加右边距

SpacingVertical 仅客户端

public static T SpacingVertical<T>(this T control, float spacing) where T : Control

添加垂直间距

SpacingHorizontal 仅客户端

public static T SpacingHorizontal<T>(this T control, float spacing) where T : Control

添加水平间距

ContentAlignHorizontal 仅客户端

public static T ContentAlignHorizontal<T>(this T control, HorizontalContentAlignment alignment) where T : Control

设置子元素水平内容对齐方式

• control — 控件
• alignment — 水平内容对齐方式

返回： 控件本身，支持方法链

ContentAlignVertical 仅客户端

public static T ContentAlignVertical<T>(this T control, VerticalContentAlignment alignment) where T : Control

设置子元素垂直内容对齐方式

• control — 控件
• alignment — 垂直内容对齐方式

返回： 控件本身，支持方法链

ContentCenter 仅客户端

public static T ContentCenter<T>(this T control) where T : Control

设置子元素居中对齐（内容对齐）

• control — 控件

返回： 控件本身，支持方法链

JustifySpaceBetween 仅客户端

public static T JustifySpaceBetween<T>(this T control) where T : Control

主轴方向均匀分布 - 等同于CSS justify-content: space-between

• control — 控件

返回： 控件本身，支持方法链

备注

根据FlowOrientation自动选择对齐轴：

• 水平流式布局时：控制水平分布
• 垂直流式布局时：控制垂直分布 子元素之间均匀分布，首末元素贴边，中间元素等间距分布。

JustifySpaceAround 仅客户端

public static T JustifySpaceAround<T>(this T control) where T : Control

主轴方向均匀分布（含边距） - 等同于CSS justify-content: space-around

• control — 控件

返回： 控件本身，支持方法链

备注

根据FlowOrientation自动选择对齐轴：

• 水平流式布局时：控制水平分布
• 垂直流式布局时：控制垂直分布 子元素周围都有相等的空间，包括首末元素。

AlignSpaceBetween 仅客户端

public static T AlignSpaceBetween<T>(this T control) where T : Control

交叉轴方向均匀分布 - 等同于CSS align-content: space-between

• control — 控件

返回： 控件本身，支持方法链

备注

根据FlowOrientation自动选择对齐轴：

• 水平流式布局时：控制垂直分布（交叉轴）
• 垂直流式布局时：控制水平分布（交叉轴） 子元素之间均匀分布，首末元素贴边，中间元素等间距分布。

AlignSpaceAround 仅客户端

public static T AlignSpaceAround<T>(this T control) where T : Control

交叉轴方向均匀分布（含边距） - 等同于CSS align-content: space-around

• control — 控件

返回： 控件本身，支持方法链

备注

根据FlowOrientation自动选择对齐轴：

• 水平流式布局时：控制垂直分布（交叉轴）
• 垂直流式布局时：控制水平分布（交叉轴） 子元素周围都有相等的空间，包括首末元素。

JustifyStretch 仅客户端

public static T JustifyStretch<T>(this T control) where T : Control

主轴方向拉伸填充 - 等同于CSS justify-content: stretch

• control — 控件

返回： 控件本身，支持方法链

备注

根据FlowOrientation自动选择对齐轴：

• 水平流式布局时：子元素在水平方向拉伸填充
• 垂直流式布局时：子元素在垂直方向拉伸填充

AlignStretch 仅客户端

public static T AlignStretch<T>(this T control) where T : Control

交叉轴方向拉伸填充 - 等同于CSS align-content: stretch

• control — 控件

返回： 控件本身，支持方法链

备注

根据FlowOrientation自动选择对齐轴：

• 水平流式布局时：子元素在垂直方向拉伸填充（交叉轴）
• 垂直流式布局时：子元素在水平方向拉伸填充（交叉轴）

JustifyHorizontalSpaceBetween 仅客户端

public static T JustifyHorizontalSpaceBetween<T>(this T control) where T : Control

水平方向均匀分布 - 显式指定水平轴

• control — 控件

返回： 控件本身，支持方法链

备注

明确设置水平内容对齐为UniformSpacing，不依赖FlowOrientation。 适用于需要明确控制水平分布的场景。

JustifyVerticalSpaceBetween 仅客户端

public static T JustifyVerticalSpaceBetween<T>(this T control) where T : Control

垂直方向均匀分布 - 显式指定垂直轴

• control — 控件

返回： 控件本身，支持方法链

备注

明确设置垂直内容对齐为UniformSpacing，不依赖FlowOrientation。 适用于需要明确控制垂直分布的场景。

HorizontalSpread 仅客户端

public static T HorizontalSpread<T>(this T control) where T : Control

创建水平均匀分布的容器 - 快捷组合方法

• control — 控件

返回： 控件本身，支持方法链

备注

等同于 .FlowHorizontal().JustifySpaceBetween() 适用于工具栏、按钮组、导航栏等水平分布场景。

VerticalSpread 仅客户端

public static T VerticalSpread<T>(this T control) where T : Control

创建垂直均匀分布的容器 - 快捷组合方法

• control — 控件

返回： 控件本身，支持方法链

备注

等同于 .FlowVertical().JustifySpaceBetween() 适用于侧边栏、菜单列表、垂直分布内容等场景。

ClipContent 仅客户端

public static T ClipContent<T>(this T control, bool clip = true) where T : Control

启用内容裁剪 - 超出控件边界的子控件将被裁剪

• control — 控件
• clip — 是否启用裁剪，默认为true

返回： 控件本身，支持方法链

NoClip 仅客户端

public static T NoClip<T>(this T control) where T : Control

禁用内容裁剪 - 允许子控件超出边界显示

• control — 控件

返回： 控件本身，支持方法链

AllowDrop 仅客户端

public static T AllowDrop<T>(this T control, bool allowDrop = true) where T : Control

设置是否允许拖放到该控件上

• control — 控件
• allowDrop — 是否允许拖放，默认为true

返回： 控件本身，支持方法链

AllowDrag 仅客户端

public static T AllowDrag<T>(this T control, bool allowDrag = true) where T : Control

设置是否允许拖拽该控件

• control — 控件
• allowDrag — 是否允许拖拽，默认为true

返回： 控件本身，支持方法链

PositionType 仅客户端

public static T PositionType<T>(this T control, UIPositionType positionType) where T : Control

设置控件的布局定位类型

• control — 控件
• positionType — 定位类型（Relative 或 Absolute）

返回： 控件本身，支持方法链

备注

Relative：控件位置基于自身排版后的位置进行偏移。 Absolute：控件位置基于父容器的左上角进行偏移，脱离正常布局流。

Absolute 仅客户端

public static T Absolute<T>(this T control) where T : Control

设置控件为绝对定位

• control — 控件

返回： 控件本身，支持方法链

备注

绝对定位的控件位置基于父容器的左上角进行偏移，脱离正常布局流。

Relative 仅客户端

public static T Relative<T>(this T control) where T : Control

设置控件为相对定位

• control — 控件

返回： 控件本身，支持方法链

备注

相对定位的控件位置基于自身排版后的位置进行偏移。

Top 仅客户端

public static T Top<T>(this T control, float value) where T : Control

设置控件距离父容器顶部的距离（绝对定位）

• control — 控件
• value — 距离顶部的像素值

返回： 控件本身，支持方法链

备注

此方法会自动将控件设置为绝对定位，并设置 Y 坐标。

Left 仅客户端

public static T Left<T>(this T control, float value) where T : Control

设置控件距离父容器左侧的距离（绝对定位）

• control — 控件
• value — 距离左侧的像素值

返回： 控件本身，支持方法链

备注

此方法会自动将控件设置为绝对定位，并设置 X 坐标。

TopLeft 仅客户端

public static T TopLeft<T>(this T control, float left, float top) where T : Control

同时设置控件距离父容器顶部和左侧的距离（绝对定位）

• control — 控件
• left — 距离左侧的像素值
• top — 距离顶部的像素值

返回： 控件本身，支持方法链

备注

此方法会自动将控件设置为绝对定位。

Visible 仅客户端

public static T Visible<T>(this T control, bool visible) where T : Control

设置控件可见性

• control — 控件
• visible — 是否可见

返回： 控件本身，支持方法链

Named 仅客户端

public static T Named<T>(this T control, string name) where T : Control

设置控件名称（支持链式调用）

• control — 控件
• name — 控件名称，用于通过 FindChild 查找

返回： 控件本身，支持方法链

备注

此方法是 Name 属性的链式调用版本。 var button = UI.Button("确定") .Named("confirmButton") .Click(() => Confirm()) .AddToRoot(); // 稍后可以通过名称查找 var found = parent.FindChild("confirmButton");

Grow 仅客户端

public static T Grow<T>(this T control, float ratio) where T : Control

设置统一的拉伸比例（宽度和高度使用相同比例）

• control — 控件
• ratio — 拉伸比例，范围为0.0到1.0

返回： 控件本身，支持方法链

备注

此方法同时设置 WidthStretchRatio 和 HeightStretchRatio 为相同的值。 如果需要分别设置，请使用 Single)。

Static 仅客户端

public static T Static<T>(this T control, bool isStatic = true) where T : Control

设置控件是否为静态（不可交互）

• control — 控件
• isStatic — 是否为静态，默认为 true

返回： 控件本身，支持方法链

备注

静态控件不会响应用户输入，但其子控件仍可响应事件。

Disabled 仅客户端

public static T Disabled<T>(this T control, bool disabled) where T : Control

设置控件禁用状态

• control — 控件
• disabled — 是否禁用

返回： 控件本身，支持方法链

备注

禁用的控件不可交互，其子控件也会受影响。

Rotation 仅客户端

public static T Rotation<T>(this T control, float degrees) where T : Control

设置控件旋转角度

• control — 控件
• degrees — 旋转角度（度）

返回： 控件本身，支持方法链

Scale 仅客户端

public static T Scale<T>(this T control, float scale) where T : Control

设置控件统一缩放比例

• control — 控件
• scale — 缩放比例，1.0 为原始大小

返回： 控件本身，支持方法链

Scale 仅客户端

public static T Scale<T>(this T control, float scaleX, float scaleY) where T : Control

设置控件 X/Y 轴缩放比例

• control — 控件
• scaleX — X 轴缩放比例
• scaleY — Y 轴缩放比例

返回： 控件本身，支持方法链

Image 仅客户端

public static T Image<T>(this T control, string imagePath) where T : Control

设置控件背景图片

• control — 控件
• imagePath — 图片资源路径

返回： 控件本身，支持方法链

Image 仅客户端

public static T Image<T>(this T control, Texture2D texture, string runtimeName) where T : Control

Sets a runtime texture as the control background image.

SpriteSheet 仅客户端

public static Sprites SpriteSheet(this Sprites sprites, int frameWidth, int frameHeight, int frameCount, int framesPerRow)

配置普通单图 sprite sheet 的单帧尺寸、总帧数和每行帧数。

• sprites — 要配置的序列帧控件。
• frameWidth — 单帧宽度，单位为像素。
• frameHeight — 单帧高度，单位为像素。
• frameCount — 总帧数。
• framesPerRow — 每行帧数。

返回： 当前 Sprites 实例，支持链式调用。

备注

该方法用于 .Image("xxx.png") 这类普通图片文件路径，告诉控件如何从单张图中切出序列帧。 传入文件夹序列资源时，帧区域由子图列表决定，通常不需要调用该方法。

SpriteSheet 仅客户端

public static Sprites SpriteSheet(this Sprites sprites, Size frameSize, int frameCount, int framesPerRow)

配置普通单图 sprite sheet 的单帧尺寸、总帧数和每行帧数。

• sprites — 要配置的序列帧控件。
• frameSize — 单帧像素尺寸。
• frameCount — 总帧数。
• framesPerRow — 每行帧数。

返回： 当前 Sprites 实例，支持链式调用。

备注

该方法用于 .Image("xxx.png") 这类普通图片文件路径，等价于设置 SpriteSize、FrameCount 和 RowFrameCount。

SpriteFrames 仅客户端

public static Sprites SpriteFrames(this Sprites sprites, int startFrame, int endFrame)

配置序列帧播放范围，下标从 0 开始。

• sprites — 要配置的序列帧控件。
• startFrame — 起始帧下标。
• endFrame — 结束帧下标。

返回： 当前 Sprites 实例，支持链式调用。

备注

播放会限制在该范围内；循环播放时超过结束帧后回到起始帧，非循环播放时到达结束帧后停止。

ImageMask 仅客户端

public static T ImageMask<T>(this T control, string maskPath) where T : Control

设置控件图片遮罩

• control — 控件
• maskPath — 遮罩图片资源路径

返回： 控件本身，支持方法链

Flip 仅客户端

public static T Flip<T>(this T control, bool flipX = false, bool flipY = false) where T : Control

设置控件图片翻转

• control — 控件
• flipX — 是否水平翻转
• flipY — 是否垂直翻转

返回： 控件本身，支持方法链

备注

PanelScrollable 的底层滚动控件不支持图片翻转；对其调用本方法会记录警告， 请改用普通 Panel。

FlipX 仅客户端

public static T FlipX<T>(this T control) where T : Control

水平翻转图片

• control — 控件

返回： 控件本身，支持方法链

备注

PanelScrollable 不支持图片翻转；对其调用本方法会记录警告，请改用普通 Panel。

FlipY 仅客户端

public static T FlipY<T>(this T control) where T : Control

垂直翻转图片

• control — 控件

返回： 控件本身，支持方法链

备注

PanelScrollable 不支持图片翻转；对其调用本方法会记录警告，请改用普通 Panel。

Desaturate 仅客户端

public static T Desaturate<T>(this T control, bool desaturated = true) where T : Control

设置控件为灰度（去色）显示

• control — 控件
• desaturated — 是否灰度显示，默认为 true

返回： 控件本身，支持方法链

备注

灰度显示常用于表示禁用状态或特殊视觉效果。

Blur 仅客户端

public static T Blur<T>(this T control, uint level) where T : Control

设置控件图片模糊等级

• control — 控件
• level — 模糊等级，0 为不模糊

返回： 控件本身，支持方法链

NineSlice 仅客户端

public static T NineSlice<T>(this T control, float edge) where T : Control

设置控件九宫格切片边距（四边相同）

• control — 控件
• edge — 边距值

返回： 控件本身，支持方法链

备注

九宫格切片用于保持图片边角在缩放时不变形。

NineSlice 仅客户端

public static T NineSlice<T>(this T control, float left, float top, float right, float bottom) where T : Control

设置控件九宫格切片边距（分别指定四边）

• control — 控件
• left — 左边距
• top — 上边距
• right — 右边距
• bottom — 下边距

返回： 控件本身，支持方法链

UI 仅客户端

命名空间 GameUI.Control.Extensions

public static class UI

现代化的UI构建器，提供简洁的静态方法

方法

Panel 仅客户端

public static PanelScrollable Panel()

创建面板

Panel 仅客户端

public static PanelScrollable Panel(Control child)

创建包含单个子控件的面板

• child — 子控件

返回： 包含子控件的面板

备注

用于包装单个控件并添加背景、边框等样式。 如果需要包含多个子控件，请使用 Control[]) 或 Control[])。

Page 仅客户端

public static Page Page()

创建页面级根容器。

备注

Page 天生占满 viewport，适合作为完整界面或页面状态的根节点。 如果页面内容需要滚动，请在 Page 内部放置可滚动容器。

Page 仅客户端

public static Page Page(Control child)

创建包含单个子控件的页面级根容器。

Button 仅客户端

public static TextButton Button()

创建按钮（默认高度40px，宽度根据内容自适应）

备注

按钮具有合理的默认尺寸，可直接使用。宽度根据文本内容自适应， 如需固定宽度可链式调用 .Width() 或 .Size() 方法。

Button 仅客户端

public static TextButton Button(string text)

创建带文本的按钮（默认高度40px，宽度根据内容自适应）

备注

按钮具有合理的默认尺寸，可直接使用。宽度根据文本内容自适应， 如需固定宽度可链式调用 .Width() 或 .Size() 方法。

ButtonSmall 仅客户端

public static TextButton ButtonSmall(string text)

创建小尺寸按钮（高度32px）

ButtonLarge 仅客户端

public static TextButton ButtonLarge(string text)

创建大尺寸按钮（高度48px）

ButtonXLarge 仅客户端

public static TextButton ButtonXLarge(string text)

创建超大尺寸按钮（高度56px）

TextButton 仅客户端

public static TextButton TextButton()

创建文本按钮（默认高度40px，宽度根据内容自适应）

TextButton 仅客户端

public static TextButton TextButton(string text)

创建带文本的按钮（默认高度40px，宽度根据内容自适应）

Label 仅客户端

public static Label Label()

创建标签（尺寸根据文本内容自适应）

Label 仅客户端

public static Label Label(string text)

创建带文本的标签（尺寸根据文本内容自适应）

Input 仅客户端

public static Input Input()

创建输入框（默认尺寸：高度40px，宽度280px）

备注

输入框具有合理的默认尺寸，可直接使用。 如需调整尺寸可链式调用 .Width()、.Height() 或 .Size() 方法。

Input 仅客户端

public static Input Input(string placeholder)

创建带占位符的输入框（默认尺寸：高度40px，宽度280px）

备注

输入框具有合理的默认尺寸，可直接使用。 如需调整尺寸可链式调用 .Width()、.Height() 或 .Size() 方法。

InputSmall 仅客户端

public static Input InputSmall(string placeholder = "")

创建小尺寸输入框（高度32px，宽度200px）

InputLarge 仅客户端

public static Input InputLarge(string placeholder = "")

创建大尺寸输入框（高度48px，宽度360px）

ScrollPanel 仅客户端

public static PanelScrollable ScrollPanel()

创建滚动面板

Canvas 仅客户端

public static Canvas Canvas()

创建画布（用于自由绘制图形）

备注

Canvas 支持绑定动画帧事件 (CanvasAnimated) 或直接调用绑定绘制方法的即时绘制模式。 var canvas = UI.Canvas() .Size(400, 300) .Background(Color.White); canvas.StrokePaint = new SolidPaint(Color.Black); canvas.DrawLine(0, 0, 100, 100); canvas.DrawCircle(50, 50, 25);

Canvas 仅客户端

public static Canvas Canvas(float width, float height)

创建指定尺寸的画布

• width — 宽度
• height — 高度

Video 仅客户端

public static Video Video()

创建视频控件。先配置播放参数和事件，再通过 Source 设置项目视频路径。

Video 仅客户端

public static Video Video(float width, float height)

创建指定尺寸的视频控件。

AnimatedCanvas 仅客户端

public static CanvasAnimated AnimatedCanvas()

创建动画画布（支持逐帧渲染动画）

备注

CanvasAnimated 在每一帧自动触发 OnRender 事件，适合需要持续更新的动画场景。 var canvas = UI.AnimatedCanvas() .Size(400, 300); canvas.OnRender += (sender, e) => { e.Canvas.Clear(Color.White); e.Canvas.DrawCircle(x, y, 10); };

AnimatedCanvas 仅客户端

public static CanvasAnimated AnimatedCanvas(float width, float height)

创建指定尺寸的动画画布

• width — 宽度
• height — 高度

Title 仅客户端

public static Label Title(string text, int size = 24)

创建标题

Subtitle 仅客户端

public static Label Subtitle(string text, int size = 18)

创建副标题

Body 仅客户端

public static Label Body(string text, int size = 16)

创建正文

Caption 仅客户端

public static Label Caption(string text, int size = 12)

创建说明文字

Primary 仅客户端

public static TextButton Primary(string text)

创建主要按钮

Secondary 仅客户端

public static TextButton Secondary(string text)

创建次要按钮

Success 仅客户端

public static TextButton Success(string text)

创建成功按钮

Danger 仅客户端

public static TextButton Danger(string text)

创建危险按钮

Outlined 仅客户端

public static Border Outlined(string text)

创建轮廓按钮（透明背景 + 边框）

备注

适用于次要操作，视觉权重低于填充按钮。 var cancelBtn = UI.Outlined("取消").Click(() => Cancel());

Outlined 仅客户端

public static Border Outlined(string text, Color color)

创建轮廓按钮（指定颜色）

Ghost 仅客户端

public static TextButton Ghost(string text)

创建幽灵按钮（透明背景，无边框，悬停时显示背景）

备注

适用于工具栏、紧凑空间中的操作。视觉权重最低。 var moreBtn = UI.Ghost("更多").Click(() => ShowMore());

Ghost 仅客户端

public static TextButton Ghost(string text, Color color)

创建幽灵按钮（指定颜色）

TextLink 仅客户端

public static TextButton TextLink(string text)

创建文本按钮（无背景无边框，仅文字）

备注

适用于内联链接、辅助操作。 var linkBtn = UI.TextLink("了解更多").Click(() => ShowHelp());

TextLink 仅客户端

public static TextButton TextLink(string text, Color color)

创建文本按钮（指定颜色）

VStack 仅客户端

public static SpacingPanel VStack(float spacing = 0f, params Control[] children)

创建垂直堆叠

HStack 仅客户端

public static SpacingPanel HStack(float spacing = 0f, params Control[] children)

创建水平堆叠

Grid 仅客户端

public static SpacingPanel Grid(float rowSpacing = 0f, float columnSpacing = 0f, params Control[] children)

创建网格布局

TrueGrid 仅客户端

public static SpacingPanel TrueGrid(int columns, float rowSpacing = 0f, float columnSpacing = 0f, params Control[] children)

创建真正的网格布局

SimpleGrid 仅客户端

public static SpacingPanel SimpleGrid(float spacing, params Control[] children)

创建简单网格布局

ScrollableVStack 仅客户端

public static SpacingPanel ScrollableVStack(float spacing = 0f, params Control[] children)

创建可滚动的垂直堆叠

ScrollableHStack 仅客户端

public static SpacingPanel ScrollableHStack(float spacing = 0f, params Control[] children)

创建可滚动的水平堆叠

ForEach 仅客户端

public static SpacingPanel ForEach<T>(IEnumerable<T> items, Func<T, Control> itemBuilder, float spacing = 0f)

根据数据集合生成垂直排列的控件列表（一次性生成，不响应数据变化）

• items — 数据集合
• itemBuilder — 为每个数据项生成控件的函数
• spacing — 控件之间的间距，默认为0

返回： 包含所有生成控件的垂直面板

备注

此方法适用于少量数据（<50项）的简单列表。对于大量数据，请使用 SizeF})。 // 生成物品列表 var itemList = UI.ForEach(inventory.Items, item => UI.HStack(8) .Add( UI.Label(item.Name), UI.Label($"x{item.Count}") ) .Click(() => SelectItem(item)) );

ForEachHorizontal 仅客户端

public static SpacingPanel ForEachHorizontal<T>(IEnumerable<T> items, Func<T, Control> itemBuilder, float spacing = 0f)

根据数据集合生成水平排列的控件列表（一次性生成，不响应数据变化）

• items — 数据集合
• itemBuilder — 为每个数据项生成控件的函数
• spacing — 控件之间的间距，默认为0

返回： 包含所有生成控件的水平面板

备注

此方法适用于少量数据（<50项）的简单列表。对于大量数据，请使用虚拟化面板。 // 生成技能栏 var skillBar = UI.ForEachHorizontal(player.Skills, skill => UI.Button(skill.Icon) .Square(64) .Click(() => UseSkill(skill)) , spacing: 8);

ForEachGrid 仅客户端

public static SpacingPanel ForEachGrid<T>(IEnumerable<T> items, Func<T, Control> itemBuilder, int columns, float rowSpacing = 0f, float columnSpacing = 0f)

根据数据集合生成网格排列的控件列表（一次性生成，不响应数据变化）

• items — 数据集合
• itemBuilder — 为每个数据项生成控件的函数
• columns — 列数
• rowSpacing — 行间距，默认为0
• columnSpacing — 列间距，默认为0

返回： 包含所有生成控件的网格面板

备注

此方法适用于少量数据（<50项）的简单网格。对于大量数据，请使用虚拟化面板。 // 生成物品网格（4列） var itemGrid = UI.ForEachGrid(inventory.Items, item => UI.Panel() .Square(64) .Background(item.Rarity.ToColor()) .Click(() => SelectItem(item)) , columns: 4, rowSpacing: 4, columnSpacing: 4);

Bordered 仅客户端

public static Border Bordered(Control content, float thickness, Color? color = null)

将控件包装在带边框的面板中

• content — 要包装的控件
• thickness — 边框粗细
• color — 边框颜色，默认为DesignColors.Outline

返回： 包装后的Border控件

备注

推荐使用此工厂方法来添加边框，可保证所有控件配置在包装之前完成。 // 创建带边框的按钮 var borderedButton = UI.Bordered( UI.Button("确定").Size(100, 40).Click(() => Submit()), thickness: 1 ); // 创建带自定义边框颜色的面板 var borderedPanel = UI.Bordered( UI.VStack(8).Add( UI.Label("标题"), UI.Label("内容") ), thickness: 2, color: Color.Gold );

Bordered 仅客户端

public static Border Bordered(Control content, Thickness thickness, Color? color = null)

将控件包装在带边框的面板中（四边不同粗细）

• content — 要包装的控件
• thickness — 边框粗细（四边可不同）
• color — 边框颜色，默认为DesignColors.Outline

返回： 包装后的Border控件

Card 仅客户端

public static PanelScrollable Card(params Control[] children)

创建卡片容器

• children — 子控件

返回： 带卡片样式的面板

备注

预设样式：圆角、内边距、Surface 背景色。 var card = UI.Card( UI.Label("标题").Title(), UI.Label("内容描述") ).Click(() => OpenDetail());

Dialog 仅客户端

public static PanelScrollable Dialog(params Control[] children)

创建对话框容器

• children — 子控件

返回： 带对话框样式的面板

ListItem 仅客户端

public static SpacingPanel ListItem(params Control[] children)

创建列表项

• children — 子控件

返回： 带列表项样式的面板

Badge 仅客户端

public static Label Badge(string text)

创建徽章

• text — 徽章文本

返回： 带徽章样式的标签

Badge 仅客户端

public static Label Badge(string text, Color backgroundColor, Color textColor)

创建徽章（自定义颜色）

• text — 徽章文本
• backgroundColor — 背景色
• textColor — 文字颜色

返回： 带徽章样式的标签

ToolbarButton 仅客户端

public static TextButton ToolbarButton(string icon)

创建工具栏按钮

• icon — 图标文本或 emoji

返回： 带工具栏按钮样式的按钮

Spacer 仅客户端

public static Panel Spacer()

创建弹性空间

Space 仅客户端

public static Panel Space(float size)

创建固定尺寸的间距

• size — 间距大小（像素）

返回： 固定高度的Panel，用作垂直间距

Divider 仅客户端

public static Panel Divider(float thickness = 1f, Color? color = null)

创建分隔线

VDivider 仅客户端

public static Panel VDivider(float thickness = 1f, Color? color = null)

创建垂直分隔线

HDivider 仅客户端

public static Panel HDivider(float thickness = 1f, Color? color = null)

创建水平分隔线

Modal 仅客户端

public static Panel Modal(string title, Control content, params Control[] actions)

创建模态对话框

Notification 仅客户端

public static Panel Notification(string message, Color backgroundColor = default(Color), Color textColor = default(Color))

创建通知消息

LoadingIndicator 仅客户端

public static Panel LoadingIndicator(string message = "加载中...")

创建加载指示器

Form 仅客户端

public static Panel Form(params (string label, Control input)[] fields)

TabView 仅客户端

public static Panel TabView(params (string title, Control content)[] tabs)

VideoExtensions 仅客户端

命名空间 GameUI.Control.Extensions

public static class VideoExtensions

视频控件的流式配置。Source 应放在播放选项和事件订阅之后。

方法

Source 仅客户端

public static T Source<T>(this T video, string path) where T : Video

设置项目 res 下的视频路径并开始加载。

AutoPlay 仅客户端

public static T AutoPlay<T>(this T video, bool enabled = true) where T : Video

配置新视频加载完成后是否自动播放，默认参数为启用。

Loop 仅客户端

public static T Loop<T>(this T video, bool enabled = true) where T : Video

配置循环播放。

Muted 仅客户端

public static T Muted<T>(this T video, bool enabled = true) where T : Video

配置静音。

Volume 仅客户端

public static T Volume<T>(this T video, float volume) where T : Video

配置音量，范围为 0 到 1。

PlaybackRate 仅客户端

public static T PlaybackRate<T>(this T video, float rate) where T : Video

配置播放速度，范围为 0.25 到 4。

PauseWhenHidden 仅客户端

public static T PauseWhenHidden<T>(this T video, bool enabled = true) where T : Video

配置隐藏或脱离界面树时暂停。

Stretch 仅客户端

public static T Stretch<T>(this T video, VideoStretch stretch) where T : Video

配置视频画面的缩放方式。

OnVideoOpened 仅客户端

public static T OnVideoOpened<T>(this T video, EventHandler handler) where T : Video

订阅视频就绪事件。

OnVideoEnded 仅客户端

public static T OnVideoEnded<T>(this T video, EventHandler handler) where T : Video

订阅非循环视频结束事件。

OnVideoFailed 仅客户端

public static T OnVideoFailed<T>(this T video, EventHandler handler) where T : Video

订阅视频失败事件，原因见 LastError。

OnVideoStateChanged 仅客户端

public static T OnVideoStateChanged<T>(this T video, EventHandler handler) where T : Video

订阅状态变化事件。

VirtualizingDebugExtensions 仅客户端

命名空间 GameUI.Control.Extensions

public static class VirtualizingDebugExtensions

VirtualizingDebugPanel的专用扩展方法，提供流式构造和便利API 简化虚拟化调试面板的创建和配置

方法

DebugPanel 仅客户端

public static VirtualizingDebugPanel DebugPanel(string title = "虚拟化列表调试信息", float width = 400f, float height = 600f)

创建虚拟化调试面板

• title — 面板标题
• width — 面板宽度
• height — 面板高度

返回： 配置好的调试面板

CompactDebugPanel 仅客户端

public static VirtualizingDebugPanel CompactDebugPanel(string title = "调试信息")

创建紧凑型调试面板

• title — 面板标题

返回： 紧凑型调试面板

LargeDebugPanel 仅客户端

public static VirtualizingDebugPanel LargeDebugPanel(string title = "详细调试信息")

创建大型调试面板

• title — 面板标题

返回： 大型调试面板

Title 仅客户端

public static VirtualizingDebugPanel Title(this VirtualizingDebugPanel panel, string title)

设置调试面板标题

• panel — 调试面板
• title — 标题文本

返回： 调试面板本身，支持链式调用

Position 仅客户端

public static VirtualizingDebugPanel Position(this VirtualizingDebugPanel panel, VerticalAlignment verticalAlignment = VerticalAlignment.Top, HorizontalAlignment horizontalAlignment = HorizontalAlignment.Right)

设置调试面板位置

• panel — 调试面板
• verticalAlignment — 垂直对齐
• horizontalAlignment — 水平对齐

返回： 调试面板本身，支持链式调用

Size 仅客户端

public static VirtualizingDebugPanel Size(this VirtualizingDebugPanel panel, float width, float height)

设置调试面板大小

• panel — 调试面板
• width — 宽度
• height — 高度

返回： 调试面板本身，支持链式调用

Background 仅客户端

public static VirtualizingDebugPanel Background(this VirtualizingDebugPanel panel, Color color)

设置调试面板背景色

• panel — 调试面板
• color — 背景颜色

返回： 调试面板本身，支持链式调用

Opacity 仅客户端

public static VirtualizingDebugPanel Opacity(this VirtualizingDebugPanel panel, float opacity)

设置调试面板透明度

• panel — 调试面板
• opacity — 透明度 (0-1)

返回： 调试面板本身，支持链式调用

CornerRadius 仅客户端

public static VirtualizingDebugPanel CornerRadius(this VirtualizingDebugPanel panel, float radius)

设置调试面板圆角

• panel — 调试面板
• radius — 圆角半径

返回： 调试面板本身，支持链式调用

Padding 仅客户端

public static VirtualizingDebugPanel Padding(this VirtualizingDebugPanel panel, float padding)

设置调试面板内边距

• panel — 调试面板
• padding — 内边距

返回： 调试面板本身，支持链式调用

Padding 仅客户端

public static VirtualizingDebugPanel Padding(this VirtualizingDebugPanel panel, float left, float top, float right, float bottom)

设置调试面板内边距

• panel — 调试面板
• left — 左边距
• top — 上边距
• right — 右边距
• bottom — 下边距

返回： 调试面板本身，支持链式调用

Enable 仅客户端

public static VirtualizingDebugPanel Enable(this VirtualizingDebugPanel panel)

启用调试面板

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Disable 仅客户端

public static VirtualizingDebugPanel Disable(this VirtualizingDebugPanel panel)

禁用调试面板

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Visible 仅客户端

public static VirtualizingDebugPanel Visible(this VirtualizingDebugPanel panel, bool visible)

设置调试面板可见性

• panel — 调试面板
• visible — 是否可见

返回： 调试面板本身，支持链式调用

Show 仅客户端

public static VirtualizingDebugPanel Show(this VirtualizingDebugPanel panel)

显示调试面板

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Hide 仅客户端

public static VirtualizingDebugPanel Hide(this VirtualizingDebugPanel panel)

隐藏调试面板

• panel — 调试面板

返回： 调试面板本身，支持链式调用

AttachTo 仅客户端

public static VirtualizingDebugPanel AttachTo(this VirtualizingDebugPanel panel, VirtualizingPanel virtualizingPanel)

附加到虚拟化面板并返回调试面板

• panel — 调试面板
• virtualizingPanel — 要调试的虚拟化面板

返回： 调试面板本身，支持链式调用

Detach 仅客户端

public static VirtualizingDebugPanel Detach(this VirtualizingDebugPanel panel)

从虚拟化面板分离并返回调试面板

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Clear 仅客户端

public static VirtualizingDebugPanel Clear(this VirtualizingDebugPanel panel)

清除调试信息并返回调试面板

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Floating 仅客户端

public static VirtualizingDebugPanel Floating(this VirtualizingDebugPanel panel)

设置调试面板为浮动模式（右上角）

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Bottom 仅客户端

public static VirtualizingDebugPanel Bottom(this VirtualizingDebugPanel panel)

设置调试面板为底部模式

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Left 仅客户端

public static VirtualizingDebugPanel Left(this VirtualizingDebugPanel panel)

设置调试面板为左侧模式

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Right 仅客户端

public static VirtualizingDebugPanel Right(this VirtualizingDebugPanel panel)

设置调试面板为右侧模式

• panel — 调试面板

返回： 调试面板本身，支持链式调用

SemiTransparent 仅客户端

public static VirtualizingDebugPanel SemiTransparent(this VirtualizingDebugPanel panel, float opacity = 0.8f)

设置调试面板为半透明模式

• panel — 调试面板
• opacity — 透明度 (0-1)

返回： 调试面板本身，支持链式调用

Compact 仅客户端

public static VirtualizingDebugPanel Compact(this VirtualizingDebugPanel panel)

设置调试面板为紧凑模式

• panel — 调试面板

返回： 调试面板本身，支持链式调用

Detailed 仅客户端

public static VirtualizingDebugPanel Detailed(this VirtualizingDebugPanel panel)

设置调试面板为详细模式

• panel — 调试面板

返回： 调试面板本身，支持链式调用

VirtualizingDebugUI 仅客户端

命名空间 GameUI.Control.Extensions

public static class VirtualizingDebugUI

UI扩展类，提供调试面板的便捷创建方法

方法

DebugPanel 仅客户端

public static VirtualizingDebugPanel DebugPanel(string title = "虚拟化列表调试信息")

创建虚拟化调试面板

• title — 面板标题

返回： 调试面板

CompactDebugPanel 仅客户端

public static VirtualizingDebugPanel CompactDebugPanel(string title = "调试信息")

创建紧凑型调试面板

• title — 面板标题

返回： 紧凑型调试面板

LargeDebugPanel 仅客户端

public static VirtualizingDebugPanel LargeDebugPanel(string title = "详细调试信息")

创建大型调试面板

• title — 面板标题

返回： 大型调试面板

VirtualizingExtensions 仅客户端

命名空间 GameUI.Control.Extensions

public static class VirtualizingExtensions

VirtualizingPanel的专用扩展方法，提供类似Flexbox的便捷API 解决虚拟化面板特殊的模板配置需求

方法

VirtualList 仅客户端

public static VirtualizingPanel VirtualList(IGameLink<GameDataControl> itemTemplate, SizeF? itemSize = null, float cachePages = 1f)

创建垂直虚拟化列表

• itemTemplate — 项模板
• itemSize — 项大小（可选，如果不指定会自动测量）
• cachePages — 缓存页数

返回： 配置好的垂直虚拟化面板

VirtualHorizontalList 仅客户端

public static VirtualizingPanel VirtualHorizontalList(IGameLink<GameDataControl> itemTemplate, SizeF? itemSize = null, float cachePages = 1f)

创建水平虚拟化列表

• itemTemplate — 项模板
• itemSize — 项大小（可选，如果不指定会自动测量）
• cachePages — 缓存页数

返回： 配置好的水平虚拟化面板

VirtualListWithSelector 仅客户端

public static VirtualizingPanel VirtualListWithSelector(ItemTemplateSelector itemTemplateSelector, Orientation orientation = Orientation.Vertical, SizeF? itemSize = null, float cachePages = 1f)

创建带选择器的虚拟化列表

• itemTemplateSelector — 项模板选择器
• orientation — 滚动方向
• itemSize — 项大小（可选，如果不指定会自动测量）
• cachePages — 缓存页数

返回： 配置好的虚拟化面板

Cache 仅客户端

public static VirtualizingPanel Cache(this VirtualizingPanel panel, float beforeViewport, float afterViewport, VirtualizationCacheLengthUnit unit = VirtualizationCacheLengthUnit.Page)

设置虚拟化缓存配置

• panel — 虚拟化面板
• beforeViewport — 视口前缓存大小
• afterViewport — 视口后缓存大小
• unit — 缓存单位

返回： 面板本身，支持链式调用

ItemSize 仅客户端

public static VirtualizingPanel ItemSize(this VirtualizingPanel panel, float width, float height)

设置项大小

• panel — 虚拟化面板
• width — 项宽度
• height — 项高度

返回： 面板本身，支持链式调用

ItemSize 仅客户端

public static VirtualizingPanel ItemSize(this VirtualizingPanel panel, float size)

设置项大小（正方形）

• panel — 虚拟化面板
• size — 项大小

返回： 面板本身，支持链式调用

Template 仅客户端

public static VirtualizingPanel Template(this VirtualizingPanel panel, IGameLink<GameDataControl> template)

设置项模板

• panel — 虚拟化面板
• template — 项模板

返回： 面板本身，支持链式调用

TemplateSelector 仅客户端

public static VirtualizingPanel TemplateSelector(this VirtualizingPanel panel, ItemTemplateSelector selector)

设置项模板选择器

• panel — 虚拟化面板
• selector — 模板选择器

返回： 面板本身，支持链式调用

Items 仅客户端

public static VirtualizingPanel Items<T>(this VirtualizingPanel panel, IEnumerable<T> items, bool autoVirtulzation = true)

设置数据源

• panel — 虚拟化面板
• items — 数据项集合
• autoVirtulzation — 是否自动虚拟化。 若为 true，则会自动生成子控件。 若为 false，则需要在之后手动调用GenerateChildren来生成子控件。

返回： 面板本身，支持链式调用

ArrangeOnScroll 仅客户端

public static VirtualizingPanel ArrangeOnScroll(this VirtualizingPanel panel, bool enabled = true)

启用/禁用滚动时重新排列

• panel — 虚拟化面板
• enabled — 是否启用

返回： 面板本身，支持链式调用

VirtualUI 仅客户端

命名空间 GameUI.Control.Extensions

public static class VirtualUI

UI工厂类的虚拟化扩展

方法

VirtualList 仅客户端

public static VirtualizingPanel VirtualList(IGameLink<GameDataControl> itemTemplate, SizeF? itemSize = null)

创建垂直虚拟化列表

• itemTemplate — 项模板
• itemSize — 项大小（可选）

返回： 垂直虚拟化面板

VirtualHorizontalList 仅客户端

public static VirtualizingPanel VirtualHorizontalList(IGameLink<GameDataControl> itemTemplate, SizeF? itemSize = null)

创建水平虚拟化列表

• itemTemplate — 项模板
• itemSize — 项大小（可选）

返回： 水平虚拟化面板

VirtualListWithSelector 仅客户端

public static VirtualizingPanel VirtualListWithSelector(ItemTemplateSelector selector, Orientation orientation = Orientation.Vertical, SizeF? itemSize = null)

创建带选择器的虚拟化列表

• selector — 模板选择器
• orientation — 方向
• itemSize — 项大小（可选）

返回： 虚拟化面板

IVirtualizingDebugPanel 仅客户端

命名空间 GameUI.Control.Interface

public interface IVirtualizingDebugPanel

虚拟化列表调试信息面板接口 用于显示虚拟化列表控件的调试信息，包括虚拟化状态、缓存信息、子控件信息等

方法

UpdateVirtualizationState 仅客户端

void UpdateVirtualizationState(bool isVirtualizing, int cacheStartIndex, int cachedChildrenCount, SizeF viewportSize, float scrollBarValue, int viewportFirstItemIndex)

更新虚拟化状态信息

• isVirtualizing — 是否正在虚拟化
• cacheStartIndex — 缓存起始索引
• cachedChildrenCount — 缓存的子控件数量
• viewportSize — 视口大小
• scrollBarValue — 滚动条值
• viewportFirstItemIndex — 视口第一个项目索引

UpdateCacheInfo 仅客户端

void UpdateCacheInfo(int cacheBeforeViewportItemCount, int cacheAfterViewportItemCount, int pageItemCount, float logicItemsTotalSize, Dictionary<string, int> recyclePoolCounts)

更新缓存信息

• cacheBeforeViewportItemCount — 视口前缓存项目数量
• cacheAfterViewportItemCount — 视口后缓存项目数量
• pageItemCount — 页面项目数量
• logicItemsTotalSize — 逻辑项目总大小
• recyclePoolCounts — 回收池各类型数量

UpdateChildrenInfo 仅客户端

void UpdateChildrenInfo(IReadOnlyList<Control> children, IEnumerable<object>? itemsSource)

更新子控件信息

• children — 子控件列表
• itemsSource — 数据源

ClearDebugInfo 仅客户端

void ClearDebugInfo()

清空调试信息

SetDebugEnabled 仅客户端

void SetDebugEnabled(bool enabled)

设置是否启用调试信息显示

• enabled — 是否启用

Border 仅客户端

命名空间 GameUI.Control.Primitive

public class Border : Panel

属性

Content 仅客户端

public Control? Content { get; set; }

Thickness 仅客户端

public Thickness Thickness { get; set; }

Color 仅客户端

public ColorBrush Color { get; set; }

方法

AddChild 仅客户端

public override bool AddChild(Control child)

RemoveChild 仅客户端

public override bool RemoveChild(Control child)

Button 仅客户端

命名空间 GameUI.Control.Primitive

public class Button : Control, IGameObject<GameDataControlButton>, IGameObject

表示 UI 按钮控件。

备注

按钮控件默认不会转发鼠标事件（PointerClicked, PointerDoubleClicked, PointerPressed, PointerReleased, PointerEntered, PointerExited）到父控件或游戏场景， 防止点击按钮时意外触发游戏场景中的操作。如果需要按钮转发某些鼠标事件， 可以手动设置 RoutedEvents 属性。

构造函数

Button 仅客户端

public Button(IGameLink<GameDataControlButton> link)

使用指定模板链接初始化按钮实例。

• link — 按钮模板数据链接。

Button 仅客户端

public Button()

使用默认模板初始化按钮实例。

备注

构造函数会自动设置按钮不转发任何鼠标事件，防止点击按钮时触发游戏场景中的操作。

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlButton> DefaultTemplate { get; }

获取按钮的默认模板链接。

ImageHover 仅客户端

public UTF8String ImageHover { get; set; }

ImagePressed 仅客户端

public UTF8String ImagePressed { get; set; }

Link 仅客户端

public new IGameLink<GameDataControlButton> Link { get; }

Cache 仅客户端

public new GameDataControlButton Cache { get; }

方法

OnKeyboardAcceleratorInvokedInternal 仅客户端

protected override bool OnKeyboardAcceleratorInvokedInternal(KeyboardAccelerator accelerator)

Canvas 仅客户端

命名空间 GameUI.Control.Primitive

public class Canvas : Control, ICanvasImage, IGameObject<GameDataControlCanvas>, IGameObject

画布控件类，提供2D图形绘制功能

备注

Canvas类继承自Control，提供了丰富的2D绘图API，包括： 基础图形绘制（线条、圆形、矩形、三角形等） 图像绘制和变换操作 复杂路径绘制（包括贝塞尔曲线、圆弧等） 颜色和样式管理 该类采用partial class设计，功能分布在多个文件中： Canvas.cs基础类定义和构造函数 Canvas.Draw.cs基础绘制方法 Canvas.DrawPath.cs路径绘制功能 Canvas.Properties.cs绘制属性管理

构造函数

Canvas 仅客户端

public Canvas(IGameLink<GameDataControlCanvas> link)

使用指定的游戏链接初始化Canvas实例

• link — 指向GameDataControlCanvas数据的游戏链接

备注

此构造函数将创建一个与指定数据链接绑定的Canvas控件， 控件类型设置为SCEImportGUI.ControlType.Canvas

Canvas 仅客户端

public Canvas()

使用默认模板初始化Canvas实例

备注

此构造函数使用DefaultTemplate作为数据源创建Canvas控件， 适用于不需要特定数据绑定的场景

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlCanvas> DefaultTemplate { get; }

获取Canvas控件的默认模板链接

IsRendering 仅客户端

public bool IsRendering { get; set; }

获取是否正在渲染

备注

此属性用于判断是否正在渲染。 当渲染时，此属性为true，否则为false。

DefaultPathWinding 仅客户端

public WindingMode DefaultPathWinding { get; set; }

获取或设置路径的默认缠绕模式

备注

缠绕模式决定了复杂路径的填充规则： NonZero: 非零缠绕规则，适用于大多数情况 EvenOdd: 奇偶规则，用于创建镂空效果 该属性仅接受NonZero和EvenOdd两个值，设置其他值会抛出异常。

FillPaint 仅客户端

public Paint FillPaint { get; set; }

获取或设置用于填充图形的画笔

备注

此属性控制所有填充操作（如FillRectangle、FillCircle、FillPath等）使用的画笔。 支持的画笔类型： SolidPaint: 实心颜色画笔 GradientPaint: 渐变画笔（线性、径向、盒式） 当设置新画笔时，会自动将其应用到底层渲染系统。

StrokePaint 仅客户端

public Paint StrokePaint { get; set; }

获取或设置用于绘制图形轮廓的画笔

备注

此属性控制所有线条和轮廓绘制操作（如DrawLine、DrawCircle、DrawRectangle等）使用的画笔。 支持的画笔类型： SolidPaint: 实心颜色画笔 GradientPaint: 渐变画笔（线性、径向、盒式） 当设置新画笔时，会自动将其应用到底层渲染系统。 如果设置的画笔与当前画笔相同，则不会执行任何操作以提高性能。

StrokeWidth 仅客户端

public float StrokeWidth { get; set; }

设置或获取用于绘制图形轮廓的线条宽度

备注

此属性控制所有线条和轮廓绘制操作的线条粗细。 值必须大于0。较大的值会产生更粗的线条。 当属性值发生变化时，会自动将新宽度设置到底层渲染系统。 如果设置的宽度与当前宽度相同，则不会执行任何操作以提高性能。

LineCap 仅客户端

public LineCap LineCap { get; set; }

获取或设置线条端点的样式

备注

此属性控制线条两端的形状： Butt: 平头端点，线条在端点处平齐截止 Round: 圆形端点，线条端点为半圆形 Square: 方形端点，线条端点向外延伸半个线宽 该属性影响所有线条绘制操作的外观。

LineJoin 仅客户端

public LineJoin LineJoin { get; set; }

获取或设置线条连接处的样式

备注

此属性控制两条线段相交时连接点的形状： Miter: 斜接连接，线条在连接处以尖角相接 Round: 圆形连接，线条在连接处以圆弧相接 Bevel: 斜切连接，线条在连接处以平角相接 该属性影响路径和多边形绘制时转角的外观。

MiterLimit 仅客户端

public float MiterLimit { get; set; }

获取或设置斜接限制值

备注

当LineJoin设置为Miter时，此属性控制斜接连接的最大长度。 当两条线段的夹角很小时，斜接连接可能会变得很长。 如果斜接长度超过 (线宽 * MiterLimit)，则会自动切换为斜切连接。 较大的值允许更尖锐的角度，较小的值会更早切换为斜切连接。

Alpha 仅客户端

public float Alpha { get; set; }

获取或设置全局透明度

备注

此属性控制画布上所有绘制操作的全局透明度： 1.0: 完全不透明 0.5: 半透明 0.0: 完全透明（不可见） 全局透明度会与颜色自身的alpha值相乘，影响最终的渲染效果。 该属性影响所有后续的绘制操作，包括填充、描边和图像绘制。

BlendMode 仅客户端

public BlendMode BlendMode { get; set; }

获取或设置混合模式

备注

混合模式决定了新绘制的内容如何与已有内容混合： SourceOver: 标准混合模式，新内容覆盖在已有内容之上 SourceIn: 只在已有内容区域内绘制新内容 SourceOut: 只在已有内容区域外绘制新内容 SourceAtop: 新内容只替换已有内容的非透明部分 Multiply: 颜色相乘混合，产生更暗的颜色 Screen: 颜色相加混合，产生更亮的颜色 Overlay: 覆盖混合，结合相乘和相加效果 不同的混合模式可以创建各种特殊的视觉效果。

FontSize 仅客户端

public float FontSize { get; set; }

获取或设置文本字体大小

FontBlur 仅客户端

public float FontBlur { get; set; }

获取或设置文本字体模糊效果

TextLetterSpacing 仅客户端

public float TextLetterSpacing { get; set; }

获取或设置文本字母间距（Text 前缀用于消除歧义）

TextLineHeight 仅客户端

public float TextLineHeight { get; set; }

获取或设置文本行高（Text 前缀用于消除歧义）

TextAlign 仅客户端

public TextAlign TextAlign { get; set; }

获取或设置文本对齐方式

Resolution 仅客户端

public SizeF Resolution { get; set; }

获取或设置画布的分辨率

备注

画布分辨率决定了绘制的精度和质量。 更高的分辨率提供更好的绘制质量，但会消耗更多的内存和处理资源。 当AutoUpdateResolutionOnResize为true时，分辨率会自动根据控件大小调整。 手动设置此属性会覆盖自动调整的行为。

AutoUpdateResolutionOnResize 仅客户端

public bool AutoUpdateResolutionOnResize { get; set; }

获取或设置是否在控件大小改变时自动更新分辨率

备注

当此属性为true时，画布分辨率会自动根据控件大小和坐标模式进行调整： DesignResolution模式：分辨率 = 控件大小 / 设备像素比 CanvasResolution模式：分辨率 = 控件大小 设置为false时，分辨率保持固定值，不会自动调整。 自动调整有助于在不同设备和缩放比例下保持一致的绘制质量。

CoordinateMode 仅客户端

public CanvasCoordinateMode CoordinateMode { get; set; }

获取或设置画布的坐标模式

备注

坐标模式决定了画布如何处理坐标系统和像素比例： DesignResolution: 使用设计分辨率坐标系统，与框架其他控件一致，AI友好 CanvasResolution: 使用Canvas原始分辨率坐标系统，适用于像素级精确绘制 DesignResolution模式会自动处理设备像素比例，确保在不同设备上的一致性。 CanvasResolution模式提供1:1的像素精确控制，适合精密绘制需求。

Link 仅客户端

public new IGameLink<GameDataControlCanvas> Link { get; }

Cache 仅客户端

public new GameDataControlCanvas Cache { get; }

方法

DrawImage 仅客户端

public void DrawImage(GameCore.ResourceType.Image image, float x, float y, float width, float height)

在指定位置和尺寸绘制图像

• image — 要绘制的图像资源
• x — 图像左上角的X坐标
• y — 图像左上角的Y坐标
• width — 图像显示宽度
• height — 图像显示高度

备注

此方法将图像绘制到画布的指定位置。如果图像路径为空，则不执行绘制操作。 图像会被缩放以适应指定的宽度和高度。

DrawImage 仅客户端

public void DrawImage(GameCore.ResourceType.Image image, float x, float y)

在指定位置绘制图像（原始尺寸）

• image — 要绘制的图像资源
• x — 图像左上角的X坐标
• y — 图像左上角的Y坐标

备注

此方法将图像以原始尺寸绘制到画布的指定位置。 如果图像路径为空，则不执行绘制操作。

DrawImage 仅客户端

public void DrawImage(GameCore.ResourceType.Image image, float sourceX, float sourceY, float sourceWidth, float sourceHeight, float x, float y, float width, float height)

绘制图像的指定区域到画布的指定位置和尺寸

• image — 要绘制的图像资源
• sourceX — 源图像裁剪区域的X坐标
• sourceY — 源图像裁剪区域的Y坐标
• sourceWidth — 源图像裁剪区域的宽度
• sourceHeight — 源图像裁剪区域的高度
• x — 目标位置的X坐标
• y — 目标位置的Y坐标
• width — 目标绘制宽度
• height — 目标绘制高度

备注

此方法允许选择图像的指定区域，并将其缩放绘制到目标区域。 如果图像路径为空，则不执行绘制操作。 源区域和目标区域可以有不同的尺寸，图像会自动缩放以适应。

DrawImage 仅客户端

public void DrawImage(GameCore.ResourceType.Image image, RectangleF sourceRect, RectangleF destRect)

使用矩形结构体绘制图像的指定区域到画布的指定位置和尺寸

• image — 要绘制的图像资源
• sourceRect — 源图像的裁剪区域
• destRect — 目标绘制区域

备注

此方法是DrawImage多参数重载的便利版本，使用RectangleF结构体简化参数传递。 如果图像路径为空，则不执行绘制操作。 源区域和目标区域可以有不同的尺寸，图像会自动缩放以适应。 此重载特别适合AI代码生成，因为参数更直观易理解。

DrawLine 仅客户端

public void DrawLine(float x1, float y1, float x2, float y2)

绘制从起点到终点的直线

• x1 — 起点的X坐标
• y1 — 起点的Y坐标
• x2 — 终点的X坐标
• y2 — 终点的Y坐标

备注

直线的颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定

DrawCircle 仅客户端

public void DrawCircle(float centerX, float centerY, float radius)

绘制圆形轮廓

• centerX — 圆心的X坐标
• centerY — 圆心的Y坐标
• radius — 圆的半径

备注

只绘制圆形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等价于StrokeCircle，推荐使用StrokeCircle以与FillCircle形成一致的命名对。

DrawCircle 仅客户端

public void DrawCircle(PointF center, float radius)

绘制圆形轮廓

• center — 圆心坐标
• radius — 圆的半径

备注

只绘制圆形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等价于StrokeCircle，推荐使用StrokeCircle以与FillCircle形成一致的命名对。

DrawCircle 仅客户端

public void DrawCircle(PointF center, float radius, float startAngle, float endAngle, bool clockwise)

绘制圆弧轮廓

• center — 圆心坐标
• radius — 圆的半径
• startAngle — 起始角度（以度为单位）
• endAngle — 结束角度（以度为单位）
• clockwise — 是否顺时针绘制

备注

绘制圆形的一段弧形轮廓。角度以度为单位，0度指向右侧（正X轴方向）。 轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。

DrawTriangle 仅客户端

public void DrawTriangle(float x1, float y1, float x2, float y2, float x3, float y3)

绘制三角形轮廓

• x1 — 第一个顶点的X坐标
• y1 — 第一个顶点的Y坐标
• x2 — 第二个顶点的X坐标
• y2 — 第二个顶点的Y坐标
• x3 — 第三个顶点的X坐标
• y3 — 第三个顶点的Y坐标

备注

通过连接三个顶点来绘制三角形轮廓。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等价于StrokeTriangle，推荐使用StrokeTriangle以与FillTriangle形成一致的命名对。

DrawRectangle 仅客户端

public void DrawRectangle(float x, float y, float width, float height)

绘制矩形轮廓

• x — 矩形左上角的X坐标
• y — 矩形左上角的Y坐标
• width — 矩形的宽度
• height — 矩形的高度

备注

只绘制矩形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等价于StrokeRectangle，推荐使用StrokeRectangle以与FillRectangle形成一致的命名对。

DrawEllipse 仅客户端

public void DrawEllipse(float centerX, float centerY, float radiusX, float radiusY)

绘制椭圆轮廓

• centerX — 椭圆中心的X坐标
• centerY — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

只绘制椭圆的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 椭圆通过指定不同的X轴和Y轴半径来创建，当两个半径相等时等效于圆形。 椭圆的轴与坐标轴平行，如需旋转椭圆请结合变换方法使用。 等价于StrokeEllipse，推荐使用StrokeEllipse以与FillEllipse形成一致的命名对。

DrawEllipse 仅客户端

public void DrawEllipse(PointF center, float radiusX, float radiusY)

绘制椭圆轮廓

• center — 椭圆中心坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

只绘制椭圆的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 这是DrawEllipse方法的重载版本，使用PointF结构体表示中心点，提供更简洁的API。 等价于StrokeEllipse，推荐使用StrokeEllipse以与FillEllipse形成一致的命名对。

DrawEllipseAtCenter 仅客户端

public void DrawEllipseAtCenter(float centerX, float centerY, float radiusX, float radiusY)

在指定中心点绘制椭圆轮廓（AI友好的明确方法）

• centerX — 椭圆中心的X坐标
• centerY — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

⚠️ 此方法使用中心坐标系统（中心点+半径）。 这是DrawEllipse方法的语义明确版本，方法名清晰表明使用中心坐标，避免AI混淆。 轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等效于DrawEllipse(centerX, centerY, radiusX, radiusY)。

DrawEllipseInBounds 仅客户端

public void DrawEllipseInBounds(float x, float y, float width, float height)

在矩形边界内绘制椭圆轮廓（包围盒方式，AI友好）

• x — 椭圆包围盒左上角的X坐标
• y — 椭圆包围盒左上角的Y坐标
• width — 椭圆包围盒的宽度
• height — 椭圆包围盒的高度

备注

⚠️ 此方法使用包围盒坐标系统（左上角+宽高），与DrawRectangle保持一致。 这种方式与Java AWT、GDI+等传统图形API的drawOval/DrawEllipse方法兼容。 轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 椭圆将内接于由(x, y, width, height)定义的矩形区域中。 如需使用中心坐标，请使用DrawEllipse或DrawEllipseAtCenter方法。

FillCircle 仅客户端

public void FillCircle(float centerX, float centerY, float radius)

绘制填充的圆形

• centerX — 圆心的X坐标
• centerY — 圆心的Y坐标
• radius — 圆的半径

备注

绘制实心圆形。填充颜色由FillPaint属性决定

FillEllipse 仅客户端

public void FillEllipse(float centerX, float centerY, float radiusX, float radiusY)

绘制填充的椭圆

• centerX — 椭圆中心的X坐标
• centerY — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

绘制实心椭圆。填充颜色由FillPaint属性决定。 椭圆通过指定不同的X轴和Y轴半径来创建，当两个半径相等时等效于圆形。 椭圆的轴与坐标轴平行，如需旋转椭圆请结合变换方法使用。 此方法特别适用于创建自然的形状，如云朵、鸟类身体、眼睛等有机形状。

FillEllipse 仅客户端

public void FillEllipse(PointF center, float radiusX, float radiusY)

绘制填充的椭圆

• center — 椭圆中心坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

绘制实心椭圆。填充颜色由FillPaint属性决定。 这是FillEllipse方法的重载版本，使用PointF结构体表示中心点，提供更简洁的API。 特别适合在AI代码生成场景中使用，减少参数传递的复杂性。

FillEllipseAtCenter 仅客户端

public void FillEllipseAtCenter(float centerX, float centerY, float radiusX, float radiusY)

在指定中心点绘制填充的椭圆（AI友好的明确方法）

• centerX — 椭圆中心的X坐标
• centerY — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

⚠️ 此方法使用中心坐标系统（中心点+半径）。 这是FillEllipse方法的语义明确版本，方法名清晰表明使用中心坐标，避免AI混淆。 填充颜色由FillPaint属性决定。 等效于FillEllipse(centerX, centerY, radiusX, radiusY)。

FillEllipseInBounds 仅客户端

public void FillEllipseInBounds(float x, float y, float width, float height)

在矩形边界内绘制填充的椭圆（包围盒方式，AI友好）

• x — 椭圆包围盒左上角的X坐标
• y — 椭圆包围盒左上角的Y坐标
• width — 椭圆包围盒的宽度
• height — 椭圆包围盒的高度

备注

⚠️ 此方法使用包围盒坐标系统（左上角+宽高），与FillRectangle保持一致。 这种方式与Java AWT、GDI+等传统图形API的fillOval/FillEllipse方法兼容。 填充颜色由FillPaint属性决定。 椭圆将内接于由(x, y, width, height)定义的矩形区域中。 如需使用中心坐标，请使用FillEllipse或FillEllipseAtCenter方法。

DrawEllipse 仅客户端

public void DrawEllipse(float x, float y, float radiusX, float radiusY, float rotation, float startAngle, float endAngle, bool anticlockwise = false)

绘制椭圆弧轮廓（HTML5 Canvas API兼容版本）

• x — 椭圆中心的X坐标
• y — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径
• rotation — 椭圆旋转角度（以度为单位），顺时针方向
• startAngle — 起始角度（以度为单位），从正X轴开始测量
• endAngle — 结束角度（以度为单位），从正X轴开始测量
• anticlockwise — 是否逆时针绘制（默认为false，即顺时针）

备注

此方法与HTML5 Canvas API的ellipse()方法兼容，支持绘制完整椭圆或椭圆弧。 当startAngle为0且endAngle为360时，绘制完整椭圆。 rotation参数允许旋转整个椭圆，适用于绘制任意方向的椭圆弧。 轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 注意：此方法使用度数制而非弧度制，与HTML5原生API（使用弧度）不同。

DrawEllipse 仅客户端

public void DrawEllipse(PointF center, float radiusX, float radiusY, float rotation, float startAngle, float endAngle, bool anticlockwise = false)

绘制椭圆弧轮廓（HTML5 Canvas API兼容版本，使用PointF）

• center — 椭圆中心坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径
• rotation — 椭圆旋转角度（以度为单位），顺时针方向
• startAngle — 起始角度（以度为单位），从正X轴开始测量
• endAngle — 结束角度（以度为单位），从正X轴开始测量
• anticlockwise — 是否逆时针绘制（默认为false，即顺时针）

备注

此方法是DrawEllipse的重载版本，使用PointF结构体表示中心点。 其他行为与主方法完全一致。

FillEllipse 仅客户端

public void FillEllipse(float x, float y, float radiusX, float radiusY, float rotation, float startAngle, float endAngle, bool anticlockwise = false)

填充椭圆弧（HTML5 Canvas API兼容版本）

• x — 椭圆中心的X坐标
• y — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径
• rotation — 椭圆旋转角度（以度为单位），顺时针方向
• startAngle — 起始角度（以度为单位），从正X轴开始测量
• endAngle — 结束角度（以度为单位），从正X轴开始测量
• anticlockwise — 是否逆时针绘制（默认为false，即顺时针）

备注

此方法与HTML5 Canvas API的ellipse()方法兼容，支持填充完整椭圆或椭圆弧扇形。 当startAngle为0且endAngle为360时，填充完整椭圆。 当绘制椭圆弧时，会自动封闭路径（从弧的终点连线到中心点，再连回起点），形成扇形区域进行填充。 rotation参数允许旋转整个椭圆，适用于绘制任意方向的椭圆弧扇形。 填充颜色由FillPaint属性决定。 注意：此方法使用度数制而非弧度制，与HTML5原生API（使用弧度）不同。

FillEllipse 仅客户端

public void FillEllipse(PointF center, float radiusX, float radiusY, float rotation, float startAngle, float endAngle, bool anticlockwise = false)

填充椭圆弧（HTML5 Canvas API兼容版本，使用PointF）

• center — 椭圆中心坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径
• rotation — 椭圆旋转角度（以度为单位），顺时针方向
• startAngle — 起始角度（以度为单位），从正X轴开始测量
• endAngle — 结束角度（以度为单位），从正X轴开始测量
• anticlockwise — 是否逆时针绘制（默认为false，即顺时针）

备注

此方法是FillEllipse的重载版本，使用PointF结构体表示中心点。 其他行为与主方法完全一致。

FillTriangle 仅客户端

public void FillTriangle(float x1, float y1, float x2, float y2, float x3, float y3)

绘制填充的三角形

• x1 — 第一个顶点的X坐标
• y1 — 第一个顶点的Y坐标
• x2 — 第二个顶点的X坐标
• y2 — 第二个顶点的Y坐标
• x3 — 第三个顶点的X坐标
• y3 — 第三个顶点的Y坐标

备注

绘制实心三角形。填充颜色由FillPaint属性决定

FillRectangle 仅客户端

public void FillRectangle(float x, float y, float width, float height)

绘制填充的矩形

• x — 矩形左上角的X坐标
• y — 矩形左上角的Y坐标
• width — 矩形的宽度
• height — 矩形的高度

备注

绘制实心矩形。填充颜色由FillPaint属性决定

DrawRoundedRectangle 仅客户端

public void DrawRoundedRectangle(float x, float y, float width, float height, float cornerRadius)

绘制圆角矩形轮廓

• x — 矩形左上角的X坐标
• y — 矩形左上角的Y坐标
• width — 矩形的宽度
• height — 矩形的高度
• cornerRadius — 圆角半径

备注

只绘制圆角矩形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等价于StrokeRoundedRectangle，推荐使用StrokeRoundedRectangle以与FillRoundedRectangle形成一致的命名对。

FillRoundedRectangle 仅客户端

public void FillRoundedRectangle(float x, float y, float width, float height, float cornerRadius)

绘制填充的圆角矩形

• x — 矩形左上角的X坐标
• y — 矩形左上角的Y坐标
• width — 矩形的宽度
• height — 矩形的高度
• cornerRadius — 圆角半径

备注

绘制实心圆角矩形。填充颜色由FillPaint属性决定

ClipRect 仅客户端

public void ClipRect(float x, float y, float width, float height)

设置矩形裁剪区域

• x — 裁剪矩形左上角的X坐标
• y — 裁剪矩形左上角的Y坐标
• width — 裁剪矩形的宽度
• height — 裁剪矩形的高度

备注

设置一个矩形裁剪区域，只有在此区域内的绘制内容才会显示。 此操作会影响后续所有的绘制操作，直到调用ResetState()或设置新的裁剪区域。 裁剪区域可以用来创建窗口效果或限制绘制范围。

SubtractFromClip 仅客户端

public void SubtractFromClip(float x, float y, float width, float height)

从当前裁剪区域中移除指定的矩形区域

• x — 要移除的矩形左上角X坐标
• y — 要移除的矩形左上角Y坐标
• width — 要移除的矩形宽度
• height — 要移除的矩形高度

备注

此方法从当前的裁剪区域中减去指定的矩形，创建一个镂空效果。 在被减去的区域内，后续的绘制操作将不会显示。 这可以用来创建复杂的裁剪形状或遮罩效果。

Rotate 仅客户端

public void Rotate(float degrees)

旋转画布坐标系

• degrees — 旋转角度（以度为单位）

备注

围绕原点旋转画布坐标系。正值表示顺时针旋转，负值表示逆时针旋转。 此变换会影响后续所有绘制操作的坐标。 ⚠️ 注意：此方法使用角度制（度数）

RotateDegrees 仅客户端

public void RotateDegrees(float degrees)

以度为单位旋转画布坐标系（AI友好的明确方法）

• degrees — 旋转角度，以度为单位（0-360度）

备注

这是Rotate方法的语义明确版本，专门标明使用角度制。 围绕原点旋转画布坐标系。正值表示顺时针旋转，负值表示逆时针旋转。 角度会自动标准化到合理范围内，避免过大的数值。 对于AI代码生成场景，此方法比Rotate()更加语义明确，避免角度制/弧度制混淆。

RotateRadians 仅客户端

public void RotateRadians(float radians)

以弧度为单位旋转画布坐标系（AI友好的明确方法）

• radians — 旋转角度，以弧度为单位（0到2π弧度）

备注

使用弧度制旋转画布坐标系，更适合数学计算。 围绕原点旋转画布坐标系。正值表示顺时针旋转，负值表示逆时针旋转。 1弧度 ≈ 57.3度，π弧度 = 180度，2π弧度 = 360度。 对于AI代码生成场景，此方法提供明确的弧度制接口，避免与角度制混淆。

Scale 仅客户端

public new void Scale(float scaleX, float scaleY)

缩放画布坐标系

• scaleX — X轴缩放因子
• scaleY — Y轴缩放因子

备注

缩放画布坐标系。值大于1会放大，值小于1会缩小。 此变换会影响后续所有绘制操作的尺寸和位置。 使用new关键字隐藏基类的Scale方法。

Translate 仅客户端

public void Translate(float deltaX, float deltaY)

平移画布坐标系

• deltaX — X轴平移距离
• deltaY — Y轴平移距离

备注

平移画布坐标系原点。正值向右/向下移动，负值向左/向上移动。 此变换会影响后续所有绘制操作的位置。

Transform 仅客户端

public void Transform(float a, float b, float c, float d, float e, float f)

应用2D变换矩阵

• a — 变换矩阵的m11分量（X轴缩放）
• b — 变换矩阵的m12分量（X轴倾斜）
• c — 变换矩阵的m21分量（Y轴倾斜）
• d — 变换矩阵的m22分量（Y轴缩放）
• e — 变换矩阵的m31分量（X轴平移）
• f — 变换矩阵的m32分量（Y轴平移）

备注

应用一个3x2仿射变换矩阵到画布坐标系。 变换矩阵的格式为: [ a c e ] [ x ] [ b d f ] × [ y ] [ 0 0 1 ] [ 1 ] 此方法会与当前变换矩阵相乘，实现复合变换效果。

ConcatenateTransform 仅客户端

public void ConcatenateTransform(Matrix3x2 transform)

连接指定的变换矩阵到当前变换

• transform — 要连接的3x2变换矩阵

备注

将指定的变换矩阵与当前的变换矩阵相乘，实现复合变换。 新的变换会应用到当前变换之后，影响后续所有的绘制操作。 这是应用复杂变换（如组合旋转、缩放、平移）的推荐方法。

ResetTransform 仅客户端

public void ResetTransform()

重置变换矩阵为单位矩阵

备注

将当前的变换矩阵重置为单位矩阵，取消所有的旋转、缩放和平移变换。 调用此方法后，坐标系将恢复到初始状态。 这对于在应用临时变换后恢复原始坐标系很有用。

SaveState 仅客户端

public void SaveState()

保存当前画布状态到状态栈

备注

将当前的画布状态（包括变换矩阵、裁剪区域、绘制属性等）推入状态栈。 保存的状态可以通过调用RestoreState()方法恢复。 状态栈支持嵌套保存，后保存的状态会先恢复（LIFO原则）。 这对于在局部区域应用临时设置后恢复原始状态很有用。

RestoreState 仅客户端

public void RestoreState()

从状态栈恢复之前保存的画布状态

备注

从状态栈中弹出最近保存的画布状态并应用到当前画布。 恢复的状态包括变换矩阵、裁剪区域、绘制属性等所有画布设置。 必须与SaveState()方法配对使用，确保状态栈平衡。 如果状态栈为空时调用此方法，行为是未定义的。

ResetState 仅客户端

public void ResetState()

重置画布状态

备注

清除画布上的所有绘制内容，并重置坐标变换状态，但不会重置状态栈

DrawSquare 仅客户端

public void DrawSquare(float x, float y, float size)

绘制正方形轮廓

• x — 正方形左上角的X坐标
• y — 正方形左上角的Y坐标
• size — 正方形的边长

备注

这是StrokeRectangle方法的便利版本，专门用于绘制正方形。 轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 等价于StrokeSquare，推荐使用StrokeSquare以与FillSquare形成一致的命名对。

FillSquare 仅客户端

public void FillSquare(float x, float y, float size)

绘制填充的正方形

• x — 正方形左上角的X坐标
• y — 正方形左上角的Y坐标
• size — 正方形的边长

备注

这是FillRectangle方法的便利版本，专门用于绘制实心正方形。 填充颜色由FillPaint属性决定。 此方法对AI代码生成特别友好，语义更清晰，参数更简单。

StrokeCircle 仅客户端

public void StrokeCircle(float centerX, float centerY, float radius)

绘制圆形轮廓

• centerX — 圆心的X坐标
• centerY — 圆心的Y坐标
• radius — 圆的半径

备注

只绘制圆形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillCircle形成一致的Stroke/Fill命名对。

StrokeCircle 仅客户端

public void StrokeCircle(PointF center, float radius)

绘制圆形轮廓

• center — 圆心坐标
• radius — 圆的半径

备注

只绘制圆形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillCircle形成一致的Stroke/Fill命名对。

StrokeTriangle 仅客户端

public void StrokeTriangle(float x1, float y1, float x2, float y2, float x3, float y3)

绘制三角形轮廓

• x1 — 第一个顶点的X坐标
• y1 — 第一个顶点的Y坐标
• x2 — 第二个顶点的X坐标
• y2 — 第二个顶点的Y坐标
• x3 — 第三个顶点的X坐标
• y3 — 第三个顶点的Y坐标

备注

通过连接三个顶点来绘制三角形轮廓。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillTriangle形成一致的Stroke/Fill命名对。

StrokeRectangle 仅客户端

public void StrokeRectangle(float x, float y, float width, float height)

绘制矩形轮廓

• x — 矩形左上角的X坐标
• y — 矩形左上角的Y坐标
• width — 矩形的宽度
• height — 矩形的高度

备注

只绘制矩形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillRectangle形成一致的Stroke/Fill命名对。

StrokeEllipse 仅客户端

public void StrokeEllipse(float centerX, float centerY, float radiusX, float radiusY)

绘制椭圆轮廓

• centerX — 椭圆中心的X坐标
• centerY — 椭圆中心的Y坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

只绘制椭圆的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 椭圆通过指定不同的X轴和Y轴半径来创建，当两个半径相等时等效于圆形。 与FillEllipse形成一致的Stroke/Fill命名对。

StrokeEllipse 仅客户端

public void StrokeEllipse(PointF center, float radiusX, float radiusY)

绘制椭圆轮廓

• center — 椭圆中心坐标
• radiusX — 椭圆的X轴半径
• radiusY — 椭圆的Y轴半径

备注

只绘制椭圆的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillEllipse形成一致的Stroke/Fill命名对。

StrokeSquare 仅客户端

public void StrokeSquare(float x, float y, float size)

绘制正方形轮廓

• x — 正方形左上角的X坐标
• y — 正方形左上角的Y坐标
• size — 正方形的边长

备注

这是StrokeRectangle方法的便利版本，专门用于绘制正方形。 轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillSquare形成一致的Stroke/Fill命名对。

StrokeRoundedRectangle 仅客户端

public void StrokeRoundedRectangle(float x, float y, float width, float height, float cornerRadius)

绘制圆角矩形轮廓

• x — 矩形左上角的X坐标
• y — 矩形左上角的Y坐标
• width — 矩形的宽度
• height — 矩形的高度
• cornerRadius — 圆角半径

备注

只绘制圆角矩形的轮廓，不填充内部。轮廓颜色由StrokePaint属性决定，线宽由StrokeWidth属性决定。 与FillRoundedRectangle形成一致的Stroke/Fill命名对。

SetColors 仅客户端

public void SetColors(Color fillColor, Color strokeColor)

同时设置填充和描边颜色

• fillColor — 填充颜色
• strokeColor — 描边颜色

备注

这是一个便利方法，同时设置FillPaint和StrokePaint为指定的实心颜色。 减少了AI代码生成时的重复操作，提高了代码的可读性。 此方法会创建新的SolidPaint实例，适合快速设置基本颜色。

FontFaceId 仅客户端

public void FontFaceId(int fontId)

通过字体ID设置当前字体

• fontId — 字体ID（通过CreateFont或FindFont获取）

备注

使用字体ID设置当前绘制文本使用的字体。 字体ID是通过CreateFont创建字体或FindFont查找已加载字体获得的。 使用字体ID比字体名称更高效，适合频繁切换字体的场景。

FontFace 仅客户端

public void FontFace(string fontName)

通过字体名称设置当前字体

• fontName — 字体名称

备注

使用字体名称设置当前绘制文本使用的字体。 字体名称必须是之前通过CreateFont加载的字体名称。 此方法比FontFaceId稍慢，但更直观易用。

DrawText 仅客户端

public float DrawText(float x, float y, string text)

在指定位置绘制文本

• x — 文本起始位置的X坐标
• y — 文本基线的Y坐标
• text — 要绘制的文本内容

返回： 文本的前进宽度（以像素为单位）

备注

在指定位置绘制单行文本。 文本颜色由FillPaint属性决定。 Y坐标对应文本的基线位置，具体显示位置取决于TextAlign设置。 返回值是文本的前进宽度，可用于计算下一个文本的起始位置。 ⚠️ 在 OnRender 外调用时，文本仍会被正常绘制（指令会队列化到下一帧提交）， 但返回值（前进宽度）将不正确。如需使用返回值，请在 OnRender 回调中调用。

DrawTextBox 仅客户端

public void DrawTextBox(float x, float y, float breakRowWidth, string text)

在指定位置绘制多行文本框

• x — 文本框左上角的X坐标
• y — 文本框左上角的Y坐标
• breakRowWidth — 文本换行的最大宽度
• text — 要绘制的文本内容

备注

在指定区域内绘制多行文本，文本会自动换行。 文本颜色由FillPaint属性决定。 当文本宽度超过breakRowWidth时，会自动在合适的位置（如空格）换行。 行间距由LineHeight设置控制。 可在 OnRender 外调用，文本绘制指令会队列化到下一帧提交。

MeasureText 仅客户端

public (float advance, RectangleF bounds) MeasureText(float x, float y, string text)

计算文本的边界框和前进宽度

• x — 文本起始位置的X坐标
• y — 文本基线的Y坐标
• text — 要测量的文本内容

返回： 包含文本前进宽度和边界框的元组

备注

测量文本的尺寸和位置信息，不实际绘制文本。 返回的advance是文本的前进宽度，bounds是文本的实际边界框。 边界框包含文本的实际渲染区域，可能与前进宽度不同。 此方法对于文本布局和碰撞检测很有用。 ⚠️ 此方法必须在 OnRender 回调中调用才能获得正确的返回值。 在 OnRender 外调用时返回值将不正确（度量依赖底层渲染上下文状态）。

MeasureTextBox 仅客户端

public RectangleF MeasureTextBox(float x, float y, float breakRowWidth, string text)

计算多行文本框的边界框

• x — 文本框左上角的X坐标
• y — 文本框左上角的Y坐标
• breakRowWidth — 文本换行的最大宽度
• text — 要测量的文本内容

返回： 文本框的边界矩形

备注

测量多行文本框的边界，不实际绘制文本。 返回的边界框包含所有换行后的文本行。 此方法对于计算文本区域大小和实现文本容器很有用。 ⚠️ 此方法必须在 OnRender 回调中调用才能获得正确的返回值。 在 OnRender 外调用时返回值将不正确（度量依赖底层渲染上下文状态）。

GetTextMetrics 仅客户端

public TextMetrics? GetTextMetrics()

获取当前字体的度量信息

返回： 包含字体度量信息的 TextMetrics 对象；如果不在渲染状态中则返回 null

备注

返回当前字体的度量信息，包括ascender、descender和lineHeight。 Ascender: 字体基线以上的高度 Descender: 字体基线以下的深度（通常为负值） LineHeight: 推荐的行高 这些信息对于精确的文本布局和对齐很重要。 ⚠️ 此方法必须在 OnRender 回调中调用。 在 OnRender 外调用将返回 null 并记录警告（度量依赖底层渲染上下文状态）。

CreateFont 仅客户端

public static int CreateFont(string name, string filename)

创建字体（全局共享资源）

• name — 字体名称（用于后续引用）
• filename — 字体文件路径

返回： 字体ID（-1表示失败）

备注

从文件加载字体并为其分配一个名称和ID。 字体资源在所有Canvas实例之间共享，无需为每个Canvas重复加载。 字体名称可用于FontFace方法，字体ID可用于FontFaceId方法。 支持TrueType (.ttf)和OpenType (.otf)字体格式。 如果加载失败，返回-1。 ⚠️ 此方法是静态方法，字体加载后全局可用。

FindFont 仅客户端

public static int FindFont(string name)

查找已加载的字体（全局共享资源）

• name — 字体名称

返回： 字体ID（-1表示未找到）

备注

查找之前通过CreateFont加载的字体。 如果字体存在，返回其ID；否则返回-1。 此方法可用于检查字体是否已加载，避免重复加载。 ⚠️ 此方法是静态方法，查找全局字体资源。

AddFallbackFontId 仅客户端

public static void AddFallbackFontId(int baseFont, int fallbackFont)

通过字体ID添加备用字体（全局设置）

• baseFont — 基础字体ID
• fallbackFont — 备用字体ID

备注

为基础字体添加一个备用字体。 当基础字体中缺少某个字形时，会尝试使用备用字体。 这对于支持多语言文本或特殊字符（如表情符号）很有用。 可以为一个基础字体添加多个备用字体，它们会按添加顺序依次查找。 ⚠️ 此方法是静态方法，备用字体设置全局生效。

AddFallbackFont 仅客户端

public static void AddFallbackFont(string baseFont, string fallbackFont)

通过字体名称添加备用字体（全局设置）

• baseFont — 基础字体名称
• fallbackFont — 备用字体名称

备注

为基础字体添加一个备用字体（使用字体名称）。 当基础字体中缺少某个字形时，会尝试使用备用字体。 这对于支持多语言文本或特殊字符（如表情符号）很有用。 可以为一个基础字体添加多个备用字体，它们会按添加顺序依次查找。 ⚠️ 此方法是静态方法，备用字体设置全局生效。

DrawPath 仅客户端

public void DrawPath(PathF path)

绘制完整路径的轮廓

• path — 要绘制的路径对象

备注

根据PathF对象中定义的路径操作序列绘制完整的路径轮廓。 支持的路径操作包括：移动、直线、二次贝塞尔曲线、三次贝塞尔曲线、圆弧和路径闭合。 如果路径为空或包含0个操作，则不执行任何绘制。 绘制使用当前的StrokePaint和StrokeWidth设置。

FillPath 仅客户端

public void FillPath(PathF path, WindingMode? windingMode = null)

填充路径

• path — 要填充的路径对象
• windingMode — 可选的路径缠绕模式，为null时使用DefaultPathWinding

备注

根据PathF对象中定义的路径操作序列填充封闭区域。 支持的路径操作包括：移动、直线、二次贝塞尔曲线、三次贝塞尔曲线、圆弧和路径闭合。 如果路径为空或包含0个操作，则不执行任何填充。 填充使用当前的FillPaint设置。 缠绕模式决定了复杂路径的填充规则： NonZero: 非零缠绕规则，适用于大多数普通形状 EvenOdd: 奇偶规则，常用于创建镂空效果 如果提供了windingMode参数，会临时使用该模式进行填充，之后恢复到DefaultPathWinding。

DrawTexture 仅客户端

public void DrawTexture(Texture2D texture, float x, float y)

Draws a Texture2D at its original size.

DrawTexture 仅客户端

public void DrawTexture(Texture2D texture, float x, float y, float width, float height)

Draws a Texture2D into a destination rectangle.

DrawTexture 仅客户端

public void DrawTexture(Texture2D texture, float sourceX, float sourceY, float sourceWidth, float sourceHeight, float x, float y, float width, float height)

Draws a clipped source rectangle from a Texture2D into a destination rectangle.

DrawTexture 仅客户端

public void DrawTexture(Texture2D texture, RectangleF sourceRect, RectangleF destRect)

Draws a clipped source rectangle from a Texture2D into a destination rectangle.

DisposeManaged 仅客户端

protected override void DisposeManaged()

释放Canvas特定的托管资源

备注

此方法重写基类的DisposeManaged方法，用于释放Canvas特有的资源。 主要执行以下清理操作： 清理Canvas特定的事件订阅 调用基类的DisposeManaged方法 继承类如需额外的资源清理，应重写此方法并确保调用base.DisposeManaged()。

事件

OnRender 仅客户端

public event EventHandler? OnRender

CanvasAnimated 仅客户端

命名空间 GameUI.Control.Primitive

public class CanvasAnimated : Canvas, IGameObject<GameDataControlCanvasAnimated>, IGameObject

动画画布控件类，继承自Canvas，提供动画相关的时间信息

备注

CanvasAnimated扩展了Canvas的功能，为动画开发提供便利： 提供帧间隔时间（DeltaTime）用于实现帧率无关的动画 提供自画布开始计时以来的总时间 支持自定义计时起点，适应游戏重开等场景 如果动画画布永久不再使用，应调用 Destroy 释放控件和底层渲染资源；不要只调用 RemoveFromParent。

构造函数

CanvasAnimated 仅客户端

public CanvasAnimated(IGameLink<GameDataControlCanvasAnimated> link)

使用指定的游戏链接初始化CanvasAnimated实例

• link — 指向GameDataControlCanvasAnimated数据的游戏链接

CanvasAnimated 仅客户端

public CanvasAnimated()

使用默认模板初始化CanvasAnimated实例

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlCanvasAnimated> DefaultTemplate { get; }

获取CanvasAnimated控件的默认模板链接

StartingTickOffsetInMilliseconds 仅客户端

public int StartingTickOffsetInMilliseconds { get; set; }

获取或设置计时起点偏移量（毫秒）

备注

此属性记录了画布开始计时时游戏客户端的时间戳。 通过调用StartTiming()方法可以重置此值。

TotalElapsedTimeInMilliseconds 仅客户端

public int TotalElapsedTimeInMilliseconds { get; }

获取自画布开始计时以来的总时间（毫秒）

TotalElapsedTimeInSeconds 仅客户端

public float TotalElapsedTimeInSeconds { get; }

获取自画布开始计时以来的总时间（秒）

Link 仅客户端

public new IGameLink<GameDataControlCanvasAnimated> Link { get; }

Cache 仅客户端

public new GameDataControlCanvasAnimated Cache { get; }

方法

StartTiming 仅客户端

public void StartTiming(int startTimeInMilliseconds = 0, AnimationStartTimeSetType startTimeSetType = AnimationStartTimeSetType.FromCurrentTime)

开始计时

• startTimeInMilliseconds — 起始时间偏移量（毫秒）
• startTimeSetType — 起始时间设置类型

备注

根据 的不同， 的含义也不同： FromCurrentTime：从当前时间开始计时， 为偏移量（正值表示从过去开始，负值表示延迟开始） FromBeginning：从绝对时间0开始计时， 为绝对起始时间

StartTimingDelayed 仅客户端

public void StartTimingDelayed(int delayInMilliseconds)

延迟指定时间后开始计时

• delayInMilliseconds — 延迟时间（毫秒），必须为正值

备注

在延迟时间结束前，OnAnimatedRender事件不会触发。 延迟结束后，TotalElapsedTimeInMilliseconds将从0开始计算。 此方法等效于 StartTiming(-delayInMilliseconds)。

DrawAnimatedImage 仅客户端

public void DrawAnimatedImage(IAnimatedImageSource animatedImageSource, float x, float y)

在指定位置绘制帧动画到画布

• animatedImageSource — 帧动画源
• x — 绘制位置的X坐标
• y — 绘制位置的Y坐标

备注

此方法使用画布的计时系统自动计算当前应显示的帧。 动画将以其原点（由帧的Pivot决定）为基准绘制在指定位置。

DisposeManaged 仅客户端

protected override void DisposeManaged()

事件

OnAnimatedRender 仅客户端

public event EventHandler<CanvasAnimatedEventArgs>? OnAnimatedRender

动画渲染事件，提供帧间隔时间和总计时信息

备注

与基类OnRender事件不同，此事件提供CanvasAnimatedEventArgs参数， 包含动画开发所需的时间信息。 注意：若TotalElapsedTimeInMilliseconds为负（计时尚未开始），此事件不会触发。 可通过Int32)方法延迟渲染开始时间。 取消订阅所有处理器会关闭底层渲染回调；调用 Destroy 时也会自动清理该事件。

Input 仅客户端

命名空间 GameUI.Control.Primitive

public class Input : Control, ITextControl, IGameObject<GameDataControlInput>, IGameObject

表示 UI 输入框控件。

构造函数

Input 仅客户端

public Input(IGameLink<GameDataControlInput> link)

使用指定模板链接初始化输入框实例。

• link — 输入框模板数据链接。

Input 仅客户端

public Input()

使用默认模板初始化输入框实例。

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlInput> DefaultTemplate { get; }

获取输入框的默认模板链接。

Text 仅客户端

public string? Text { get; set; }

Font 仅客户端

public UTF8String Font { get; set; }

FontSize 仅客户端

public float FontSize { get; set; }

设计坐标中的字号，随 ScreenViewport 的全局缩放换算到屏幕像素。

TextColor 仅客户端

public Color TextColor { get; set; }

Bold 仅客户端

public bool Bold { get; set; }

Italic 仅客户端

public bool Italic { get; set; }

Link 仅客户端

public new IGameLink<GameDataControlInput> Link { get; }

Cache 仅客户端

public new GameDataControlInput Cache { get; }

方法

DisposeManaged 仅客户端

protected override void DisposeManaged()

事件

OnInputTextChanged 仅客户端

public event EventHandler<InputEventArgs>? OnInputTextChanged

OnGotFocus 仅客户端

public event EventHandler? OnGotFocus

OnLostFocus 仅客户端

public event EventHandler? OnLostFocus

OnInputKeyDown 仅客户端

public event EventHandler<InputKeyEventArgs>? OnInputKeyDown

在输入框获得焦点的前提下，按下键盘按键时触发。

备注

注意：此事件与全局键盘事件 OnKeyDown 不同，专门用于输入框控件。 输入框在进行输入时会屏蔽全局按键事件，只有此事件会触发。

OnInputKeyUp 仅客户端

public event EventHandler<InputKeyEventArgs>? OnInputKeyUp

在输入框获得焦点的前提下，松开键盘按键时触发。

备注

注意：此事件与全局键盘事件 OnKeyUp 不同，专门用于输入框控件。 输入框在进行输入时会屏蔽全局按键事件，只有此事件会触发。

Label 仅客户端

命名空间 GameUI.Control.Primitive

public class Label : Control, ITextControl, IGameObject<GameDataControlLabel>, IGameObject

表示 UI 文本标签控件。

备注

文字对齐方式设置： Label 控件提供两套对齐属性来控制不同层面的对齐效果： 控件位置对齐 使用 HorizontalAlignment 和 VerticalAlignment 来控制 Label 控件本身在父容器中的位置。 文字内容对齐 使用 HorizontalContentAlignment 和 VerticalContentAlignment 来控制文字在 Label 控件内部的对齐方式。这是设置文字左对齐、居中、右对齐的正确方法。 示例用法： var titleLabel = new Label() { Text = "标题文本", // 控件在父容器中居中 HorizontalAlignment = HorizontalAlignment.Center, VerticalAlignment = VerticalAlignment.Top, // 文字在Label内部居中显示 HorizontalContentAlignment = HorizontalContentAlignment.Center, VerticalContentAlignment = VerticalContentAlignment.Center }; var leftAlignedLabel = new Label() { Text = "左对齐文本", // 文字在Label内部左对齐 HorizontalContentAlignment = HorizontalContentAlignment.Left, VerticalContentAlignment = VerticalContentAlignment.Top };

构造函数

Label 仅客户端

public Label(IGameLink<GameDataControlLabel> link)

使用指定模板链接初始化标签实例。

• link — 标签模板数据链接。

Label 仅客户端

public Label()

使用默认模板初始化标签实例。

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlLabel> DefaultTemplate { get; }

获取标签的默认模板链接。

Text 仅客户端

public string? Text { get; set; }

获取或设置标签显示的文本内容。

备注

支持以下富文本标签： <b>粗体</b><i>斜体</i><u>下划线</u><color value="#RRGGBB">颜色</color>，也支持 #RRGGBBAA 透明度格式 <br/> 换行 <link id="link_id">可点击文本</link>，点击时触发 OnLinkClicked 标签可以嵌套使用。该语法是 Label 支持的富文本标记子集，并非完整 HTML。 要控制文本的对齐方式，请使用以下属性： HorizontalContentAlignment - 控制文字的水平对齐（左对齐、居中、右对齐） VerticalContentAlignment - 控制文字的垂直对齐（顶部、居中、底部对齐） 注意：HorizontalAlignment 和 VerticalAlignment 控制的是 Label 控件本身在父容器中的位置， 而非文字在 Label 内部的对齐方式。

Font 仅客户端

public UTF8String Font { get; set; }

FontSize 仅客户端

public float FontSize { get; set; }

设计坐标中的字号，随 ScreenViewport 的全局缩放换算到屏幕像素。

TextColor 仅客户端

public Color TextColor { get; set; }

LineSpacingRatio 仅客户端

public float LineSpacingRatio { get; set; }

TextWrap 仅客户端

public bool TextWrap { get; set; }

Bold 仅客户端

public bool Bold { get; set; }

Italic 仅客户端

public bool Italic { get; set; }

StrokeSize 仅客户端

public float StrokeSize { get; set; }

StrokeColor 仅客户端

public Color StrokeColor { get; set; }

ShadowOffset 仅客户端

public Vector2 ShadowOffset { get; set; }

ShadowColor 仅客户端

public Color ShadowColor { get; set; }

TextTrimming 仅客户端

public TextTrimming TextTrimming { get; set; }

Link 仅客户端

public new IGameLink<GameDataControlLabel> Link { get; }

Cache 仅客户端

public new GameDataControlLabel Cache { get; }

方法

DisposeManaged 仅客户端

protected override void DisposeManaged()

事件

OnLinkClicked 仅客户端

public event EventHandler<LinkClickedEventArgs>? OnLinkClicked

当用户点击标签文本中的 <link> 区域时触发。

备注

链接使用 <link id="link_id">文本</link> 声明，链接标识可通过 LinkId 获取。 点击标签中不属于链接的文本不会触发此事件。

Page 仅客户端

命名空间 GameUI.Control.Primitive

public class Page : Panel, IGameObject<GameDataControlPanel>, IGameObject

页面级根容器，语义上表示一个完整的视口页面。

备注

Page 的默认布局就是占满整个 viewport，因此不需要额外调用 FullScreen() 之类的铺满辅助方法。 如果页面内容需要滚动，请在 Page 内部放置可滚动容器， 而不是改变 Page 自身的视口语义。

构造函数

Page 仅客户端

public Page(IGameLink<GameDataControl> link)

Page 仅客户端

public Page()

Page 仅客户端

public Page(IGameLink<GameDataControlPanel> link)

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlPanel> DefaultTemplate { get; }

Link 仅客户端

public new IGameLink<GameDataControlPanel> Link { get; }

Cache 仅客户端

public new GameDataControlPanel Cache { get; }

Panel 仅客户端

命名空间 GameUI.Control.Primitive

public class Panel : Control, IGameObject<GameDataControlPanel>, IGameObject

构造函数

Panel 仅客户端

public Panel(IGameLink<GameDataControlPanel> link)

Panel 仅客户端

public Panel()

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlPanel> DefaultTemplate { get; }

Link 仅客户端

public new IGameLink<GameDataControlPanel> Link { get; }

Cache 仅客户端

public new GameDataControlPanel Cache { get; }

PanelScrollable 仅客户端

命名空间 GameUI.Control.Primitive

public class PanelScrollable : Panel, IGameObject<GameDataControlPanelScrollable>, IGameObject

构造函数

PanelScrollable 仅客户端

public PanelScrollable(IGameLink<GameDataControlPanel> link)

PanelScrollable 仅客户端

public PanelScrollable()

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlPanelScrollable> DefaultTemplate { get; }

ScrollEnabled 仅客户端

public bool ScrollEnabled { get; set; }

ScrollOrientation 仅客户端

public virtual Orientation ScrollOrientation { get; set; }

ScrollBarSize 仅客户端

public float ScrollBarSize { get; set; }

ScrollBarColor 仅客户端

public ColorBrush ScrollBarColor { get; set; }

ScrollBarValue 仅客户端

public float ScrollBarValue { get; set; }

In percentage, 0-1

Link 仅客户端

public new IGameLink<GameDataControlPanelScrollable> Link { get; }

Cache 仅客户端

public new GameDataControlPanelScrollable Cache { get; }

方法

BringItemIntoView 仅客户端

public virtual bool BringItemIntoView(int itemIndex)

DisposeManaged 仅客户端

protected override void DisposeManaged()

事件

OnScrollChangedHandler 仅客户端

protected event EventHandler<ScrollChangedEventArgs>? OnScrollChangedHandler

OnScrollChanged 仅客户端

public event EventHandler<ScrollChangedEventArgs>? OnScrollChanged

Particle 仅客户端

命名空间 GameUI.Control.Primitive

public class Particle : Control, IGameObject<GameDataControlParticle>, IGameObject

粒子特效预览控件，用于在UI中显示和控制粒子特效

备注

此控件支持粒子特效的播放控制、速度调整、缩放设置和视图模式切换等功能。 可以通过 ParticleAutoScale 属性启用自动缩放，使粒子特效自动适应控件尺寸。

构造函数

Particle 仅客户端

public Particle(IGameLink<GameDataControlParticle> link)

粒子特效预览控件，用于在UI中显示和控制粒子特效

备注

此控件支持粒子特效的播放控制、速度调整、缩放设置和视图模式切换等功能。 可以通过 ParticleAutoScale 属性启用自动缩放，使粒子特效自动适应控件尺寸。

Particle 仅客户端

public Particle()

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlParticle> DefaultTemplate { get; }

Resource 仅客户端

public UTF8String Resource { get; set; }

获取或设置粒子特效的资源路径

备注

资源路径应指向有效的粒子特效文件。更改此属性会重新加载粒子特效。

IsPlaying 仅客户端

public bool IsPlaying { get; set; }

获取或设置粒子特效是否正在播放

Speed 仅客户端

public float Speed { get; set; }

获取或设置粒子特效的播放速度

ParticleOffset 仅客户端

public PointF ParticleOffset { get; set; }

粒子显示偏移 (0-1范围，(0,0)为左上角) (0.5, 0.5) 为居中

ParticleAutoScale 仅客户端

public bool ParticleAutoScale { get; set; }

是否启用粒子自动缩放 如果启用，则粒子会根据参考尺寸和控件的实际尺寸计算出粒子缩放比例。 如果禁用，则粒子会根据ParticleScale缩放。 如果启用自动缩放，则ParticleReferenceSize必须设置。

ParticleReferenceSize 仅客户端

public SizeF ParticleReferenceSize { get; set; }

粒子自动缩放的参考尺寸，只在ParticleAutoScale为true时生效 参考尺寸是粒子相对于画布的尺寸，而不是世界尺寸。

备注

参考尺寸指的是粒子在100%缩放下时占据的画布尺寸。 控件会根据参考尺寸和控件的实际尺寸计算出粒子缩放比例。 例如，参考尺寸为100x100，控件的实际尺寸为200x300，则粒子在x轴上会缩放到2倍，在y轴上会缩放到3倍。 当使用 ParticleAutoScale 时必须设置此属性，否则粒子会不可见。

ParticleScale 仅客户端

public SizeF ParticleScale { get; set; }

粒子缩放比例，只在ParticleAutoScale为false时生效

ParticleView 仅客户端

public ParticleView ParticleView { get; set; }

获取或设置粒子特效的视图模式

Link 仅客户端

public new IGameLink<GameDataControlParticle> Link { get; }

Cache 仅客户端

public new GameDataControlParticle Cache { get; }

PlatformAdaptivePanel 仅客户端

命名空间 GameUI.Control.Primitive

public class PlatformAdaptivePanel : Panel, IGameObject<GameDataControlPlatformAdaptivePanel>, IGameObject

平台自适应面板控件，根据当前运行平台自动选择显示对应的子控件。 这种控件类型只能通过数编模版来创建，无法通过参数的构造函数来创建。

构造函数

PlatformAdaptivePanel 仅客户端

public PlatformAdaptivePanel(IGameLink<GameDataControlPanel> link)

使用指定的数据模板创建平台自适应面板控件

• link — 数据模板链接

备注

初始化时会根据当前平台选择对应的子控件并显示。 这种控件类型只能通过数编模版来创建，无法通过参数的构造函数来创建。

属性

ResultingChild 仅客户端

public Control? ResultingChild { get; }

Link 仅客户端

public new IGameLink<GameDataControlPlatformAdaptivePanel> Link { get; }

Cache 仅客户端

public new GameDataControlPlatformAdaptivePanel Cache { get; }

Progress 仅客户端

命名空间 GameUI.Control.Primitive

public class Progress : Control, IGameObject<GameDataControlProgress>, IGameObject

构造函数

Progress 仅客户端

public Progress(IGameLink<GameDataControlProgress> link)

Progress 仅客户端

public Progress()

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlProgress> DefaultTemplate { get; }

Value 仅客户端

public float Value { get; set; }

ProgressionMode 仅客户端

public ProgressionMode ProgressionMode { get; set; }

ProgressRotation 仅客户端

public float ProgressRotation { get; set; }

Only works for ProgressionMode.Clockwise and ProgressionMode.CounterClockwise, set the rotation of the progress bar fill.

Link 仅客户端

public new IGameLink<GameDataControlProgress> Link { get; }

Cache 仅客户端

public new GameDataControlProgress Cache { get; }

SpacingPanel 仅客户端

命名空间 GameUI.Control.Primitive

public class SpacingPanel : PanelScrollable, ITickFinalizer, IGameObject<GameDataSpacingPanel>, IGameObject

带间距管理的Panel，自动处理子元素的间距

构造函数

SpacingPanel 仅客户端

public SpacingPanel(IGameLink<GameDataSpacingPanel> link)

构造函数

属性

Spacing 仅客户端

public float Spacing { get; set; }

间距大小

SpacingOrientation 仅客户端

public Orientation SpacingOrientation { get; set; }

间距方向

Link 仅客户端

public new IGameLink<GameDataSpacingPanel> Link { get; }

Cache 仅客户端

public new GameDataSpacingPanel Cache { get; }

方法

AddChild 仅客户端

public override bool AddChild(Control child)

添加子控件并标记需要刷新布局

RemoveChild 仅客户端

public override bool RemoveChild(Control child)

移除子控件并标记需要刷新布局

SetSpacing 仅客户端

public void SetSpacing(float spacing, Orientation orientation)

设置间距并标记需要刷新布局

TickFinalizer 仅客户端

public void TickFinalizer()

在帧末统一刷新布局

Spine 仅客户端

命名空间 GameUI.Control.Primitive

public class Spine : Control, IGameObject<GameDataControlButton>, IGameObject

表示 UI Spine动画控件，用于在UI中渲染Spine骨骼动画。

备注

Spine控件说明： Spine控件用于在UI界面中显示Spine 2D骨骼动画，常用于角色展示、技能特效、NPC对话等场景。 版本兼容性： 当前运行时支持 Spine 4.2 资源格式，兼容 Spine 4.1 导出的资源，并额外支持 Spine 3.8 导出的 .skel 二进制资源；旧版本 .json 不在兼容范围内。 资源放置规则： Spine动画资源需要放置在项目的 ui\Spine 资源路径下。例如： ui\Spine\character\hero\hero-ess.skel ui\Spine\character\hero\hero-ess.atlas ui\Spine\character\hero\hero-ess.png 资源引用方式： 引用资源时，路径从 Spine 开始，不需要包含文件后缀。例如： var spine = new Spine(); spine.Resource = "Spine\\character\\hero\\hero-ess"; spine.Animation = "idle"; spine.Skin = "default"; spine.IsLooping = true; 流式扩展语法（推荐）： 也可以使用流式扩展语法更简洁地创建Spine控件。详见BuilderExtensions。 var spine = new Spine() .Size(200, 300) .Center() .SpineResource("Spine\\character\\hero\\hero-ess") .SpineAnimation("idle") .SpineSkin("default") .SpineLoop(); 常见使用场景： 角色选择界面 - 展示角色动画 技能特效 - 播放技能释放动画 NPC对话 - 显示NPC表情和动作 UI装饰 - 添加动态效果提升界面美观度 注意事项： Spine控件仅在客户端可用，需要使用 #if CLIENT 预处理指令 确保Spine资源文件完整（.skel、.atlas、.png） 动画名称和皮肤名称必须在Spine资源中存在 不再使用的Spine控件应调用 Dispose 释放资源

构造函数

Spine 仅客户端

public Spine(IGameLink<GameDataControlSpine> link)

表示 UI Spine动画控件，用于在UI中渲染Spine骨骼动画。

备注

Spine控件说明： Spine控件用于在UI界面中显示Spine 2D骨骼动画，常用于角色展示、技能特效、NPC对话等场景。 版本兼容性： 当前运行时支持 Spine 4.2 资源格式，兼容 Spine 4.1 导出的资源，并额外支持 Spine 3.8 导出的 .skel 二进制资源；旧版本 .json 不在兼容范围内。 资源放置规则： Spine动画资源需要放置在项目的 ui\Spine 资源路径下。例如： ui\Spine\character\hero\hero-ess.skel ui\Spine\character\hero\hero-ess.atlas ui\Spine\character\hero\hero-ess.png 资源引用方式： 引用资源时，路径从 Spine 开始，不需要包含文件后缀。例如： var spine = new Spine(); spine.Resource = "Spine\\character\\hero\\hero-ess"; spine.Animation = "idle"; spine.Skin = "default"; spine.IsLooping = true; 流式扩展语法（推荐）： 也可以使用流式扩展语法更简洁地创建Spine控件。详见BuilderExtensions。 var spine = new Spine() .Size(200, 300) .Center() .SpineResource("Spine\\character\\hero\\hero-ess") .SpineAnimation("idle") .SpineSkin("default") .SpineLoop(); 常见使用场景： 角色选择界面 - 展示角色动画 技能特效 - 播放技能释放动画 NPC对话 - 显示NPC表情和动作 UI装饰 - 添加动态效果提升界面美观度 注意事项： Spine控件仅在客户端可用，需要使用 #if CLIENT 预处理指令 确保Spine资源文件完整（.skel、.atlas、.png） 动画名称和皮肤名称必须在Spine资源中存在 不再使用的Spine控件应调用 Dispose 释放资源

Spine 仅客户端

public Spine()

使用默认模板初始化Spine控件实例。

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlSpine> DefaultTemplate { get; }

获取Spine控件的默认模板链接。

IsLooping 仅客户端

public bool IsLooping { get; set; }

获取或设置动画是否循环播放。

备注

循环播放适用于待机、行走等持续性动画。 单次播放适用于攻击、施法等一次性动画效果。 也可以使用流式扩展方法 Boolean) 设置此属性。

Resource 仅客户端

public UTF8String Resource { get; set; }

获取或设置Spine动画资源的路径。

备注

版本兼容性： 当前运行时支持 Spine 4.2 资源格式，兼容 Spine 4.1 导出的数据，并额外支持 Spine 3.8 导出的 .skel 二进制数据；旧版本 .json 不在兼容范围内。 资源放置位置： Spine动画资源需要放置在项目的 ui\Spine 资源路径下。资源包含三个文件： .skel - Spine骨骼数据文件 .atlas - 纹理图集描述文件 .png - 纹理图集图片文件 路径格式： 引用时路径从 Spine 开始，使用反斜杠 \ 分隔目录，不需要包含文件后缀。 示例： 如果资源文件位于： ui\Spine\character\hero\hero-ess.skel ui\Spine\character\hero\hero-ess.atlas ui\Spine\character\hero\hero-ess.png 则资源路径应设置为： spine.Resource = "Spine\character\hero\hero-ess"; 也可以使用流式扩展方法 String) 设置此属性。

Animation 仅客户端

public UTF8String Animation { get; set; }

获取或设置当前播放的动画名称。

备注

动画名称： 动画名称必须与Spine资源中定义的动画名称完全一致（区分大小写）。 常见的动画名称包括：idle（待机）、walk（行走）、run（奔跑）、attack（攻击）、die（死亡）等。 动画切换： 可以在运行时动态更改此属性来切换动画，切换时会立即开始播放新动画。 也可以使用流式扩展方法 String) 设置此属性。

Skin 仅客户端

public UTF8String Skin { get; set; }

获取或设置Spine动画的皮肤名称。

备注

皮肤系统： Spine的皮肤系统允许在同一骨骼动画上应用不同的外观，实现角色换装、颜色变化等效果。 皮肤名称必须与Spine资源中定义的皮肤名称完全一致（区分大小写）。 默认皮肤： 大多数Spine资源都包含一个名为 default 的默认皮肤。 动态换装： 可以在运行时动态更改此属性来切换皮肤，实现角色换装效果。 也可以使用流式扩展方法 String) 设置此属性。

Link 仅客户端

public new IGameLink<GameDataControlButton> Link { get; }

Cache 仅客户端

public new GameDataControlButton Cache { get; }

方法

GetSpineInstance 仅客户端

public SpineInstance GetSpineInstance()

获取此 Spine 控件的运行时操作对象。 通过返回的 SpineInstance 可以访问 AnimationState 和 Skeleton， 进行细粒度的动画控制、骨骼操作、事件监听等。

返回： SpineInstance 实例。多次调用返回同一对象（除非控件重建）。

备注

在设置 Resource 之后调用，否则底层 Spine 运行时尚未初始化。 简单的动画切换可直接使用 Animation 属性；需要多轨道、 事件监听、骨骼定位等高级功能时使用此方法。

Sprites 仅客户端

命名空间 GameUI.Control.Primitive

public class Sprites : Control, IGameObject<GameDataControlButton>, IGameObject

序列帧图片控件，支持单张横竖排列的 sprite sheet 图片，也支持文件夹/序列纹理中的多张子图。

备注

当 Image 指向普通图片文件时，控件按单图 sprite sheet 解释图片，需要设置 SpriteSize、FrameCount 和 RowFrameCount 才能正确切帧。 当 Image 指向文件夹序列资源时，native 侧会从子图列表推导帧数和每帧区域； 此时 SpriteSize 与 RowFrameCount 不参与切帧，FrameCount 仅作为播放上限。

构造函数

Sprites 仅客户端

public Sprites(IGameLink<GameDataControlSprites> link)

Sprites 仅客户端

public Sprites()

属性

DefaultTemplate 仅客户端

public static IGameLink<GameDataControlSprites> DefaultTemplate { get; }

IsLooping 仅客户端

public bool IsLooping { get; set; }

获取或设置动画到达结束帧后是否继续从起始帧播放。

备注

默认值为 true。设为 false 时，动画推进到 EndFrame 后停止。

IsPlaying 仅客户端

public bool IsPlaying { get; set; }

获取或设置动画是否正在播放。

备注

设为 true 会从 StartFrame 重新开始计时播放；设为 false 只停止推进，不重置当前帧。

IntervalMillisecond 仅客户端

public float IntervalMillisecond { get; set; }

获取或设置每帧之间的间隔时间，单位为毫秒。

备注

默认值为 30 毫秒。该属性与 FramePerSecond 表达同一份速度配置，后设置的值会覆盖先前的速度。

FramePerSecond 仅客户端

public float FramePerSecond { get; set; }

获取或设置播放帧率，单位为 FPS。

备注

该属性会换算并写入 IntervalMillisecond。例如 10 FPS 等价于每帧 100 毫秒。

FrameCount 仅客户端

public int FrameCount { get; set; }

获取或设置动画总帧数。

备注

普通单图 sprite sheet 模式下表示需要从图片中切出的总帧数，通常必须显式设置。 文件夹序列模式下表示最多播放的子图数量，native 侧实际值不会超过真实子图数量；空文件夹会兜底为 1 帧以避免除零。 未显式设置 EndFrame 时，设置该属性会同步把结束帧更新为 FrameCount - 1。

RowFrameCount 仅客户端

public int RowFrameCount { get; set; }

获取或设置普通单图 sprite sheet 中每一行包含的帧数。

备注

只对普通图片文件模式有意义，用于根据当前帧计算图片裁剪区域。 值为 0 表示未配置；普通图片模式下未配置该值时控件不会绘制序列帧。文件夹序列模式会忽略该值。

FramesPerRow 仅客户端

public int FramesPerRow { get; set; }

获取或设置 RowFrameCount 的可读别名。

SpriteSize 仅客户端

public Size SpriteSize { get; set; }

获取或设置普通单图 sprite sheet 中单帧的像素尺寸。

备注

只对普通图片文件模式有意义。文件夹序列模式使用每个子图资源自身记录的区域，不使用该属性切帧。

FrameSize 仅客户端

public Size FrameSize { get; set; }

获取或设置 SpriteSize 的可读别名。

StartFrame 仅客户端

public int StartFrame { get; set; }

获取或设置播放起始帧，下标从 0 开始。

备注

有效帧下标通常为 0 到 FrameCount - 1。 native 侧当前会按有效帧数对超出范围的值取模，因此建议业务代码仍传入清晰的有效下标。

EndFrame 仅客户端

public int EndFrame { get; set; }

获取或设置播放结束帧，下标从 0 开始。

备注

未显式设置时默认为 FrameCount - 1，并会在 FrameCount 改变时同步更新。 有效帧下标通常为 0 到 FrameCount - 1；native 侧当前会按有效帧数对超出范围的值取模。

Link 仅客户端

public new IGameLink<GameDataControlButton> Link { get; }

Cache 仅客户端

public new GameDataControlButton Cache { get; }

方法

ConfigureSpriteSheet 仅客户端

public Sprites ConfigureSpriteSheet(int frameWidth, int frameHeight, int frameCount, int framesPerRow)

一次性配置普通单图 sprite sheet 的单帧尺寸、总帧数和每行帧数。

• frameWidth — 单帧宽度，单位为像素。
• frameHeight — 单帧高度，单位为像素。
• frameCount — 总帧数。
• framesPerRow — 每行帧数。

返回： 当前 Sprites 实例，便于链式调用。

备注

该方法主要用于 Image("xxx.png") 这类普通图片文件路径。 文件夹序列模式不需要配置单帧尺寸和每行帧数。

ConfigureSpriteSheet 仅客户端

public Sprites ConfigureSpriteSheet(Size frameSize, int frameCount, int framesPerRow)

一次性配置普通单图 sprite sheet 的单帧尺寸、总帧数和每行帧数。

• frameSize — 单帧像素尺寸。
• frameCount — 总帧数。
• framesPerRow — 每行帧数。

返回： 当前 Sprites 实例，便于链式调用。

备注

该方法会依次设置 SpriteSize、FrameCount 和 RowFrameCount。

ConfigureFrameRange 仅客户端

public Sprites ConfigureFrameRange(int startFrame, int endFrame)

配置序列帧播放范围。

• startFrame — 起始帧下标，从 0 开始。
• endFrame — 结束帧下标，从 0 开始。

返回： 当前 Sprites 实例，便于链式调用。

备注

播放时会在该区间内推进；当 IsLooping 为 true 时，超过结束帧后回到起始帧。

Play 仅客户端

public Sprites Play()

从 StartFrame 开始播放动画。

返回： 当前 Sprites 实例，便于链式调用。

Stop 仅客户端

public Sprites Stop()

停止动画推进。

返回： 当前 Sprites 实例，便于链式调用。

备注

停止不会重置当前帧；再次调用 Play 时会从 StartFrame 开始。

Video 仅客户端

命名空间 GameUI.Control.Primitive

public class Video : Canvas, IThinker, IGameObject<GameDataControlVideo>, IGameObject

Displays a project video and owns its player and frame texture.

备注

Source is relative to res/. Loading is asynchronous. Call Destroy when finished; removing the control from its parent only detaches it. Playback buttons are composed separately.

构造函数

Video 仅客户端

public Video()

Video 仅客户端

public Video(IGameLink<GameDataControlVideo> link)

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlVideo> DefaultTemplate { get; }

Default data template.

Source 仅客户端

public string Source { get; set; }

Video path relative to res/, for example video/intro.mp4. Empty unloads the video.

备注

Changing the path cancels and disposes the previous player. Use Reload for the same path.

AutoPlay 仅客户端

public bool AutoPlay { get; set; }

Whether a newly loaded source starts playing. Default false.

PauseWhenHidden 仅客户端

public bool PauseWhenHidden { get; set; }

Pause while hidden, detached, or under a hidden parent. Default true. Reappearance resumes only playback paused by this policy; manual Pause/Stop cancel that resume.

Stretch 仅客户端

public VideoStretch Stretch { get; set; }

Frame fitting mode. Default Uniform.

IsLooping 仅客户端

public bool IsLooping { get; set; }

IsMuted 仅客户端

public bool IsMuted { get; set; }

Volume 仅客户端

public float Volume { get; set; }

Audio volume, clamped to 0 through 1.

PlaybackRate 仅客户端

public float PlaybackRate { get; set; }

Playback rate, clamped to 0.25 through 4. Audio pitch changes with rate.

State 仅客户端

public VideoViewState State { get; }

IsLoading 仅客户端

public bool IsLoading { get; }

IsPlaying 仅客户端

public bool IsPlaying { get; }

IsReady 仅客户端

public bool IsReady { get; }

LastError 仅客户端

public string LastError { get; }

Last failure description; empty after unloading or beginning a new load.

CurrentTime 仅客户端

public float CurrentTime { get; }

Playback position in seconds. Ended reports Duration.

Duration 仅客户端

public float Duration { get; }

VideoWidth 仅客户端

public int VideoWidth { get; }

VideoHeight 仅客户端

public int VideoHeight { get; }

Link 仅客户端

public new IGameLink<GameDataControlVideo> Link { get; }

Cache 仅客户端

public new GameDataControlVideo Cache { get; }

方法

Reload 仅客户端

public void Reload()

Reload the current Source, applying AutoPlay again.

Play 仅客户端

public void Play()

Play or resume. During loading, request playback when ready.

Pause 仅客户端

public void Pause()

Pause, including cancellation of automatic playback requested during loading.

Stop 仅客户端

public void Stop()

Stop and rewind. During loading, suppress automatic playback.

Seek 仅客户端

public void Seek(float seconds)

Seek in seconds. A seek during loading is applied when the source opens.

DisposeManaged 仅客户端

protected override void DisposeManaged()

事件

OnOpened 仅客户端

public event EventHandler? OnOpened

Raised when loading completes, before optional automatic playback.

OnEnded 仅客户端

public event EventHandler? OnEnded

Raised once on a transition to Ended. Loop boundaries do not raise this event.

OnFailed 仅客户端

public event EventHandler? OnFailed

Raised on loading failure. Inspect LastError.

OnStateChanged 仅客户端

public event EventHandler? OnStateChanged

VirtualizingPanel 仅客户端

命名空间 GameUI.Control.Primitive

public class VirtualizingPanel : PanelScrollable, ITickFinalizer, IGameObject<GameDataControlVirtualizingPanel>, IGameObject

构造函数

VirtualizingPanel 仅客户端

public VirtualizingPanel()

VirtualizingPanel 仅客户端

public VirtualizingPanel(IGameLink<GameDataControlVirtualizingPanel> link)

属性

DefaultTemplate 仅客户端

public new static IGameLink<GameDataControlVirtualizingPanel> DefaultTemplate { get; }

MeasureDirty 仅客户端

protected bool MeasureDirty { get; set; }

ArrangeDirty 仅客户端

protected bool ArrangeDirty { get; set; }

MeasureInProgress 仅客户端

protected bool MeasureInProgress { get; set; }

ArrangeInProgress 仅客户端

protected bool ArrangeInProgress { get; set; }

CachedChildren 仅客户端

protected List<Control> CachedChildren { get; set; }

CacheLength 仅客户端

public VirtualizationCacheLength CacheLength { get; set; }

Use this property to configure the dimensions of the cache before and after the viewport when virtualizing. Please note that the unit of these dimensions is determined by the value of the CacheLengthUnit.

CacheLengthUnit 仅客户端

public VirtualizationCacheLengthUnit CacheLengthUnit { get; set; }

Use this property to configure the unit portion of the before and after cache sizes.

ItemSize 仅客户端

public SizeF? ItemSize { get; set; }

The item size used for virtualization. This value is used to determine the size of the items in the panel, if not specified, the size will be determined by the first item in the panel.

ReferenceItemSize 仅客户端

protected SizeF? ReferenceItemSize { get; }

Gets the size of the first child element in the collection, based on the current scroll orientation.

ViewportSize 仅客户端

protected SizeF ViewportSize { get; }

PageItemCount 仅客户端

protected int PageItemCount { get; }

CacheItemMaxCount 仅客户端

protected int CacheItemMaxCount { get; }

CacheBeforeViewportItemCount 仅客户端

protected int CacheBeforeViewportItemCount { get; }

CacheAfterViewportItemCount 仅客户端

protected int CacheAfterViewportItemCount { get; }

LogicItemsTotalSize 仅客户端

protected float LogicItemsTotalSize { get; }

IsVirtualizing 仅客户端

public bool IsVirtualizing { get; set; }

ArrangeOnScroll 仅客户端

public bool ArrangeOnScroll { get; set; }

Whether if the virtualization should be performed on scroll. Should be set to true unless you have a special reason.

ItemsSource 仅客户端

public override IEnumerable<object>? ItemsSource { get; set; }

FlowOrientation 仅客户端

public override Orientation? FlowOrientation { get; set; }

ScrollOrientation 仅客户端

public override Orientation ScrollOrientation { get; set; }

DebugPanel 仅客户端

public IVirtualizingDebugPanel? DebugPanel { get; set; }

调试信息面板，用于显示虚拟化列表的调试信息

Link 仅客户端

public new IGameLink<GameDataControlVirtualizingPanel> Link { get; }

Cache 仅客户端

public new GameDataControlVirtualizingPanel Cache { get; }

方法

InvalidateMeasure 仅客户端

public virtual void InvalidateMeasure()

Invalidates the measurement state for the element. This has the effect of also invalidating the arrange state for the element. The element will be queued for an update layout for size and position. For virtualizing panels, this will start the virtualization process.

InvalidateArrange 仅客户端

public virtual void InvalidateArrange()

Invalidates the arrange state of the element, marking it as requiring a new layout pass. For virtualizing panels, this will start the virtualization process.

GenerateChildren 仅客户端

public override void GenerateChildren()

OnScrollInternal 仅客户端

public void OnScrollInternal(object? __, ScrollChangedEventArgs _)

DisposeManaged 仅客户端

protected override void DisposeManaged()

TickFinalizer 仅客户端

public void TickFinalizer()

GetChildByItem 仅客户端

public override Control? GetChildByItem(int itemIndex)

CachedRangeToRecycle 仅客户端

protected void CachedRangeToRecycle(int start, int count)

Recycles a range of cached child elements, preparing them for reuse.

• start — The zero-based index of the first child element in the range to recycle.
• count — The number of child elements to recycle, starting from the index.

备注

This method removes the specified range of child elements from the cache, detaches them from their parent, and adds them to a recycling pool for future reuse. It also resets the item index of each recycled child and removes them from the pending virtualization list.

GetOrRecycleOrGenerateChildByItem 仅客户端

public Control? GetOrRecycleOrGenerateChildByItem(int itemIndex)

ClearCache 仅客户端

public void ClearCache()

Measure 仅客户端

protected virtual void Measure()

Arrange 仅客户端

protected virtual void Arrange()

事件

OnChildVirtualizationPhase 仅客户端

public event EventHandler<ApplyControlTemplatePhaseEventArgs>? OnChildVirtualizationPhase

Occurs when a virtualization phase is going to be applied.

备注

This event is triggered to notify subscribers about the current phase of virtualization being applied, allowing for custom logic or updates to be performed during the rendering process.

字段

CacheStartIndex 仅客户端

protected int CacheStartIndex

RecyclePool 仅客户端

protected QuickDictionary<GameDataControl, HashSet<Control>> RecyclePool

PendingVirtualizationChildren 仅客户端

protected HashSet<Control> PendingVirtualizationChildren

arrangedOnce 仅客户端

protected bool arrangedOnce

viewportSize 仅客户端

protected SizeF? viewportSize

pageItemCount 仅客户端

protected int? pageItemCount

cacheItemMaxCount 仅客户端

protected int? cacheItemMaxCount

cacheBeforeViewportItemCount 仅客户端

protected int? cacheBeforeViewportItemCount

cacheAfterViewportItemCount 仅客户端

protected int? cacheAfterViewportItemCount

logicItemsTotalSize 仅客户端

protected float? logicItemsTotalSize

ReferenceItem 仅客户端

protected Control? ReferenceItem

BeforeViewportPlaceHolder 仅客户端

protected Panel? BeforeViewportPlaceHolder

AfterViewportPlaceHolder 仅客户端

protected Panel? AfterViewportPlaceHolder

CanvasAnimatedEventArgs 仅客户端

命名空间 GameUI.Control.Primitive.Struct

public class CanvasAnimatedEventArgs : EventArgs

动画画布渲染事件参数，提供帧间时间差和计时信息

备注

此事件参数用于CanvasAnimated的渲染事件， 提供动画所需的时间信息，包括帧间隔和自画布开始计时以来的总时间。

构造函数

CanvasAnimatedEventArgs 仅客户端

public CanvasAnimatedEventArgs(int deltaTimeInMilliseconds, int totalElapsedTimeInMilliseconds)

初始化CanvasAnimatedEventArgs实例

• deltaTimeInMilliseconds — 自上次渲染以来的时间差（毫秒）
• totalElapsedTimeInMilliseconds — 自画布开始计时以来的总时间（毫秒）

属性

DeltaTimeInMilliseconds 仅客户端

public int DeltaTimeInMilliseconds { get; }

获取自上次渲染以来的时间差（毫秒）

备注

此值可用于实现与帧率无关的动画，通过将动画速度乘以此值来确保动画速度一致。

TotalElapsedTimeInMilliseconds 仅客户端

public int TotalElapsedTimeInMilliseconds { get; }

获取自画布开始计时以来的总时间（毫秒）

备注

此值考虑了StartingTickOffsetInMilliseconds偏移量， 因此反映的是画布自身的计时而非游戏客户端的全局计时。

DeltaTimeInSeconds 仅客户端

public float DeltaTimeInSeconds { get; }

获取自上次渲染以来的时间差（秒）

TotalElapsedTimeInSeconds 仅客户端

public float TotalElapsedTimeInSeconds { get; }

获取自画布开始计时以来的总时间（秒）

InputEventArgs 仅客户端

命名空间 GameUI.Control.Primitive.Struct

public class InputEventArgs : EventArgs

构造函数

InputEventArgs 仅客户端

public InputEventArgs(string text, UpdateSourceTrigger updateSourceTrigger)

属性

Text 仅客户端

public string Text { get; }

UpdateSourceTrigger 仅客户端

public UpdateSourceTrigger UpdateSourceTrigger { get; set; }

InputKeyEventArgs 仅客户端

命名空间 GameUI.Control.Primitive.Struct

public class InputKeyEventArgs : EventArgs

构造函数

InputKeyEventArgs 仅客户端

public InputKeyEventArgs(VirtualKey key, PointerButtons pointerButtons, GameCore.Platform.Urho.VirtualKeyModifiers modifiers)

属性

Modifiers 仅客户端

public GameCore.Platform.Urho.VirtualKeyModifiers Modifiers { get; set; }

The virtual key modifiers, such as Shift, Ctrl, or Alt, that were pressed when the event occurred.

PointerButtons 仅客户端

public PointerButtons PointerButtons { get; set; }

The pointer buttons that were pressed when the event occurred. For mouse events, this indicates which mouse buttons were pressed. For finger events, differentiate between fingers by using the touching ID.

Key 仅客户端

public VirtualKey Key { get; set; }

The virtual key that triggered the event.

LinkClickedEventArgs 仅客户端

命名空间 GameUI.Control.Primitive.Struct

public class LinkClickedEventArgs : PointerEventArgs

提供标签内链接被点击时的数据。

构造函数

LinkClickedEventArgs 仅客户端

public LinkClickedEventArgs(string linkId, PointerButtons pointerButtons)

提供标签内链接被点击时的数据。

属性

LinkId 仅客户端

public string LinkId { get; }

获取 <link> 标签中指定的链接标识。

ScrollChangedEventArgs 仅客户端

命名空间 GameUI.Control.Primitive.Struct

public class ScrollChangedEventArgs : EventArgs

构造函数

ScrollChangedEventArgs 仅客户端

public ScrollChangedEventArgs(float scrollValue)

属性

ScrollValue 仅客户端

public float ScrollValue { get; set; }

SizeChangedEventArgs 仅客户端

命名空间 GameUI.Control.Primitive.Struct

public class SizeChangedEventArgs : EventArgs

构造函数

SizeChangedEventArgs 仅客户端

public SizeChangedEventArgs(int widthPx, int heightPx)

属性

WidthPx 仅客户端

public int WidthPx { get; set; }

HeightPx 仅客户端

public int HeightPx { get; set; }

Size 仅客户端

public SizeF Size { get; }

ApplyControlTemplateEventArgs 仅客户端

命名空间 GameUI.Control.Struct

public class ApplyControlTemplateEventArgs : EventArgs

Provides data for events related to applying a control template.

构造函数

ApplyControlTemplateEventArgs 仅客户端

public ApplyControlTemplateEventArgs(Control control, IGameData<GameDataControl>? template)

Provides data for events related to applying a control template.

属性

Control 仅客户端

public Control Control { get; }

Gets the control to which the template is being applied.

Template 仅客户端

public IGameData<GameDataControl>? Template { get; }

Gets the template data being applied to the control.

ApplyControlTemplatePhaseEventArgs 仅客户端

命名空间 GameUI.Control.Struct

public class ApplyControlTemplatePhaseEventArgs : ApplyControlTemplateEventArgs

Provides data for events related to applying a control template at a specific phase.

构造函数

ApplyControlTemplatePhaseEventArgs 仅客户端

public ApplyControlTemplatePhaseEventArgs(Control control, IGameData<GameDataControl>? template, int phase)

Provides data for events related to applying a control template at a specific phase.

属性

Phase 仅客户端

public int Phase { get; }

Gets the phase of the template application process.

DropEventArgs 仅客户端

命名空间 GameUI.Control.Struct

public class DropEventArgs : EventArgs

Provides data for drag-and-drop events, indicating the target control of a drop operation.

构造函数

DropEventArgs 仅客户端

public DropEventArgs(Control? targetControl)

Provides data for drag-and-drop events, indicating the target control of a drop operation.

属性

TargetControl 仅客户端

public Control? TargetControl { get; }

Gets the control that is the target of the drop operation. If null, the drop occurred on a blank area or on a control that does not support drop.

ItemTemplateSelector 仅客户端

命名空间 GameUI.Control.Struct

public delegate ItemTemplateSelector

KeyboardAccelerator 仅客户端

命名空间 GameUI.Control.Struct

public class KeyboardAccelerator

Represents a keyboard accelerator that defines a key and optional modifiers to trigger an action.

备注

A keyboard accelerator is typically used to associate a specific key combination with a command or action within an application. The accelerator is considered active when IsEnabled is true.

构造函数

KeyboardAccelerator 仅客户端

public KeyboardAccelerator()

属性

IsEnabled 仅客户端

public bool IsEnabled { get; set; }

Gets or sets a value indicating whether this key combination is enabled.

Key 仅客户端

public VirtualKey Key { get; set; }

Modifiers 仅客户端

public GameCore.Platform.Urho.VirtualKeyModifiers Modifiers { get; set; }

AllowExtraModifiers 仅客户端

public bool AllowExtraModifiers { get; set; }

Allows the accelerator to match key-down events even when the key event contains extra modifier keys.

备注

For example, a W accelerator with no required modifiers can still match Shift+W when this is true.

方法

Matches 仅客户端

public bool Matches(EventGameKey key)

MatchesRelease 仅客户端

public bool MatchesRelease(EventGameKey key)

KeyboardAcceleratorEventArgs 仅客户端

命名空间 GameUI.Control.Struct

public class KeyboardAcceleratorEventArgs : EventArgs

Provides data for events when a keyboard accelerator is invoked on a control. Only one control can invoke a keyboard accelerator at a time.

构造函数

KeyboardAcceleratorEventArgs 仅客户端

public KeyboardAcceleratorEventArgs(Control control, KeyboardAccelerator accelerator)

KeyboardAcceleratorEventArgs 仅客户端

public KeyboardAcceleratorEventArgs(Control control, KeyboardAccelerator accelerator, bool isRepeat)

属性

Accelerator 仅客户端

public KeyboardAccelerator Accelerator { get; }

Gets the keyboard accelerator that triggered the event.

Control 仅客户端

public Control Control { get; }

Gets the control that invoked the keyboard accelerator.

IsRepeat 仅客户端

public bool IsRepeat { get; }

Gets a value indicating whether this invocation was caused by key repeat. Key release events always report false.

Handled 仅客户端

public bool Handled { get; set; }

Gets or sets a value indicating whether the event has been handled. When set to true, it indicates that the event has been processed and no further action is required. The default invoked action of the control will not be executed. For example, if the control is a button, the click action will not be triggered.

PointerCapturedMoveEventArgs 仅客户端

命名空间 GameUI.Control.Struct

public class PointerCapturedMoveEventArgs : PointerEventArgs

Provides data for pointer move events when the pointer is captured by a control. This event argument is used to indicate which pointer buttons are involved in the move, and which buttons are currently pressed on the control during the event.

构造函数

PointerCapturedMoveEventArgs 仅客户端

public PointerCapturedMoveEventArgs(PointerButtons button, PointerButtons buttonsOnControl)

Provides data for pointer move events when the pointer is captured by a control. This event argument is used to indicate which pointer buttons are involved in the move, and which buttons are currently pressed on the control during the event.

属性

ButtonsOnControl 仅客户端

public PointerButtons ButtonsOnControl { get; init; }

Gets the set of pointer buttons that are currently pressed on the control at the time of the move event. This property is especially useful for handling multi-button or multi-finger interactions, such as resizing or complex gestures. If multiple pointer buttons are captured and moving on the control, each will trigger its own move event with the corresponding set of pressed buttons.

PointerEventArgs 仅客户端

命名空间 GameUI.Control.Struct

public class PointerEventArgs : EventArgs

Provides data for pointer-related events, such as mouse or touch input.

备注

This event argument is used for pointer events, including mouse clicks, presses, releases, and finger touches. 提供了多种方式获取指针位置： X/Y - 直接获取坐标值（推荐，最简洁） Position - 获取 PointF 结构体（便于绑定到绘图API） PointerPosition - 获取完整的 UIPosition 结构体

构造函数

PointerEventArgs 仅客户端

public PointerEventArgs(PointerButtons button)

Provides data for pointer-related events, such as mouse or touch input.

备注

This event argument is used for pointer events, including mouse clicks, presses, releases, and finger touches. 提供了多种方式获取指针位置： X/Y - 直接获取坐标值（推荐，最简洁） Position - 获取 PointF 结构体（便于绑定到绘图API） PointerPosition - 获取完整的 UIPosition 结构体

属性

PointerButtons 仅客户端

public PointerButtons PointerButtons { get; init; }

Gets the pointer buttons that triggered the event. For mouse events, this indicates which mouse buttons were pressed. For finger events, differentiate between fingers by using the touching ID.

PointerPosition 仅客户端

public UIPosition? PointerPosition { get; }

获取指针的完整位置信息

备注

如果只需要X/Y坐标，建议直接使用 X 和 Y 属性。

X 仅客户端

public float X { get; }

获取指针的X坐标

备注

如果无法获取位置信息（例如指针不存在），返回 NaN。 可以使用 Single) 检查是否有效。

Y 仅客户端

public float Y { get; }

获取指针的Y坐标

备注

如果无法获取位置信息（例如指针不存在），返回 NaN。 可以使用 Single) 检查是否有效。

Position 仅客户端

public PointF Position { get; }

获取指针位置（返回 PointF 类型）

备注

这是一个便捷属性，将 X 和 Y 封装为 PointF。 如果无法获取位置信息，X 和 Y 值将为 NaN。

HasPosition 仅客户端

public bool HasPosition { get; }

检查指针位置是否有效

备注

等效于检查 PointerPosition 是否有值，或检查 X/Y 是否为 NaN。

VirtualizationCacheLength 仅客户端

命名空间 GameUI.Control.Struct

public readonly struct VirtualizationCacheLength : IEquatable<VirtualizationCacheLength>

构造函数

VirtualizationCacheLength 仅客户端

public VirtualizationCacheLength(double cacheBeforeAndAfterViewport)

Constructor, initializes the CacheBeforeViewport and the CacheAfterViewport to their sizes. Units are specified as a seperate VisualizationCacheLengthUnit property.

• cacheBeforeAndAfterViewport — Value to be stored by this VirtualizationCacheLength instance as the cacheBeforeViewport and cacheAfterViewport.

VirtualizationCacheLength 仅客户端

public VirtualizationCacheLength(double cacheBeforeViewport, double cacheAfterViewport)

属性

CacheBeforeViewport 仅客户端

public double CacheBeforeViewport { get; }

Returns cacheBeforeViewport part of this VirtualizationCacheLength instance.

CacheAfterViewport 仅客户端

public double CacheAfterViewport { get; }

Returns cacheAfterViewport part of this VirtualizationCacheLength instance.

方法

operator == 仅客户端

public static bool operator ==(VirtualizationCacheLength cl1, VirtualizationCacheLength cl2)

Overloaded operator, compares 2 VirtualizationCacheLength's.

• cl1 — first VirtualizationCacheLength to compare.
• cl2 — second VirtualizationCacheLength to compare.

返回： true if specified VirtualizationCacheLengths have same value and unit type.

operator != 仅客户端

public static bool operator !=(VirtualizationCacheLength cl1, VirtualizationCacheLength cl2)

Overloaded operator, compares 2 VirtualizationCacheLength's.

• cl1 — first VirtualizationCacheLength to compare.
• cl2 — second VirtualizationCacheLength to compare.

返回： true if specified VirtualizationCacheLengths have either different value or unit type.

Equals 仅客户端

public override bool Equals(object? obj)

Compares this instance of VirtualizationCacheLength with another object.

• obj — Reference to an object for comparison.

返回： trueif this VirtualizationCacheLength instance has the same value and unit type as oCompare.

Equals 仅客户端

public bool Equals(VirtualizationCacheLength cacheLength)

Compares this instance of VirtualizationCacheLength with another instance.

• cacheLength — Cache length instance to compare.

返回： trueif this VirtualizationCacheLength instance has the same value and unit type as cacheLength.

GetHashCode 仅客户端

public override int GetHashCode()

GetHashCode

返回： GetHashCode

VirtualizationCacheLengthUnit 仅客户端

命名空间 GameUI.Control.Struct

public enum VirtualizationCacheLengthUnit

VirtualizationCacheLengthUnit enum is used to indicate what kind of value the VirtualizationCacheLength is holding.

枚举值

• Item — The value is expressed as an item.
• Page — The value is expressed as a page full of item.