1# @ohos.file.fileAccess (公共文件访问与管理) 2 3fileAccess模块是基于extension机制实现的一个对公共文件访问和操作的框架。该模块一方面对接各类文件管理服务，如媒体库、外置存储管理服务等，另一方面为系统应用提供一套统一的文件访问管理接口。其中，媒体库服务提供本地设备、分布式设备等公共文件访问服务；外置存储管理服务可以提供共享盘、U盘、SD卡等设备的公共文件访问服务。 4 5>**说明：** 6> 7> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口，三方应用不支持调用，当前只支持FilePicker、文件管理器调用。 9 10## 导入模块 11 12```js 13import fileAccess from '@ohos.file.fileAccess'; 14``` 15 16## fileAccess.getFileAccessAbilityInfo 17 18getFileAccessAbilityInfo() : Promise<Array<Want>> 19 20以异步方法获取系统内extension配置为fileAccess类型的所有Want信息。使用Promise异步回调。 21 22**模型约束**：此接口仅可在Stage模型下使用。 23 24**系统能力**：SystemCapability.FileManagement.UserFileService 25 26**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 27 28**返回值：** 29 30 | 类型 | 说明 | 31 | --- | -- | 32 | Promise<Array<[Want](js-apis-app-ability-want.md)>> | 表示当前系统配置fileAccess的所有文件管理类服务 | 33 34**错误码：** 35 36接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 37 38**示例：** 39 40 ```js 41 async getFileAccessAbilityInfo() { 42 let wantInfos = []; 43 try { 44 wantInfos = await fileAccess.getFileAccessAbilityInfo(); 45 console.log("getFileAccessAbilityInfo data " + JSON.stringify(wantInfos)); 46 } catch (error) { 47 console.error("getFileAccessAbilityInfo failed, errCode:" + error.code + ", errMessage:" + error.message); 48 } 49 } 50 ``` 51 52## fileAccess.getFileAccessAbilityInfo 53 54getFileAccessAbilityInfo(callback: AsyncCallback<Array<Want>>): void 55 56以异步方法获取系统内extension配置为fileAccess类型的所有Want信息。使用callback异步回调。 57 58**模型约束**：此接口仅可在Stage模型下使用。 59 60**系统能力**：SystemCapability.FileManagement.UserFileService 61 62**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 63 64**参数：** 65 66 | 参数名 | 类型 | 必填 | 说明 | 67 | --- | --- | --- | -- | 68 | callback | AsyncCallback<Array<[Want](js-apis-app-ability-want.md)>> | 是 | 表示当前系统配置fileAccess的所有文件管理类服务 | 69 70**错误码：** 71 72接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 73 74**示例：** 75 76 ```js 77 async getFileAccessAbilityInfo() { 78 try { 79 fileAccess.getFileAccessAbilityInfo(function (err, wantInfos) { 80 if (err) { 81 console.error("Failed to getFileAccessAbilityInfo in async, errCode:" + err.code + ", errMessage:" + err.message); 82 return; 83 } 84 console.log("getFileAccessAbilityInfo data " + JSON.stringify(wantInfos)); 85 }); 86 } catch (error) { 87 console.error("getFileAccessAbilityInfo failed, errCode:" + error.code + ", errMessage:" + error.message); 88 } 89 } 90 ``` 91 92## fileAccess.createFileAccessHelper 93 94createFileAccessHelper(context: Context, wants: Array<Want>) : FileAccessHelper 95 96以同步方法创建连接指定wants的helper对象。 97 98**模型约束**：此接口仅可在Stage模型下使用。 99 100**系统能力**：SystemCapability.FileManagement.UserFileService 101 102**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 103 104**参数：** 105 106 | 参数名 | 类型 | 必填 | 说明 | 107 | --- | --- | --- | -- | 108 | context | [Context](js-apis-inner-application-context.md) | 是 | 代表ability的上下文的能力 | 109 | wants | Array<[Want](js-apis-app-ability-want.md)> | 是 | Want是一种基本通信组件，主要用于服务拉起 | 110 111**返回值：** 112 113 | 类型 | 说明 | 114 | --- | -- | 115 | [FileAccessHelper](#fileaccesshelper) | 提供文件访问和操作能力的helper对象 | 116 117**错误码：** 118 119接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 120 121**示例：** 122 123 ```js 124 createFileAccessHelper() { 125 let fileAccessHelper = null; 126 // wantInfos 从getFileAccessAbilityInfo()获取 127 // 创建只连接媒体库服务的helper对象 128 let wantInfos = [ 129 { 130 "bundleName": "com.ohos.medialibrary.medialibrarydata", 131 "abilityName": "FileExtensionAbility", 132 }, 133 ] 134 try { 135 // this.context 是EntryAbility 传过来的context 136 fileAccessHelper = fileAccess.createFileAccessHelper(this.context, wantInfos); 137 if (!fileAccessHelper) 138 console.error("createFileAccessHelper interface returns an undefined object"); 139 } catch (error) { 140 console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message); 141 } 142 } 143 ``` 144 145## fileAccess.createFileAccessHelper 146 147createFileAccessHelper(context: Context) : FileAccessHelper 148 149以同步方法创建连接当前系统内所有文件管理服务的helper对象。 150 151**模型约束**：此接口仅可在Stage模型下使用。 152 153**系统能力**：SystemCapability.FileManagement.UserFileService 154 155**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 156 157**参数：** 158 159 | 参数名 | 类型 | 必填 | 说明 | 160 | --- | --- | --- | -- | 161 | context | [Context](js-apis-inner-application-context.md) | 是 | ability的上下文的能力 | 162 163**返回值：** 164 165 | 类型 | 说明 | 166 | --- | -- | 167 | [FileAccessHelper](#fileaccesshelper) | 提供文件访问和操作的能力的helper对象 | 168 169**错误码：** 170 171接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 172 173**示例：** 174 175 ```js 176 createFileAccessHelper() { 177 let fileAccessHelperAllServer = null; 178 // 创建连接系统内所有配置fileAccess的文件管理类服务的helper对象 179 try { 180 // this.context 是EntryAbility 传过来的context 181 fileAccessHelperAllServer = fileAccess.createFileAccessHelper(this.context); 182 if (!fileAccessHelperAllServer) 183 console.error("createFileAccessHelper interface returns an undefined object"); 184 } catch (error) { 185 console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message); 186 } 187 } 188 ``` 189 190## FileInfo 191 192表示文件(夹)属性信息和接口能力。 193 194**模型约束**：此接口仅可在Stage模型下使用。 195 196**系统能力**：SystemCapability.FileManagement.UserFileService。 197 198**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 199 200### 属性 201 202| 名称 | 类型 | 可读 | 可写 | 说明 | 203| ------ | ------ | -------- | ------ | -------- | 204| uri | string | 是 | 否 | 文件(夹)的uri | 205| fileName | string | 是 | 否 | 文件(夹)的名称 | 206| mode | number | 是 | 否 | 文件(夹)的权限信息 | 207| size | number | 是 | 否 | 文件(夹)的大小 | 208| mtime | number | 是 | 否 | 文件(夹)的修改时间 | 209| mimeType | string | 是 | 否 | 文件(夹)的媒体资源类型 | 210 211### listFile 212 213listFile(filter?: Filter) : FileIterator 214 215以同步方法从某个目录，基于过滤器，获取下一级符合条件的文件(夹)信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备过滤，外置存储设备不支持过滤。 216 217**模型约束**：此接口仅可在Stage模型下使用。 218 219**系统能力**：SystemCapability.FileManagement.UserFileService 220 221**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 222 223**参数：** 224 225 | 参数名 | 类型 | 必填 | 说明 | 226 | --- | --- | -- | -- | 227 | filter | [Filter](js-apis-file-fs.md#filter) | 否 | 过滤器对象 | 228 229**返回值：** 230 231 | 类型 | 说明 | 232 | --- | -- | 233 | [FileIterator](#fileiterator) | 文件(夹)信息的迭代器对象FileIterator | 234 235**错误码：** 236 237接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 238 239**示例：** 240 241 ```js 242 // fileInfoDir 表示某个目录信息 243 // let filter = { suffix : [".txt", ".jpg", ".xlsx"] }; 244 let fileInfoDir = fileInfos[0]; 245 let subfileInfos = []; 246 let isDone = false; 247 try { 248 let fileIterator = fileInfoDir.listFile(); 249 // 含过滤器实现的listFile 250 // let fileIterator = rootInfo.listFile(filter); 251 if (!fileIterator) { 252 console.error("listFile interface returns an undefined object"); 253 return; 254 } 255 while (!isDone) { 256 let result = fileIterator.next(); 257 console.log("next result = " + JSON.stringify(result)); 258 isDone = result.done; 259 if (!isDone) 260 subfileInfos.push(result.value); 261 } 262 } catch (error) { 263 console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message); 264 } 265 ``` 266 267### scanFile 268 269scanFile(filter?: Filter) : FileIterator 270 271以同步方法从某个目录，基于过滤器，递归获取符合条件的文件信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备。 272 273**模型约束**：此接口仅可在Stage模型下使用。 274 275**系统能力**：SystemCapability.FileManagement.UserFileService 276 277**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 278 279**参数：** 280 281 | 参数名 | 类型 | 必填 | 说明 | 282 | --- | --- | -- | -- | 283 | filter | [Filter](js-apis-file-fs.md#filter) | 否 | 过滤器对象 | 284 285**返回值：** 286 287 | 类型 | 说明 | 288 | --- | -- | 289 | [FileIterator](#fileiterator) | 文件信息的迭代器对象FileIterator | 290 291**错误码：** 292 293接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 294 295**示例：** 296 297 ```js 298 // fileInfoDir 表示某个目录信息 299 // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; 300 let fileInfoDir = fileInfos[0]; 301 let subfileInfos = []; 302 let isDone = false; 303 try { 304 let fileIterator = fileInfoDir.scanFile(); 305 // 含过滤器实现的scanFile 306 // let fileIterator = rootInfo.scanFile(filter); 307 if (!fileIterator) { 308 console.error("scanFile interface returns an undefined object"); 309 return; 310 } 311 while (!isDone) { 312 let result = fileIterator.next(); 313 console.log("next result = " + JSON.stringify(result)); 314 isDone = result.done; 315 if (!isDone) 316 subfileInfos.push(result.value); 317 } 318 } catch (error) { 319 console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message); 320 } 321 ``` 322 323## FileIterator 324 325表示文件夹的迭代器对象。 326 327**模型约束**：此接口仅可在Stage模型下使用。 328 329**系统能力**：SystemCapability.FileManagement.UserFileService 330 331**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 332 333### next 334 335next() : { value: FileInfo, done: boolean } 336 337可以通过next同步方法获取下一级文件(夹)信息。 338 339**模型约束**：此接口仅可在Stage模型下使用。 340 341**系统能力**：SystemCapability.FileManagement.UserFileService。 342 343**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 344 345**返回值：** 346 347| 类型 | 说明 | 348| --- | -- | 349| {value: [FileInfo](#fileinfo), done: boolean} | 通过next遍历文件夹，直到done返回true结束；value字段返回fileInfo。| 350 351**错误码：** 352 353接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 354 355## RootInfo 356 357表示设备的根属性信息和接口能力。 358 359**模型约束**：此接口仅可在Stage模型下使用。 360 361**系统能力**：SystemCapability.FileManagement.UserFileService。 362 363**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 364 365### 属性 366 367| 名称 | 类型 | 可读 | 可写 | 说明 | 368| ------ | ------ | -------- | ------ | -------- | 369| deviceType | number | 是 | 否 |设备类型 | 370| uri | string | 是 | 否 | 设备根目录Uri | 371| displayName | string | 是 | 否 | 设备名称 | 372| deviceFlags | number | 是 | 否 | 设备支持的能力 | 373 374### listFile 375 376listFile(filter?: Filter) : FileIterator 377 378以同步方法从某设备根节点开始，基于过滤器，获取第一级符合条件的文件(夹)信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备过滤，外置存储设备不支持过滤。 379 380**模型约束**：此接口仅可在Stage模型下使用。 381 382**系统能力**：SystemCapability.FileManagement.UserFileService 383 384**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 385 386**参数：** 387 388 | 参数名 | 类型 | 必填 | 说明 | 389 | --- | --- | -- | -- | 390 | filter | [Filter](js-apis-file-fs.md#filter) | 否 | 过滤器对象 | 391 392**返回值：** 393 394 | 类型 | 说明 | 395 | --- | -- | 396 | [FileIterator](#fileiterator) | 文件(夹)信息的迭代器对象FileIterator | 397 398**错误码：** 399 400接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 401 402**示例：** 403 404 ```js 405 // rootinfos 从getRoots()获取 406 // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; 407 let rootInfo = rootinfos[0]; 408 let fileInfos = []; 409 let isDone = false; 410 try { 411 let fileIterator = rootInfo.listFile(); 412 // 含过滤器实现的listFile 413 // let fileIterator = rootInfo.listFile(filter); 414 if (!fileIterator) { 415 console.error("listFile interface returns an undefined object"); 416 return; 417 } 418 while (!isDone) { 419 let result = fileIterator.next(); 420 console.log("next result = " + JSON.stringify(result)); 421 isDone = result.done; 422 if (!isDone) 423 fileInfos.push(result.value); 424 } 425 } catch (error) { 426 console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message); 427 } 428 ``` 429 430### scanFile 431 432scanFile(filter?: Filter) : FileIterator 433 434以同步方法从某设备根节点开始，基于过滤器，递归获取符合条件的文件信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备。 435 436**模型约束**：此接口仅可在Stage模型下使用。 437 438**系统能力**：SystemCapability.FileManagement.UserFileService 439 440**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 441 442**参数：** 443 444 | 参数名 | 类型 | 必填 | 说明 | 445 | --- | --- | -- | -- | 446 | filter | [Filter](js-apis-file-fs.md#filter) | 否 | 过滤器对象 | 447 448**返回值：** 449 450 | 类型 | 说明 | 451 | --- | -- | 452 | [FileIterator](#fileiterator) | 文件信息的迭代器对象FileIterator | 453 454**错误码：** 455 456接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 457 458**示例：** 459 460 ```js 461 // rootInfos 从 getRoots()获取 462 // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; 463 let rootInfo = rootInfos[0]; 464 let fileInfos = []; 465 let isDone = false; 466 try { 467 let fileIterator = rootInfo.scanFile(); 468 // 含过滤器实现的scanFile 469 // let fileIterator = rootInfo.scanFile(filter); 470 if (!fileIterator) { 471 console.error("scanFile interface returns undefined object"); 472 return; 473 } 474 while (!isDone) { 475 let result = fileIterator.next(); 476 console.log("next result = " + JSON.stringify(result)); 477 isDone = result.done; 478 if (!isDone) 479 fileInfos.push(result.value); 480 } 481 } catch (error) { 482 console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message); 483 } 484 ``` 485 486## RootIterator 487 488表示设备根目录的迭代器对象。 489 490**模型约束**：此接口仅可在Stage模型下使用。 491 492**系统能力**：SystemCapability.FileManagement.UserFileService 493 494**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 495 496### next 497 498next() : { value: RootInfo, done: boolean } 499 500通过next同步方法获取下一级设备根目录。 501 502**模型约束**：此接口仅可在Stage模型下使用。 503 504**系统能力**：SystemCapability.FileManagement.UserFileService。 505 506**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 507 508**返回值：** 509 510| 类型 | 说明 | 511| --- | -- | 512| {value: [RootInfo](#rootinfo), done: boolean} | 通过next遍历文件夹，直到done返回true结束；value字段返回rootInfo。| 513 514**错误码：** 515 516接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 517 518## FileAccessHelper 519 520FileAccessHelper对象。 521 522**模型约束**：此接口仅可在Stage模型下使用。 523 524**系统能力**：SystemCapability.FileManagement.UserFileService 525 526**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 527 528### getRoots 529 530getRoots() : Promise<RootIterator> 531 532以异步方法获取helper对象连接的文件管理服务类的设备根节点信息。使用Promise异步回调。 533该方法返回迭代器对象RootIterator，然后通过[next](#next-1)方法返回[RootInfo](#rootinfo)。 534 535**模型约束**：此接口仅可在Stage模型下使用。 536 537**系统能力**：SystemCapability.FileManagement.UserFileService 538 539**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 540 541**返回值：** 542 543| 类型 | 说明 | 544| --- | -- | 545| Promise<[RootIterator](#rootiterator)> | 根设备目录信息组成迭代器对象 | 546 547**错误码：** 548 549接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 550 551**示例：** 552 553 ```js 554 async getRoots() { 555 let rootIterator = null; 556 let rootinfos = []; 557 let isDone = false; 558 try { 559 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 560 rootIterator = await fileAccessHelper.getRoots(); 561 if (!rootIterator) { 562 console.error("getRoots interface returns an undefined object"); 563 return; 564 } 565 while (!isDone) { 566 let result = rootIterator.next(); 567 console.log("next result = " + JSON.stringify(result)); 568 isDone = result.done; 569 if (!isDone) 570 rootinfos.push(result.value); 571 } 572 } catch (error) { 573 console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); 574 } 575 } 576 ``` 577 578### getRoots 579 580getRoots(callback:AsyncCallback<RootIterator>) : void 581 582以异步方法获取helper对象连接的文件管理服务类的设备根节点信息。使用callback异步回调。 583callback带回迭代器对象RootIterator，然后通过[next](#next-1)方法返回[RootInfo](#rootinfo)。 584 585**模型约束**：此接口仅可在Stage模型下使用。 586 587**系统能力**：SystemCapability.FileManagement.UserFileService 588 589**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 590 591**参数：** 592 593| 参数名 | 类型 | 必填 | 说明 | 594| --- | --- | --- | -- | 595| callback | AsyncCallback<[RootIterator](#rootiterator)> | 是 | 根设备目录信息组成迭代器对象 | 596 597**错误码：** 598 599接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 600 601**示例：** 602 603 ```js 604 async getRoots() { 605 let rootinfos = []; 606 let isDone = false; 607 try { 608 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 609 fileAccessHelper.getRoots(function (err, rootIterator) { 610 if (err) { 611 console.error("Failed to getRoots in async, errCode:" + err.code + ", errMessage:" + err.message); 612 return; 613 } 614 while (!isDone) { 615 let result = rootIterator.next(); 616 console.log("next result = " + JSON.stringify(result)); 617 isDone = result.done; 618 if (!isDone) 619 rootinfos.push(result.value); 620 } 621 }); 622 } catch (error) { 623 console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); 624 } 625 } 626 ``` 627 628### createFile 629 630createFile(uri: string, displayName: string) : Promise<string> 631 632以异步方法创建文件到指定目录，返回新文件uri。使用Promise异步回调。 633 634**模型约束**：此接口仅可在Stage模型下使用。 635 636**系统能力**：SystemCapability.FileManagement.UserFileService 637 638**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 639 640**参数：** 641 642| 参数名 | 类型 | 必填 | 说明 | 643| --- | --- | --- | -- | 644| uri | string | 是 | 表示需要创建文件的父目录的Uri | 645| displayName | string | 是 | 待创建文件的名称，默认本地文件需要添加后缀 | 646 647**返回值：** 648 649| 类型 | 说明 | 650| --- | -- | 651| Promise<string> | 新创建的文件的uri | 652 653**错误码：** 654 655接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 656 657**示例：** 658 659 ```js 660 // 以媒体库uri为例 661 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 662 // 开发者应根据自己实际获取的uri进行开发 663 let sourceUri = "datashare:///media/file/6"; 664 let displayName = "file1" 665 let fileUri = null; 666 try { 667 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 668 fileUri = await fileAccessHelper.createFile(sourceUri, displayName) 669 if (!fileUri) { 670 console.error("createFile return undefined object"); 671 return; 672 } 673 console.log("createFile sucess, fileUri: " + JSON.stringify(fileUri)); 674 } catch (error) { 675 console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message); 676 }; 677 ``` 678 679### createFile 680 681createFile(uri: string, displayName: string, callback: AsyncCallback<string>) : void 682 683以异步方法创建文件到指定目录，返回新文件uri。使用callback异步回调。 684 685**模型约束**：此接口仅可在Stage模型下使用。 686 687**系统能力**：SystemCapability.FileManagement.UserFileService 688 689**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 690 691**参数：** 692 693| 参数名 | 类型 | 必填 | 说明 | 694| --- | --- | --- | -- | 695| uri | string | 是 | 表示需要创建文件的父目录的Uri | 696| displayName | string | 是 | 待创建文件的名称，默认本地文件需要添加后缀 | 697| callback | AsyncCallback<string> | 是 | 新创建的文件的uri | 698 699**错误码：** 700 701接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 702 703**示例：** 704 705 ```js 706 // 以媒体库uri为例 707 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 708 // 开发者应根据自己实际获取的uri进行开发 709 let sourceUri = "datashare:///media/file/6"; 710 let displayName = "file1" 711 try { 712 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 713 fileAccessHelper.createFile(sourceUri, displayName, function (err, fileUri) { 714 if (err) { 715 console.error("Failed to createFile in async, errCode:" + err.code + ", errMessage:" + err.message); 716 return; 717 } 718 console.log("createFile sucess, fileUri: " + JSON.stringify(fileUri)); 719 }); 720 } catch (error) { 721 console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message); 722 }; 723 ``` 724 725### mkDir 726 727mkDir(parentUri: string, displayName: string) : Promise<string> 728 729以异步方法创建文件夹到指定目录，返回文件夹uri。使用Promise异步回调。 730 731**模型约束**：此接口仅可在Stage模型下使用。 732 733**系统能力**：SystemCapability.FileManagement.UserFileService 734 735**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 736 737**参数：** 738 739| 参数名 | 类型 | 必填 | 说明 | 740| --- | --- | --- | -- | 741| parentUri | string | 是 | 表示需要创建文件夹的父目录的Uri | 742| displayName | string | 是 | 待创建文件夹的名称| 743 744**返回值：** 745 746| 类型 | 说明 | 747| --- | -- | 748| Promise<string> | 新创建的文件夹的uri | 749 750**错误码：** 751 752接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 753 754**示例：** 755 756 ```js 757 // 以媒体库uri为例 758 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 759 // 开发者应根据自己实际获取的uri进行开发 760 let sourceUri = "datashare:///media/file/6"; 761 let dirName = "dirTest" 762 let dirUri = null; 763 try { 764 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 765 dirUri = await fileAccessHelper.mkDir(sourceUri, dirName) 766 if (!dirUri) { 767 console.error("mkDir return undefined object"); 768 return; 769 } 770 console.log("mkDir sucess, dirUri: " + JSON.stringify(dirUri)); 771 } catch (error) { 772 console.error("mkDir failed, errCode:" + error.code + ", errMessage:" + error.message); 773 }; 774 ``` 775 776### mkDir 777 778mkDir(parentUri: string, displayName: string, callback: AsyncCallback<string>) : void 779 780以异步方法创建文件夹到指定目录，返回文件夹uri。使用callback异步回调。 781 782**模型约束**：此接口仅可在Stage模型下使用。 783 784**系统能力**：SystemCapability.FileManagement.UserFileService 785 786**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 787 788**参数：** 789 790| 参数名 | 类型 | 必填 | 说明 | 791| --- | --- | --- | -- | 792| parentUri | string | 是 | 表示需要创建文件夹的父目录的Uri | 793| displayName | string | 是 | 待创建文件夹的名称| 794| callback | AsyncCallback<string> | 是 | 新创建的文件夹的uri | 795 796**错误码：** 797 798接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 799 800**示例：** 801 802 ```js 803 // 以媒体库uri为例 804 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 805 // 开发者应根据自己实际获取的uri进行开发 806 let sourceUri = "datashare:///media/file/6"; 807 let dirName = "dirTest" 808 try { 809 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 810 fileAccessHelper.mkDir(sourceUri, dirName, function (err, dirUri) { 811 if (err) { 812 console.error("Failed to mkDir in async, errCode:" + err.code + ", errMessage:" + err.message); 813 return; 814 } 815 console.log("mkDir sucess, dirUri: " + JSON.stringify(dirUri)); 816 }); 817 } catch (error) { 818 console.error("mkDir failed, errCode:" + error.code + ", errMessage:" + error.message); 819 }; 820 ``` 821 822### openFile 823 824openFile(uri: string, flags: OPENFLAGS) : Promise<number> 825 826以异步方法打开文件，返回文件描述符。使用Promise异步回调。 827 828**模型约束**：此接口仅可在Stage模型下使用。 829 830**系统能力**：SystemCapability.FileManagement.UserFileService 831 832**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 833 834**参数：** 835 836| 参数名 | 类型 | 必填 | 说明 | 837| --- | --- | --- | -- | 838| uri | string | 是 | 待打开文件的uri | 839| flags | [OPENFLAGS](#openflags) | 是 | 文件打开的标志 | 840 841**返回值：** 842 843| 类型 | 说明 | 844| --- | -- | 845| Promise<number> | 文件描述符 | 846 847**错误码：** 848 849接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 850 851**示例：** 852 853 ```js 854 // 以媒体库uri为例 855 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 856 // 开发者应根据自己实际获取的uri进行开发 857 let targetUri = "datashare:///media/file/100"; 858 try { 859 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 860 let fd = await fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ); 861 } catch (error) { 862 console.error("openFile failed, errCode:" + error.code + ", errMessage:" + error.message); 863 }; 864 ``` 865 866### openFile 867 868openFile(uri: string, flags: OPENFLAGS, callback: AsyncCallback<number>) : void 869 870以异步方法打开文件，返回文件描述符。使用callback异步回调。 871 872**模型约束**：此接口仅可在Stage模型下使用。 873 874**系统能力**：SystemCapability.FileManagement.UserFileService 875 876**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 877 878**参数：** 879 880| 参数名 | 类型 | 必填 | 说明 | 881| --- | --- | --- | -- | 882| uri | string | 是 | 待打开文件的uri | 883| flags | [OPENFLAGS](#openflags) | 是 | 文件打开的标志 | 884| callback | AsyncCallback<number> | 是 | 文件描述符 | 885 886**错误码：** 887 888接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 889 890**示例：** 891 892 ```js 893 // 以媒体库uri为例 894 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 895 // 开发者应根据自己实际获取的uri进行开发 896 let targetUri = "datashare:///media/file/100"; 897 try { 898 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 899 fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ, function (err, fd) { 900 if (err) { 901 console.error("Failed to openFile in async, errCode:" + err.code + ", errMessage:" + err.message); 902 return; 903 } 904 console.log("openFile sucess, fd: " + fd); 905 }); 906 } catch (error) { 907 console.error("openFile failed, errCode:" + error.code + ", errMessage:" + error.message); 908 }; 909 ``` 910 911### delete 912 913delete(uri: string) : Promise<number> 914 915以异步方法删除文件(夹)，返回错误码。使用Promise异步回调。 916 917**模型约束**：此接口仅可在Stage模型下使用。 918 919**系统能力**：SystemCapability.FileManagement.UserFileService 920 921**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 922 923**参数：** 924 925| 参数名 | 类型 | 必填 | 说明 | 926| --- | --- | --- | -- | 927| uri | string | 是 | 待删除文件(夹)的uri | 928 929**返回值：** 930 931| 类型 | 说明 | 932| --- | -- | 933| Promise<number> | 删除操作的错误码 | 934 935**错误码：** 936 937接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 938 939**示例：** 940 941 ```js 942 // 以媒体库uri为例 943 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 944 // 开发者应根据自己实际获取的uri进行开发 945 let targetUri = "datashare:///media/file/100"; 946 try { 947 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 948 let code = await fileAccessHelper.delete(targetUri); 949 if (code != 0) 950 console.error("delete failed, code " + code); 951 } catch (error) { 952 console.error("delete failed, errCode:" + error.code + ", errMessage:" + error.message); 953 }; 954 ``` 955 956### delete 957 958delete(uri: string, callback: AsyncCallback<number>) : void 959 960以异步方法删除文件(夹)，返回错误码。使用callback异步回调。 961 962**模型约束**：此接口仅可在Stage模型下使用。 963 964**系统能力**：SystemCapability.FileManagement.UserFileService 965 966**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 967 968**参数：** 969 970| 参数名 | 类型 | 必填 | 说明 | 971| --- | --- | --- | -- | 972| uri | string | 是 | 待删除文件(夹)的uri | 973| callback | AsyncCallback<number> | 是 | 删除操作的错误码 | 974 975**错误码：** 976 977接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 978 979**示例：** 980 981 ```js 982 // 以媒体库uri为例 983 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 984 // 开发者应根据自己实际获取的uri进行开发 985 let targetUri = "datashare:///media/file/100"; 986 try { 987 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 988 fileAccessHelper.delete(targetUri, function (err, code) { 989 if (err) { 990 console.error("Failed to delete in async, errCode:" + err.code + ", errMessage:" + err.message); 991 return; 992 } 993 console.log("delete sucess, code: " + code); 994 }); 995 } catch (error) { 996 console.error("delete failed, errCode:" + error.code + ", errMessage:" + error.message); 997 }; 998 ``` 999 1000### move 1001 1002move(sourceFile: string, destFile: string) : Promise<string> 1003 1004以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用Promise异步回调。目前仅支持设备内移动，跨设备不支持移动。 1005 1006**模型约束**：此接口仅可在Stage模型下使用。 1007 1008**系统能力**：SystemCapability.FileManagement.UserFileService 1009 1010**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1011 1012**参数：** 1013 1014| 参数名 | 类型 | 必填 | 说明 | 1015| --- | --- | --- | -- | 1016| sourceFile | string | 是 | 待移动的源文件(夹)的uri | 1017| destFile | string | 是 | 目标文件夹的uri | 1018 1019**返回值：** 1020 1021| 类型 | 说明 | 1022| ----- | ------ | 1023| Promise<string> | 新路径下的文件(夹)的uri | 1024 1025**错误码：** 1026 1027接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 1028 1029**示例：** 1030 1031 ```js 1032 // 以媒体库uri为例 1033 // 示例代码sourceFile destFile表示Download目录下文件或文件夹，该uri是对应的fileInfo中uri 1034 // 开发者应根据自己实际获取的uri进行开发 1035 let sourceFile = "datashare:///media/file/102"; 1036 let destFile = "datashare:///media/file/101"; 1037 try { 1038 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1039 let fileUri = await fileAccessHelper.move(sourceFile, destFile); 1040 console.log("move sucess, fileUri: " + JSON.stringify(fileUri)); 1041 } catch (error) { 1042 console.error("move failed, errCode:" + error.code + ", errMessage:" + error.message); 1043 }; 1044 ``` 1045 1046### move 1047 1048move(sourceFile: string, destFile: string, callback: AsyncCallback<string>) : void 1049 1050以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用callback异步回调。目前仅支持设备内移动，跨设备不支持移动。 1051 1052**模型约束**：此接口仅可在Stage模型下使用。 1053 1054**系统能力**：SystemCapability.FileManagement.UserFileService 1055 1056**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1057 1058**参数：** 1059 1060| 参数名 | 类型 | 必填 | 说明 | 1061| --- | --- | --- | -- | 1062| sourceFile | string | 是 | 待移动的源文件(夹)的uri | 1063| destFile | string | 是 | 目标文件夹的uri | 1064| callback | AsyncCallback<string> | 是 | 新路径下的文件(夹)的uri | 1065 1066**错误码：** 1067 1068接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 1069 1070**示例：** 1071 1072 ```js 1073 // 以媒体库uri为例 1074 // 示例代码sourceFile destFile表示Download目录下文件或文件夹，该uri是对应的fileInfo中uri 1075 // 开发者应根据自己实际获取的uri进行开发 1076 let sourceFile = "datashare:///media/file/102"; 1077 let destFile = "datashare:///media/file/101"; 1078 try { 1079 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1080 fileAccessHelper.move(sourceFile, destFile, function (err, fileUri) { 1081 if (err) { 1082 console.error("Failed to move in async, errCode:" + err.code + ", errMessage:" + err.message); 1083 return; 1084 } 1085 console.log("move sucess, fileUri: " + JSON.stringify(fileUri)); 1086 }); 1087 } catch (error) { 1088 console.error("move failed, errCode:" + error.code + ", errMessage:" + error.message); 1089 }; 1090 ``` 1091 1092### rename 1093 1094rename(uri: string, displayName: string) : Promise<string> 1095 1096以异步方法重命名文件(夹)，返回重命名后的文件(夹)的Uri。使用Promise异步回调。 1097 1098**模型约束**：此接口仅可在Stage模型下使用。 1099 1100**系统能力**：SystemCapability.FileManagement.UserFileService 1101 1102**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1103 1104**参数：** 1105 1106| 参数名 | 类型 | 必填 | 说明 | 1107| --- | --- | --- | -- | 1108| uri | string | 是 | 源文件(夹)的uri | 1109| displayName | string | 是 | 文件(夹)名，支持带后缀 | 1110 1111**返回值：** 1112 1113| 类型 | 说明 | 1114| --- | -- | 1115| Promise<string> | 重命名后的文件(夹)的uri | 1116 1117**错误码：** 1118 1119接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 1120 1121**示例：** 1122 1123 ```js 1124 // 以媒体库uri为例 1125 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1126 // 开发者应根据自己实际获取的uri进行开发 1127 let sourceDir = "datashare:///media/file/100"; 1128 try { 1129 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1130 let DestDir = await fileAccessHelper.rename(sourceDir, "testDir"); 1131 console.log("rename sucess, DestDir: " + JSON.stringify(DestDir)); 1132 } catch (error) { 1133 console.error("rename failed, errCode:" + error.code + ", errMessage:" + error.message); 1134 }; 1135 ``` 1136 1137### rename 1138 1139rename(uri: string, displayName: string, callback: AsyncCallback<string>) : void 1140 1141以异步方法重命名文件(夹)，返回重命名后的文件(夹)的Uri。使用callback异步回调。 1142 1143**模型约束**：此接口仅可在Stage模型下使用。 1144 1145**系统能力**：SystemCapability.FileManagement.UserFileService 1146 1147**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1148 1149**参数：** 1150 1151| 参数名 | 类型 | 必填 | 说明 | 1152| --- | --- | --- | -- | 1153| uri | string | 是 | 源文件(夹)的uri | 1154| displayName | string | 是 | 文件(夹)名，支持带后缀 | 1155| callback | AsyncCallback<string> | 是 | 重命名后的文件(夹)的uri | 1156 1157**错误码：** 1158 1159接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 1160 1161**示例：** 1162 1163 ```js 1164 // 以媒体库uri为例 1165 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1166 // 开发者应根据自己实际获取的uri进行开发 1167 let sourceDir = "datashare:///media/file/100"; 1168 try { 1169 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1170 fileAccessHelper.rename(sourceDir, "testDir", function (err, DestDir) { 1171 if (err) { 1172 console.error("Failed to rename in async, errCode:" + err.code + ", errMessage:" + err.message); 1173 return; 1174 } 1175 console.log("rename sucess, DestDir: " + JSON.stringify(DestDir)); 1176 }); 1177 } catch (error) { 1178 console.error("rename failed, errCode:" + error.code + ", errMessage:" + error.message); 1179 }; 1180 ``` 1181 1182### access 1183 1184access(sourceFileUri: string) : Promise<boolean> 1185 1186以异步方法判断文件(夹)是否存在。使用Promise异步回调。 1187 1188**模型约束**：此接口仅可在Stage模型下使用。 1189 1190**系统能力**：SystemCapability.FileManagement.UserFileService 1191 1192**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1193 1194**参数：** 1195 1196| 参数名 | 类型 | 必填 | 说明 | 1197| --- | --- | --- | -- | 1198| sourceFileUri | string | 是 | 文件(夹)的uri | 1199 1200**返回值：** 1201 1202| 类型 | 说明 | 1203| --- | -- | 1204| Promise<boolean> | 文件(夹)是否存在 | 1205 1206**错误码：** 1207 1208接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 1209 1210**示例：** 1211 1212 ```js 1213 // 以媒体库uri为例 1214 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1215 // 开发者应根据自己实际获取的uri进行开发 1216 let sourceDir = "datashare:///media/file/100"; 1217 try { 1218 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1219 let existJudgment = await fileAccessHelper.access(sourceDir); 1220 if (existJudgment) 1221 console.log("sourceDir exists"); 1222 else 1223 console.log("sourceDir does not exist"); 1224 } catch (error) { 1225 console.error("access failed, errCode:" + error.code + ", errMessage:" + error.message); 1226 }; 1227 ``` 1228 1229### access 1230 1231access(sourceFileUri: string, callback: AsyncCallback<boolean>) : void 1232 1233以异步方法判断文件(夹)是否存在。使用callback异步回调。 1234 1235**模型约束**：此接口仅可在Stage模型下使用。 1236 1237**系统能力**：SystemCapability.FileManagement.UserFileService 1238 1239**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1240 1241**参数：** 1242 1243| 参数名 | 类型 | 必填 | 说明 | 1244| --- | --- | --- | -- | 1245| sourceFileUri | string | 是 | 文件(夹)的uri | 1246| callback | AsyncCallback<boolean> | 是 | 文件(夹)是否存在 | 1247 1248**错误码：** 1249 1250接口抛出错误码的详细介绍请参见[文件管理错误码](../errorcodes/errorcode-filemanagement.md)。 1251 1252**示例：** 1253 1254 ```js 1255 // 以媒体库uri为例 1256 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1257 // 开发者应根据自己实际获取的uri进行开发 1258 let sourceDir = "datashare:///media/file/100"; 1259 try { 1260 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1261 fileAccessHelper.access(sourceDir, function (err, existJudgment) { 1262 if (err) { 1263 console.error("Failed to access in async, errCode:" + err.code + ", errMessage:" + err.message); 1264 return; 1265 } 1266 if (existJudgment) 1267 console.log("sourceDir exists"); 1268 else 1269 console.log("sourceDir does not exist"); 1270 }); 1271 } catch (error) { 1272 console.error("access failed, errCode:" + error.code + ", errMessage:" + error.message); 1273 }; 1274 ``` 1275 1276## OPENFLAGS 1277 1278目前支持的文件打开的标志位。 1279 1280**系统能力：** SystemCapability.FileManagement.UserFileService 1281 1282| 名称 | 值 | 说明 | 1283| ----- | ------ | ------ | 1284| READ | 0o0 | 读模式。 | 1285| WRITE | 0o1 | 写模式。 | 1286| WRITE_READ | 0o2 | 读写模式。 | 1287