1# @ohos.file.fileuri (文件URI) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @lvzhenjie--> 5<!--Designer: @wang_zhangjun; @chenxi0605--> 6<!--Tester: @liuhonggang123--> 7<!--Adviser: @foryourself--> 8 9该模块提供通过PATH获取文件统一资源标志符（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 { fileUri } from '@kit.CoreFileKit'; 19``` 20 21使用该功能模块前，需要先获取其应用沙箱路径，开发示例如下： 22 23 ```ts 24 import { UIAbility } from '@kit.AbilityKit'; 25 import { window } from '@kit.ArkUI'; 26 27 export default class EntryAbility extends UIAbility { 28 onWindowStageCreate(windowStage: window.WindowStage) { 29 let context = this.context; 30 let pathDir = context.filesDir; 31 } 32 } 33 ``` 34 35## FileUri<sup>10+</sup> 36 37### 属性 38 39**系统能力**：SystemCapability.FileManagement.AppFileService 40 41| 名称 | 类型 | 只读 | 可选 | 说明| 42| -------- | --------| --- |-------- |----------------| 43| path<sup>10+</sup> | string | 否 | 否 | 将uri转换成对应的沙箱路径path。 1、uri转path过程中会将uri中存在的ASCII码进行解码后拼接在原处，非系统接口生成的uri中可能存在ASCII码解析范围之外的字符，导致字符串无法正常拼接；2、转换处理为系统约定的字符串替换规则（规则随系统演进可能会发生变化），转换过程中不进行路径校验操作，无法保证转换结果的一定可以访问。 | 44| name<sup>10+</sup> | string | 是 | 否 | 通过传入的uri获取到对应的文件名称。（如果文件名中存在ASCII码将会被解码处理后拼接在原处）<br>**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。| 45 46### constructor<sup>10+</sup> 47 48constructor(uriOrPath: string) 49 50constructor是FileUri的构造函数。 51 52**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 53 54**系统能力**：SystemCapability.FileManagement.AppFileService 55 56**参数：** 57 58| 参数名 | 类型 | 必填 | 说明| 59| -------- | -------- | -------- |--------| 60| uriOrPath | string | 是 | URI或路径。URI类型：<br/>- 应用沙箱URI：file://\<bundleName>/\<sandboxPath> <br/>- 公共目录文件类URI：file://docs/storage/Users/currentUser/\<publicPath> <br/>- 公共目录媒体类URI：file://media/\<mediaType>/IMG_DATATIME_ID/\<displayName> | 61 62**错误码：** 63 64以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 65| 错误码ID| 错误信息 | 66| -------- | ---------- | 67| 13900005 | I/O error | 68| 13900042 | Unknown error | 69| 13900020 | Invalid argument | 70| 14300002 | Invalid uri | 71 72**示例：** 73 74 ```ts 75 let path = pathDir + '/test'; 76 let uri = fileUri.getUriFromPath(path); // file://<packageName>/data/storage/el2/base/haps/entry/files/test 77 let fileUriObject = new fileUri.FileUri(uri); 78 console.info("The name of FileUri is " + fileUriObject.name); 79 ``` 80 81### toString<sup>10+</sup> 82 83toString(): string 84 85**系统能力**：SystemCapability.FileManagement.AppFileService 86 87返回字符串类型URI。 88 89**返回值：** 90 91| 类型 | 说明 | 92| -------- | -------- | 93| string | 返回字符串类型URI。 | 94 95**示例：** 96 97 ```ts 98 let path = pathDir + '/test'; 99 let fileUriObject = new fileUri.FileUri(path); 100 console.info("The uri of FileUri is " + fileUriObject.toString()); 101 ``` 102 103### getFullDirectoryUri<sup>11+</sup> 104 105getFullDirectoryUri(): string 106 107获取所在路径URI。URI指向文件则返回所在路径的URI，URI指向目录则不处理直接返回原串；URI指向的文件不存在或属性获取失败则返回空串。 108 109如果当前FileUri指向文件，将返回文件所在路径URI。如`xxx/example.txt`，将返回`xxx`。 110 111如果当前FileUri指向目录，将返回当前路径的URI。 112 113**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 114 115**系统能力**：SystemCapability.FileManagement.AppFileService 116 117**返回值：** 118 119| 类型| 说明| 120| --------- |--------| 121| string | 获取所在路径URI，文件获取所在路径URI，目录获取当前路径URI。 | 122 123**错误码：** 124 125以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 126 127| 错误码ID| 错误信息| 128| -------- |--------| 129| 13900002 | No such file or directory | 130| 13900012 | Permission denied | 131| 13900042 | Unknown error | 132 133**示例：** 134 135 ```ts 136 import { BusinessError } from '@kit.BasicServicesKit'; 137 try { 138 let path = pathDir + '/test.txt'; 139 let fileUriObject = new fileUri.FileUri(path); 140 let directoryUri = fileUriObject.getFullDirectoryUri(); 141 console.log(`success to getFullDirectoryUri: ${JSON.stringify(directoryUri)}`); 142 } catch (error) { 143 console.error(`failed to getFullDirectoryUri because: ${JSON.stringify(error)}`); 144 } 145 ``` 146 147### isRemoteUri<sup>12+</sup> 148 149isRemoteUri(): boolean 150 151判断当前URI是否是远端URI。 152 153**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 154 155**系统能力**：SystemCapability.FileManagement.AppFileService 156 157**返回值：** 158 159| 类型| 说明| 160| -------- |---------| 161| boolean | - 返回true，表示当前FileUri指向远端文件或目录，如`xxx/example.txt?networkid=xxx`。<br>- 返回false，表示当前FileUri指向本地的文件或目录。 | 162 163**错误码：** 164 165以下错误码的详细介绍请参见[文件管理子系统错误码](errorcode-filemanagement.md)。 166 167| 错误码ID| 错误信息| 168| --------- |--------| 169| 13900042 | Unknown error| 170 171**示例：** 172 173 ```ts 174 import { BusinessError } from '@kit.BasicServicesKit'; 175 function isRemoteUriExample() { 176 let uri = "file://com.example.demo/data/storage/el2/base/test.txt?networkid=xxxx";//?networkid设备id，远端URI的标识 177 let fileUriObject = new fileUri.FileUri(uri); 178 let ret = fileUriObject.isRemoteUri(); 179 if (ret) { 180 console.log(`It is a remote uri.`); 181 } 182 } 183 ``` 184 185## fileUri.getUriFromPath 186 187getUriFromPath(path: string): string 188 189通过传入的路径path生成应用自己的URI；将path转URI时，路径中的中文及非数字字母的特殊字符将会被编译成对应的ASCII码，拼接在URI中。 190 191**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 192 193**系统能力**：SystemCapability.FileManagement.AppFileService 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明| 198| ------ | ------ | ---- | ------- | 199| path | string | 是 | 文件的沙箱路径。 | 200 201**返回值：** 202 203 | 类型 | 说明| 204 | ------- |------| 205 | string | 通过传入的路径path生成应用自己的URI；将path转URI时，路径中的中文及非数字字母的特殊字符将会被编译成对应的ASCII码，拼接在URI中。 | 206 207**错误码：** 208 209以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 210| 错误码ID| 错误信息 | 211| ---------- | ---------- | 212| 401 | The input parameter is invalid. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types | 213 214**示例：** 215 216 ```ts 217 let filePath = pathDir + "/test"; 218 let uri = fileUri.getUriFromPath(filePath); 219 ```