API / CLASS REFERENCE

UltralightView

继承: TextureRect

在 Godot TextureRect 中显示 HTML、CSS 和 JavaScript 页面。

进入场景且尺寸有效后自动初始化。用 load_url 或 load_html 显式导航，用 UltralightAPI 在页面脚本执行前安装业务接口，并在导航后自动恢复。

新的求值接口默认共享容器，并用 UltralightResult 明确报告错误。导航、rebuild 和 close 会使旧文档句柄及未完成任务失效。逻辑更新与绘制由 Godot 帧循环推进，无需 AppCore。

属性

成员	类型	默认值
`accelerated`	`bool`	`—`
`max_render_fps`	`int`	`—`
`source_type`	`int`	`—`
`initial_url`	`String`	`—`
`initial_html`	`String`	`—`
`initial_base_url`	`String`	`—`
`document_ready`	`bool`	`—`
`navigation_id`	`int`	`—`
`current_url`	`String`	`—`
`html`	`String`	`—`
`htmlUrl`	`String`	`—`
`transparent`	`bool`	`—`
`lazy`	`bool`	`—`

方法

set_accelerated(enabled: bool) → void
get_accelerated() → bool const
is_accelerated() → bool const
get_render_statistics() → Dictionary const
set_max_render_fps(fps: int) → void
get_max_render_fps() → int const
get_bridge_statistics() → Dictionary const
unbind(name: String) → void
load_url(url: String, timeout: float = 30.0) → UltralightTask
load_html(html: String, base_url: String = "", timeout: float = 30.0) → UltralightTask
reload(timeout: float = 30.0) → UltralightTask
wait_ready(timeout: float = 30.0) → UltralightTask
wait_for_selector(selector: String, timeout: float = 30.0) → UltralightTask
evaluate(source: String) → UltralightResult
evaluate_copy(source: String) → UltralightResult
evaluate_handle(source: String) → UltralightResult
evaluate_async(source: String, timeout: float = 30.0) → UltralightTask
is_closed() → bool const
close() → void
is_initialized() → bool const
is_loading() → bool const
is_document_ready() → bool const
get_navigation_id() → int const
get_current_url() → String const
get_last_load_error() → UltralightError const
input_text(text: String) → void
scroll_pixels(delta: Vector2) → void
set_source_type(value: int) → void
get_source_type() → int const
set_initial_url(value: String) → void
get_initial_url() → String const
set_initial_html(value: String) → void
get_initial_html() → String const
set_initial_base_url(value: String) → void
get_initial_base_url() → String const
set_html_content(html: String) → void
get_html_content() → String
set_html_url(htmlUrl: String) → void
get_html_url() → String
set_transparent(is_transparent: bool) → void
get_transparent() → bool
set_lazy(is_lazy: bool) → void
get_lazy() → bool
rebuild() → void
init_view() → void
bind_func(funcName: String, callback: Callable) → void
bind_object(name: String, object: Object, options: UltralightBindingOptions = null) → UltralightBinding
bind_function(name: String, function: Callable, options: UltralightBindingOptions = null) → UltralightBinding
bind_object_legacy(propertyName: String, instance: Object, query_members: bool = false) → void
execute_script(script: String) → Variant
fire_key_event(key_event: InputEventKey) → void
fire_mouse_event(position: Vector2, button_index: MouseButton, is_pressed: bool) → void

acceleratedbool

请求 GPU RenderingDevice。实际结果用 is_accelerated 查询；修改后调用 rebuild 应用，会重新加载页面。Compatibility、headless 或设备不可用时回退到 CPU。

默认值: — · 访问器: set_accelerated() / get_accelerated()

max_render_fpsint

单 View 动画与重绘帧率上限，运行时立即生效并在重建后保留。0 仅移除此项限制；SDK Free 版的 60 FPS 上限、Godot 帧率限制和 VSync 仍独立生效。

默认值: — · 访问器: set_max_render_fps() / get_max_render_fps()

source_typeint

初始来源类型：0 为 URL，1 为内联 HTML。

默认值: — · 访问器: set_source_type() / get_source_type()

initial_urlString

source_type 为 0 时，自动初始化加载的 URL。

默认值: — · 访问器: set_initial_url() / get_initial_url()

initial_htmlString

source_type 为 1 时，自动初始化加载的 HTML。

默认值: — · 访问器: set_initial_html() / get_initial_html()

initial_base_urlString

初始内联 HTML 中相对资源的基址。

默认值: — · 访问器: set_initial_base_url() / get_initial_base_url()

document_readybool

当前主文档是否已达到 DOM 就绪，只读。

默认值: — · 访问器: is_document_ready() · 只读

navigation_idint

主文档代次，只读。

默认值: — · 访问器: get_navigation_id() · 只读

current_urlString

运行时主文档的实际 URL，与初始页面配置分开，只读。

默认值: — · 访问器: get_current_url() · 只读

htmlString

兼容的内联来源属性。新代码使用 initial_html／source_type 配置初始页面，或 load_html 显式导航。

默认值: — · 访问器: set_html_content() / get_html_content()

htmlUrlString

兼容的 URL 来源属性。新代码使用 initial_url 配置初始页面，或 load_url 显式导航。

默认值: — · 访问器: set_html_url() / get_html_url()

transparentbool

启用透明页面背景。初始化前配置；已创建页面需 rebuild 才能应用。

默认值: — · 访问器: set_transparent() / get_transparent()

lazybool

推迟自动初始化；显式加载请求仍会在布局尺寸有效后触发初始化。

默认值: — · 访问器: set_lazy() / get_lazy()

set_accelerated

set_accelerated(enabled: bool) → void

设置 accelerated。

get_accelerated

get_accelerated() → bool const

读取 accelerated。

is_accelerated

is_accelerated() → bool const

返回实际是否使用 GPU RenderingDevice。accelerated 仅表示请求；设备不可用或初始化失败时可回退到 CPU。

get_render_statistics

get_render_statistics() → Dictionary const

返回渲染统计。始终包含实际后端 accelerated、SDK 版本 sdk_edition、SDK 帧率上限 sdk_max_fps、单 View 上限 max_render_fps、共享 Ultralight 渲染时间 ultralight_render_us，以及当前 View 的 cpu_page_upload_bytes、cpu_mipmap_count、cpu_upload_us。CPU 累计计数在重建后保留。

仅实际启用 GPU 时追加 gpu_available、bitmap_upload_bytes、geometry_upload_bytes、state_upload_bytes、draws、batches、feedback_copies、render_passes、rd_record_us、gpu_us、gpu_draws_by_shader。GPU 计数覆盖全部 View；GPU 计时为零也可能表示时间戳不可用。Canvas 等 SDK 位图内容在 GPU 模式仍可能上传。

CPU、未初始化和回退状态不包含 GPU 字段。渲染准备时间不包含渲染调用以外的脚本执行，不能作为应用总帧耗时。

set_max_render_fps

set_max_render_fps(fps: int) → void

设置 max_render_fps。

get_max_render_fps

get_max_render_fps() → int const

读取 max_render_fps。

get_bridge_statistics

get_bridge_statistics() → Dictionary const

返回绑定、宿主容器代理、宿主对象代理与 JS 保留句柄数量，用于诊断。尚无桥接上下文时返回空 Dictionary。

unbind

unbind(name: String) → void

撤销当前同名临时导出及其嵌套代理。持久注册项使用注册表的 unregister。

load_url

load_url(url: String, timeout: float = 30.0) → UltralightTask

导航到 url，返回等待主文档 DOM 就绪的任务。timeout 单位为秒，须有限、为正且不超过 1,000,000,000。尚未完成布局时等待有效尺寸。

load_html

load_html(html: String, base_url: String = "", timeout: float = 30.0) → UltralightTask

加载内联 HTML，base_url 为相对脚本、样式和图片提供基址。返回主文档 DOM 就绪任务；timeout 单位为秒。

reload

reload(timeout: float = 30.0) → UltralightTask

重新加载当前页面，返回主文档 DOM 就绪任务。内联页面保留 HTML 与 base_url。

wait_ready

wait_ready(timeout: float = 30.0) → UltralightTask

观察调用时的主文档。已就绪时可同步完成；未完成时发生导航会使等待失效。

wait_for_selector

wait_for_selector(selector: String, timeout: float = 30.0) → UltralightTask

等待当前主文档出现匹配的 CSS 元素。只检查存在性，不检查可见性；无效选择器返回错误。

evaluate

evaluate(source: String) → UltralightResult

同步求值并返回明确的 Result。数组和普通对象使用实时共享句柄，null 对应 Nil，undefined 对应 UltralightUndefined。

evaluate_copy

evaluate_copy(source: String) → UltralightResult

同步求值并将自有可枚举数据递归复制为独立 Godot 容器。循环、超过 64 层或不支持的值会失败。

evaluate_handle

evaluate_handle(source: String) → UltralightResult

求值并保留原始 JS 值，返回 UltralightJSValue，包括原始字符串、其他基本值和函数。

evaluate_async

evaluate_async(source: String, timeout: float = 30.0) → UltralightTask

求值并观察返回的 Promise；普通返回值也会完成任务。timeout 单位为秒，导航会撤销旧文档投递。

is_closed

is_closed() → bool const

返回此 View 是否已被 close 永久关闭。

close

close() → void

永久关闭 View，分离注册表，使旧句柄失效并结束未完成任务。之后不能重新加载。

is_initialized

is_initialized() → bool const

返回原生 SDK View 是否已创建。

is_loading

is_loading() → bool const

返回主文档是否正在加载。

is_document_ready

is_document_ready() → bool const

读取 document_ready。

get_navigation_id

get_navigation_id() → int const

读取 navigation_id。

get_current_url

get_current_url() → String const

读取 current_url。

get_last_load_error

get_last_load_error() → UltralightError const

返回最近一次主文档加载错误；没有错误时为 null。

input_text

input_text(text: String) → void

向页面发送已经提交的文本，不包含 IME 预编辑和候选框定位。

scroll_pixels

scroll_pixels(delta: Vector2) → void

向页面发送像素单位的滚动增量。

set_source_type

set_source_type(value: int) → void

设置 source_type。

get_source_type

get_source_type() → int const

读取 source_type。

set_initial_url

set_initial_url(value: String) → void

设置 initial_url。

get_initial_url

get_initial_url() → String const

读取 initial_url。

set_initial_html

set_initial_html(value: String) → void

设置 initial_html。

get_initial_html

get_initial_html() → String const

读取 initial_html。

set_initial_base_url

set_initial_base_url(value: String) → void

设置 initial_base_url。

get_initial_base_url

get_initial_base_url() → String const

读取 initial_base_url。

set_html_content

set_html_content(html: String) → void

设置 html。

get_html_content

get_html_content() → String

读取 html。

set_html_url

set_html_url(htmlUrl: String) → void

设置 htmlUrl。

get_html_url

get_html_url() → String

读取 htmlUrl。

set_transparent

set_transparent(is_transparent: bool) → void

设置 transparent。

get_transparent

get_transparent() → bool

读取 transparent。

set_lazy

set_lazy(is_lazy: bool) → void

设置 lazy。

get_lazy

get_lazy() → bool

读取 lazy。

rebuild

rebuild() → void

按当前渲染配置重建原生 View，使旧文档状态和任务失效；新文档会恢复已附着的 API 注册表。

init_view

init_view() → void

兼容的重建入口。普通加载使用自动初始化和显式 load 方法，无需手写布局等待流程。

bind_func

bind_func(funcName: String, callback: Callable) → void

兼容的函数导出入口。新代码使用返回可撤销句柄的 bind_function，或持久注册表的 register_function。

bind_object

bind_object(name: String, object: Object, options: UltralightBindingOptions = null) → UltralightBinding

临时导出 Godot Object，可配置 UltralightBindingOptions，并返回可撤销句柄。根 Array／Dictionary 或跨导航导出使用 UltralightAPI.register_object。

bind_function

bind_function(name: String, function: Callable, options: UltralightBindingOptions = null) → UltralightBinding

临时导出全局函数，返回可撤销的 UltralightBinding。导航持久化使用 UltralightAPI。

bind_object_legacy

bind_object_legacy(propertyName: String, instance: Object, query_members: bool = false) → void

兼容旧 query_members 布尔参数。新代码使用注册表和独立的成员／只读选项。

execute_script

execute_script(script: String) → Variant

兼容的按值求值入口，以 Nil 和日志报告失败。新代码使用 evaluate 区分成功 null 与错误，并获取共享值。

fire_key_event

fire_key_event(key_event: InputEventKey) → void

向已初始化页面转发键盘事件。普通 Control 输入会在 View 获得焦点时自动转发。

fire_mouse_event

fire_mouse_event(position: Vector2, button_index: MouseButton, is_pressed: bool) → void

向已初始化页面转发鼠标事件。position 为 View 本地像素坐标；MOUSE_BUTTON_NONE 表示移动，普通按钮配合 is_pressed 表示按下／释放，滚轮按钮表示滚动。普通 Control 会自动转发 GUI 输入。

内部生命周期回调

on_update_frame

on_update_frame() → void

内部生命周期回调，在 Godot 绘制后发布纹理。已自动连接，应用无需调用。

on_resized

on_resized() → void

内部生命周期回调，按 Control 尺寸调整已初始化页面。已自动连接，应用无需调用。

查看类文档源码 ↗