050 — Core File Kit 与文件选择器沙箱文件管理与批量授权简介鸿蒙系统采用沙箱文件机制来保障用户数据安全——每个应用只能访问自己的沙箱目录访问外部文件需要通过文件选择器Picker获取用户授权。MoneyTrack 在反馈模块中完整实践了这一流程用户通过 Picker 选择图片或文件系统返回 URI 后应用通过fileUri.getUriFromPath()完成路径转换再读取文件内容进行上传。批量授权机制让用户可以一次选择多个文件并统一授权避免了逐个确认的繁琐操作。核心知识点1. 沙箱文件目录结构鸿蒙应用的沙箱路径遵循以下目录结构/data/storage/el2/base/haps/entry/files/ ← 应用文件目录 /data/storage/el2/base/haps/entry/cache/ ← 缓存目录系统可清理 /data/storage/el2/base/data/ ← 应用数据库和 SharedPreferences /data/storage/el2/base/preferences/ ← 首选项存储目录沙箱分为两个层级应用沙箱应用私有目录无需授权即可读写但数据随应用卸载而删除。用户沙箱用户公开目录如相册、下载需要通过 Picker 授权访问。2. fileUri URI 转换fileUri模块提供沙箱路径与 URI 的相互转换fileUri.getUriFromPath(path)将本地沙箱路径转换为file://协议 URI。fileUri.getPathFromUri(uri)将 URI 转换回本地路径。URI 格式的跨进程传递更为安全和标准。3. 文件选择器PickerPicker 是系统提供的标准文件选择界面核心 Picker 类型如下Picker 类型适用场景核心参数PhotoViewPicker图片/视频选择maxCount, selectTypeDocumentViewPicker文档选择PDF/Word/ExcelmaxCount, fileSuffixFiltersAudioViewPicker音频文件选择maxCountPhotoViewPicker 完整参数说明参数类型说明示例maxCountnumber最大选择数量默认 109selectTypePhotoSelectType筛选类型IMAGE、VIDEO、IMAGE_VIDEOIMAGEDocumentViewPicker用于选择文档文件支持按文件后缀筛选constdocPickernewDocumentViewPicker();constresultawaitdocPicker.select({maxCount:5,fileSuffixFilters:[.pdf,.doc,.docx]});// result 返回选中文件的 URI 列表4. PersistableURI 持久化授权Picker 返回的 URI 默认是临时授权——应用在前台运行时有效。如果需要后台或下次启动时继续访问需要通过PersistableURI机制持久化授权。持久化后应用在后续启动时无需用户再次授权即可访问这些文件。5. 文件选择→授权→URI转换→读取→上传完整流程渲染错误:Mermaid 渲染失败: Parse error on line 2: graph TD A[用户点击选择文件] -- B[调用 Pick -------------------^ Expecting SQE, DOUBLECIRCLEEND, PE, -), STADIUMEND, SUBROUTINEEND, PIPE, CYLINDEREND, DIAMOND_STOP, TAGEND, TRAPEND, INVTRAPEND, UNICODE_TEXT, TEXT, TAGSTART, got STR项目代码案例反馈模块中的上传文件处理文件路径feature_feedback组件import{photoAccessHelper}fromkit.MediaLibraryKit;import{fileUri}fromkit.CoreFileKit;import{fileIoasfs}fromkit.CoreFileKit;asyncfunctionpickAndUpload(){// 打开 Picker 选择图片constpickernewphotoAccessHelper.PhotoViewPicker();constresultawaitpicker.select({maxCount:9,// 最多选择 9 张selectType:photoAccessHelper.PhotoSelectType.IMAGE// 仅图片});for(consturiofresult.photoUris){// URI 转路径constpathfileUri.getPathFromUri(uri);// 读取文件并上传awaituploadFile(uri,path);}}asyncfunctionuploadFile(uri:string,path:string){// 使用 fs 打开文件读取内容constfilefs.openSync(path,fs.OpenMode.READ_ONLY);constbuffernewArrayBuffer(4096);fs.readSync(file.fd,buffer);fs.closeSync(file);// 通过 FormData 上传constformDatanewFormData();formData.append(file,uri);returnaxios.post(/api/feedback/upload,formData,{headers:{Content-Type:multipart/form-data}});}// 持久化授权的示例asyncfunctionpersistFileAccess(uris:string[]){constpersistentUrinewPersistableURI(uris[0]);awaitpersistentUri.persist();// 持久化授权console.info(文件访问权限已持久化);}使用 DocumentViewPicker 选择文档import{DocumentViewPicker}fromkit.CoreFileKit;asyncfunctionpickDocument(){constdocPickernewDocumentViewPicker();constresultawaitdocPicker.select({maxCount:3,fileSuffixFilters:[.pdf,.xlsx,.docx]});if(resultresult.length0){for(constdocUriofresult){constpathfileUri.getPathFromUri(docUri);// 处理文件...}}}最佳实践合理设置 maxCount根据业务需求设置最大选择数量图片上传建议 9 张以内文档选择建议 5 张以内避免一次性选择过多文件导致内存溢出。使用 selectType 过滤明确指定selectType让用户在 Picker 中只看到需要的文件类型提升选择效率。及时释放文件资源使用fs.openSync后务必在 finally 中调用fs.closeSync避免文件句柄泄漏。临时授权 vs 持久化授权大多数上传场景使用临时授权即可只有需要跨应用启动周期访问的场景如下载目录中的文件才需要 PersistableURI。URI 优先于路径传递URI 是跨进程传递的标准格式优先使用 URI 而非拼接后的路径确保兼容性和安全性。错误处理Picker 可能被用户取消返回 null或文件被删除读取失败务必做好错误处理并给出用户友好的提示。推荐参考文档Core File Kit 文件管理指南PhotoViewPicker / DocumentViewPicker API 参考PersistableURI API 参考
