方法

CefTexture 提供一组方法，用于控制浏览器行为并与网页内容交互。

CefTexture2D 输入转发辅助方法

CefTexture2D 仍以渲染/运行时为主，但也提供底层输入转发辅助方法，便于高级场景集成：

forward_mouse_button_event(event, pixel_scale_factor, device_scale_factor)
forward_mouse_motion_event(event, pixel_scale_factor, device_scale_factor)
forward_pan_gesture_event(event, pixel_scale_factor, device_scale_factor)
forward_magnify_gesture_event(event)
forward_key_event(event, focus_on_editable_field)
forward_screen_touch_event(event, pixel_scale_factor, device_scale_factor)
forward_screen_drag_event(event, pixel_scale_factor, device_scale_factor)
forward_input_event(event, pixel_scale_factor, device_scale_factor, focus_on_editable_field)

这些方法刻意保持与节点类型无关：不会自动把事件坐标从 viewport/global 空间转换为本地坐标。请在调用前自行完成坐标映射并传入明确的缩放参数。

gdscript

# 示例：在 Sprite2D/3D 工作流中手动转发输入
var browser_tex := CefTexture2D.new()
browser_tex.texture_size = Vector2i(1024, 1024)

func _unhandled_input(event: InputEvent) -> void:
    var pixel_scale := 1.0
    var device_scale := DisplayServer.screen_get_scale()
    browser_tex.forward_input_event(event, pixel_scale, device_scale, false)

CefTexture2D 运行时辅助方法

CefTexture2D 还提供运行时/浏览器控制相关的辅助方法。CefTexture 内部会使用这些能力，高级用户也可以直接调用：

eval(...)
go_back(), go_forward(), can_go_back(), can_go_forward()
reload(), reload_ignore_cache(), stop_loading(), is_loading()
set_zoom_level(...), get_zoom_level()
set_audio_muted(...), is_audio_muted()
send_ipc_message(...), send_ipc_binary_message(...), send_ipc_data(...)
find_text(...), find_next(), find_previous(), stop_finding()
grant_permission(...), deny_permission(...), is_permission_pending(...)
get_permission_setting(...)

为保持 API 一致性，这些核心控制在命名上与 CefTexture 保持一致（也包括 url、enable_accelerated_osr、background_color、popup_policy 等共享属性）。

当你直接使用 CefTexture2D 时，需要自行在场景中完成这些方法的集成（例如坐标映射与焦点状态管理）。

JavaScript 执行

`eval(code: String)`

在浏览器主 Frame（main frame）中执行 JavaScript 代码。

如果 JavaScript 必须在页面 document 加载前可用，请使用 preload_script 或 preload_script_path 属性，而不是导航后再调用 eval。

gdscript

# Execute JavaScript
cef_texture.eval("document.body.style.backgroundColor = 'red'")

# Call a JavaScript function
cef_texture.eval("updateScore(100)")

# Interact with the DOM
cef_texture.eval("document.getElementById('player-name').innerText = 'Player1'")

IPC（进程间通信）

`send_ipc_message(message: String)`

从 Godot 向 JavaScript 发送消息。网页端如果注册了 window.onIpcMessage(msg) 回调，就会收到该消息。

gdscript

# Send a simple string message
cef_texture.send_ipc_message("Hello from Godot!")

# Send structured data as JSON using a Dictionary
var payload := {"action": "update", "value": 42}
cef_texture.send_ipc_message(JSON.stringify(payload))

网页端 JavaScript（在 CEF 浏览器中运行）：

javascript

// Register the callback to receive messages from Godot
window.onIpcMessage = function(msg) {
    console.log("Received from Godot:", msg);
    var data = JSON.parse(msg);
    // Handle the message...
};

`send_ipc_binary_message(data: PackedByteArray)`

从 Godot 向 JavaScript 发送二进制数据。如果注册了 window.onIpcBinaryMessage(arrayBuffer) 回调，数据将作为 ArrayBuffer 传递。

使用原生 CEF 进程消息传递，零编码开销，可高效传输二进制数据（图像、音频、协议缓冲区等）。

gdscript

# Send raw binary data
var data := PackedByteArray([0x01, 0x02, 0x03, 0x04])
cef_texture.send_ipc_binary_message(data)

# Send an image as binary
var image := Image.load_from_file("res://icon.png")
var png_data := image.save_png_to_buffer()
cef_texture.send_ipc_binary_message(png_data)

# Send a file's contents
var file := FileAccess.open("res://data.bin", FileAccess.READ)
var file_data := file.get_buffer(file.get_length())
cef_texture.send_ipc_binary_message(file_data)

在您的 JavaScript 中（在 CEF 浏览器中运行）：

javascript

// Register the callback to receive binary data from Godot
window.onIpcBinaryMessage = function(arrayBuffer) {
    console.log("Received binary data:", arrayBuffer.byteLength, "bytes");
    
    // Example: Process as an image
    const blob = new Blob([arrayBuffer], { type: 'image/png' });
    const url = URL.createObjectURL(blob);
    document.getElementById('image').src = url;
    
    // Example: Process as typed array
    const view = new Uint8Array(arrayBuffer);
    console.log("First byte:", view[0]);
};

缩放控制

`set_zoom_level(level: float)`

设置浏览器的缩放级别。0.0 是默认值（100%）。正值放大，负值缩小。

gdscript

cef_texture.set_zoom_level(1.0)   # Zoom in
cef_texture.set_zoom_level(-1.0)  # Zoom out
cef_texture.set_zoom_level(0.0)   # Reset to default

`get_zoom_level() -> float`

返回当前缩放级别。

gdscript

var zoom = cef_texture.get_zoom_level()
print("Current zoom: ", zoom)

音频控制

`set_audio_muted(muted: bool)`

静音或取消静音浏览器音频。

gdscript

cef_texture.set_audio_muted(true)   # Mute
cef_texture.set_audio_muted(false)  # Unmute

`is_audio_muted() -> bool`

如果浏览器音频已静音，返回 true。

gdscript

if cef_texture.is_audio_muted():
    print("Audio is muted")

音频捕获

这些方法可将浏览器音频通过 Godot 音频系统路由。详细文档请参见音频捕获页面。

TIP

在创建浏览器之前，必须在项目设置中启用音频捕获（godot_cef/audio/enable_audio_capture）。

`is_audio_capture_enabled() -> bool`

如果项目设置中启用了音频捕获模式，返回 true。

gdscript

if cef_texture.is_audio_capture_enabled():
    print("Audio capture is enabled")

`create_audio_stream() -> AudioStreamGenerator`

创建并返回一个配置了正确采样率的 AudioStreamGenerator。

gdscript

var audio_stream = cef_texture.create_audio_stream()
audio_player.stream = audio_stream
audio_player.play()

`push_audio_to_playback(playback: AudioStreamGeneratorPlayback) -> int`

将 CEF 缓冲的音频数据推送到给定的播放器。返回推送的帧数。在 _process() 中每帧调用此方法。

gdscript

func _process(_delta):
    var playback = audio_player.get_stream_playback()
    if playback:
        cef_texture.push_audio_to_playback(playback)

`has_audio_data() -> bool`

如果缓冲区中有可用的音频数据，返回 true。

gdscript

if cef_texture.has_audio_data():
    print("Audio data available")

`get_audio_buffer_size() -> int`

返回当前缓冲的音频数据包数量。

gdscript

var buffer_size = cef_texture.get_audio_buffer_size()

拖放

这些方法可在 Godot 和 CEF 浏览器之间进行拖放操作。详细文档请参见拖放页面。

`drag_enter(file_paths: Array[String], position: Vector2, allowed_ops: int)`

通知 CEF 拖动操作已进入浏览器区域。在处理 Godot 的 _can_drop_data() 时调用此方法。

gdscript

func _can_drop_data(at_position: Vector2, data) -> bool:
    if data is Array:
        cef_texture.drag_enter(data, at_position, DragOperation.COPY)
        return true
    return false

`drag_over(position: Vector2, allowed_ops: int)`

在拖动移动到浏览器上方时更新拖动位置。在拖动操作期间重复调用此方法。

gdscript

cef_texture.drag_over(mouse_position, DragOperation.COPY)

`drag_leave()`

通知 CEF 拖动已离开浏览器区域但未放下。

gdscript

cef_texture.drag_leave()

`drag_drop(position: Vector2)`

完成拖动操作并在指定位置放下数据。

gdscript

func _drop_data(at_position: Vector2, data):
    cef_texture.drag_drop(at_position)

`drag_source_ended(position: Vector2, operation: int)`

通知 CEF 浏览器发起的拖动已用放置结果结束。此方法会完成浏览器拖动操作，因此之后不要再调用 drag_source_system_ended()。

gdscript

cef_texture.drag_source_ended(drop_position, DragOperation.COPY)

`drag_source_system_ended()`

通知 CEF 浏览器发起的拖动已取消，或没有放置结果就结束。此方法会以 DragOperation.NONE 完成浏览器拖动操作。

gdscript

cef_texture.drag_source_system_ended()

`is_dragging_from_browser() -> bool`

如果当前有从浏览器发起的拖动操作正在进行，返回 true。

gdscript

if cef_texture.is_dragging_from_browser():
    print("Browser drag in progress")

`is_drag_over() -> bool`

如果当前有拖动操作在 CefTexture 上方，返回 true。

gdscript

if cef_texture.is_drag_over():
    print("Drag is over browser area")

权限处理

以下方法同时适用于 CefTexture 与 CefTexture2D。浏览器实际使用的 permission_policy 为 SIGNAL 时，可用应答方法回答 permission_requested；配置查询适用于任何策略。策略、超时和界面清理示例见权限。

`grant_permission(request_id: int) -> bool`

为此 ID 记录允许决定。如果一次 CEF 请求包含多项权限，必须允许所有 ID 后才向 CEF 授权。

成功记录回答时返回 true，不代表整组已经获准。 ID 已超时、不存在、已失效或已经回答时返回 false。未知权限类型不可授权，尝试允许仍会使整组以 denied 结束。

gdscript

func _on_permission_requested(permission_type: String, url: String, request_id: int):
    if permission_type == "geolocation" and url == "https://maps.example/":
        cef_texture.grant_permission(request_id)
    else:
        cef_texture.deny_permission(request_id)

`deny_permission(request_id: int) -> bool`

立即拒绝此请求，以及同一 CEF 请求中的其他权限。

成功接受回答时返回 true；ID 已超时、不存在、已失效或已经回答时返回 false。

`is_permission_pending(request_id: int) -> bool`

返回此 ID 是否仍可回答。某个 ID 的允许决定记录后，就不能再次回答，即使同组请求仍在等待其他权限的决定。通过 permission_request_finished 获知整组最终结果并清理对话框。

`get_permission_setting(permission_type: String, requesting_url: String, top_level_url: String) -> String`

从浏览器共享的请求上下文同步读取支持的权限内容设置。浏览器准备好后，在 Godot 主线程调用，并显式提供请求页面与顶层页面的绝对 HTTP(S) URL。不接受空 URL 或含用户名、密码的 URL。

CEF 值返回为 allow、block、ask、default、session_only 或 unknown；无法查询时返回 unsupported、unavailable 或 invalid_url。 default 不代表 ask。

此方法查询配置值，不判断应用、浏览器与操作系统合并后的实际授权状态，也不修改策略或回答待处理请求。支持的标签、URL 范围及摄像头和麦克风的限制见查询配置中的权限设置。

这些方法允许您查询、设置和删除 Cookie，以及将 Cookie 存储刷新到磁盘。所有操作都是异步的——结果通过信号传递（参见信号）。

`get_all_cookies() -> bool`

发起获取所有 Cookie 的请求。完成后，cookies_received 信号会携带 CookieInfo 对象数组触发。

如果请求已发起返回 true，浏览器未准备好则返回 false。

gdscript

func _ready():
    cef_texture.cookies_received.connect(_on_cookies_received)
    cef_texture.get_all_cookies()

func _on_cookies_received(cookies):
    for cookie in cookies:
        print(cookie.name, " = ", cookie.value)

`get_cookies(url: String, include_http_only: bool) -> bool`

获取与指定 URL 匹配的 Cookie。完成后触发 cookies_received 信号。

参数：

url：用于匹配 Cookie 的 URL
include_http_only：是否包含 HTTP-only Cookie（JavaScript 无法访问的 Cookie）

如果请求已发起返回 true，浏览器未准备好则返回 false。

gdscript

# 获取某个域的所有 Cookie（包括 HTTP-only）
cef_texture.get_cookies("https://example.com", true)

# 仅获取非 HTTP-only Cookie
cef_texture.get_cookies("https://example.com", false)

`set_cookie(url: String, name: String, value: String, domain: String, path: String, secure: bool, httponly: bool) -> bool`

设置一个 Cookie。完成后，cookie_set 信号会携带一个 bool 值触发，表示是否成功。

参数：

url：Cookie 关联的 URL
name：Cookie 名称
value：Cookie 值
domain：Cookie 域（如 .example.com）
path：Cookie 路径（如 /）
secure：是否仅通过 HTTPS 发送
httponly：是否为 HTTP-only（JavaScript 无法访问）

如果请求已发起返回 true，浏览器未准备好则返回 false。

gdscript

# 设置会话 Cookie
cef_texture.set_cookie(
    "https://example.com",
    "session_id", "abc123",
    ".example.com", "/",
    true,   # secure
    true    # httponly
)

# 设置简单偏好 Cookie
cef_texture.set_cookie(
    "https://example.com",
    "theme", "dark",
    ".example.com", "/",
    false, false
)

`delete_cookies(url: String, cookie_name: String) -> bool`

删除与指定 URL 和/或名称匹配的 Cookie。完成后，cookies_deleted 信号会携带已删除的 Cookie 数量触发。

参数：

url：URL 过滤器。传空字符串 "" 匹配所有 URL。
cookie_name：名称过滤器。传空字符串 "" 匹配该 URL 下的所有 Cookie 名称。

如果请求已发起返回 true，浏览器未准备好则返回 false。

gdscript

# 删除特定 Cookie
cef_texture.delete_cookies("https://example.com", "session_id")

# 删除某个域的所有 Cookie
cef_texture.delete_cookies("https://example.com", "")

# 删除所有 Cookie（等同于 clear_cookies()）
cef_texture.delete_cookies("", "")

`clear_cookies() -> bool`

便捷方法，删除所有 Cookie。等同于 delete_cookies("", "")。

完成后触发 cookies_deleted 信号。

gdscript

cef_texture.clear_cookies()

`flush_cookies() -> bool`

将 Cookie 存储刷新到磁盘。完成后触发 cookies_flushed 信号。

如果请求已发起返回 true，浏览器未准备好则返回 false。

gdscript

# 关闭前确保 Cookie 已持久化
cef_texture.flush_cookies()

方法 ​

CefTexture2D 输入转发辅助方法 ​

CefTexture2D 运行时辅助方法 ​

导航 ​

go_back() ​

go_forward() ​

can_go_back() -> bool ​

can_go_forward() -> bool ​

reload() ​

reload_ignore_cache() ​

stop_loading() ​

is_loading() -> bool ​

JavaScript 执行 ​

eval(code: String) ​

IPC（进程间通信） ​

send_ipc_message(message: String) ​

send_ipc_binary_message(data: PackedByteArray) ​

缩放控制 ​

set_zoom_level(level: float) ​

get_zoom_level() -> float ​

音频控制 ​

set_audio_muted(muted: bool) ​

is_audio_muted() -> bool ​

音频捕获 ​

is_audio_capture_enabled() -> bool ​

create_audio_stream() -> AudioStreamGenerator ​

push_audio_to_playback(playback: AudioStreamGeneratorPlayback) -> int ​

has_audio_data() -> bool ​

get_audio_buffer_size() -> int ​

拖放 ​

drag_enter(file_paths: Array[String], position: Vector2, allowed_ops: int) ​

drag_over(position: Vector2, allowed_ops: int) ​

drag_leave() ​

drag_drop(position: Vector2) ​

drag_source_ended(position: Vector2, operation: int) ​

drag_source_system_ended() ​

is_dragging_from_browser() -> bool ​

is_drag_over() -> bool ​

权限处理 ​

grant_permission(request_id: int) -> bool ​

deny_permission(request_id: int) -> bool ​

is_permission_pending(request_id: int) -> bool ​

get_permission_setting(permission_type: String, requesting_url: String, top_level_url: String) -> String ​

Cookie 与会话管理 ​

get_all_cookies() -> bool ​

get_cookies(url: String, include_http_only: bool) -> bool ​

set_cookie(url: String, name: String, value: String, domain: String, path: String, secure: bool, httponly: bool) -> bool ​

delete_cookies(url: String, cookie_name: String) -> bool ​

clear_cookies() -> bool ​

flush_cookies() -> bool ​

方法

CefTexture2D 输入转发辅助方法

CefTexture2D 运行时辅助方法

导航

`go_back()`

`go_forward()`

`can_go_back() -> bool`

`can_go_forward() -> bool`

`reload()`

`reload_ignore_cache()`

`stop_loading()`

`is_loading() -> bool`

JavaScript 执行

`eval(code: String)`

IPC（进程间通信）

`send_ipc_message(message: String)`

`send_ipc_binary_message(data: PackedByteArray)`

缩放控制

`set_zoom_level(level: float)`

`get_zoom_level() -> float`

音频控制

`set_audio_muted(muted: bool)`

`is_audio_muted() -> bool`

音频捕获

`is_audio_capture_enabled() -> bool`

`create_audio_stream() -> AudioStreamGenerator`

`push_audio_to_playback(playback: AudioStreamGeneratorPlayback) -> int`

`has_audio_data() -> bool`

`get_audio_buffer_size() -> int`

拖放

`drag_enter(file_paths: Array[String], position: Vector2, allowed_ops: int)`

`drag_over(position: Vector2, allowed_ops: int)`

`drag_leave()`

`drag_drop(position: Vector2)`

`drag_source_ended(position: Vector2, operation: int)`

`drag_source_system_ended()`

`is_dragging_from_browser() -> bool`

`is_drag_over() -> bool`

权限处理

`grant_permission(request_id: int) -> bool`

`deny_permission(request_id: int) -> bool`

`is_permission_pending(request_id: int) -> bool`

`get_permission_setting(permission_type: String, requesting_url: String, top_level_url: String) -> String`

Cookie 与会话管理

`get_all_cookies() -> bool`

`get_cookies(url: String, include_http_only: bool) -> bool`

`set_cookie(url: String, name: String, value: String, domain: String, path: String, secure: bool, httponly: bool) -> bool`

`delete_cookies(url: String, cookie_name: String) -> bool`

`clear_cookies() -> bool`

`flush_cookies() -> bool`