下载器使用指导
下载器组件：把网上的文件下载保存到手机，可以同时下载多个，随时报告进度，下载完成后给出文件路径。
下载由系统负责，切到后台、锁屏都不会中断，还可以在通知栏显示进度。下载完成拿到的文件路径可以直接交给 图像、音频播放器、视频播放器 等组件使用。 如果只是请求接口拿数据，用 Web客户端；更新自己的应用安装包，用应用更新。
快速上手
- 拖一个 下载器、一个按钮、一个标签、一个图像到屏幕；
- 搭下面的代码块：点按钮开始下载，标签显示进度，下完把图片显示出来。
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮1.Click() {
下载器1.Download("https://www.fun123.cn/static/images/logo.png", "")
}
when 下载器1.DownloadProgress(编号, 已下载, 总大小, 百分比) {
标签1.Text = join("已下载 ", 百分比, "%")
}
when 下载器1.DownloadCompleted(编号, 文件路径) {
标签1.Text = "下载完成"
图像1.Picture = 文件路径
}
when 下载器1.DownloadFailed(编号, 原因) {
标签1.Text = join("下载失败：", 原因)
}
同时下载多个：每次调用下载（URL网址，文件名）（Download）都会返回一个编号，事件里的 编号 就是它，用来分辨是哪一个下载。
可以把编号存进全局变量，或者存进字典对应到列表里的某一行。
搭建与测试
在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。
可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。
案例：取消指定下载
增加一个取消按钮；保存下载方法返回的任务编号，不要用文件名取消。网址替换成自己的可访问文件。
global 下载编号 = 0
when 按钮_下载.Click() {
下载编号 = 下载器1.Download("https://www.fun123.cn/static/images/logo.png", "logo.png")
}
when 按钮_取消.Click() {
下载器1.Cancel(下载编号)
}
进度事件中的编号用于区分同时进行的下载；服务器不给总长度时，不能仅靠百分比判断完成，完成状态以 DownloadCompleted 为准。
属性、方法与事件速查
完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。
| 入口 | 用途 |
|---|---|
保存位置（SaveLocation） |
文件保存位置：应用目录（默认，不需要权限，卸载应用时删除）或公共下载目录（文件管理器的「下载」里能看到）。 |
通知栏显示进度（ShowNotification） |
下载时在通知栏显示进度，完成后保留完成通知。 |
取消（编号）（Cancel） |
取消指定编号的下载并删除已下载部分，随后触发「下载失败」，原因为「已取消」。 |
全部取消（CancelAll） |
取消全部进行中的下载。 |
下载（URL网址，文件名）（Download） |
开始下载，返回下载编号（事件里用它区分多个下载）。文件名留空时从网址里取；同名文件已存在时系统自动改名，实际路径以「下载完成」为准。开始失败时返回 -1 并触发「下载失败」。 |
下载完成（编号，文件路径）（DownloadCompleted） |
下载完成，文件路径可直接给图像、音频播放器、文件等组件使用。 |
下载失败（编号，原因）（DownloadFailed） |
下载失败或被取消，原因是中文说明。开始下载就失败时编号为 -1。 |
下载进度（编号，已下载，总大小，百分比）（DownloadProgress） |
下载进度变化。已下载与总大小单位为字节；服务器没给文件大小时总大小为 -1、百分比为 0。 |
常见问题与验收
| 检查项 | 操作与预期 |
|---|---|
| 初始化 | 对照案例检查是否已经调用加载、注册、连接或显示方法；仅拖入组件不会替你执行这些步骤。 |
| 结果返回 | 将成功事件和失败事件都接到标签，记录事件参数；异步操作完成前不读取结果属性。 |
| 输入配置 | 检查素材名大小写、网址是否为直接资源地址、文件是否存在、编号和索引是否在范围内。 |
| 平台与权限 | 按组件参考中的平台说明测试；授权被拒绝时应有明确提示，不继续假定操作成功。 |
| 最小案例 | 先验证页面中的最小案例，再验证第二个场景；重复操作、取消、返回屏幕后结果应符合事件说明。 |
完整 .aia 源码与操作指导
需要手机与电脑同一局域网，先启动本页附带的HTTP对端。普通文件测试完成，慢速大文件测试进度与取消，404测试失败。鸿蒙无法静默写公共下载目录，两种设置都保存应用目录；路径以完成事件为准。
导入 DownloaderAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| SaveLocation / ShowNotification 设计器及读写 | 选择位置、通知开关后点设置 | 展示实际设置；初始运行时应用目录不通知 |
| Download / DownloadCompleted | 电脑服务sample.txt网址点开始 | 返回实际编号，完成事件给实际文件路径；可多次下载 |
| DownloadProgress | 用slow.bin网址下载 | 实际字节与百分比持续更新，已完成路径以事件为准 |
| Cancel / DownloadFailed | 下载slow.bin后尽快点取消最近 | 取消最近编号，失败事件显示已取消 |
| CancelAll | 启动两个slow.bin下载后点全部取消 | 取消本案例的正在进行下载，事件分别带编号 |
| 下载失败 | 输入服务的missing路径或错误端口 | 显示实际失败原因；修正后可再下 |
| 平台目录差异 | 选择公共下载目录测试 | 安卓公共下载目录可能涉及授权；鸿蒙两种设置均落应用files/Download，不伪装跨应用写入 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
下载器
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 需要手机与电脑同一局域网，先启动本页附带的HTTP对端。普通文件测试完成，慢速大文件测试进度与取消，404测试失败。鸿蒙无法静默写公共下载目录，两种设置都保存应用目录；路径以完成事件为准。 覆盖检查 12/12。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
电脑端可直接运行的下载对端
把下面保存为 http-peer.py，执行 python3 http-peer.py。不需要第三方包；Windows也可执行 python http-peer.py。手机填写 http://电脑实际局域网IP:8768/sample.txt。测试进度与取消时把路径改成 /slow.bin，文件名改成 download-case.bin；失败测试用 /missing。防火墙允许8768端口，手机地址不要填localhost或0.0.0.0。
#!/usr/bin/env python3
"""下载器实测HTTP对端：普通文本、慢速8MiB文件及404失败。"""
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import time
class 下载处理器(BaseHTTPRequestHandler):
def do_GET(self):
路径 = self.path.split("?", 1)[0]
if 路径 == "/sample.txt":
数据 = "设备001\n温度23.5\n下载测试完成\n".encode("utf-8")
self.send_response(200)
self.send_header("Content-Type", "text/plain; charset=utf-8")
self.send_header("Content-Length", str(len(数据)))
self.end_headers()
self.wfile.write(数据)
elif 路径 == "/slow.bin":
总长度 = 8 * 1024 * 1024
分块 = bytes(range(256)) * 64
self.send_response(200)
self.send_header("Content-Type", "application/octet-stream")
self.send_header("Content-Length", str(总长度))
self.end_headers()
try:
for _ in range(总长度 // len(分块)):
self.wfile.write(分块)
self.wfile.flush()
time.sleep(0.02)
except (BrokenPipeError, ConnectionResetError):
print("客户端取消了下载", flush=True)
else:
数据 = "文件不存在".encode("utf-8")
self.send_response(404)
self.send_header("Content-Type", "text/plain; charset=utf-8")
self.send_header("Content-Length", str(len(数据)))
self.end_headers()
self.wfile.write(数据)
if __name__ == "__main__":
服务 = ThreadingHTTPServer(("0.0.0.0", 8768), 下载处理器)
print("HTTP监听8768；sample.txt正常，slow.bin慢速，其他路径404。", flush=True)
try:
服务.serve_forever()
except KeyboardInterrupt:
pass
finally:
服务.server_close()
扫码添加客服咨询
