API 参考
正在准备搜索索引…

带有效性检查的 RmlUi 原生元素包装器。

包装器共享原生销毁状态。元素销毁或运行时关闭后,操作会抛出异常; 重新初始化不会恢复旧包装器。原生销毁会自动释放监听器。 原生资源保留原渲染管理器,因此禁止跨渲染接口移动子树;可改用 clone。 使用同一渲染接口的上下文可迁移节点并保留身份。

继承关系

层级 (查看层级一览)

源码与继承
成员目录120

构造函数

访问器

方法

构造函数

  • 构造游离原生元素,或包装内部原生句柄。

    参数

    tagOrHandle
    string | object

    原生标签,与具体原生类型相互独立。

    attributes
    Record<string, VariantValue> = {}

    自有初始值;默认为空字典。

    返回值

    原生分配器保留确切释放来源并初始化输入默认值。不修改全局 Factory 注册, 不发送插件创建通知。JS 子类使用最近的已注册具体原生类型。 ElementFormControl 为抽象类,拒绝直接按标签构造。

    源码与继承

访问器

  • get absoluteLeft(): number

    读取 GetAbsoluteLeft,单位为上下文像素。

    返回值

    number

    相对上下文的水平偏移。

    源码与继承
  • get absoluteTop(): number

    读取 GetAbsoluteTop,单位为上下文像素。

    返回值

    number

    相对上下文的垂直偏移。

    源码与继承
  • get baseline(): number

    读取 GetBaseline:从下外边距边缘向上的像素偏移。

    返回值

    number

    基线向上偏移,单位为像素。

    源码与继承
  • get clientHeight(): number

    读取 GetClientHeight:内边距区域高度减去水平滚动条。

    返回值

    number

    客户区高度,单位为像素。

    源码与继承
  • get clientLeft(): number

    读取 GetClientLeft,即左边框宽度。

    返回值

    number

    左边框宽度。

    源码与继承
  • get clientTop(): number

    读取 GetClientTop,即顶部边框宽度。

    返回值

    number

    顶部边框宽度。

    源码与继承
  • get clientWidth(): number

    读取 GetClientWidth:内边距区域宽度减去垂直滚动条。

    返回值

    number

    客户区宽度,单位为像素。

    源码与继承
  • get innerRML(): string

    内部 RML 标记。

    返回值

    string

    内部标记字符串。

    源码与继承
  • set innerRML(rml: string): void

    通过 Rml::Element::SetInnerRML 替换子元素标记。

    参数

    rml
    string

    新标记;现有子元素包装器随之失效。

    返回值

    void
    源码与继承
  • get offsetHeight(): number

    读取 GetOffsetHeight:包含内容、内边距和边框,不包含外边距。

    返回值

    number

    边框区域高度,单位为像素。

    源码与继承
  • get offsetLeft(): number

    读取 GetOffsetLeft:相对偏移父元素的左边框偏移。

    返回值

    number

    边框的水平偏移。

    源码与继承
  • get offsetTop(): number

    读取 GetOffsetTop:相对偏移父元素的顶部边框偏移。

    返回值

    number

    边框的垂直偏移。

    源码与继承
  • get offsetWidth(): number

    读取 GetOffsetWidth:包含内容、内边距和边框,不包含外边距。

    返回值

    number

    边框区域宽度,单位为像素。

    源码与继承
  • get scrollHeight(): number

    读取 GetScrollHeight,包含内边距和可滚动内容。

    返回值

    number

    可滚动高度,单位为像素。

    源码与继承
  • get scrollLeft(): number

    原生 GetScrollLeft/SetScrollLeft,保留取整与范围限制。 偏移变化时同步派发 scroll 事件。

    返回值

    number

    水平滚动偏移。

    源码与继承
  • set scrollLeft(value: number): void

    通过 Rml::Element::SetScrollLeft 设置水平滚动偏移。

    参数

    value
    number

    水平像素偏移,由 RmlUi 限制范围。

    返回值

    void
    源码与继承
  • get scrollTop(): number

    原生 GetScrollTop/SetScrollTop,保留取整与范围限制。 偏移变化时同步派发 scroll 事件。

    返回值

    number

    垂直滚动偏移。

    源码与继承
  • set scrollTop(value: number): void

    通过 Rml::Element::SetScrollTop 设置垂直滚动偏移。

    参数

    value
    number

    垂直像素偏移,由 RmlUi 限制范围。

    返回值

    void
    源码与继承
  • get scrollWidth(): number

    读取 GetScrollWidth,包含内边距和可滚动内容。

    返回值

    number

    可滚动宽度,单位为像素。

    源码与继承

方法

  • 通过 Rml::Element::AddAnimationKey 追加关键帧副本。

    参数

    property
    string | PropertyId

    原生属性名或 ID。

    target

    有类型的目标值。

    duration
    number

    新增的非负持续秒数。

    tween可选

    缓动,默认原生 Linear/Out。

    返回值

    boolean

    原生成功结果;没有现有动画时返回 false。

    源码与继承
  • 挂载事件监听器。

    参数

    type
    string | number

    事件名称或已注册的原生 EventId。

    listener

    同步回调,可在不同注册项之间复用。

    capture
    boolean = false

    是否在捕获阶段监听,默认为 false。

    返回值

    void

    相同元素、类型、回调和 capture 的重复注册只生效一次。 解绑或销毁元素时自动释放回调。分发期间可移除自身或其他监听器。 异常从触发事件的原生入口传播。类名、样式、属性、标题和无关子树可同步修改。 销毁活动事件目标或原生调用接收者、关闭运行时及递归更新和输入会被拒绝; 属性设置和移除也会保守地拒绝活动目标的祖先。活动输入元素的 type 设置或移除会被拒绝,以保护仍在执行的原生控件。 请通过 queueMicrotask 等方式安排这些操作在分发后执行。

    源码与继承
  • 按属性名或 ID 调用 Rml::Element::Animate,启动或替换动画。

    参数

    property
    string | PropertyId

    原生属性名或 ID。

    target

    有类型的目标值,由 RmlUi 复制。

    duration
    number

    非负持续时间,单位秒。

    tween可选

    缓动,默认原生 Linear/Out。

    iterations
    number = 1

    迭代次数,默认 1;-1 无限重复。

    alternate
    boolean = true

    每隔一次迭代反向,默认 true。

    delay
    number = 0

    延迟秒数,默认零。

    start
    null | Property = null

    起始值副本;null 使用当前属性值。

    返回值

    boolean

    原生成功结果;未知或不支持的属性返回 false。

    源码与继承
  • 通过 Rml::Element::AppendChild 转移脱离节点的所有权。

    参数

    child

    持有所有权的脱离节点,已挂载节点须先移除。

    domElement
    boolean = true

    是否参与 DOM 遍历,默认为 true。

    返回值

    同一个子节点包装器。

    拒绝环、上下文根及活动原生调用或事件子树。 文档保留原上下文,只能在该活动上下文内转移。上下文根只接受自己的文档作为 DOM 子节点。 所有权只转移一次,监听器在脱离与重新插入后保留。 原生控件内部节点可读,但不能移除或替换;通过这些接口添加的非 DOM 节点仍可转移。

    源码与继承
  • 使用 ArePseudoClassesSet 检查全部伪类。

    参数

    names
    readonly string[]

    待检查名称;空列表返回 true。

    返回值

    boolean

    是否全部启用。

    源码与继承
  • 通过 Rml::Element::Clone 复制属性、样式和内容。

    返回值

    null | Element

    持有所有权的脱离副本;工厂失败时为 null,不复制 JS 监听器。

    源码与继承
  • 通过 Rml::Element::Closest 查找匹配的祖先,不包含自身。

    参数

    selector
    string

    RCSS 选择器。

    返回值

    null | Element

    首个匹配祖先,不包含自身,不存在时为 null。

    源码与继承
  • 通过 Rml::Element::Contains 检查包含关系,包含自身。

    参数

    element
    null | Element

    待检查节点或 null。

    返回值

    boolean

    自身或后代返回 true,null 或无关节点返回 false。

    源码与继承
  • 通过 Rml::Element::DispatchEvent 派发事件,允许嵌套派发。

    参数

    type
    string | number

    事件名称或已注册的原生 EventId。

    parameters
    Readonly<Record<string, VariantValue>> = {}

    原生 Variant 参数,默认为空。

    options可选

    省略时使用上游事件定义的默认值。

    返回值

    boolean

    事件是否仍可传播。

    参数 getter 在原生元素校验前执行。getter 销毁接收元素或被引用元素时, 派发会抛出异常;监听器中不能通过替换子树销毁元素参数。

    源码与继承
  • 通过 Rml::Element::Focus 请求焦点。

    参数

    focusVisible
    boolean = false

    激活 focus-visible 反馈,默认 false。

    返回值

    boolean

    原生焦点请求是否成功。

    源码与继承
  • 复制 GetActivePseudoClasses 的结果。

    返回值

    string[]

    按原生顺序排列的独立快照。

    源码与继承
  • 使用 GetAddress 格式化地址,从当前叶节点指向父节点。

    参数

    includePseudoClasses
    boolean = false

    是否包含伪类,默认 false。

    includeParents
    boolean = true

    是否包含祖先地址,默认 true。

    返回值

    string

    原生地址字符串,不是 CSS 选择器。

    源码与继承
  • 以字符串读取属性。

    参数

    name
    string

    属性名。

    返回值

    null | string

    属性值;不存在时为 null。

    源码与继承
  • 按默认值的原生类型读取 GetAttribute。

    类型参数

    参数

    name
    string

    属性名。

    defaultValue

    非空回退值,其类型决定原生转换方式。

    返回值

    原生转换结果,以回退值初始化。

    number 选择 double;BigInt 选择 int64,超过 INT64_MAX 时选择 uint64。 不安全的数字到整数转换会抛错。向量与颜色按值复制。 缺失键保留回退值;number 默认值按原生 atof 将无效数字字符串转换为零。

    源码与继承
  • 将主 Rml::Element::GetBox 复制到独立原生存储。

    返回值

    可写盒快照;使用 setBox 应用修改。

    源码与继承
  • 复制 Rml::Element::GetBox(index, offset),包含输出偏移。

    参数

    index
    number

    盒索引;越界时返回主盒及零偏移。INT32_MIN 会被拒绝, 避免上游有符号溢出。

    返回值

    独立持有的盒及偏移。

    源码与继承
  • 返回 Rml::Element::GetChild,支持原生非 DOM 节点索引。

    参数

    index
    number

    从零开始的 int32 索引。

    返回值

    null | Element

    子节点,越界时为 null。

    源码与继承
  • 读取 GetClassNames,返回空格分隔的类名字符串。

    返回值

    string

    原生类名列表。

    源码与继承
  • 读取 GetClosestScrollableContainer,查找范围包含当前元素。

    返回值

    null | Element

    最近的原生滚动容器;不存在时返回 null。

    先调用 context.update() 解析样式和布局。auto/scroll 仅在对应轴内容超过 客户区尺寸时符合条件;overscroll-behavior: contain 无需内容溢出也符合条件。

    源码与继承
  • 通过所属文档读取 GetContext。

    返回值

    null | Context

    唯一上下文对象;脱离文档及其后代保留上下文,其他脱离元素和上下文根返回 null。

    源码与继承
  • 通过受检查的原生模型索引读取 Rml::Element::GetDataModel。

    返回值

    唯一的数据模型构造器包装;未绑定模型时为 null。

    返回 RmlUi 已关联的模型;元素脱离或移除模型会清除关联。 返回模型的生命周期由上下文管理。

    源码与继承
  • 以受检查的元素回退值读取 GetAttribute<ScriptInterface*>。

    参数

    name
    string

    属性名。

    defaultValue
    null | Element = null

    键缺失或转换失败时的回退元素,默认 null。

    返回值

    null | Element

    存活元素;已销毁的保存目标转换为 null。

    源码与继承
  • 在所属文档中按 id 查找元素。

    参数

    id
    string

    元素 id。

    返回值

    null | Element

    匹配的元素;不存在时为 null。

    广度优先搜索整个所属文档,包括兄弟元素;没有所属文档时从当前元素开始。 RmlUi 还接受 #self、#document、#parent。 仅搜索后代时使用 querySelector。

    源码与继承
  • 通过 Rml::Element::GetElementsByClassName 获取后代快照。

    参数

    name
    string

    类名。

    返回值

    包含实时包装器的快照数组。

    源码与继承
  • 通过 Rml::Element::GetElementsByTagName 获取后代快照。

    参数

    tag
    string

    原生标签名。

    返回值

    包含实时包装器的快照数组。

    源码与继承
  • 复制 Rml::Element::GetEventDispatcherSummary 的调试摘要。

    返回值

    string

    原生事件类型和监听器数量;没有监听器时为空字符串。

    源码与继承
  • 获取最深的焦点后代;没有子项聚焦时返回此元素。

    返回值

    最深的焦点后代;没有子元素聚焦时返回自身。

    源码与继承
  • 从计算样式读取原生 GetLineHeight。

    返回值

    number

    计算后的像素行高。

    源码与继承
  • 获取主布局盒和附加布局盒的总数。

    返回值

    number

    主盒及附加盒的总数。

    源码与继承
  • 通过 Rml::Element::GetNumChildren 统计子节点。

    参数

    includeNonDomElements
    boolean = false

    包含内部子节点,默认为 false。

    返回值

    number

    原生子节点数。

    源码与继承
  • 将 Rml::Element::GetProperty 结果复制为自有属性。

    参数

    name
    string | PropertyId

    属性名或原生编号。

    返回值

    null | Property

    自有属性;不存在时返回 null。

    包含继承及默认值;层叠变量应在上下文更新后读取。

    源码与继承
  • 使用原生类型样本读取 Rml::Element::GetProperty。

    类型参数

    参数

    name
    string

    属性名。

    type

    原生转换类型样本。

    返回值

    转换值或原生类型的默认值。

    包含继承及默认值;层叠变量应在上下文更新后读取。缺失或转换失败时返回 T{};样本值不作为回退值。

    源码与继承
  • 复制 Rml::Element::GetRenderBox,用于网格构造。

    参数

    fillArea
    BoxArea = BoxArea.Padding

    Border、Padding 或 Content;默认 Padding。

    index
    number = 0

    盒索引,默认零;越界行为与 getBox(index) 相同。

    返回值

    独立渲染盒值。

    源码与继承
  • 读取 Rml::Element::GetStyleSheet,包含文档的重写实现。

    返回值

    null | StyleSheet

    只读编译视图;没有可用样式表时为 null。

    文档销毁或替换样式表后,视图仍保留原容器;原容器重新编译会使旧视图失效。

    源码与继承
  • 查询 HasAttribute,包括值为 NONE 的属性。

    参数

    name
    string

    属性名。

    返回值

    boolean

    键是否存在。

    源码与继承
  • 通过 Rml::Element::HasChildNodes 检查 DOM 子节点。

    返回值

    boolean

    是否存在至少一个 DOM 子节点。

    源码与继承
  • 通过 Rml::Element::InsertBefore 转移脱离节点的所有权。

    参数

    child

    脱离节点,遵守 appendChild 的所有权检查。

    adjacent
    null | Element

    参考子节点;为 null 或非子节点时追加到 DOM。

    返回值

    同一子节点,继承参考子节点的 DOM 或非 DOM 状态。

    源码与继承
  • 返回 class 是否存在。

    参数

    className
    string

    类名。

    返回值

    boolean

    class 存在时为 true。

    源码与继承
  • 调用原生 IsPointWithinElement 检测边框区域。 变换后的屏幕坐标应先调用 project。

    参数

    point

    元素平面上的上下文像素坐标。

    返回值

    boolean

    原生边框区域是否包含坐标。

    源码与继承
  • 查询 IsPseudoClassSet。

    参数

    name
    string

    伪类名。

    返回值

    boolean

    伪类是否启用。

    源码与继承
  • 调用原生 IsReplaced,判断元素是否自行渲染。

    返回值

    boolean

    是否为替换元素。

    源码与继承
  • 调用原生 IsVisible,可选择同时检查祖先。

    参数

    includeAncestors
    boolean = false

    同时检查祖先,默认 false。

    返回值

    boolean

    原生可见性结果。

    源码与继承
  • 一次原生遍历复制 Rml::Element::IterateLocalProperties。

    参数

    filterInheritedBy
    null | Element = null

    仅保留该元素实际继承的属性;null 表示不筛选。

    返回值

    [string, Property][]

    按原生顺序排列的名称和属性对;值为独立的自有副本。

    包含行内、样式表或类属性、自定义变量及含变量的简写;遵循原生覆盖和继承筛选。 后续样式变更或元素销毁不会影响副本。

    源码与继承
  • 通过 Rml::Element::Matches 检查当前元素。

    参数

    selector
    string

    RCSS 选择器。

    返回值

    boolean

    当前元素是否匹配。

    源码与继承
  • 使用活事件调用虚方法 Rml::Element::ProcessDefaultAction。

    参数

    event

    此元素当前执行中的监听器收到的事件。

    返回值

    void

    接收者必须等于 event.currentTarget。保留阶段、参数及传播状态, 已停止传播的事件也会执行动作。此调用不会取消后续自动动作; 若只需手动执行,应对可中断事件调用 stopPropagation。 顺序调用会重复原生副作用;同一事件的手动动作执行期间禁止重入。

    源码与继承
  • 按原生深度优先顺序查找首个匹配 CSS 选择器的后代元素。

    参数

    selector
    string

    CSS 选择器。

    返回值

    null | Element

    匹配的元素;不存在时为 null。

    源码与继承
  • 通过 Rml::Element::QuerySelectorAll 获取后代快照。

    参数

    selector
    string

    RCSS 选择器。

    返回值

    按原生深度优先顺序排列的实时包装器数组;数组成员不随树变动。

    源码与继承
  • 通过原分配器释放此自有游离原生子树。

    返回值

    void

    拒绝已挂接、借用及正在调用的子树。原生析构同步执行, 子树中全部仍存活的包装器均失效。

    源码与继承
  • 通过 Rml::Element::RemoveChild 取得子节点所有权。

    参数

    child

    要脱离的子节点;活动原生调用或事件子树会被拒绝。

    返回值

    null | Element

    同一脱离包装器;不是当前节点的子节点时为 null。

    源码与继承
  • 移除此前挂载的事件监听器。

    参数

    type
    string | number

    事件名称或已注册的原生 EventId。

    listener

    挂载时使用的同一个回调引用。

    capture
    boolean = false

    挂载时使用的捕获阶段标志,默认为 false。

    返回值

    void

    无匹配注册项时不执行操作,注册项的四个字段必须全部匹配。

    源码与继承
  • 移除局部 CSS 覆盖值,对应 Rml::Element::RemoveProperty。

    参数

    name
    string | PropertyId

    原生编号或名称,支持 --accent 等自定义变量。

    返回值

    void
    源码与继承
  • 通过 Rml::Element::ReplaceChild 转移节点所有权。

    参数

    child

    脱离的替换节点,遵守 appendChild 检查。

    replaced
    null | Element

    现有子节点;为 null 或非子节点时改为追加。

    返回值

    null | Element

    持有所有权的被替换脱离节点;追加时为 null。

    源码与继承
  • 在元素当前样式和上下文中调用 Rml::Element::ResolveLength。

    参数

    value

    原生数值;非长度单位返回零。

    返回值

    number

    像素长度;字段无效或溢出时抛出异常。

    源码与继承
  • 使用原生单位转换调用 Rml::Element::ResolveNumericValue。

    参数

    value

    数值。NUMBER 乘以基数,PERCENT 按 number / 100 缩放基数; 角度返回弧度,非数值单位返回零。

    baseValue
    number

    NUMBER 和 PERCENT 使用的有限基数。

    返回值

    number

    原生解析结果;字段无效或溢出时抛出异常。

    源码与继承
  • 通过 SetAttributes 合并属性。

    参数

    attributes
    Readonly<Record<string, VariantValue>>

    属性拥有的值;全部转换完成后才修改原生状态。

    返回值

    void

    其他键保留。原生 OnAttributeChange 对整组属性调用一次。

    源码与继承
  • 将值复制到 Rml::Element::SetBox,并清除附加盒。

    参数

    box

    有限盒值;后续修改不会影响元素。

    返回值

    void

    后续布局更新可能覆盖手动设置的盒。

    源码与继承
  • 添加或移除一个 class。

    参数

    className
    string

    类名。

    activate
    boolean

    为 true 时添加,为 false 时移除。

    返回值

    void
    源码与继承
  • 通过 SetClassNames 替换全部类名。

    参数

    names
    string

    以空格分隔的原生类名。

    返回值

    void
    源码与继承
  • 通过 Rml::Element::SetOffset 设置原生布局基准偏移。

    参数

    offset

    有限像素坐标;遵循原生 position 规则。

    offsetParent
    null | Element

    严格祖先;null 使用独立基准。

    offsetFixed
    boolean = false

    忽略祖先滚动,默认 false。

    返回值

    void

    下次原生布局更新可能重设基准;fixed 定位隐含 offsetFixed。 祖先检查避免循环和悬空原生布局指针;节点脱离会清除指向树外的偏移父节点。

    源码与继承
  • 通过 Rml::Element::SetProperty 设置局部 RCSS 属性。

    参数

    name
    string

    RCSS 文本使用属性名,类型化值使用 PropertyId。

    value
    string

    RCSS 文本或按值复制的原生 Property。

    返回值

    boolean

    属性是否成功应用。

    源码与继承
  • 通过 Rml::Element::SetProperty 设置局部 RCSS 属性。

    参数

    name

    RCSS 文本使用属性名,类型化值使用 PropertyId。

    value

    RCSS 文本或按值复制的原生 Property。

    返回值

    boolean

    属性是否成功应用。

    源码与继承
  • 通过 SetPseudoClass 设置原生伪类。

    参数

    name
    string

    不含冒号的伪类名。

    active
    boolean

    是否启用。

    返回值

    void
    源码与继承
  • 注册托管原生脚本对象,保留 DOM 所有权规则。

    参数

    object
    null | object

    宿主对象,或传 null 清除关联。

    返回值

    void

    挂接的原生树保留对象;脱离后的闭包环可回收,克隆初始为 null。 原生 RTTI 保持不变。

    源码与继承
  • 调用原生 SetScrollableOverflowRectangle。

    参数

    size

    有限且非负的像素尺寸。

    clampScrollOffset
    boolean

    最终溢出尺寸确定后限制滚动范围。

    返回值

    void
    源码与继承

Icons made by Lorc, Delapouite & Skoll · game-icons.net · CC BY 3.0