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> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.fileshare (文件分享)](js-apis-fileShare-sys.md)。 15 16## 导入模块 17 18```ts 19import { fileShare } from '@kit.CoreFileKit'; 20``` 21 22## fileShare.grantUriPermission 23 24grantUriPermission(uri: string, bundleName: string, flag: wantConstant.Flags, callback: AsyncCallback<void>): void 25 26对公共目录文件URI进行授权操作，使用callback异步回调。 27 28**需要权限：** ohos.permission.WRITE_MEDIA 29 30**系统接口：** 此接口为系统接口。 31 32**系统能力：** SystemCapability.FileManagement.AppFileService 33 34**参数：** 35 36| 参数名 | 类型| 必填 | 说明| 37| ------ |---------| ---- |-----------| 38| uri | string| 是 | 公共目录文件uri。 | 39| bundleName | string| 是 | 分享目标的包名。 | 40| flag | [wantConstant.Flags](../apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | 是 | 授权的权限。 | 41 | callback | AsyncCallback<void>| 是 | 异步授权之后的回调。 | 42 43**错误码：** 44 45以下错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md) 46 47| 错误码ID| 错误信息| 48| ------ | ------- | 49| 201 | Permission verification failed. | 50| 202 | The caller is not a system application. | 51| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 52| 143000001 | IPC error. | 53 54**示例：** 55 56 ```ts 57 import { wantConstant } from '@kit.AbilityKit'; 58 import { BusinessError } from '@kit.BasicServicesKit'; 59 let uri: string = 'file://docs/storage/Users/currentUser/Document/1.txt'; // 推荐使用系统接口生成URI。fileUri.getUriFromPath("沙箱路径"); 60 let bundleName: string = 'com.demo.test'; 61 try { 62 fileShare.grantUriPermission(uri, bundleName, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION | 63 wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION, (err: BusinessError) => { 64 if (err) { 65 console.error("grantUriPermission failed with error: " + JSON.stringify(err)); 66 return; 67 } 68 console.info("grantUriPermission success!"); 69 }); 70 } catch (err) { 71 let error: BusinessError = err as BusinessError; 72 console.error("grantUriPermission failed with error:" + JSON.stringify(error)); 73 } 74 ``` 75 76## fileShare.grantUriPermission 77 78grantUriPermission(uri: string, bundleName: string, flag: wantConstant.Flags): Promise<void> 79 80将公共目录文件URI进行授权操作，使用Promise异步回调。 81 82**需要权限：** ohos.permission.WRITE_MEDIA 83 84**系统接口：** 此接口为系统接口。 85 86**系统能力：** SystemCapability.FileManagement.AppFileService 87 88**参数：** 89 90| 参数名 | 类型| 必填 | 说明 | 91| ------ |-------| ---- |-----------| 92| uri | string| 是 | 公共目录文件uri。 | 93| bundleName | string| 是 | 分享目标的包名。 | 94| flag | [wantConstant.Flags](../apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | 是 | 授权的权限。 | 95 96**返回值：** 97 98 | 类型 | 说明 | 99 | ---------- | ---------- | 100 | Promise<void> | Promise对象，无返回值。 | 101 102**错误码：** 103 104以下错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 105 106| 错误码ID| 错误信息| 107| ------- | ---------- | 108| 201 | Permission verification failed. | 109| 202 | The caller is not a system application. | 110| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 111| 143000001 | IPC error. | 112 113**示例：** 114 115 ```ts 116 import { wantConstant } from '@kit.AbilityKit'; 117 import { BusinessError } from '@kit.BasicServicesKit'; 118 let uri: string = 'file://docs/storage/Users/currentUser/Document/1.txt'; // 推荐使用系统接口生成URI。fileUri.getUriFromPath("沙箱路径"); 119 let bundleName: string = 'com.demo.test'; 120 try { 121 fileShare.grantUriPermission(uri, bundleName, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION | 122 wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION).then(() => { 123 console.info("grantUriPermission success!"); 124 }).catch((error: BusinessError) => { 125 console.error("grantUriPermission failed with error:" + JSON.stringify(error)); 126 }); 127 } catch (err) { 128 let error: BusinessError = err as BusinessError; 129 console.error("grantUriPermission failed with error:" + JSON.stringify(error)); 130 } 131 ``` 132 133## fileShare.checkPathPermission<sup>15+</sup> 134 135checkPathPermission(tokenID: number, policies: Array<PathPolicyInfo>, policyType: PolicyType): Promise<Array<boolean>> 136 137异步方法校验所选择的多个文件或目录是否有临时或持久化授权，以promise形式返回结果。 138 139**需要权限：** ohos.permission.CHECK_SANDBOX_POLICY 140 141**系统接口：** 此接口为系统接口。 142 143**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 144 145**参数：** 146 147| 参数名 | 类型| 必填 | 说明| 148| -------- |-------| -------- |----------| 149| tokenID| number | 是 | 目标应用的身份标识。可通过应用的[ApplicationInfo](../apis-ability-kit/js-apis-bundleManager-applicationInfo.md)的accessTokenId字段获得。| 150| policies| Array<[PathPolicyInfo](js-apis-fileShare.md#pathpolicyinfo15)> | 是 | 需要授权路径的策略信息，policies数组大小上限为500。| 151| policyType| [PolicyType](js-apis-fileShare.md#policytype15) | 是 | 要查询的授权类型，具体是临时授权或持久化授权。 | 152 153**返回值：** 154 155|类型|说明| 156| ------ | ------ | 157| Promise<Array<boolean>> | Promise对象，返回true表示授权类型匹配policyType的查询类型，否则返回false。 | 158 159**错误码：** 160 161以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 162 163| 错误码ID | 错误信息 | 164|----------| --------- | 165| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 166| 202 | The caller is not a system application.| 167| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 168| 801 | Capability not supported. | 169 170**示例：** 171 172 ```ts 173 import { BusinessError } from '@kit.BasicServicesKit'; 174 import { fileShare } from '@kit.CoreFileKit'; 175 176 async function checkPersistentPermissionExample() { 177 try { 178 let pathPolicyInfo1: fileShare.PathPolicyInfo = { 179 path: "/storage/Users/currentUser/Documents/1.txt", 180 operationMode: fileShare.OperationMode.READ_MODE, 181 } 182 let pathPolicyInfo2: fileShare.PathPolicyInfo = { 183 path: "/storage/Users/currentUser/Desktop/2.txt", 184 operationMode: fileShare.OperationMode.READ_MODE, 185 } 186 187 let policies: Array<fileShare.PathPolicyInfo> = [pathPolicyInfo1, pathPolicyInfo2]; 188 let policyType: fileShare.PolicyType = fileShare.PolicyType.PERSISTENT_TYPE; 189 let tokenid = 537688848; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取 190 191 fileShare.checkPathPermission(tokenid, policies, policyType).then((result:Array<boolean>) => { 192 for (let x of result) { 193 console.info('check permission result is', x); 194 } 195 }) 196 console.info("checkPathPermission finish"); 197 } 198 catch (error) { 199 console.info(error.code + 'checkPathPermission error' + error.message); 200 } 201 } 202 ``` 203 204## fileShare.grantUriPermission<sup>20+</sup> 205 206grantUriPermission(policies: Array<PolicyInfo>, targetBundleName: string, appCloneIndex: number): Promise<void> 207 208给应用授予目标文件临时权限，使用Promise异步回调。 209 210**需要权限：** ohos.permission.FILE_ACCESS_MANAGER 211 212**系统接口：** 此接口为系统接口。 213 214**系统能力：** SystemCapability.FileManagement.AppFileService.FolderAuthorization 215 216**参数：** 217 218| 参数名 | 类型| 必填 | 说明| 219| -------- |-------| -------- |----------| 220| policies| Array<[PolicyInfo](js-apis-fileShare.md#policyinfo11)> | 是 | 需要授权路径的策略信息，policies数组大小上限为500。| 221| targetBundleName| string | 是 | 被授权应用的应用包名。 | 222| appCloneIndex| number | 是 | 被授权应用的分身索引，取值为0时表示主应用。 | 223 224**返回值：** 225 226|类型|说明| 227| ------ | ------ | 228| Promise<void> | Promise对象。无返回结果的Promise对象。 | 229 230**错误码：** 231 232以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[文件管理子系统错误码](errorcode-filemanagement.md)。 233 234| 错误码ID | 错误信息 | 235|----------| --------- | 236| 201 | Permission verification failed, usually the result returned by VerifyAccessToken.| 237| 202 | The caller is not a system application.| 238| 801 | Capability not supported. | 239| 13900001 | Operation not permitted. | 240| 13900011 | Out of memory. | 241 242**示例：** 243 244 ```ts 245 import { BusinessError } from '@kit.BasicServicesKit'; 246 import { fileShare } from '@kit.CoreFileKit'; 247 248 async function grantUriPermissionExample() { 249 try { 250 let uri = "file://docs/storage/Users/currentUser/Documents/1.txt"; 251 let policyInfo: fileShare.PolicyInfo = { 252 uri: uri, 253 operationMode: fileShare.OperationMode.CREATE_MODE | fileShare.OperationMode.READ_MODE, 254 }; 255 let policies: Array<fileShare.PolicyInfo> = [policyInfo]; 256 257 fileShare.grantUriPermission(policies, "com.example.myapplicationtest", 0).then(() => { 258 }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => { 259 console.error("grantUriPermission failed. Code: " + 260 err.code + ", message: " + err.message); 261 }); 262 } 263 catch (error) { 264 console.info('grantUriPermission error, Code: ' + error.code + ', message: ' + error.message); 265 } 266 } 267 ```