API / CLASS REFERENCE

UltralightJSValue

以文档作用域句柄执行带错误检查的 JavaScript 操作。

只能在 Godot 主线程及创建它的文档中使用。大多数访问方法返回 UltralightResult；嵌套数组和对象继续共享，snapshot 则生成独立容器。

close 释放当前句柄，并使共享该句柄的别名失效。导航、绑定撤销和关闭 View 同样使句柄失效。快照拒绝循环和超过 64 层的嵌套。

方法

get_value(key: Variant) → UltralightResult

读取索引或名称对应的属性，结果使用共享转换。JS 属性不存在时成功返回 UltralightUndefined。

set_value(key: Variant, value: Variant) → UltralightResult

写入索引或名称对应的属性，遵守源容器类型和只读约束。失败通过 Result 返回。

utf8_bytes() → UltralightResult

将保留的 JS 值转为 UTF-8 字节，成功结果为 PackedByteArray。可保留 Godot String 无法表示的内嵌 NUL 字节。

snapshot() → UltralightResult

递归复制支持的数据，生成独立容器；循环引用、超过 64 层的嵌套或不支持的值返回错误。

keys() → UltralightResult

成功结果为自有可枚举字符串键组成的 Array。

size() → int

返回数组长度或自有可枚举键数量。关闭或访问失败时返回 -1；0 表示有效的空集合。

append(value: Variant) → UltralightResult

向 JS Array 尾部追加共享转换后的值；非数组句柄返回 TypeMismatch。

remove(key: Variant) → UltralightResult

按 JS delete 语义删除属性，数组后续索引不会移动。不可配置的属性无法删除，返回失败结果。

invoke_method(name: String, arguments: Array) → UltralightResult

使用 arguments 调用对象上名为 name 的函数，并保留此对象作为 this。成员不是函数时返回 TypeMismatch。

invoke(arguments: Array) → UltralightResult

使用 arguments 调用保留的函数。返回值使用共享转换；需要保留接收对象的 this 时使用 invoke_method。

close() → void

释放保留值，共享同一句柄的别名同时失效。

is_closed() → bool const

返回是否已显式关闭，或所属文档／绑定是否已失效。