1# @ohos.fileshare (文件分享) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @lvzhenjie; @hongjin-li_admin--> 5<!--Designer: @chenxi0605; @JerryH1011--> 6<!--Tester: @leiyuqian--> 7<!--Adviser: @foryourself--> 8 9该模块提供文件分享能力，提供系统应用将公共目录文件统一资源标志符（Uniform Resource Identifier，URI）以读写权限授权给其他应用的接口，授权后应用可通过[@ohos.file.fs](js-apis-file-fs.md)的相关接口进行相关open、read、write等操作，实现文件分享。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import fileShare from '@ohos.fileshare'; 19``` 20 21## OperationMode<sup>11+</sup> 22 23枚举，授予或使能权限的URI访问模式。 24 25**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 26 27| 名称 | 值 | 说明 | 28| ----- |-----|-----| 29| READ_MODE | 0b1 | 读权限。 | 30| WRITE_MODE | 0b10 | 写权限。 | 31| CREATE_MODE<sup>20+</sup> | 0b100 | 创建文件/文件夹权限。 | 32| DELETE_MODE<sup>20+</sup> | 0b1000 | 删除文件/文件夹权限。 | 33| RENAME_MODE<sup>20+</sup> | 0b10000 | 重命名文件/文件夹权限。 | 34 35## PolicyErrorCode<sup>11+</sup> 36 37枚举，授予或使能权限策略失败的URI对应的错误码。 38 39**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 40 41| 名称 | 值 | 说明 | 42| ----- |-----|-----------| 43| PERSISTENCE_FORBIDDEN | 1 | URI禁止被持久化。 | 44| INVALID_MODE | 2 | 无效的模式。 | 45| INVALID_PATH | 3 | 无效的路径。 | 46| PERMISSION_NOT_PERSISTED<sup>12+</sup> | 4 | 权限没有被持久化。 | 47 48## PolicyErrorResult<sup>11+</sup> 49 50授予或使能权限失败的URI策略结果。支持persistPermission、revokePermission、activatePermission、deactivatePermission接口抛出错误时使用。 51 52type PolicyErrorResult = { uri: string; code: PolicyErrorCode; message: string; } 53 54**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 55 56| 名称| 类型| 必填 | 说明| 57|--------|--------|--------|---------| 58| uri | string| 是 | 授予或使能权限失败的URI。| 59| code | [PolicyErrorCode](#policyerrorcode11) | 是 | 授权策略失败的URI对应的错误码。 | 60| message | string| 是 | 授权策略失败的URI对应的原因。 | 61 62## PolicyInfo<sup>11+</sup> 63 64需要授予或使能权限URI的策略信息。 65 66**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 67 68| 名称 | 类型 | 只读 | 可选 | 说明 | 69|------|-------|------|-----|------------------------------------------------------| 70| uri| string | 否 | 否 | 需要授予或使能权限的URI。 | 71| operationMode | number | 否 | 否 | 授予或使能权限的URI访问模式，参考[OperationMode](#operationmode11)。 | 72 73## PathPolicyInfo<sup>15+</sup> 74 75需要查询的文件或目录的信息。 76 77**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 78 79| 名称 | 类型 | 只读 | 可选 | 说明 | 80|------|-------|-----|-----|--------| 81| path | string | 否 | 否 | 需要查询的path。| 82| operationMode | OperationMode | 否 | 否 | 需要查询的path的访问模式，参考[OperationMode](#operationmode11)。 | 83 84## PolicyType<sup>15+</sup> 85 86枚举，所查询策略信息对应的授权模式。 87 88**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 89 90| 名称 | 值 | 说明 | 91| ----- |-----|-----------| 92| TEMPORARY_TYPE | 0 | 临时授权。 | 93| PERSISTENT_TYPE | 1 | 持久化授权。 | 94 95## fileShare.persistPermission<sup>11+</sup> 96 97persistPermission(policies: Array<PolicyInfo>): Promise<void> 98 99异步方法对所选择的多个文件或目录URI持久化授权，以promise形式返回结果。该接口仅对具有该系统能力的设备开放（此接口不支持媒体类URI及远端URI的持久化）。 100 101**需要权限：** ohos.permission.FILE_ACCESS_PERSIST 102 103**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| -------- |---------| -------- |--------| 109| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 110 111**返回值：** 112 113| 类型 | 说明 | 114| -------- | -------- | 115| Promise<void> | 无返回结果的Promise对象。 | 116 117**错误码：** 118 119以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)和[通用错误码](../errorcode-universal.md)。 120如果存在URI授权失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 121 122| 错误码ID | 错误信息 | 123|----------| --------- | 124| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 125| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 126| 801 | Capability not supported. | 127| 13900001 | Operation not permitted.| 128| 13900042 | Unknown error.| 129 130**示例：** 131 132 ```ts 133 import { BusinessError } from '@kit.BasicServicesKit'; 134 import { picker } from '@kit.CoreFileKit'; 135 136 async function persistPermissionExample() { 137 try { 138 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 139 let documentPicker = new picker.DocumentViewPicker(); 140 let uris = await documentPicker.select(DocumentSelectOptions); 141 let policyInfo: fileShare.PolicyInfo = { 142 uri: uris[0], 143 operationMode: fileShare.OperationMode.READ_MODE, 144 }; 145 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 146 fileShare.persistPermission(policies).then(() => { 147 console.info("persistPermission successfully"); 148 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 149 console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code); 150 if (err.code == 13900001 && err.data) { 151 for (let i = 0; i < err.data.length; i++) { 152 console.error("error code : " + JSON.stringify(err.data[i].code)); 153 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 154 console.error("error reason : " + JSON.stringify(err.data[i].message)); 155 } 156 } 157 }); 158 } catch (error) { 159 let err: BusinessError = error as BusinessError; 160 console.error('persistPermission failed with err: ' + JSON.stringify(err)); 161 } 162 } 163 ``` 164 165## fileShare.revokePermission<sup>11+</sup> 166 167revokePermission(policies: Array<PolicyInfo>): Promise<void> 168 169异步方法对所选择的多个文件或目录uri取消持久化授权，以promise形式返回结果。该接口仅对具有该系统能力的设备开放（此接口不支持媒体类URI及远端URI的持久化）。 170 171**需要权限：** ohos.permission.FILE_ACCESS_PERSIST 172 173**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 174 175**参数：** 176 177| 参数名 | 类型 | 必填 | 说明 | 178| -------- |----------| -------- |----------| 179| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 180 181**返回值：** 182 183| 类型 | 说明 | 184| -------- | -------- | 185| Promise<void> | 无返回结果的Promise对象。 | 186 187**错误码：** 188 189以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)和[通用错误码](../errorcode-universal.md)。 190如果存在URI取消授权失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 191 192| 错误码ID | 错误信息 | 193|----------| --------- | 194| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 195| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 196| 801 | Capability not supported. | 197| 13900001 | Operation not permitted.| 198| 13900042 | Unknown error.| 199 200**示例：** 201 202 ```ts 203 import { BusinessError } from '@kit.BasicServicesKit'; 204 import { picker } from '@kit.CoreFileKit'; 205 206 async function revokePermissionExample() { 207 try { 208 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 209 let documentPicker = new picker.DocumentViewPicker(); 210 let uris = await documentPicker.select(DocumentSelectOptions); 211 let policyInfo: fileShare.PolicyInfo = { 212 uri: uris[0], 213 operationMode: fileShare.OperationMode.READ_MODE, 214 }; 215 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 216 fileShare.revokePermission(policies).then(() => { 217 console.info("revokePermission successfully"); 218 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 219 console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code); 220 if (err.code == 13900001 && err.data) { 221 for (let i = 0; i < err.data.length; i++) { 222 console.error("error code : " + JSON.stringify(err.data[i].code)); 223 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 224 console.error("error reason : " + JSON.stringify(err.data[i].message)); 225 } 226 } 227 }); 228 } catch (error) { 229 let err: BusinessError = error as BusinessError; 230 console.error('revokePermission failed with err: ' + JSON.stringify(err)); 231 } 232 } 233 ``` 234 235## fileShare.activatePermission<sup>11+</sup> 236 237activatePermission(policies: Array<PolicyInfo>): Promise<void> 238 239异步方法使能多个已经永久授权过的文件或目录，以promise形式返回结果。该接口仅对具有该系统能力的设备开放（此接口不支持媒体类URI及远端URI的持久化）。 240 241**需要权限：** ohos.permission.FILE_ACCESS_PERSIST 242 243**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 244 245**参数：** 246 247| 参数名 | 类型 | 必填 | 说明 | 248| -------- | -------- | -------- |---------| 249| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 250 251**返回值：** 252 253| 类型 | 说明 | 254| -------- | -------- | 255| Promise<void> | 无返回结果的Promise对象。 | 256 257**错误码：** 258 259以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)和[通用错误码](../errorcode-universal.md)。 260如果存在URI使能权限失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 261 262| 错误码ID | 错误信息 | 263|----------| --------- | 264| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 265| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 266| 801 | Capability not supported. | 267| 13900001 | Operation not permitted.| 268| 13900042 | Unknown error.| 269 270**示例：** 271 272 ```ts 273 import { BusinessError } from '@kit.BasicServicesKit'; 274 import { picker } from '@kit.CoreFileKit'; 275 276 async function activatePermissionExample() { 277 try { 278 let uri = "file://docs/storage/Users/username/tmp.txt"; 279 let policyInfo: fileShare.PolicyInfo = { 280 uri: uri, 281 operationMode: fileShare.OperationMode.READ_MODE, 282 }; 283 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 284 fileShare.activatePermission(policies).then(() => { 285 console.info("activatePermission successfully"); 286 }).catch(async (err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 287 console.error("activatePermission failed with error message: " + err.message + ", error code: " + err.code); 288 if (err.code == 13900001 && err.data) { 289 for (let i = 0; i < err.data.length; i++) { 290 console.error("error code : " + JSON.stringify(err.data[i].code)); 291 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 292 console.error("error reason : " + JSON.stringify(err.data[i].message)); 293 if(err.data[i].code == fileShare.PolicyErrorCode.PERMISSION_NOT_PERSISTED){ 294 await fileShare.persistPermission(policies); 295 } 296 } 297 } 298 }); 299 } catch (error) { 300 let err: BusinessError = error as BusinessError; 301 console.error('activatePermission failed with err: ' + JSON.stringify(err)); 302 } 303 } 304 ``` 305 306## fileShare.deactivatePermission<sup>11+</sup> 307 308deactivatePermission(policies: Array<PolicyInfo>): Promise<void> 309 310异步方法取消使能授权过的多个文件或目录，以promise形式返回结果。该接口仅对具有该系统能力的设备开放（此接口不支持媒体类URI及远端URI的持久化）。 311 312**需要权限：** ohos.permission.FILE_ACCESS_PERSIST 313 314**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 315 316**参数：** 317 318| 参数名 | 类型 | 必填 | 说明 | 319| -------- | -------- | -------- |---------| 320| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 321 322**返回值：** 323 324| 类型 | 说明 | 325| -------- | -------- | 326| Promise<void> | 无返回结果的Promise对象。 | 327 328**错误码：** 329 330以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)和[通用错误码](../errorcode-universal.md)。 331如果存在URI取消使能权限失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 332 333| 错误码ID | 错误信息 | 334|----------| --------- | 335| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 336| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 337| 801 | Capability not supported. | 338| 13900001 | Operation not permitted.| 339| 13900042 | Unknown error.| 340 341**示例：** 342 343 ```ts 344 import { BusinessError } from '@kit.BasicServicesKit'; 345 import { picker } from '@kit.CoreFileKit'; 346 347 async function deactivatePermissionExample() { 348 try { 349 let uri = "file://docs/storage/Users/username/tmp.txt"; 350 let policyInfo: fileShare.PolicyInfo = { 351 uri: uri, 352 operationMode: fileShare.OperationMode.READ_MODE, 353 }; 354 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 355 fileShare.deactivatePermission(policies).then(() => { 356 console.info("deactivatePermission successfully"); 357 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 358 console.error("deactivatePermission failed with error message: " + err.message + ", error code: " + err.code); 359 if (err.code == 13900001 && err.data) { 360 for (let i = 0; i < err.data.length; i++) { 361 console.error("error code : " + JSON.stringify(err.data[i].code)); 362 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 363 console.error("error reason : " + JSON.stringify(err.data[i].message)); 364 } 365 } 366 }); 367 } catch (error) { 368 let err: BusinessError = error as BusinessError; 369 console.error('deactivatePermission failed with err: ' + JSON.stringify(err)); 370 } 371 } 372 ``` 373 374## fileShare.checkPersistentPermission<sup>12+</sup> 375 376checkPersistentPermission(policies: Array<PolicyInfo>): Promise<Array<boolean>> 377 378异步方法校验所选择的多个文件或目录URI持久化授权，以promise形式返回结果。 379 380**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 381 382**参数：** 383 384| 参数名 | 类型 | 必填 | 说明 | 385| -------- |---------------------------------------| -------- |-------------------------| 386| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 387 388**返回值：** 389 390| 类型 | 说明 | 391| ------- | ------- | 392| Promise<Array<boolean>> | Promise对象。返回true表示有持久化授权；false表示不具有持久化授权。 | 393 394**错误码：** 395 396以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)和[通用错误码](../errorcode-universal.md)。 397 398| 错误码ID | 错误信息 | 399|----------| --------- | 400| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 401| 801 | Capability not supported. | 402| 13900042 | Unknown error.| 403 404**示例：** 405 406 ```ts 407 import { BusinessError } from '@kit.BasicServicesKit'; 408 import { picker } from '@kit.CoreFileKit'; 409 410 async function checkPersistentPermissionExample() { 411 try { 412 let documentSelectOptions = new picker.DocumentSelectOptions(); 413 let documentPicker = new picker.DocumentViewPicker(); 414 let uris = await documentPicker.select(documentSelectOptions); 415 let policyInfo: fileShare.PolicyInfo = { 416 uri: uris[0], 417 operationMode: fileShare.OperationMode.READ_MODE, 418 }; 419 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 420 fileShare.checkPersistentPermission(policies).then(async (data) => { 421 let result: Array<boolean> = data; 422 for (let i = 0; i < result.length; i++) { 423 console.log("checkPersistentPermission result: " + JSON.stringify(result[i])); 424 if(!result[i]){ 425 let info: fileShare.PolicyInfo = { 426 uri: policies[i].uri, 427 operationMode: policies[i].operationMode, 428 }; 429 let policy : Array<fileShare.PolicyInfo> = [info]; 430 await fileShare.persistPermission(policy); 431 } 432 } 433 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 434 console.error("checkPersistentPermission failed with error message: " + err.message + ", error code: " + err.code); 435 }); 436 } catch (error) { 437 let err: BusinessError = error as BusinessError; 438 console.error('checkPersistentPermission failed with err: ' + JSON.stringify(err)); 439 } 440 } 441 ``` 442