GFDownloadUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/io/gf_download_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
通用文件下载队列。 提供顺序下载、临时文件提交、可选续传、SHA-256 校验、暂停、取消和诊断快照。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | download_started |
signal download_started(task_id: int, task: GFDownloadTask) |
| 信号 | download_progressed |
signal download_progressed(task_id: int, received_bytes: int, total_bytes: int) |
| 信号 | download_completed |
signal download_completed(task_id: int, result: Dictionary) |
| 信号 | download_failed |
signal download_failed(task_id: int, result: Dictionary) |
| 信号 | download_cancelled |
signal download_cancelled(task_id: int, result: Dictionary) |
| 属性 | timeout_seconds |
var timeout_seconds: float = 30.0 |
| 属性 | default_temp_suffix |
var default_temp_suffix: String = ".download" |
| 属性 | default_segment_suffix |
var default_segment_suffix: String = ".segment" |
| 属性 | overwrite_existing |
var overwrite_existing: bool = true |
| 属性 | emit_progress_interval_seconds |
var emit_progress_interval_seconds: float = 0.1 |
| 属性 | default_max_retries |
var default_max_retries: int = 0 |
| 属性 | default_retry_delay_seconds |
var default_retry_delay_seconds: float = 0.0 |
| 方法 | init |
func init() -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | tick |
func tick(_delta: float = 0.0) -> void: |
| 方法 | enqueue_download |
func enqueue_download( url: String, target_path: String, callback: Callable = Callable(), options: Dictionary = {} ) -> int: |
| 方法 | cancel |
func cancel(task_id: int, delete_temp: bool = false) -> bool: |
| 方法 | set_paused |
func set_paused(value: bool) -> void: |
| 方法 | pause |
func pause() -> void: |
| 方法 | resume |
func resume() -> void: |
| 方法 | is_paused |
func is_paused() -> bool: |
| 方法 | clear_queue |
func clear_queue(cancel_active: bool = false, delete_temp: bool = false) -> void: |
| 方法 | get_active_task |
func get_active_task() -> GFDownloadTask: |
| 方法 | get_queued_task_ids |
func get_queued_task_ids() -> PackedInt32Array: |
| 方法 | get_result |
func get_result(task_id: int) -> Dictionary: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
| 方法 | _start_http_request |
func _start_http_request(request_data: Dictionary) -> Error: |
| 方法 | _complete_active_download |
func _complete_active_download( success: bool, response_code: int, error: String = "", retryable: bool = false ) -> void: |
信号¶
download_started¶
- API：
public
下载任务开始时发出。
参数：
| 名称 | 说明 |
|---|---|
task_id |
下载任务句柄。 |
task |
下载任务快照。 |
download_progressed¶
- API：
public
下载进度更新时发出。
参数：
| 名称 | 说明 |
|---|---|
task_id |
下载任务句柄。 |
received_bytes |
已接收字节数。 |
total_bytes |
总字节数；未知时为 -1。 |
download_completed¶
- API：
public
下载任务成功完成时发出。
参数：
| 名称 | 说明 |
|---|---|
task_id |
下载任务句柄。 |
result |
下载结果字典。 |
结构：
result: Dictionary，包含任务字段、success、cancelled 和可选完成元数据。
download_failed¶
- API：
public
下载任务失败时发出。
参数：
| 名称 | 说明 |
|---|---|
task_id |
下载任务句柄。 |
result |
下载结果字典。 |
结构：
result: Dictionary，包含任务字段、success、cancelled 和错误详情。
download_cancelled¶
- API：
public
下载任务被取消时发出。
参数：
| 名称 | 说明 |
|---|---|
task_id |
下载任务句柄。 |
result |
下载结果字典。 |
结构：
result: Dictionary，包含任务字段、success、cancelled 和取消详情。
属性¶
timeout_seconds¶
- API：
public
HTTP 请求超时时间，单位秒。
default_temp_suffix¶
- API：
public
临时文件后缀。
default_segment_suffix¶
- API：
public
分段续传临时文件后缀。
overwrite_existing¶
- API：
public
目标文件已存在时默认是否覆盖。
emit_progress_interval_seconds¶
- API：
public
进度信号最小间隔，单位秒。
default_max_retries¶
- API：
public
默认最大重试次数。
default_retry_delay_seconds¶
- API：
public
默认重试等待秒数。
方法¶
init¶
- API：
public
初始化下载队列运行时状态并启用暂停无关处理。
dispose¶
- API：
public
取消下载、释放 HTTPRequest 并清理运行时状态。
tick¶
- API：
public
驱动下载进度采样。
参数：
| 名称 | 说明 |
|---|---|
_delta |
为兼容统一 tick 签名而保留的参数。 |
enqueue_download¶
- API：
public
func enqueue_download( url: String, target_path: String, callback: Callable = Callable(), options: Dictionary = {} ) -> int:
将下载任务加入队列。
参数：
| 名称 | 说明 |
|---|---|
url |
下载 URL。 |
target_path |
最终写入路径。 |
callback |
完成、失败或取消时执行的回调，签名为 func(result: Dictionary)。 |
options |
可选参数，支持 headers、resume、overwrite、expected_sha256、metadata、temp_path、segment_path、max_retries、retry_delay_seconds。 |
返回：任务句柄；输入无效时返回 0。
结构：
options: Dictionary，可包含 headers、resume、overwrite、expected_sha256、metadata、temp_path、segment_path、max_retries 和 retry_delay_seconds。
cancel¶
- API：
public
取消下载任务。
参数：
| 名称 | 说明 |
|---|---|
task_id |
任务句柄。 |
delete_temp |
是否删除临时文件。 |
返回：找到并取消任务时返回 true。
set_paused¶
- API：
public
设置下载队列暂停状态。暂停时不会启动新任务，当前任务会保留临时文件并回到队首。
参数：
| 名称 | 说明 |
|---|---|
value |
是否暂停。 |
pause¶
- API：
public
暂停下载队列。
resume¶
- API：
public
恢复下载队列。
is_paused¶
- API：
public
检查下载队列是否暂停。
返回：暂停时返回 true。
clear_queue¶
- API：
public
清空等待队列，可选取消当前任务。
参数：
| 名称 | 说明 |
|---|---|
cancel_active |
是否取消当前任务。 |
delete_temp |
是否删除临时文件。 |
get_active_task¶
- API：
public
获取当前正在下载的任务拷贝。
返回：当前任务；没有任务时返回 null。
get_queued_task_ids¶
- API：
public
获取等待队列中的任务 ID。
返回：任务 ID 列表。
get_result¶
- API：
public
获取指定任务最近结果。
参数：
| 名称 | 说明 |
|---|---|
task_id |
任务句柄。 |
返回：结果字典；不存在时返回空字典。
结构：
return: Dictionary，包含最新任务结果；没有结果时为空字典。
get_debug_snapshot¶
- API：
public
获取下载工具诊断快照。
返回：诊断快照字典。
结构：
return: Dictionary，包含 paused、queued_count、queued_task_ids、active_task 和 result_count。
_start_http_request¶
- API：
protected
启动底层 HTTP 下载请求。
参数：
| 名称 | 说明 |
|---|---|
request_data |
请求数据。 |
返回：Godot 错误码。
结构：
request_data: Dictionary，包含 task_id、url、headers、download_file 和 resume_offset。
_complete_active_download¶
- API：
protected
func _complete_active_download( success: bool, response_code: int, error: String = "", retryable: bool = false ) -> void:
完成当前活动下载，并根据结果提交、重试或失败任务。
参数：
| 名称 | 说明 |
|---|---|
success |
底层请求是否成功取得响应体。 |
response_code |
HTTP 响应码。 |
error |
失败原因。 |
retryable |
是否允许按任务重试策略重新入队。 |