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