下载地址、File/Directory 写入目标、限制、取消信号与进度回调；两种 target 分支及全部字段见 DownloadOptions。
Host 完成原子提交后的 readwrite FileHandle。File target 返回传入的同一
代理；Directory target 返回目标目录中新建或替换的直接子 File 代理。
HbMiniProgramSDKError 参数、URL、Header、目标或 Host 返回值不合法时返回
INVALID_PARAMS / INVALID_NETWORK_RESPONSE；当前运行快照缺少或未启用 network、filesystem
时返回 PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED；Host 能力缺失时返回
METHOD_FORBIDDEN，旧 Runtime 可返回 METHOD_NOT_FOUND。
HbMiniProgramSDKError 非成功或部分 HTTP 响应返回 DOWNLOAD_HTTP_STATUS；
网络/响应 framing 失败、空闲超时、提交前取消或超出 maxBytes 分别返回
DOWNLOAD_NETWORK_FAILED、DOWNLOAD_TIMEOUT、DOWNLOAD_CANCELLED、FILE_TOO_LARGE。
文件授权、存在性、同名冲突、类型、配额和 I/O 失败返回对应稳定 FILE_* /
DIRECTORY_* 错误码。下载不会抛出 HbMiniProgramNetworkError。
需要同时声明并启用 network 与 filesystem，其中 network 还必须获得平台批准；访问
当前公开 Host 的流式下载 adapter 不支持小黑盒官方域名；useOfficialDomain 的批准不能
单独保证 download() 可用，也不会绕过敏感路径、Header、重定向、大小或超时策略。
下载本身不要求可信用户手势，但外部 File/Directory
必须事先通过 files picker 或 saveFile() 获得当前 session 的 readwrite 授权。
固定使用 GET，不跟随重定向，也不接受 body、Range、上传或自定义 validateStatus。
非 2xx、206、226 与 Content-Range 都不会进入文件提交；DOWNLOAD_HTTP_STATUS.data
仅包含脱敏的 status、可选 statusText 和安全响应头。响应字节留在 Host，并直接流式写入
临时目标，不经过 iframe bridge。
timeout 是网络/响应 body 空闲超时；maxBytes 是单次提交上限。Host 只有在长度与大小
约束全部满足并完成原子提交后才会 resolve。取消、超时、超限或其他失败不会改动原目标；
signal 与原子提交竞态时，提交前取消返回 DOWNLOAD_CANCELLED，提交已完成则仍返回成功。
Directory 文件名按安全的 Content-Disposition filename*、filename、suggestedName、
URL basename、download.bin 依次选择；不安全的响应候选会跳过，但调用方显式提供的非法
suggestedName 会在 Host I/O 前返回 INVALID_PARAMS。
import hbSDK from '@heybox/hb-sdk'
const directory = hbSDK.files.sandbox.directory('downloads')
await directory.create({ recursive: true })
const controller = new AbortController()
const file = await hbSDK.network.download({
url: 'https://cdn.example.com/report.json',
to: directory,
params: { format: 'full' },
headers: { accept: 'application/json' },
suggestedName: 'report.json',
overwrite: true,
timeout: 15_000,
maxBytes: 8 * 1024 * 1024,
signal: controller.signal,
onProgress: ({ loaded, total, lengthComputable }) => {
console.log(lengthComputable ? `${loaded}/${total}` : loaded)
},
})
const exactFile = hbSDK.files.sandbox.file('downloads/latest.json')
await exactFile.create()
const replaced = await hbSDK.network.download({
url: 'https://cdn.example.com/latest.json',
to: exactFile,
})
console.log(replaced === exactFile) // true
将 GET 响应流式写入受控 File/Directory target。