GFBackgroundWorkTask¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/jobs/gf_background_work_task.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时句柄 (
runtime_handle) - 首次版本：
3.17.0
后台工作记录。 保存后台工作状态、进度、输入数据、结果、错误文本和应用回调。 任务本身不直接启动线程；执行由 GFBackgroundWorkUtility 统一协调。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | Kind |
enum Kind |
| 枚举 | Status |
enum Status |
| 属性 | work_id |
var work_id: StringName = &"" |
| 属性 | kind |
var kind: Kind = Kind.CPU |
| 属性 | status |
var status: Status = Status.QUEUED |
| 属性 | priority |
var priority: int = 0 |
| 属性 | input_data |
var input_data: Variant = null |
| 属性 | result |
var result: Variant = null |
| 属性 | apply_result |
var apply_result: Variant = null |
| 属性 | error_message |
var error_message: String = "" |
| 属性 | progress |
var progress: float = 0.0 |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 属性 | resource_path |
var resource_path: String = "" |
| 属性 | resource_type_hint |
var resource_type_hint: String = "" |
| 属性 | cancel_requested |
var cancel_requested: bool = false |
| 属性 | created_msec |
var created_msec: int = 0 |
| 属性 | started_msec |
var started_msec: int = 0 |
| 属性 | finished_msec |
var finished_msec: int = 0 |
| 方法 | is_finished |
func is_finished() -> bool: |
| 方法 | to_dict |
func to_dict() -> Dictionary: |
| 方法 | kind_name |
static func kind_name(value: Kind) -> String: |
| 方法 | status_name |
static func status_name(value: Status) -> String: |
枚举¶
Kind¶
- API：
public
后台工作类型。
Status¶
- API：
public
enum Status { ## 已入队，等待启动。 QUEUED, ## 正在后台运行或等待资源加载。 RUNNING, ## 正在等待主线程应用回调。 APPLYING, ## 已成功完成。 COMPLETED, ## 已失败。 FAILED, ## 已取消。 CANCELLED, }
后台工作生命周期状态。
属性¶
work_id¶
- API：
public
工作 ID。
kind¶
- API：
public
工作类型。
status¶
- API：
public
当前状态。
priority¶
- API：
public
优先级，数值越大越早从等待队列启动。
input_data¶
- API：
public
工作输入数据。默认应只包含纯 Variant 数据。
结构：
input_data: Variant，复制到工作线程的纯数据载荷；显式允许对象载荷时除外。
result¶
- API：
public
工作结果。线程任务返回值或资源加载结果会写入该字段。
结构：
result: Variant，工作线程结果、资源加载结果或失败载荷。
apply_result¶
- API：
public
主线程应用回调的返回值。
结构：
apply_result: Variant，由可选主线程 apply 回调返回。
error_message¶
- API：
public
错误文本。
progress¶
- API：
public
进度，范围建议为 0.0 到 1.0。
metadata¶
- API：
public
项目自定义元数据。框架不解释该字段。
结构：
metadata: Dictionary，复制到后台任务中的项目侧元数据。
resource_path¶
- API：
public
资源加载路径，仅 RESOURCE 任务使用。
resource_type_hint¶
- API：
public
资源类型提示，仅 RESOURCE 任务使用。
cancel_requested¶
- API：
public
是否已请求取消。正在执行的线程任务不会被强行终止，只会在返回后转入取消终态。
created_msec¶
- API：
public
创建时间。
started_msec¶
- API：
public
开始时间。
finished_msec¶
- API：
public
结束时间。
方法¶
is_finished¶
- API：
public
当前工作是否已经进入终态。
返回：已完成、失败或取消时返回 true。
to_dict¶
- API：
public
转换为 Dictionary。
返回：工作字典。
结构：
return: Dictionary，包含 work_id、kind、kind_name、status、status_name、priority、progress、error_message、metadata、资源字段、cancel_requested、时间戳和结果标记。
kind_name¶
- API：
public
获取工作类型名称。
参数：
| 名称 | 说明 |
|---|---|
value |
工作类型枚举值。 |
返回：工作类型名称。
status_name¶
- API：
public
获取状态名称。
参数：
| 名称 | 说明 |
|---|---|
value |
状态枚举值。 |
返回：状态名称。