文件增强使用指导
不可见组件：功能完整的文件工具箱。基于广受欢迎的 FileTools 拓展（v10）内化为原生组件并更名「文件增强」，
方法名与原拓展一致，新项目无需再导入 .aix；同时修复了原拓展完成事件不触发、Android 10 以上路径解析等问题。
功能亮点
- 文件操作：复制、移动、删除（目录连同内容一起删）、重命名、创建目录、判断是否存在，结果直接返回真假。
- 大文件不卡界面：复制文件、列目录有「异步」版本，完成后在对应事件里拿结果。
- 目录浏览：列出目录下的文件（可按扩展名过滤，如
"jpg,png"，可递归子目录、可包含文件夹）、只列子文件夹。 - 文件信息：文件或文件夹大小、最后修改时间（自定义日期格式）、MIME 类型。
- 存储与路径：应用专属目录（无需存储权限）、剩余/总空间；
文件路径与
content://URI 互转，把相册、文件选择器返回的 URI 变成可直接使用的文件路径。 - 素材读取：以
//开头的路径指向应用素材（如//data.json），打包 APK 和 AI伴侣 调试里都能用。
需要在桌面创建快捷方式请用应用工具组件。
路径写法：/storage、/sdcard、/data、/mnt 开头的系统路径原样使用；其它路径（无论是否以 / 开头）都从外部存储根目录算起；// 开头为应用素材。
快速上手
- 拖一个 文件增强 到屏幕（不可见组件，位于「数据存储」分类）；
- 下面是最常用的「异步列目录 + 异步复制」模式：目录里文件多时用异步版本，完成后在事件里取结果，避免卡界面。
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮1.Click() {
文件增强1.FileListAsync(文件增强1.ApplicationSpecificDirectory(), "txt", true, false)
}
when 文件增强1.GotFileList(文件列表) {
标签1.Text = join("共找到 ", length(文件列表), " 个文件")
}
when 文件增强1.FileCopied(是否成功, 响应) {
if 是否成功 {
标签1.Text = "复制完成"
} else {
标签1.Text = join("复制失败：", 响应)
}
}
复制、移动、创建目录、删除都直接返回真假，可以接在「如果」里判断；只有大文件复制需要用
异步复制文件（来源，目标）（CopyFileAsync），在文件复制完成时（是否成功，响应）（FileCopied）事件里拿结果。
搭建与测试
在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。
可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。
案例：列出项目素材
放文件增强、一个按钮和一个列表显示框。此案例不写入公共目录，用于检查项目打包的素材名。
when 按钮_素材.Click() {
列表显示框1.Elements = 文件增强1.FileListFromAssets()
}
应用专属目录无需公共存储权限。content:// 不是普通文件路径；转换后先检查文件是否存在。异步复制结果在 FileCopied 中处理。
属性、方法与事件速查
完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。
| 入口 | 用途 |
|---|---|
应用专属目录（ApplicationSpecificDirectory） |
返回应用专属外部目录路径。 |
拷贝文件（从，到）（CopyFile） |
复制文件，返回是否成功。大文件请用「异步复制文件」以免卡住界面。 |
异步复制文件（来源，目标）（CopyFileAsync） |
在后台复制大文件，完成后触发「文件复制完成时」事件。 |
创建目录（目录）（CreateDirectory） |
创建目录（含上级目录），返回是否成功；目录已存在也返回真。 |
删除（文件或文件夹名）（Delete） |
删除文件或目录（目录连同内容一起删），返回是否成功。 |
是否存在（文件名或目录名）（Exists） |
检查文件或目录是否存在。 |
异步获取文件列表（目录，过滤器，含文件夹，递归）（FileListAsync） |
异步获取目录文件列表，完成后触发 GotFileList。 |
获取资源文件列表（FileListFromAssets） |
返回素材根目录文件列表。 |
文件或目录大小（路径）（FileOrFolderSize） |
返回文件或目录大小（字节）。 |
文件路径（文件名）（FilePath） |
返回文件名对应的绝对路径。 |
文件列表（目录，过滤器，含文件夹，递归）（FilesList） |
返回目录中的文件列表，可按扩展名过滤。 |
目录列表（目录）（FolderList） |
返回目录下的直接子目录列表。 |
剩余空间（目录名称）（FreeSpace） |
返回目录可用空间（字节）。 |
获取内容URI（文件名）（GetContentUri） |
将文件名转换为 file:// 内容 URI。 |
是否文件（路径）（IsFile） |
判断路径是否为文件。 |
最后修改时间（路径，格式）（LastModTime） |
返回文件最后修改时间，format 使用 SimpleDateFormat 格式。 |
MIME类型（文件名）（MimeType） |
根据文件名返回 MIME 类型。 |
移动文件（从，到）（MoveFile） |
移动文件（也可用来改名），返回是否成功。 |
URI转路径（内容URI）（PathFromUri） |
将 content URI 转换为文件路径。 |
重命名文件（文件名，新文件名）（RenameFile） |
重命名文件。 |
总空间（目录名称）（TotalSpace） |
返回目录总空间（字节）。 |
文件复制完成时（是否成功，响应）（FileCopied） |
异步复制完成后触发。 |
获得文件列表时（文件列表）（GotFileList） |
异步列出文件完成后触发。 |
常见问题与验收
| 检查项 | 操作与预期 |
|---|---|
| 初始化 | 对照案例检查是否已经调用加载、注册、连接或显示方法；仅拖入组件不会替你执行这些步骤。 |
| 结果返回 | 将成功事件和失败事件都接到标签，记录事件参数；异步操作完成前不读取结果属性。 |
| 输入配置 | 检查素材名大小写、网址是否为直接资源地址、文件是否存在、编号和索引是否在范围内。 |
| 平台与权限 | 按组件参考中的平台说明测试；授权被拒绝时应有明确提示，不继续假定操作成功。 |
| 最小案例 | 先验证页面中的最小案例，再验证第二个场景；重复操作、取消、返回屏幕后结果应符合事件说明。 |
完整 .aia 源码与操作指导
设备巡检记录的真实文件闭环：打包素材→应用专属独立目录→复制／异步复制→移动／重命名→文本内容读取→递归列表／过滤→URI与空间→可恢复清理。案例不申请共享存储权限，所有修改仅限FileToolsAllFeatures目录，素材永不移动或删除。
导入 FileToolsAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| ApplicationSpecificDirectory、CreateDirectory、CopyFile | 初始化或准备目录 | 专属目录下创建FileToolsAllFeatures/sub；真实文本与CSV复制。已有目录时CreateDirectory可能假，结合Exists判断 |
| FileListFromAssets、FilePath、Exists、IsFile、FileOrFolderSize | 素材及所选文件属性入口 | 枚举真实sample.txt、notes.csv；素材与副本路径、大小可核对 |
| CopyFileAsync、FileCopied | 异步复制或不存在源测试 | 真实成功／失败事件和response；事件未到不再启动新的文件操作 |
| MoveFile、RenameFile | 同步复制→移动→重命名→选择renamed.txt读内容 | 真实源／目的存在变化；RenameFile无返回值，必须核对目的实际存在 |
| FilesList、FolderList、FileListAsync、GotFileList | 过滤txt,csv，切换递归与目录，再同步／异步列出 | 真实列表；扩展名不带点；子目录与空过滤可比较 |
| MimeType、LastModTime、TotalSpace、FreeSpace | 文件信息及空间按钮 | 实际MIME、修改时间、总／剩余空间字节；平台值不同属正常 |
| GetContentUri、PathFromUri | 选已存在记录再转URI核对 | 展示真实URI和还原路径；这不是授予外部应用访问权限 |
| Delete、恢复与清理 | 删除copy.txt；确认删除独立目录；再次准备 | 只影响本案例文件；原打包素材只读且保留，重新复制可恢复 |
| 真实内容与错误恢复 | record.txt读取，失败后恢复源再读 | 显示打包中文记录原文，异步失败不冒充成功；不存在文件先给提示 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
设备记录文件管理
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 设备巡检记录的真实文件闭环：打包素材→应用专属独立目录→复制／异步复制→移动／重命名→文本内容读取→递归列表／过滤→URI与空间→可恢复清理。案例不申请共享存储权限，所有修改仅限FileToolsAllFeatures目录，素材永不移动或删除。 覆盖检查 23/23。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。
扫码添加客服咨询
