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)，例如：<br/> fileShare.OperationMode.READ_MODE ：允许读授权 <br/> fileShare.OperationMode.READ_MODE \| fileShare.OperationMode.WRITE_MODE ：允许读写授权 | 61 62## fileShare.persistPermission<sup>11+</sup> 63 64persistPermission(policies: Array<PolicyInfo>): Promise<void> 65 66异步方法对所选择的多个文件或目录URI持久化授权，以promise形式返回结果，该接口仅对具有该系统能力的设备开放。 67 68**需要权限**：ohos.permission.FILE_ACCESS_PERSIST 69 70**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| -------- |---------------------------------------| -------- |-------------------------| 76| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 77 78**返回值：** 79 80| 类型 | 说明 | 81| -------- | -------- | 82| Promise<void> | 无返回结果的Promise对象。 | 83 84**错误码：** 85 86以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 87如果存在URI授权失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 88 89| 错误码ID | 错误信息 | 90|----------| --------- | 91| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 92| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 93| 801 | Capability not supported. | 94| 13900001 | Operation not permitted. | 95| 13900042 | Unknown error | 96 97**示例：** 98 99 ```ts 100 import { BusinessError } from '@ohos.base'; 101 import picker from '@ohos.file.picker'; 102 103 async function persistPermissionExample() { 104 try { 105 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 106 let documentPicker = new picker.DocumentViewPicker(); 107 let uris = await documentPicker.select(DocumentSelectOptions); 108 let policyInfo: fileShare.PolicyInfo = { 109 uri: uris[0], 110 operationMode: fileShare.OperationMode.READ_MODE, 111 }; 112 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 113 fileShare.persistPermission(policies).then(() => { 114 console.info("persistPermission successfully"); 115 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 116 console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code); 117 if (err.code == 13900001 && err.data) { 118 for (let i = 0; i < err.data.length; i++) { 119 console.error("error code : " + JSON.stringify(err.data[i].code)); 120 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 121 console.error("error reason : " + JSON.stringify(err.data[i].message)); 122 } 123 } 124 }); 125 } catch (error) { 126 let err: BusinessError = error as BusinessError; 127 console.error('persistPermission failed with err: ' + JSON.stringify(err)); 128 } 129 } 130 ``` 131 132## fileShare.revokePermission<sup>11+</sup> 133 134revokePermission(policies: Array<PolicyInfo>): Promise<void> 135 136异步方法对所选择的多个文件或目录uri取消持久化授权，以promise形式返回结果，该接口仅对具有该系统能力的设备开放。 137 138**需要权限**：ohos.permission.FILE_ACCESS_PERSIST 139 140**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| -------- |--------------------| -------- |-------------------------| 146| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 147 148**返回值：** 149 150| 类型 | 说明 | 151| -------- | -------- | 152| Promise<void> | 无返回结果的Promise对象。 | 153 154**错误码：** 155 156以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 157如果存在URI取消授权失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 158 159| 错误码ID | 错误信息 | 160|----------| --------- | 161| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 162| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 163| 801 | Capability not supported. | 164| 13900001 | Operation not permitted. | 165| 13900042 | Unknown error | 166 167**示例：** 168 169 ```ts 170 import { BusinessError } from '@ohos.base'; 171 import picker from '@ohos.file.picker'; 172 173 async function revokePermissionExample() { 174 try { 175 let DocumentSelectOptions = new picker.DocumentSelectOptions(); 176 let documentPicker = new picker.DocumentViewPicker(); 177 let uris = await documentPicker.select(DocumentSelectOptions); 178 let policyInfo: fileShare.PolicyInfo = { 179 uri: uris[0], 180 operationMode: fileShare.OperationMode.READ_MODE, 181 }; 182 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 183 fileShare.revokePermission(policies).then(() => { 184 console.info("revokePermission successfully"); 185 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 186 console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code); 187 if (err.code == 13900001 && err.data) { 188 for (let i = 0; i < err.data.length; i++) { 189 console.error("error code : " + JSON.stringify(err.data[i].code)); 190 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 191 console.error("error reason : " + JSON.stringify(err.data[i].message)); 192 } 193 } 194 }); 195 } catch (error) { 196 let err: BusinessError = error as BusinessError; 197 console.error('revokePermission failed with err: ' + JSON.stringify(err)); 198 } 199 } 200 ``` 201 202## fileShare.activatePermission<sup>11+</sup> 203 204activatePermission(policies: Array<PolicyInfo>): Promise<void> 205 206异步方法使能多个已经永久授权过的文件或目录，以promise形式返回结果，该接口仅对具有该系统能力的设备开放。 207 208**需要权限**：ohos.permission.FILE_ACCESS_PERSIST 209 210**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| -------- | -------- | -------- |-------------------------| 216| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 217 218**返回值：** 219 220| 类型 | 说明 | 221| -------- | -------- | 222| Promise<void> | 无返回结果的Promise对象。 | 223 224**错误码：** 225 226以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 227如果存在URI使能权限失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 228 229| 错误码ID | 错误信息 | 230|----------| --------- | 231| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 232| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 233| 801 | Capability not supported. | 234| 13900001 | Operation not permitted. | 235| 13900042 | Unknown error | 236 237**示例：** 238 239 ```ts 240 import { BusinessError } from '@ohos.base'; 241 import picker from '@ohos.file.picker'; 242 243 async function activatePermissionExample() { 244 try { 245 let uri = "file://docs/storage/Users/username/tmp.txt"; 246 let policyInfo: fileShare.PolicyInfo = { 247 uri: uri, 248 operationMode: fileShare.OperationMode.READ_MODE, 249 }; 250 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 251 fileShare.activatePermission(policies).then(() => { 252 console.info("activatePermission successfully"); 253 }).catch(async (err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 254 console.error("activatePermission failed with error message: " + err.message + ", error code: " + err.code); 255 if (err.code == 13900001 && err.data) { 256 for (let i = 0; i < err.data.length; i++) { 257 console.error("error code : " + JSON.stringify(err.data[i].code)); 258 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 259 console.error("error reason : " + JSON.stringify(err.data[i].message)); 260 if(err.data[i].code == fileShare.PolicyErrorCode.PERMISSION_NOT_PERSISTED){ 261 await fileShare.persistPermission(policies); 262 } 263 } 264 } 265 }); 266 } catch (error) { 267 let err: BusinessError = error as BusinessError; 268 console.error('activatePermission failed with err: ' + JSON.stringify(err)); 269 } 270 } 271 ``` 272 273## fileShare.deactivatePermission<sup>11+</sup> 274 275deactivatePermission(policies: Array<PolicyInfo>): Promise<void> 276 277异步方法取消使能授权过的多个文件或目录，以promise形式返回结果，该接口仅对具有该系统能力的设备开放。 278 279**需要权限**：ohos.permission.FILE_ACCESS_PERSIST 280 281**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 282 283**参数：** 284 285| 参数名 | 类型 | 必填 | 说明 | 286| -------- | -------- | -------- |-------------------------| 287| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 288 289**返回值：** 290 291| 类型 | 说明 | 292| -------- | -------- | 293| Promise<void> | 无返回结果的Promise对象。 | 294 295**错误码：** 296 297以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 298如果存在URI取消使能权限失败，则抛出13900001错误码，且失败URI信息将抛出异常data属性中以Array<[PolicyErrorResult](#policyerrorresult11)>形式提供错误信息。 299 300| 错误码ID | 错误信息 | 301|----------| --------- | 302| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 303| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 304| 801 | Capability not supported. | 305| 13900001 | Operation not permitted. | 306| 13900042 | Unknown error | 307 308**示例：** 309 310 ```ts 311 import { BusinessError } from '@ohos.base'; 312 import picker from '@ohos.file.picker'; 313 314 async function deactivatePermissionExample() { 315 try { 316 let uri = "file://docs/storage/Users/username/tmp.txt"; 317 let policyInfo: fileShare.PolicyInfo = { 318 uri: uri, 319 operationMode: fileShare.OperationMode.READ_MODE, 320 }; 321 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 322 fileShare.deactivatePermission(policies).then(() => { 323 console.info("deactivatePermission successfully"); 324 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 325 console.error("deactivatePermission failed with error message: " + err.message + ", error code: " + err.code); 326 if (err.code == 13900001 && err.data) { 327 for (let i = 0; i < err.data.length; i++) { 328 console.error("error code : " + JSON.stringify(err.data[i].code)); 329 console.error("error uri : " + JSON.stringify(err.data[i].uri)); 330 console.error("error reason : " + JSON.stringify(err.data[i].message)); 331 } 332 } 333 }); 334 } catch (error) { 335 let err: BusinessError = error as BusinessError; 336 console.error('deactivatePermission failed with err: ' + JSON.stringify(err)); 337 } 338 } 339 ``` 340 341## fileShare.checkPersistentPermission<sup>12+</sup> 342 343checkPersistentPermission(policies: Array<PolicyInfo>): Promise<Array<boolean>> 344 345异步方法校验所选择的多个文件或目录URI持久化授权，以promise形式返回结果。 346 347**需要权限**：ohos.permission.FILE_ACCESS_PERSIST 348 349**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 350 351**参数：** 352 353| 参数名 | 类型 | 必填 | 说明 | 354| -------- |---------------------------------------| -------- |-------------------------| 355| policies| Array<[PolicyInfo](#policyinfo11)> | 是 | 需要授权URI的策略信息，policies数组大小上限为500。| 356 357**返回值：** 358 359| 类型 | 说明 | 360| ----------------------------------- | ------------------------------------- | 361| Promise<Array<boolean>> | Promise对象，返回true表示有持久化授权，false表示不具有持久化授权。 | 362 363**错误码：** 364 365以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 366 367| 错误码ID | 错误信息 | 368|----------| --------- | 369| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 370| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 371| 801 | Capability not supported. | 372| 13900042 | Unknown error | 373 374**示例：** 375 376 ```ts 377 import { BusinessError } from '@ohos.base'; 378 import picker from '@ohos.file.picker'; 379 380 async function checkPersistentPermissionExample() { 381 try { 382 let documentSelectOptions = new picker.DocumentSelectOptions(); 383 let documentPicker = new picker.DocumentViewPicker(); 384 let uris = await documentPicker.select(documentSelectOptions); 385 let policyInfo: fileShare.PolicyInfo = { 386 uri: uris[0], 387 operationMode: fileShare.OperationMode.READ_MODE, 388 }; 389 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 390 fileShare.checkPersistentPermission(policies).then(async (data) => { 391 let result: Array<boolean> = data; 392 for (let i = 0; i < result.length; i++) { 393 console.log("checkPersistentPermission result: " + JSON.stringify(result[i])); 394 if(!result[i]){ 395 let info: fileShare.PolicyInfo = { 396 uri: policies[i].uri, 397 operationMode: policies[i].operationMode, 398 }; 399 let policy : Array<fileShare.PolicyInfo> = [info]; 400 await fileShare.persistPermission(policy); 401 } 402 } 403 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 404 console.error("checkPersistentPermission failed with error message: " + err.message + ", error code: " + err.code); 405 }); 406 } catch (error) { 407 let err: BusinessError = error as BusinessError; 408 console.error('checkPersistentPermission failed with err: ' + JSON.stringify(err)); 409 } 410 } 411 ``` 412