1# 选择用户文件 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @wang_zhangjun; @zhuangzhuang--> 5<!--Designer: @wang_zhangjun; @zhuangzhuang; @renguang1116--> 6<!--Tester: @liuhonggang123; @yue-ye2; @juxiaopang--> 7<!--Adviser: @foryourself--> 8 9用户需要分享文件、保存图片、视频等用户文件时，开发者可以通过系统预置的[文件选择器（FilePicker）](../reference/apis-core-file-kit/js-apis-file-picker.md)，实现该能力。通过Picker访问相关文件，将拉起对应的应用，引导用户完成界面操作，接口本身无需申请权限。Picker获取的URI只具有临时权限，获取持久化权限需要通过[FilePicker设置永久授权](file-persistPermission.md#通过picker获取临时授权并进行授权持久化)方式获取。 10 11根据用户文件的常见类型，选择器（FilePicker）分别提供以下选项： 12 13- [PhotoViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#photoviewpickerdeprecated)：适用于图片或视频类型文件的选择与保存（该接口在后续版本不再演进）。请使用[PhotoAccessHelper的PhotoViewPicker](../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md)来选择图片文件。请使用[安全控件保存媒体库资源](../media/medialibrary/photoAccessHelper-savebutton.md)。 14 15- [DocumentViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#documentviewpicker)：适用于文件类型文件的选择与保存。DocumentViewPicker对接的选择资源来自于FilePicker，负责文件类型的资源管理，文件类型不区分后缀，比如浏览器下载的图片、文档等，都属于文件类型。 16 17- [AudioViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#audioviewpicker)：适用于音频类型文件的选择与保存。AudioViewPicker目前对接的选择资源来自于AudioPicker。 18 19## 选择图片或视频类文件 20 21[PhotoViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#photoviewpickerdeprecated)在后续版本不再演进，请使用[PhotoAccessHelper的PhotoViewPicker](../reference/apis-media-library-kit/arkts-apis-photoAccessHelper-PhotoViewPicker.md)来选择图片文件。 22 23## 选择文档类文件 24 251. 导入选择器模块和基础文件API模块。 26 27 ```ts 28 import { picker } from '@kit.CoreFileKit'; 29 import { fileIo as fs } from '@kit.CoreFileKit'; 30 import { common } from '@kit.AbilityKit'; 31 import { BusinessError } from '@kit.BasicServicesKit'; 32 ``` 33 342. 创建文件类型、文件选择选项实例。 35 36 ```ts 37 const documentSelectOptions = new picker.DocumentSelectOptions(); 38 // 选择文档的最大数目（可选）。 39 documentSelectOptions.maxSelectNumber = 5; 40 // 指定选择的文件或者目录的URI（可选）。 41 documentSelectOptions.defaultFilePathUri = "file://docs/storage/Users/currentUser/test"; 42 // 选择文件的后缀类型['后缀类型描述|后缀类型']（可选，不传该参数，默认不过滤，即显示所有文件），若选择项存在多个后缀名，则每一个后缀名之间用英文逗号进行分隔（可选），后缀类型名不能超过100。此外2in1设备支持通配符方式['所有文件(*.*)|.*']（说明：从API version 17开始，手机支持该配置），表示为显示所有文件。 43 documentSelectOptions.fileSuffixFilters = ['图片(.png, .jpg)|.png,.jpg', '文档|.txt', '视频|.mp4', '.pdf']; 44 //选择是否对指定文件或目录授权，true为授权，当为true时，defaultFilePathUri为必选参数，拉起文管授权界面；false为非授权(默认为false)，拉起常规文管界面（可选）。该参数在2in1设备中可正常使用，在其他设备中无效果。 45 documentSelectOptions.authMode = false; 46 //批量授权模式，默认为false（非批量授权模式）。当multAuthMode为true时为批量授权模式。当multAuthMode为true时，只有multiUriArray参数生效，其他参数不生效。该参数在Phone设备中可正常使用，在其他设备中无效果。 47 documentSelectOptions.multiAuthMode = false; 48 //需要传入批量授权的uri数组（仅支持文件，文件夹不生效）。配合multAuthMode使用。当multAuthMode为false时，配置该参数不生效。该参数在Phone设备中可正常使用，在其他设备中无效果。 49 documentSelectOptions.multiUriArray = ["file://docs/storage/Users/currentUser/test", "file://docs/storage/Users/currentUser/2test"]; 50 //开启聚合视图模式，支持拉起文件管理应用的聚合视图。默认为DEFAULT，表示该参数不生效，非聚合视图。当该参数置为非DEFAULT时，其他参数不生效。该参数在Phone设备中可正常使用，在其他设备中无效果。 51 documentSelectOptions.mergeMode = picker.MergeTypeMode.DEFAULT; 52 //是否支持加密（仅支持文件，文件夹不生效），默认为false。该参数为true时，在Picker界面可以选择对文件进行加密。（说明：从API version 19开始支持该参数）。 53 documentSelectOptions.isEncryptionSupported = false; 54 ``` 55 563. 创建[文件选择器DocumentViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#documentviewpicker)实例。调用[select()](../reference/apis-core-file-kit/js-apis-file-picker.md#select-3)接口拉起FilePicker应用界面进行文件选择。 57 58 ```ts 59 let uris: Array<string> = []; 60 // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 61 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 62 // 创建文件选择器实例 63 const documentViewPicker = new picker.DocumentViewPicker(context); 64 documentViewPicker.select(documentSelectOptions).then((documentSelectResult: Array<string>) => { 65 //文件选择成功后，返回被选中文档的URI结果集。 66 uris = documentSelectResult; 67 console.info('documentViewPicker.select to file succeed and uris are:' + uris); 68 }).catch((err: BusinessError) => { 69 console.error(`Invoke documentViewPicker.select failed, code is ${err.code}, message is ${err.message}`); 70 }) 71 ``` 72 73 > **注意：** 74 > 75 > **1**、使用Picker获取的[select()](../reference/apis-core-file-kit/js-apis-file-picker.md#select-3)返回的URI权限是临时只读权限,待退出应用后台后，获取的临时权限就会失效。<br> 76 > **2**、如果想要获取持久化权限，请参考[文件持久化授权访问](file-persistPermission.md#通过picker获取临时授权并进行授权持久化)。<br> 77 > **3**、开发者可以根据结果集中URI做进一步的处理。建议定义一个全局变量保存URI。<br> 78 > **4**、如有获取元数据需求，可以通过[基础文件API](../reference/apis-core-file-kit/js-apis-file-fs.md)和[文件URI](../reference/apis-core-file-kit/js-apis-file-fileuri.md)根据URI获取部分文件属性信息，比如文件大小、访问时间、修改时间、文件名、文件路径等。 79 804. 待界面从FilePicker返回后，使用[基础文件API的fs.openSync](../reference/apis-core-file-kit/js-apis-file-fs.md#fsopensync)接口通过URI打开这个文件得到文件描述符（fd）。 81 82 ```ts 83 let uri: string = ''; 84 //这里需要注意接口权限参数是fs.OpenMode.READ_ONLY。 85 let file = fs.openSync(uri, fs.OpenMode.READ_ONLY); 86 console.info('file fd: ' + file.fd); 87 ``` 88 895. 通过fd使用[fs.readSync](../reference/apis-core-file-kit/js-apis-file-fs.md#readsync)接口读取这个文件内的数据。 90 91 ```ts 92 let buffer = new ArrayBuffer(4096); 93 let readLen = fs.readSync(file.fd, buffer); 94 console.info('readSync data to file succeed and buffer size is:' + readLen); 95 //读取完成后关闭fd。 96 fs.closeSync(file); 97 ``` 98 99## 选择音频类文件 100 1011. 导入选择器模块和基础文件API模块。 102 103 ```ts 104 import { picker } from '@kit.CoreFileKit'; 105 import { fileIo as fs } from '@kit.CoreFileKit'; 106 import { BusinessError } from '@kit.BasicServicesKit'; 107 import { common } from '@kit.AbilityKit'; 108 ``` 109 1102. 创建音频类型文件选择选项实例。 111 112 > **说明：** 113 > 114 > 目前AudioSelectOptions不支持参数配置，默认可以选择所有类型的用户文件。 115 116 ```ts 117 const audioSelectOptions = new picker.AudioSelectOptions(); 118 ``` 119 1203. 创建[音频选择器AudioViewPicker](../reference/apis-core-file-kit/js-apis-file-picker.md#audioviewpicker)实例。调用[select()](../reference/apis-core-file-kit/js-apis-file-picker.md#select-5)接口拉起AudioPicker应用界面进行文件选择。 121 122 ```ts 123 let uris: string = ''; 124 // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 125 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 126 const audioViewPicker = new picker.AudioViewPicker(context); 127 audioViewPicker.select(audioSelectOptions).then((audioSelectResult: Array<string>) => { 128 //文件选择成功后，返回被选中音频的URI结果集。 129 uris = audioSelectResult[0]; 130 console.info('audioViewPicker.select to file succeed and uri is:' + uris); 131 }).catch((err: BusinessError) => { 132 console.error(`Invoke audioViewPicker.select failed, code is ${err.code}, message is ${err.message}`); 133 }) 134 ``` 135 136 > **注意：** 137 > 138 > **1**、使用Picker获取的[select()](../reference/apis-core-file-kit/js-apis-file-picker.md#select-3)返回的URI权限是临时只读权限,待退出应用后台后，获取的临时权限就会失效。<br> 139 > **2**、如果想要获取持久化权限，请参考[文件持久化授权访问](file-persistPermission.md#通过picker获取临时授权并进行授权持久化)。<br> 140 > **3**、开发者可以根据结果集中的URI做读取文件数据操作。建议定义一个全局变量保存URI。例如通过[基础文件API](../reference/apis-core-file-kit/js-apis-file-fs.md)根据URI拿到音频资源的文件描述符（fd），再配合媒体服务实现音频播放的开发，具体请参考[音频播放开发指导](../media/audio/audio-playback-overview.md)。 141 1424. 待界面从AudioPicker返回后，可以使用[基础文件API的fs.openSync](../reference/apis-core-file-kit/js-apis-file-fs.md#fsopensync)接口通过URI打开这个文件得到文件描述符（fd）。 143 144 ```ts 145 let uri: string = ''; 146 //这里需要注意接口权限参数是fs.OpenMode.READ_ONLY。 147 let file = fs.openSync(uri, fs.OpenMode.READ_ONLY); 148 console.info('file fd: ' + file.fd); 149 ``` 150 1515. 通过fd可以使用[基础文件API的fs.readSync](../reference/apis-core-file-kit/js-apis-file-fs.md#readsync)接口读取这个文件内的数据。 152 153 ```ts 154 let buffer = new ArrayBuffer(4096); 155 let readLen = fs.readSync(file.fd, buffer); 156 console.info('readSync data to file succeed and buffer size is:' + readLen); 157 //读取完成后关闭fd。 158 fs.closeSync(file); 159 ``` 160 161## 相关实例 162 163针对用户文件的选择，有以下相关实例可供参考： 164 165- [选择并查看文档与媒体文件（ArkTS）（API10）](https://gitcode.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Release/code/BasicFeature/FileManagement/FileShare/Picker) 166 167<!--RP1--><!--RP1End-->