GFAsyncProgress¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/common/gf_async_progress.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时句柄 (
runtime_handle) - 首次版本：
7.0.0
可节流的通用异步进度句柄。 用于把下载、预热、导入、后台任务或项目流程的进度更新统一为 0 到 1 的值、 可选消息和元数据。它不决定 UI 样式，也不绑定具体任务类型。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | progressed |
signal progressed(value: float, message: String, metadata: Dictionary) |
| 属性 | min_delta |
var min_delta: float = 0.0: |
| 属性 | min_interval_msec |
var min_interval_msec: int = 0: |
| 属性 | emit_on_message_change |
var emit_on_message_change: bool = true |
| 方法 | _init |
func _init(initial_value: float = 0.0, initial_message: String = "", initial_metadata: Dictionary = {}) -> void: |
| 方法 | update |
func update(value: float, message: String = "", metadata: Dictionary = {}) -> bool: |
| 方法 | force_emit |
func force_emit() -> bool: |
| 方法 | complete |
func complete(message: String = "", metadata: Dictionary = {}) -> bool: |
| 方法 | reset |
func reset(value: float = 0.0, message: String = "", metadata: Dictionary = {}) -> void: |
| 方法 | get_value |
func get_value() -> float: |
| 方法 | get_message |
func get_message() -> String: |
| 方法 | get_metadata |
func get_metadata() -> Dictionary: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
progressed¶
- API：
public - 首次版本：
7.0.0
进度通过节流条件并对外发布时发出。
参数：
| 名称 | 说明 |
|---|---|
value |
当前进度，范围 0 到 1。 |
message |
当前进度消息。 |
metadata |
当前进度元数据。 |
结构：
metadata: Dictionary，调用方定义的进度上下文。
属性¶
min_delta¶
- API：
public - 首次版本：
7.0.0
触发进度信号的最小数值变化。设为 0 时任意数值变化都会触发。
min_interval_msec¶
- API：
public - 首次版本：
7.0.0
触发进度信号的最小时间间隔，单位毫秒。设为 0 时不按时间节流。
emit_on_message_change¶
- API：
public - 首次版本：
7.0.0
消息变化时是否允许触发信号，即使数值变化小于 min_delta。
方法¶
_init¶
- API：
public - 首次版本：
7.0.0
func _init(initial_value: float = 0.0, initial_message: String = "", initial_metadata: Dictionary = {}) -> void:
创建进度句柄。
参数：
| 名称 | 说明 |
|---|---|
initial_value |
初始进度，范围会被夹到 0 到 1。 |
initial_message |
初始消息。 |
initial_metadata |
初始元数据。 |
结构：
initial_metadata: Dictionary，调用方定义的进度上下文。
update¶
- API：
public - 首次版本：
7.0.0
更新进度，并在满足节流条件时发出 progressed。
参数：
| 名称 | 说明 |
|---|---|
value |
新进度值，范围会被夹到 0 到 1。 |
message |
进度消息。 |
metadata |
进度元数据。 |
返回：本次更新是否发出了 progressed。
结构：
metadata: Dictionary，调用方定义的进度上下文。
force_emit¶
- API：
public - 首次版本：
7.0.0
强制发布当前进度。
返回：是否成功发出 progressed。
complete¶
- API：
public - 首次版本：
7.0.0
将进度更新为 1.0 并强制发布。
参数：
| 名称 | 说明 |
|---|---|
message |
完成消息。 |
metadata |
完成元数据。 |
返回：是否成功发出 progressed。
结构：
metadata: Dictionary，调用方定义的进度上下文。
reset¶
- API：
public - 首次版本：
7.0.0
重置进度状态，不发出信号。
参数：
| 名称 | 说明 |
|---|---|
value |
新进度值。 |
message |
新消息。 |
metadata |
新元数据。 |
结构：
metadata: Dictionary，调用方定义的进度上下文。
get_value¶
- API：
public - 首次版本：
7.0.0
获取当前进度值。
返回：当前进度值。
get_message¶
- API：
public - 首次版本：
7.0.0
获取当前消息。
返回：当前消息。
get_metadata¶
- API：
public - 首次版本：
7.0.0
获取当前元数据副本。
返回：当前元数据副本。
结构：
return: Dictionary，调用方定义的进度上下文。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取进度状态快照。
返回：进度状态快照。
结构：
return: Dictionary，包含 value、message、metadata、min_delta、min_interval_msec、has_emitted 和 last_emitted_value。