1# @ohos.file.fileAccess (公共文件访问与管理)(系统接口) 2<!--Kit: Core File Kit--> 3<!--Subsystem: FileManagement--> 4<!--Owner: @wang_zhangjun; @zhuangzhuang--> 5<!--Designer: @wang_zhangjun; @zhuangzhuang; @renguang1116--> 6<!--Tester: @liuhonggang123; @yue-ye2; @juxiaopang--> 7<!--Adviser: @foryourself--> 8 9fileAccess模块是基于[extension](../../application-models/extensionability-overview.md)机制实现的一个对公共文件访问和操作的框架。该模块一方面对接各类文件管理服务，如存储管理服务等；另一方面为系统应用提供一套统一的文件访问管理接口。存储管理服务可以管理内置存储部分目录，以及共享盘、U盘、SD卡等设备上的资源。 10 11>**说明：** 12> 13> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> - 本模块为系统接口。 15> - 当前只支持FilePicker、文件管理器调用。 16 17## 导入模块 18 19```ts 20import fileAccess from '@ohos.file.fileAccess'; 21``` 22 23## 常量 24 25表示用于监听设备上线和下线通知的URI，用作注册监听的URI。 26 27**模型约束**：仅可在Stage模型下使用。 28 29**系统能力**：SystemCapability.FileManagement.UserFileService。 30 31**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 32 33| 名称 | 类型 | 值 | 说明 | 34| ---- | --------------------------- | ---- | --------------------------------------------------------- | 35| DEVICES_URI<sup>11+</sup> | string | 'file://doc' | 监听设备上线，下线通知，作为注册监听的URI。 | 36 37## fileAccess.getFileAccessAbilityInfo 38 39getFileAccessAbilityInfo() : Promise<Array<Want>> 40 41以异步方法获取系统内extension配置为fileAccess类型的所有Want信息。使用Promise异步回调。 42 43**模型约束**：此接口仅可在Stage模型下使用。 44 45**系统能力**：SystemCapability.FileManagement.UserFileService 46 47**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 48 49**返回值：** 50 51| 类型 | 说明 | 52| --- | -- | 53| Promise<Array<[Want](../apis-ability-kit/js-apis-app-ability-want.md)>> | 表示当前系统配置fileAccess的所有文件管理类服务。 | 54 55**错误码：** 56 57接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 58 59**示例：** 60 61 ```ts 62 import { BusinessError } from '@ohos.base'; 63 import Want from '@ohos.app.ability.Want'; 64 async function getFileAccessAbilityInfo() { 65 let wantInfos: Array<Want> = []; 66 try { 67 wantInfos = await fileAccess.getFileAccessAbilityInfo(); 68 console.log("getFileAccessAbilityInfo data " + JSON.stringify(wantInfos)); 69 } catch (err) { 70 let error: BusinessError = err as BusinessError; 71 console.error("getFileAccessAbilityInfo failed, errCode:" + error.code + ", errMessage:" + error.message); 72 } 73 } 74 ``` 75 76## fileAccess.getFileAccessAbilityInfo 77 78getFileAccessAbilityInfo(callback: AsyncCallback<Array<Want>>): void 79 80以异步方法获取系统内extension配置为fileAccess类型的所有Want信息。使用callback异步回调。 81 82**模型约束**：此接口仅可在Stage模型下使用。 83 84**系统能力**：SystemCapability.FileManagement.UserFileService 85 86**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 87 88**参数：** 89 90| 参数名 | 类型 | 必填 | 说明 | 91| --- | --- | --- | -- | 92| callback | AsyncCallback<Array<[Want](../apis-ability-kit/js-apis-app-ability-want.md)>> | 是 | 表示当前系统配置fileAccess的所有文件管理类服务。 | 93 94**错误码：** 95 96接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 97 98**示例：** 99 100 ```ts 101 import { BusinessError } from '@ohos.base'; 102 import Want from '@ohos.app.ability.Want'; 103 async function getFileAccessAbilityInfo() { 104 try { 105 fileAccess.getFileAccessAbilityInfo((err: BusinessError, wantInfos: Array<Want>) => { 106 if (err) { 107 console.error("Failed to getFileAccessAbilityInfo in async, errCode:" + err.code + ", errMessage:" + err.message); 108 return; 109 } 110 console.log("getFileAccessAbilityInfo data " + JSON.stringify(wantInfos)); 111 }); 112 } catch (err) { 113 let error: BusinessError = err as BusinessError; 114 console.error("getFileAccessAbilityInfo failed, errCode:" + error.code + ", errMessage:" + error.message); 115 } 116 } 117 ``` 118 119## fileAccess.createFileAccessHelper 120 121createFileAccessHelper(context: Context, wants: Array<Want>) : FileAccessHelper 122 123以同步方法创建连接指定wants的helper对象。 124 125**模型约束**：此接口仅可在Stage模型下使用。 126 127**系统能力**：SystemCapability.FileManagement.UserFileService 128 129**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| --- | --- | --- | -- | 135| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 代表ability的上下文的能力。 | 136| wants | Array<[Want](../apis-ability-kit/js-apis-app-ability-want.md)> | 是 | Want是一种基本通信组件，主要用于服务拉起。 | 137 138**返回值：** 139 140| 类型 | 说明 | 141| --- | -- | 142| [FileAccessHelper](#fileaccesshelper) | 提供文件访问和操作能力的helper对象。 | 143 144**错误码：** 145 146接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 147 148**示例：** 149 150 ```ts 151 import { BusinessError } from '@ohos.base'; 152 import Want from '@ohos.app.ability.Want'; 153 import common from '@ohos.app.ability.common'; 154 // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 155 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 156 function createFileAccessHelper01(context: common.UIAbilityContext) { 157 let fileAccessHelper: fileAccess.FileAccessHelper; 158 // wantInfos 从getFileAccessAbilityInfo()获取 159 let wantInfos: Array<Want> = [ 160 { 161 bundleName: "com.ohos.UserFile.ExternalFileManager", 162 abilityName: "FileExtensionAbility", 163 }, 164 ] 165 try { 166 // context 是EntryAbility 传过来的context 167 fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos); 168 if (!fileAccessHelper) { 169 console.error("createFileAccessHelper interface returns an undefined object"); 170 } 171 } catch (err) { 172 let error: BusinessError = err as BusinessError; 173 console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message); 174 } 175 } 176 ``` 177 178## fileAccess.createFileAccessHelper 179 180createFileAccessHelper(context: Context) : FileAccessHelper 181 182以同步方法创建连接当前系统内所有文件管理服务的helper对象。 183 184**模型约束**：此接口仅可在Stage模型下使用。 185 186**系统能力**：SystemCapability.FileManagement.UserFileService 187 188**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 189 190**参数：** 191 192| 参数名 | 类型 | 必填 | 说明 | 193| --- | --- | --- | -- | 194| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | ability的上下文的能力。 | 195 196**返回值：** 197 198| 类型 | 说明 | 199| --- | -- | 200| [FileAccessHelper](#fileaccesshelper) | 提供文件访问和操作的能力的helper对象。 | 201 202**错误码：** 203 204接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 205 206**示例：** 207 208 ```ts 209 import { BusinessError } from '@ohos.base'; 210 import common from '@ohos.app.ability.common'; 211 // 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext 212 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 213 function createFileAccessHelper02(context: common.UIAbilityContext) { 214 let fileAccessHelperAllServer: fileAccess.FileAccessHelper; 215 // 创建连接系统内所有配置fileAccess的文件管理类服务的helper对象 216 try { 217 // context 是EntryAbility 传过来的context 218 fileAccessHelperAllServer = fileAccess.createFileAccessHelper(context); 219 if (!fileAccessHelperAllServer) { 220 console.error("createFileAccessHelper interface returns an undefined object"); 221 } 222 } catch (err) { 223 let error: BusinessError = err as BusinessError; 224 console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message); 225 } 226 } 227 ``` 228 229## FileInfo 230 231表示文件(夹)属性信息和接口能力。 232 233**模型约束**：此接口仅可在Stage模型下使用。 234 235**系统能力**：SystemCapability.FileManagement.UserFileService 236 237**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 238 239### 属性 240 241| 名称 | 类型 | 只读 | 可选 | 说明 | 242| ------ | ------ | -------- | ------ | -------- | 243| uri | string | 否 | 否 | 文件(夹)的uri。 | 244| relativePath<sup>10+</sup> | string | 是 | 否 | 文件(夹)的相对路径。 | 245| fileName | string | 否 | 否 | 文件(夹)的名称。 | 246| mode | number | 否 | 否 | 文件(夹)的权限信息。 | 247| size | number | 否 | 否 | 文件(夹)的大小。 | 248| mtime | number | 否 | 否 | 文件(夹)的修改时间。 | 249| mimeType | string | 否 | 否 | 文件(夹)的媒体资源类型。 | 250 251### listFile 252 253listFile(filter?: Filter) : FileIterator 254 255以同步方法从某个目录，基于过滤器，获取下一级符合条件的文件(夹)信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备过滤，外置存储设备不支持过滤。 256 257**模型约束**：此接口仅可在Stage模型下使用。 258 259**系统能力**：SystemCapability.FileManagement.UserFileService 260 261**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266| --- | --- | -- | -- | 267| filter | [Filter](js-apis-file-fs.md#filter10) | 否 | 过滤器对象。 | 268 269**返回值：** 270 271| 类型 | 说明 | 272| --- | -- | 273| [FileIterator](#fileiterator) | 文件(夹)信息的迭代器对象FileIterator。 | 274 275**错误码：** 276 277接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 278 279**示例：** 280 281 ```ts 282 import { BusinessError } from '@ohos.base'; 283 // fileInfoDir 表示某个目录信息 284 // let filter = { suffix : [".txt", ".jpg", ".xlsx"] }; 285 let fileInfoDir :Array<fileAccess.FileInfo> = []; 286 let subfileInfos: Array<fileAccess.FileInfo> = []; 287 let isDone: boolean = false; 288 try { 289 for (let i = 0; i < fileInfoDir.length; ++i) { 290 let fileIterator = fileInfoDir[i].listFile(); 291 // 含过滤器实现的listFile 292 // let fileIterator = fileInfoDir.listFile(filter); 293 if (!fileIterator) { 294 console.error("listFile interface returns an undefined object"); 295 } 296 while (!isDone) { 297 let result = fileIterator.next(); 298 console.log("next result = " + JSON.stringify(result)); 299 isDone = result.done; 300 if (!isDone) { 301 subfileInfos.push(result.value); 302 } 303 } 304 } 305 } catch (err) { 306 let error: BusinessError = err as BusinessError; 307 console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message); 308 } 309 ``` 310 311### scanFile 312 313scanFile(filter?: Filter) : FileIterator; 314 315以同步方法从某个目录，基于过滤器，递归获取符合条件的文件信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备。 316 317**模型约束**：此接口仅可在Stage模型下使用。 318 319**系统能力**：SystemCapability.FileManagement.UserFileService 320 321**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 322 323**参数：** 324 325| 参数名 | 类型 | 必填 | 说明 | 326| --- | --- | -- | -- | 327| filter | [Filter](js-apis-file-fs.md#filter10) | 否 | 过滤器对象。 | 328 329**返回值：** 330 331| 类型 | 说明 | 332| --- | -- | 333| [FileIterator](#fileiterator) | 文件信息的迭代器对象FileIterator。 | 334 335**错误码：** 336 337接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 338 339**示例：** 340 341 ```ts 342 import { BusinessError } from '@ohos.base'; 343 // fileInfoDir 表示某个目录信息 344 // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; 345 let fileInfoDir: Array<fileAccess.FileInfo> = []; 346 let subfileInfos: Array<fileAccess.FileInfo> = []; 347 let isDone: boolean = false; 348 try { 349 for (let i = 0; i < fileInfoDir.length; ++i) { 350 let fileIterator = fileInfoDir[i].scanFile(); 351 // 含过滤器实现的scanFile 352 // let fileIterator = fileInfoDir.scanFile(filter); 353 if (!fileIterator) { 354 console.error("scanFile interface returns an undefined object"); 355 } 356 while (!isDone) { 357 let result = fileIterator.next(); 358 console.log("next result = " + JSON.stringify(result)); 359 isDone = result.done; 360 if (!isDone) { 361 subfileInfos.push(result.value); 362 } 363 } 364 } 365 } catch (err) { 366 let error: BusinessError = err as BusinessError; 367 console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message); 368 } 369 ``` 370 371## FileIterator 372 373表示文件夹的迭代器对象。 374 375**模型约束**：此接口仅可在Stage模型下使用。 376 377**系统能力**：SystemCapability.FileManagement.UserFileService 378 379**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 380 381### next 382 383next() : { value: FileInfo, done: boolean } 384 385可以通过next同步方法获取下一级文件(夹)信息。 386 387**模型约束**：此接口仅可在Stage模型下使用。 388 389**系统能力**：SystemCapability.FileManagement.UserFileService 390 391**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 392 393**返回值：** 394 395| 类型 | 说明 | 396| --- | -- | 397| {value: [FileInfo](#fileinfo), done: boolean} | 通过next遍历文件夹，直到done返回true结束；value字段返回fileInfo。| 398 399**错误码：** 400 401接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 402 403## RootInfo 404 405表示设备的根属性信息和接口能力。 406 407**模型约束**：此接口仅可在Stage模型下使用。 408 409**系统能力**：SystemCapability.FileManagement.UserFileService 410 411**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 412 413### 属性 414 415| 名称 | 类型 | 只读 | 可选 | 说明 | 416| ------ | ------ | -------- | ------ | -------- | 417| deviceType | number | 否 | 否 |设备类型。 | 418| uri | string | 否 | 否 | 设备根目录Uri。 | 419| relativePath<sup>10+</sup> | string | 否 | 否 | 根目录的相对路径。 | 420| displayName | string | 否 | 否 | 设备名称。 | 421| deviceFlags | number | 否 | 否 | 设备支持的能力。 | 422 423### listFile 424 425listFile(filter?: Filter) : FileIterator 426 427以同步方法从某设备根节点开始，基于过滤器，获取第一级符合条件的文件(夹)信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备过滤，外置存储设备不支持过滤。 428 429**模型约束**：此接口仅可在Stage模型下使用。 430 431**系统能力**：SystemCapability.FileManagement.UserFileService 432 433**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 434 435**参数：** 436 437| 参数名 | 类型 | 必填 | 说明 | 438| --- | --- | -- | -- | 439| filter | [Filter](js-apis-file-fs.md#filter10) | 否 | 过滤器对象。 | 440 441**返回值：** 442 443| 类型 | 说明 | 444| --- | -- | 445| [FileIterator](#fileiterator) | 文件(夹)信息的迭代器对象FileIterator。 | 446 447**错误码：** 448 449接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 450 451**示例：** 452 453 ```ts 454 import { BusinessError } from '@ohos.base'; 455 // rootInfo 从getRoots()获取 456 // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; 457 let rootInfo: Array<fileAccess.FileInfo> = []; 458 let fileInfos: Array<fileAccess.FileInfo> = []; 459 let isDone: boolean = false; 460 try { 461 for (let i = 0; i < rootInfo.length; ++i) { 462 let fileIterator = rootInfo[i].listFile(); 463 // 含过滤器实现的listFile 464 // let fileIterator = rootInfo.listFile(filter); 465 if (!fileIterator) { 466 console.error("listFile interface returns an undefined object"); 467 } 468 while (!isDone) { 469 let result = fileIterator.next(); 470 console.log("next result = " + JSON.stringify(result)); 471 isDone = result.done; 472 if (!isDone) { 473 fileInfos.push(result.value); 474 } 475 } 476 } 477 } catch (err) { 478 let error: BusinessError = err as BusinessError; 479 console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message); 480 } 481 ``` 482 483### scanFile 484 485scanFile(filter?: Filter) : FileIterator 486 487以同步方法从某设备根节点开始，基于过滤器，递归获取符合条件的文件信息的迭代器对象FileIterator，然后通过[next](#next)方法返回[FileInfo](#fileinfo)。目前仅支持内置存储设备。 488 489**模型约束**：此接口仅可在Stage模型下使用。 490 491**系统能力**：SystemCapability.FileManagement.UserFileService 492 493**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| --- | --- | -- | -- | 499| filter | [Filter](js-apis-file-fs.md#filter10) | 否 | 过滤器对象。 | 500 501**返回值：** 502 503| 类型 | 说明 | 504| --- | -- | 505| [FileIterator](#fileiterator) | 文件信息的迭代器对象FileIterator。 | 506 507**错误码：** 508 509接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 510 511**示例：** 512 513 ```ts 514 import { BusinessError } from '@ohos.base'; 515 // rootInfo 从 getRoots()获取 516 // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; 517 let rootInfo: Array<fileAccess.FileInfo> = []; 518 let fileInfos: Array<fileAccess.FileInfo> = []; 519 let isDone: boolean = false; 520 try { 521 for (let i = 0; i < rootInfo.length; ++i) { 522 let fileIterator = rootInfo[i].scanFile(); 523 // 含过滤器实现的scanFile 524 // let fileIterator = rootInfo.scanFile(filter); 525 if (!fileIterator) { 526 console.error("scanFile interface returns undefined object"); 527 } 528 while (!isDone) { 529 let result = fileIterator.next(); 530 console.log("next result = " + JSON.stringify(result)); 531 isDone = result.done; 532 if (!isDone) { 533 fileInfos.push(result.value); 534 } 535 } 536 } 537 } catch (err) { 538 let error: BusinessError = err as BusinessError; 539 console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message); 540 } 541 ``` 542 543## RootIterator 544 545表示设备根目录的迭代器对象。 546 547**模型约束**：此接口仅可在Stage模型下使用。 548 549**系统能力**：SystemCapability.FileManagement.UserFileService 550 551**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 552 553### next 554 555next() : { value: RootInfo, done: boolean } 556 557通过next同步方法获取下一级设备根目录。 558 559**模型约束**：此接口仅可在Stage模型下使用。 560 561**系统能力**：SystemCapability.FileManagement.UserFileService 562 563**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 564 565**返回值：** 566 567| 类型 | 说明 | 568| --- | -- | 569| {value: [RootInfo](#rootinfo), done: boolean} | 通过next遍历文件夹，直到done返回true结束；value字段返回rootInfo。| 570 571**错误码：** 572 573接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 574 575## FileAccessHelper 576 577FileAccessHelper对象。 578 579**系统能力**：SystemCapability.FileManagement.UserFileService 580 581**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 582 583### getRoots 584 585getRoots() : Promise<RootIterator> 586 587以异步方法获取helper对象连接的文件管理服务类的设备根节点信息。使用Promise异步回调。 588该方法返回迭代器对象RootIterator，然后通过[next](#next-1)方法返回[RootInfo](#rootinfo)。 589 590**系统能力**：SystemCapability.FileManagement.UserFileService 591 592**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 593 594**返回值：** 595 596| 类型 | 说明 | 597| --- | -- | 598| Promise<[RootIterator](#rootiterator)> | 根设备目录信息组成迭代器对象。 | 599 600**错误码：** 601 602接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 603 604**示例：** 605 606 ```ts 607async function getRoots() { 608 let rootIterator: fileAccess.RootIterator; 609 let rootinfos: Array<fileAccess.RootInfo> = []; 610 let isDone: boolean = false; 611 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 612 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 613 try { 614 if (fileAccessHelper != undefined) { 615 rootIterator = await fileAccessHelper.getRoots(); 616 if (!rootIterator) { 617 console.error("getRoots interface returns an undefined object"); 618 } 619 while (!isDone) { 620 let result = rootIterator.next(); 621 console.log("next result = " + JSON.stringify(result)); 622 isDone = result.done; 623 if (!isDone) { 624 rootinfos.push(result.value); 625 } 626 } 627 } 628 } catch (err) { 629 let error: BusinessError = err as BusinessError; 630 console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); 631 } 632} 633 ``` 634 635### getRoots 636 637getRoots(callback:AsyncCallback<RootIterator>) : void 638 639以异步方法获取helper对象连接的文件管理服务类的设备根节点信息。使用callback异步回调。 640callback带回迭代器对象RootIterator，然后通过[next](#next-1)方法返回[RootInfo](#rootinfo)。 641 642**系统能力**：SystemCapability.FileManagement.UserFileService 643 644**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 645 646**参数：** 647 648| 参数名 | 类型 | 必填 | 说明 | 649| --- | --- | --- | -- | 650| callback | AsyncCallback<[RootIterator](#rootiterator)> | 是 | 根设备目录信息组成迭代器对象。 | 651 652**错误码：** 653 654接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 655 656**示例：** 657 658 ```ts 659 import { BusinessError } from '@ohos.base'; 660 async function getRoots() { 661 let rootinfos: Array<fileAccess.RootInfo> = []; 662 let isDone: boolean = false; 663 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 664 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 665 try { 666 if (fileAccessHelper != undefined) { 667 fileAccessHelper.getRoots((err: BusinessError, rootIterator: fileAccess.RootIterator) => { 668 if (err) { 669 console.error("Failed to getRoots in async, errCode:" + err.code + ", errMessage:" + err.message); 670 } 671 while (!isDone) { 672 let result = rootIterator.next(); 673 console.log("next result = " + JSON.stringify(result)); 674 isDone = result.done; 675 if (!isDone) { 676 rootinfos.push(result.value); 677 } 678 } 679 }); 680 } 681 } catch (err) { 682 let error: BusinessError = err as BusinessError; 683 console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); 684 } 685 } 686 ``` 687 688### createFile 689 690createFile(uri: string, displayName: string) : Promise<string> 691 692以异步方法创建文件到指定目录，返回新文件uri。使用Promise异步回调。 693 694**系统能力**：SystemCapability.FileManagement.UserFileService 695 696**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 697 698**参数：** 699 700| 参数名 | 类型 | 必填 | 说明 | 701| --- | --- | --- | -- | 702| uri | string | 是 | 表示需要创建文件的父目录的uri。 | 703| displayName | string | 是 | 待创建文件的名称。默认本地文件需要添加后缀。 | 704 705**返回值：** 706 707| 类型 | 说明 | 708| --- | -- | 709| Promise<string> | 新创建的文件的uri。 | 710 711**错误码：** 712 713接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 714 715**示例：** 716 717 ```ts 718 import { BusinessError } from '@ohos.base'; 719 async function createFile() { 720 // 以内置存储目录为例 721 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 722 // 开发者应根据自己实际获取的uri进行开发 723 let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; 724 let displayName: string = "file1"; 725 let fileUri: string; 726 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 727 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 728 try { 729 if (fileAccessHelper != undefined) { 730 fileUri = await fileAccessHelper.createFile(sourceUri, displayName); 731 if (!fileUri) { 732 console.error("createFile return undefined object"); 733 return; 734 } 735 console.log("createFile success, fileUri: " + JSON.stringify(fileUri)); 736 } 737 } catch (err) { 738 let error: BusinessError = err as BusinessError; 739 console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message); 740 } 741 } 742 ``` 743 744### createFile 745 746createFile(uri: string, displayName: string, callback: AsyncCallback<string>) : void 747 748以异步方法创建文件到指定目录，返回新文件uri。使用callback异步回调。 749 750**系统能力**：SystemCapability.FileManagement.UserFileService 751 752**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 753 754**参数：** 755 756| 参数名 | 类型 | 必填 | 说明 | 757| --- | --- | --- | -- | 758| uri | string | 是 | 表示需要创建文件的父目录的uri。 | 759| displayName | string | 是 | 待创建文件的名称。默认本地文件需要添加后缀。 | 760| callback | AsyncCallback<string> | 是 | 新创建的文件的uri。 | 761 762**错误码：** 763 764接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 765 766**示例：** 767 768 ```ts 769 import { BusinessError } from '@ohos.base'; 770 // 以内置存储目录为例 771 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 772 // 开发者应根据自己实际获取的uri进行开发 773 let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; 774 let displayName: string = "file1"; 775 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 776 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 777 try { 778 if (fileAccessHelper != undefined) { 779 fileAccessHelper.createFile(sourceUri, displayName, (err: BusinessError, fileUri: string) => { 780 if (err) { 781 console.error("Failed to createFile in async, errCode:" + err.code + ", errMessage:" + err.message); 782 } 783 console.log("createFile success, fileUri: " + JSON.stringify(fileUri)); 784 }); 785 } 786 } catch (err) { 787 let error: BusinessError = err as BusinessError; 788 console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message); 789 } 790 ``` 791 792### mkDir 793 794mkDir(parentUri: string, displayName: string) : Promise<string> 795 796以异步方法创建文件夹到指定目录，返回文件夹uri。使用Promise异步回调。 797 798**系统能力**：SystemCapability.FileManagement.UserFileService 799 800**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 801 802**参数：** 803 804| 参数名 | 类型 | 必填 | 说明 | 805| --- | --- | --- | -- | 806| parentUri | string | 是 | 表示需要创建文件夹的父目录的uri。 | 807| displayName | string | 是 | 待创建文件夹的名称。| 808 809**返回值：** 810 811| 类型 | 说明 | 812| --- | -- | 813| Promise<string> | 新创建的文件夹的uri。 | 814 815**错误码：** 816 817接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 818 819**示例：** 820 821 ```ts 822 import { BusinessError } from '@ohos.base'; 823 // 以内置存储目录为例 824 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 825 // 开发者应根据自己实际获取的uri进行开发 826 async function createDirectory() { 827 let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; 828 let dirName: string = "dirTest"; 829 let dirUri: string; 830 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 831 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 832 try { 833 if (fileAccessHelper != undefined) { 834 dirUri = await fileAccessHelper.mkDir(sourceUri, dirName); 835 if (!dirUri) { 836 console.error("mkDir return undefined object"); 837 } else { 838 console.log("mkDir success, dirUri: " + JSON.stringify(dirUri)); 839 } 840 } 841 } catch (err) { 842 let error: BusinessError = err as BusinessError; 843 console.error("mkDir failed, errCode:" + error.code + ", errMessage:" + error.message); 844 } 845 } 846 ``` 847 848### mkDir 849 850mkDir(parentUri: string, displayName: string, callback: AsyncCallback<string>) : void 851 852以异步方法创建文件夹到指定目录，返回文件夹uri。使用callback异步回调。 853 854**系统能力**：SystemCapability.FileManagement.UserFileService 855 856**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 857 858**参数：** 859 860| 参数名 | 类型 | 必填 | 说明 | 861| --- | --- | --- | -- | 862| parentUri | string | 是 | 表示需要创建文件夹的父目录的uri。 | 863| displayName | string | 是 | 待创建文件夹的名称。| 864| callback | AsyncCallback<string> | 是 | 新创建的文件夹的uri。 | 865 866**错误码：** 867 868接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 869 870**示例：** 871 872 ```ts 873 import { BusinessError } from '@ohos.base'; 874 // 以内置存储目录为例 875 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 876 // 开发者应根据自己实际获取的uri进行开发 877 let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; 878 let dirName: string = "dirTest"; 879 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 880 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 881 try { 882 if (fileAccessHelper != undefined) { 883 fileAccessHelper.mkDir(sourceUri, dirName, (err: BusinessError, dirUri: string) => { 884 if (err) { 885 console.error("Failed to mkDir in async, errCode:" + err.code + ", errMessage:" + err.message); 886 } 887 console.log("mkDir success, dirUri: " + JSON.stringify(dirUri)); 888 }); 889 } 890 } catch (err) { 891 let error: BusinessError = err as BusinessError; 892 console.error("mkDir failed, errCode:" + error.code + ", errMessage:" + error.message); 893 } 894 ``` 895 896### openFile 897 898openFile(uri: string, flags: OPENFLAGS) : Promise<number> 899 900以异步方法打开文件，返回文件描述符。使用Promise异步回调。 901 902**系统能力**：SystemCapability.FileManagement.UserFileService 903 904**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 905 906**参数：** 907 908| 参数名 | 类型 | 必填 | 说明 | 909| --- | --- | --- | -- | 910| uri | string | 是 | 待打开文件的uri。 | 911| flags | [OPENFLAGS](#openflags) | 是 | 文件打开的标志。 | 912 913**返回值：** 914 915| 类型 | 说明 | 916| --- | -- | 917| Promise<number> | 文件描述符。 | 918 919**错误码：** 920 921接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 922 923**示例：** 924 925 ```ts 926 import { BusinessError } from '@ohos.base'; 927 async function openFile01() { 928 // 以内置存储目录为例 929 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 930 // 开发者应根据自己实际获取的uri进行开发 931 let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 932 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 933 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 934 try { 935 if (fileAccessHelper != undefined) { 936 let fd = await fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ); 937 } 938 } catch (err) { 939 let error: BusinessError = err as BusinessError; 940 console.error("openFile failed, errCode:" + error.code + ", errMessage:" + error.message); 941 } 942 } 943 ``` 944 945### openFile 946 947openFile(uri: string, flags: OPENFLAGS, callback: AsyncCallback<number>) : void 948 949以异步方法打开文件，返回文件描述符。使用callback异步回调。 950 951**系统能力**：SystemCapability.FileManagement.UserFileService 952 953**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 954 955**参数：** 956 957| 参数名 | 类型 | 必填 | 说明 | 958| --- | --- | --- | -- | 959| uri | string | 是 | 待打开文件的uri。 | 960| flags | [OPENFLAGS](#openflags) | 是 | 文件打开的标志。 | 961| callback | AsyncCallback<number> | 是 | 文件描述符。 | 962 963**错误码：** 964 965接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 966 967**示例：** 968 969 ```ts 970 import { BusinessError } from '@ohos.base'; 971 // 以内置存储目录为例 972 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 973 // 开发者应根据自己实际获取的uri进行开发 974 let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 975 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 976 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 977 try { 978 if (fileAccessHelper != undefined) { 979 fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ, (err: BusinessError, fd: number) => { 980 if (err) { 981 console.error("Failed to openFile in async, errCode:" + err.code + ", errMessage:" + err.message); 982 } 983 console.log("openFile success, fd: " + fd); 984 }); 985 } 986 } catch (err) { 987 let error: BusinessError = err as BusinessError; 988 console.error("openFile failed, errCode:" + error.code + ", errMessage:" + error.message); 989 } 990 ``` 991 992### delete 993 994delete(uri: string) : Promise<number> 995 996以异步方法删除文件(夹)，返回错误码。使用Promise异步回调。 997 998**系统能力**：SystemCapability.FileManagement.UserFileService 999 1000**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1001 1002**参数：** 1003 1004| 参数名 | 类型 | 必填 | 说明 | 1005| --- | --- | --- | -- | 1006| uri | string | 是 | 待删除文件(夹)的uri。 | 1007 1008**返回值：** 1009 1010| 类型 | 说明 | 1011| --- | -- | 1012| Promise<number> | 删除操作的错误码。 | 1013 1014**错误码：** 1015 1016接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1017 1018**示例：** 1019 1020 ```ts 1021 import { BusinessError } from '@ohos.base'; 1022 async function deleteFile01() { 1023 // 以内置存储目录为例 1024 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 1025 // 开发者应根据自己实际获取的uri进行开发 1026 let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1027 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1028 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1029 try { 1030 if (fileAccessHelper != undefined) { 1031 let code = await fileAccessHelper.delete(targetUri); 1032 if (code != 0) 1033 console.error("delete failed, code " + code); 1034 } 1035 } catch (err) { 1036 let error: BusinessError = err as BusinessError; 1037 console.error("delete failed, errCode:" + error.code + ", errMessage:" + error.message); 1038 } 1039 } 1040 ``` 1041 1042### delete 1043 1044delete(uri: string, callback: AsyncCallback<number>) : void 1045 1046以异步方法删除文件(夹)，返回错误码。使用callback异步回调。 1047 1048**系统能力**：SystemCapability.FileManagement.UserFileService 1049 1050**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1051 1052**参数：** 1053 1054| 参数名 | 类型 | 必填 | 说明 | 1055| --- | --- | --- | -- | 1056| uri | string | 是 | 待删除文件(夹)的uri。 | 1057| callback | AsyncCallback<number> | 是 | 删除操作的错误码。 | 1058 1059**错误码：** 1060 1061接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1062 1063**示例：** 1064 1065 ```ts 1066 import { BusinessError } from '@ohos.base'; 1067 // 以内置存储目录为例 1068 // 示例代码targetUri表示Download目录下文件，该uri是对应的fileInfo中uri 1069 // 开发者应根据自己实际获取的uri进行开发 1070 let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1071 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1072 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1073 try { 1074 if (fileAccessHelper != undefined) { 1075 fileAccessHelper.delete(targetUri, (err: BusinessError, code: number) => { 1076 if (err) { 1077 console.error("Failed to delete in async, errCode:" + err.code + ", errMessage:" + err.message); 1078 } 1079 console.log("delete success, code: " + code); 1080 }); 1081 } 1082 } catch (err) { 1083 let error: BusinessError = err as BusinessError; 1084 console.error("delete failed, errCode:" + error.code + ", errMessage:" + error.message); 1085 } 1086 ``` 1087 1088### move 1089 1090move(sourceFile: string, destFile: string) : Promise<string> 1091 1092以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用Promise异步回调。目前仅支持设备内移动，跨设备不支持移动。 1093 1094**系统能力**：SystemCapability.FileManagement.UserFileService 1095 1096**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1097 1098**参数：** 1099 1100| 参数名 | 类型 | 必填 | 说明 | 1101| --- | --- | --- | -- | 1102| sourceFile | string | 是 | 待移动的源文件(夹)的uri。 | 1103| destFile | string | 是 | 目标文件夹的uri。 | 1104 1105**返回值：** 1106 1107| 类型 | 说明 | 1108| ----- | ------ | 1109| Promise<string> | 新路径下的文件(夹)的uri。 | 1110 1111**错误码：** 1112 1113接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1114 1115**示例：** 1116 1117 ```ts 1118 import { BusinessError } from '@ohos.base'; 1119 async function moveFile01() { 1120 // 以内置存储目录为例 1121 // 示例代码sourceFile destFile表示Download目录下文件和文件夹，该uri是对应的fileInfo中uri 1122 // 开发者应根据自己实际获取的uri进行开发 1123 let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1124 let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1125 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1126 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1127 try { 1128 if (fileAccessHelper != undefined) { 1129 let fileUri = await fileAccessHelper.move(sourceFile, destFile); 1130 console.log("move success, fileUri: " + JSON.stringify(fileUri)); 1131 } 1132 } catch (err) { 1133 let error: BusinessError = err as BusinessError; 1134 console.error("move failed, errCode:" + error.code + ", errMessage:" + error.message); 1135 } 1136 } 1137 ``` 1138 1139### move 1140 1141move(sourceFile: string, destFile: string, callback: AsyncCallback<string>) : void 1142 1143以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用callback异步回调。目前仅支持设备内移动，跨设备不支持移动。 1144 1145**系统能力**：SystemCapability.FileManagement.UserFileService 1146 1147**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1148 1149**参数：** 1150 1151| 参数名 | 类型 | 必填 | 说明 | 1152| --- | --- | --- | -- | 1153| sourceFile | string | 是 | 待移动的源文件(夹)的uri。 | 1154| destFile | string | 是 | 目标文件夹的uri。 | 1155| callback | AsyncCallback<string> | 是 | 新路径下的文件(夹)的uri。 | 1156 1157**错误码：** 1158 1159接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1160 1161**示例：** 1162 1163 ```ts 1164 import { BusinessError } from '@ohos.base'; 1165 // 以内置存储目录为例 1166 // 示例代码sourceFile destFile表示Download目录下文件和文件夹，该uri是对应的fileInfo中uri 1167 // 开发者应根据自己实际获取的uri进行开发 1168 let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1169 let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1170 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1171 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1172 try { 1173 if (fileAccessHelper != undefined) { 1174 fileAccessHelper.move(sourceFile, destFile, (err: BusinessError, fileUri: string) => { 1175 if (err) { 1176 console.error("Failed to move in async, errCode:" + err.code + ", errMessage:" + err.message); 1177 } 1178 console.log("move success, fileUri: " + JSON.stringify(fileUri)); 1179 }); 1180 } 1181 } catch (err) { 1182 let error: BusinessError = err as BusinessError; 1183 console.error("move failed, errCode:" + error.code + ", errMessage:" + error.message); 1184 } 1185 ``` 1186 1187### rename 1188 1189rename(uri: string, displayName: string) : Promise<string> 1190 1191以异步方法重命名文件(夹)，返回重命名后的文件(夹)的Uri。使用Promise异步回调。 1192 1193**系统能力**：SystemCapability.FileManagement.UserFileService 1194 1195**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1196 1197**参数：** 1198 1199| 参数名 | 类型 | 必填 | 说明 | 1200| --- | --- | --- | -- | 1201| uri | string | 是 | 源文件(夹)的uri。 | 1202| displayName | string | 是 | 文件(夹)名，支持带后缀。 | 1203 1204**返回值：** 1205 1206| 类型 | 说明 | 1207| --- | -- | 1208| Promise<string> | 重命名后的文件(夹)的uri。 | 1209 1210**错误码：** 1211 1212接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1213 1214**示例：** 1215 1216 ```ts 1217 import { BusinessError } from '@ohos.base'; 1218 async function renameFile01() { 1219 // 以内置存储目录为例 1220 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1221 // 开发者应根据自己实际获取的uri进行开发 1222 let sourceDir: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1223 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1224 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1225 try { 1226 if (fileAccessHelper != undefined) { 1227 let DestDir = await fileAccessHelper.rename(sourceDir, "testDir"); 1228 console.log("rename success, DestDir: " + JSON.stringify(DestDir)); 1229 } 1230 } catch (err) { 1231 let error: BusinessError = err as BusinessError; 1232 console.error("rename failed, errCode:" + error.code + ", errMessage:" + error.message); 1233 } 1234 } 1235 ``` 1236 1237### rename 1238 1239rename(uri: string, displayName: string, callback: AsyncCallback<string>) : void 1240 1241以异步方法重命名文件(夹)，返回重命名后的文件(夹)的Uri。使用callback异步回调。 1242 1243**系统能力**：SystemCapability.FileManagement.UserFileService 1244 1245**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1246 1247**参数：** 1248 1249| 参数名 | 类型 | 必填 | 说明 | 1250| --- | --- | --- | -- | 1251| uri | string | 是 | 源文件(夹)的uri。 | 1252| displayName | string | 是 | 文件(夹)名，支持带后缀。 | 1253| callback | AsyncCallback<string> | 是 | 重命名后的文件(夹)的uri。 | 1254 1255**错误码：** 1256 1257接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1258 1259**示例：** 1260 1261 ```ts 1262 import { BusinessError } from '@ohos.base'; 1263 // 以内置存储目录为例 1264 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1265 // 开发者应根据自己实际获取的uri进行开发 1266 let sourceDir: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1267 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1268 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1269 try { 1270 if (fileAccessHelper != undefined) { 1271 fileAccessHelper.rename(sourceDir, "testDir", (err: BusinessError, DestDir: string) => { 1272 if (err) { 1273 console.error("Failed to rename in async, errCode:" + err.code + ", errMessage:" + err.message); 1274 } 1275 console.log("rename success, DestDir: " + JSON.stringify(DestDir)); 1276 }); 1277 } 1278 } catch (err) { 1279 let error: BusinessError = err as BusinessError; 1280 console.error("rename failed, errCode:" + error.code + ", errMessage:" + error.message); 1281 } 1282 ``` 1283 1284### access 1285 1286access(sourceFileUri: string) : Promise<boolean> 1287 1288以异步方法判断文件(夹)是否存在。使用Promise异步回调。 1289 1290**系统能力**：SystemCapability.FileManagement.UserFileService 1291 1292**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1293 1294**参数：** 1295 1296| 参数名 | 类型 | 必填 | 说明 | 1297| --- | --- | --- | -- | 1298| sourceFileUri | string | 是 | 文件(夹)的uri。 | 1299 1300**返回值：** 1301 1302| 类型 | 说明 | 1303| --- | -- | 1304| Promise<boolean> | 文件(夹)是否存在。true为存在；false为不存在。| 1305 1306**错误码：** 1307 1308接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1309 1310**示例：** 1311 1312 ```ts 1313 import { BusinessError } from '@ohos.base'; 1314 // 以内置存储目录为例 1315 // 示例代码sourceDir表示Download目录下文件，该uri是对应的fileInfo中uri 1316 // 开发者应根据自己实际获取的uri进行开发 1317 async function accessFunc() { 1318 let sourceDir: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1319 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1320 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1321 try { 1322 if (fileAccessHelper != undefined) { 1323 let existJudgment = await fileAccessHelper.access(sourceDir); 1324 if (existJudgment) { 1325 console.log("sourceDir exists"); 1326 } else { 1327 console.log("sourceDir does not exist"); 1328 } 1329 } 1330 } catch (err) { 1331 let error: BusinessError = err as BusinessError; 1332 console.error("access failed, errCode:" + error.code + ", errMessage:" + error.message); 1333 } 1334 } 1335 ``` 1336 1337### access 1338 1339access(sourceFileUri: string, callback: AsyncCallback<boolean>) : void 1340 1341以异步方法判断文件(夹)是否存在。使用callback异步回调。 1342 1343**系统能力**：SystemCapability.FileManagement.UserFileService 1344 1345**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1346 1347**参数：** 1348 1349| 参数名 | 类型 | 必填 | 说明 | 1350| --- | --- | --- | -- | 1351| sourceFileUri | string | 是 | 文件(夹)的uri。 | 1352| callback | AsyncCallback<boolean> | 是 | 文件(夹)是否存在。true为存在；false为不存在。 | 1353 1354**错误码：** 1355 1356接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 1357 1358**示例：** 1359 1360 ```ts 1361 import { BusinessError } from '@ohos.base'; 1362 // 以内置存储目录为例 1363 // 示例代码sourceDir表示Download目录下文件夹，该uri是对应的fileInfo中uri 1364 // 开发者应根据自己实际获取的uri进行开发 1365 let sourceDir: string = "file://docs/storage/Users/currentUser/Download/test"; 1366 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1367 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1368 try { 1369 if (fileAccessHelper != undefined) { 1370 fileAccessHelper.access(sourceDir, (err: BusinessError, existJudgment: boolean) => { 1371 if (err) { 1372 console.error("Failed to access in async, errCode:" + err.code + ", errMessage:" + err.message); 1373 return; 1374 } 1375 if (existJudgment) 1376 console.log("sourceDir exists"); 1377 else 1378 console.log("sourceDir does not exist"); 1379 }); 1380 } 1381 } catch (err) { 1382 let error: BusinessError = err as BusinessError; 1383 console.error("access failed, errCode:" + error.code + ", errMessage:" + error.message); 1384 } 1385 ``` 1386 1387### getFileInfoFromUri<sup>10+</sup> 1388 1389getFileInfoFromUri(uri: string) : Promise\<FileInfo> 1390 1391以异步方法获取uri对应的FileInfo对象。使用promise异步回调。 1392 1393**系统能力**：SystemCapability.FileManagement.UserFileService 1394 1395**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1396 1397**参数：** 1398 1399| 参数名 | 类型 | 必填 | 说明 | 1400| --- | --- | --- | -- | 1401| uri | string | 是 | 文件(夹)的Uri。 | 1402 1403**返回值：** 1404 1405| 类型 | 说明 | 1406| --- | -- | 1407| Promise\<[FileInfo](#fileinfo)> | FileInfo对象。 | 1408 1409**示例：** 1410 1411 ```ts 1412 import { BusinessError } from '@ohos.base'; 1413 // 以内置存储目录为例 1414 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 1415 // 开发者应根据自己实际获取的uri进行开发 1416 async function getUri() { 1417 let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; 1418 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1419 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1420 try { 1421 if (fileAccessHelper != undefined) { 1422 let fileInfo = await fileAccessHelper.getFileInfoFromUri(sourceUri); 1423 } 1424 } catch (err) { 1425 let error: BusinessError = err as BusinessError; 1426 console.error("getFileInfoFromUri failed, errCode:" + error.code + ", errMessage:" + error.message); 1427 } 1428 } 1429 ``` 1430 1431### getFileInfoFromUri<sup>10+</sup> 1432 1433getFileInfoFromUri(uri: string, callback: AsyncCallback\<FileInfo>) : void 1434 1435以异步方法获取uri对应的FileInfo对象。使用callback异步回调。 1436 1437**系统能力**：SystemCapability.FileManagement.UserFileService 1438 1439**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1440 1441**参数：** 1442 1443| 参数名 | 类型 | 必填 | 说明 | 1444| --- | --- | --- | -- | 1445| uri | string | 是 | 文件(夹)的Uri。 | 1446| callback | AsyncCallback<[FileInfo](#fileinfo)> | 是 | uri对应的FileInfo对象。 | 1447 1448**示例：** 1449 1450 ```ts 1451 import { BusinessError } from '@ohos.base'; 1452 // 以内置存储目录为例 1453 // 示例代码sourceUri表示Download目录，该uri是对应的fileInfo中uri 1454 // 开发者应根据自己实际获取的uri进行开发 1455 let sourceUri: string = "file://docs/storage/Users/currentUser/Download"; 1456 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1457 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1458 try { 1459 if (fileAccessHelper != undefined) { 1460 fileAccessHelper.getFileInfoFromUri(sourceUri, (err: BusinessError, fileInfo: fileAccess.FileInfo) => { 1461 if (err) { 1462 console.error("Failed to getFileInfoFromUri in async, errCode:" + err.code + ", errMessage:" + err.message); 1463 return; 1464 } 1465 console.log("getFileInfoFromUri success, fileInfo: " + JSON.stringify(fileInfo)); 1466 }); 1467 } 1468 } catch (err) { 1469 let error: BusinessError = err as BusinessError; 1470 console.error("getFileInfoFromUri failed, errCode:" + error.code + ", errMessage:" + error.message); 1471 } 1472 ``` 1473 1474 1475### getFileInfoFromRelativePath<sup>10+</sup> 1476 1477getFileInfoFromRelativePath(relativePath: string) : Promise\<FileInfo> 1478 1479以异步方法获取relativePath对应的FileInfo对象。使用promise异步回调。 1480 1481**系统能力**：SystemCapability.FileManagement.UserFileService 1482 1483**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1484 1485**参数：** 1486 1487| 参数名 | 类型 | 必填 | 说明 | 1488| --- | --- | --- | -- | 1489| relativePath | string | 是 | 文件(夹)的相对路径。 | 1490 1491**返回值：** 1492 1493| 类型 | 说明 | 1494| --- | -- | 1495| Promise\<[FileInfo](#fileinfo)> | FileInfo对象。 | 1496 1497**示例：** 1498 1499 ```ts 1500 import { BusinessError } from '@ohos.base'; 1501 // 示例代码relativePath表示Download目录，该relativePath是对应的fileInfo中relativePath 1502 // 开发者应根据自己实际获取的relativePath进行开发 1503 async function getRelativePath() { 1504 let relativePath: string = "Download/"; 1505 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1506 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1507 try { 1508 if (fileAccessHelper != undefined) { 1509 let fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(relativePath); 1510 } 1511 } catch (err) { 1512 let error: BusinessError = err as BusinessError; 1513 console.error("getFileInfoFromRelativePath failed, errCode:" + error.code + ", errMessage:" + error.message); 1514 } 1515 } 1516 ``` 1517 1518### getFileInfoFromRelativePath<sup>10+</sup> 1519 1520getFileInfoFromRelativePath(relativePath: string, callback: AsyncCallback\<FileInfo>) : void 1521 1522以异步方法获取relativePath对应的FileInfo对象。使用callback异步回调。 1523 1524**系统能力**：SystemCapability.FileManagement.UserFileService 1525 1526**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1527 1528**参数：** 1529 1530| 参数名 | 类型 | 必填 | 说明 | 1531| --- | --- | --- | -- | 1532| relativePath | string | 是 | 文件(夹)的相对路径。 | 1533| callback | AsyncCallback<[FileInfo](#fileinfo)> | 是 | relativePath对应的FileInfo对象。 | 1534 1535**示例：** 1536 1537 ```ts 1538 import { BusinessError } from '@ohos.base'; 1539 // 示例代码relativePath表示Download目录，该relativePath是对应的fileInfo中relativePath 1540 // 开发者应根据自己实际获取的relativePath进行开发 1541 let relativePath: string = "Download/"; 1542 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1543 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1544 try { 1545 if (fileAccessHelper != undefined) { 1546 fileAccessHelper.getFileInfoFromRelativePath(relativePath, (err: BusinessError, fileInfo: fileAccess.FileInfo) => { 1547 if (err) { 1548 console.error("Failed to getFileInfoFromRelativePath in async, errCode:" + err.code + ", errMessage:" + err.message); 1549 return; 1550 } 1551 console.log("getFileInfoFromRelativePath success, fileInfo: " + JSON.stringify(fileInfo)); 1552 }); 1553 } 1554 } catch (err) { 1555 let error: BusinessError = err as BusinessError; 1556 console.error("getFileInfoFromRelativePath failed, errCode:" + error.code + ", errMessage:" + error.message); 1557 } 1558 ``` 1559 1560### query<sup>10+</sup> 1561 1562query(uri:string, metaJson: string) : Promise<string> 1563 1564通过uri查询文件或目录的相关信息，使用Promise异步回调。 1565 1566**系统能力**：SystemCapability.FileManagement.UserFileService 1567 1568**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1569 1570**参数：** 1571 1572| 参数名 | 类型 | 必填 | 说明 | 1573| -------- | ------ | ---- | ---------------------------------------------------- | 1574| uri | string | 是 | 所选文件或目录的uri（从[FileInfo](#fileinfo)中获取）。 | 1575| metaJson | string | 是 | json字符串，包含查询属性[FILEKEY](#filekey10) 。 | 1576 1577**返回值：** 1578 1579| 类型 | 说明 | 1580| :-------------------- | :------------------------------- | 1581| Promise<string> | 返回json字符串，包括查询属性和值。 | 1582 1583**示例：** 1584 1585```ts 1586import { BusinessError } from '@ohos.base'; 1587async function getQuery01() { 1588 let imageFileRelativePath: string = "/storage/Users/currentUser/Download/queryTest/image/01.jpg"; 1589 let jsonStrSingleRelativepath: string = JSON.stringify({ [fileAccess.FileKey.RELATIVE_PATH]: "" }); 1590 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1591 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1592 try { 1593 if (fileAccessHelper != undefined) { 1594 let fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(imageFileRelativePath); 1595 let queryResult = await fileAccessHelper.query(fileInfo.uri, jsonStrSingleRelativepath); 1596 console.log("query_file_single faf query, queryResult.relative_path: " + JSON.parse(queryResult).relative_path); 1597 } 1598 } catch (err) { 1599 let error: BusinessError = err as BusinessError; 1600 console.error("query_file_single faf query failed, error.code :" + error.code + ", errorMessage :" + error.message); 1601 } 1602} 1603``` 1604 1605### query<sup>10+</sup> 1606 1607query(uri:string, metaJson: string, callback: AsyncCallback<string>) : void 1608 1609通过uri查询文件或目录的相关信息，使用callback异步回调。 1610 1611**系统能力**：SystemCapability.FileManagement.UserFileService 1612 1613**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1614 1615**参数：** 1616 1617| 参数名 | 类型 | 必填 | 说明 | 1618| -------- | --------------------------- | ---- | ---------------------------------------------------- | 1619| uri | string | 是 | 所选文件或目录的uri（从[FileInfo](#fileinfo)中获取）。 | 1620| metaJson | string | 是 | json字符串，包含查询属性[FILEKEY](#filekey10)。 | 1621| callback | AsyncCallback<string> | 是 | 返回json字符串，包括查询属性和值。 | 1622 1623**示例：** 1624 1625```ts 1626import { BusinessError } from '@ohos.base'; 1627async function getQuery02() { 1628 let imageFileRelativePath: string = "/storage/Users/currentUser/Download/queryTest/image/01.jpg"; 1629 let jsonStrSingleRelativepath: string = JSON.stringify({ [fileAccess.FileKey.RELATIVE_PATH]: "" }); 1630 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1631 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1632 try { 1633 if (fileAccessHelper != undefined) { 1634 let fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(imageFileRelativePath); 1635 fileAccessHelper.query(fileInfo.uri, jsonStrSingleRelativepath, (err: BusinessError, queryResult: string) => { 1636 if (err) { 1637 console.error(`query_file_single faf query Failed, code is ${err.code}, message is ${err.message}`); 1638 return; 1639 } 1640 console.log("query_file_single faf query, queryResult.relative_path: " + JSON.parse(queryResult).relative_path); 1641 }) 1642 } 1643 } catch (err) { 1644 let error: BusinessError = err as BusinessError; 1645 console.error("query_file_single faf query failed, error.code :" + error.code + ", errorMessage :" + error.message); 1646 } 1647} 1648``` 1649 1650### copy<sup>10+</sup> 1651 1652copy(sourceUri: string, destUri: string, force?: boolean) : Promise<Array<CopyResult>> 1653 1654复制文件或目录，使用 Promise 异步回调。 1655 1656**系统能力**：SystemCapability.FileManagement.UserFileService 1657 1658**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1659 1660**参数：** 1661 1662| 参数名 | 类型 | 必填 | 说明 | 1663| --------- | ------- | ---- | ------------------------------------------------------------ | 1664| sourceUri | string | 是 | 待拷贝的源文件(夹)的 uri。例如：file://docs/storage/Users/currentUser/Download/1.txt。 | 1665| destUri | string | 是 | 目标文件夹的 uri。例如：file://docs/storage/Users/currentUser/Download/test。 | 1666| force | boolean | 否 | 含有同名文件时是否强制覆盖文件。force 为 true 时强制覆盖文件；force 为空或 false 时不强制覆盖文件。该参数不填，默认为false。 | 1667 1668**返回值：** 1669 1670| 类型 | 说明 | 1671| :------------------------------------------------------ | :----------------------------------------------------------- | 1672| Promise<Array<[CopyResult](#copyresult10)>> | 返回 copyresult 数组。copyResult 为复制操作失败的返回信息；复制成功无返回信息。 | 1673 1674**示例 1：force 为空** 1675 1676```ts 1677import { BusinessError } from '@ohos.base'; 1678// 以内置存储目录为例 1679// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 1680// 开发者应根据自己实际获取的uri进行开发 1681async function copyFunc01() { 1682 let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1683 let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1684 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1685 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1686 try { 1687 if (fileAccessHelper != undefined) { 1688 let copyResult = await fileAccessHelper.copy(sourceFile, destFile); 1689 if (copyResult.length === 0) { 1690 console.log("copy success"); 1691 } else { 1692 for (let i = 0; i < copyResult.length; i++) { 1693 console.error("errCode" + copyResult[i].errCode); 1694 console.error("errMsg" + copyResult[i].errMsg); 1695 console.error("sourceUri" + copyResult[i].sourceUri); 1696 console.error("destUri" + copyResult[i].destUri); 1697 } 1698 } 1699 } 1700 } catch (err) { 1701 let error: BusinessError = err as BusinessError; 1702 console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); 1703 } 1704} 1705``` 1706 1707**示例 2：force 为 true** 1708 1709```ts 1710import { BusinessError } from '@ohos.base'; 1711// 以内置存储目录为例 1712// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 1713// 开发者应根据自己实际获取的uri进行开发 1714async function copyFunc02() { 1715 let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1716 let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1717 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1718 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1719 try { 1720 if (fileAccessHelper != undefined) { 1721 let copyResult = await fileAccessHelper.copy(sourceFile, destFile, true); 1722 if (copyResult.length === 0) { 1723 console.log("copy success"); 1724 } else { 1725 for (let i = 0; i < copyResult.length; i++) { 1726 console.error("errCode" + copyResult[i].errCode); 1727 console.error("errMsg" + copyResult[i].errMsg); 1728 console.error("sourceUri" + copyResult[i].sourceUri); 1729 console.error("destUri" + copyResult[i].destUri); 1730 } 1731 } 1732 } 1733 } catch (err) { 1734 let error: BusinessError = err as BusinessError; 1735 console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); 1736 } 1737} 1738``` 1739 1740### copy<sup>10+</sup> 1741 1742copy(sourceUri: string, destUri: string, callback: AsyncCallback<Array<CopyResult>>) : void 1743 1744复制文件或目录，使用 callback 异步回调。 1745 1746**系统能力**：SystemCapability.FileManagement.UserFileService 1747 1748**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1749 1750**参数：** 1751 1752| 参数名 | 类型 | 必填 | 说明 | 1753| --------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 1754| sourceUri | string | 是 | 待拷贝的源文件(夹)的 uri。例如：file://docs/storage/Users/currentUser/Download/1.txt。 | 1755| destUri | string | 是 | 目标文件夹的 uri。例如：file://docs/storage/Users/currentUser/Download/test。 | 1756| callback | AsyncCallback<Array<[CopyResult](#copyresult10)>> | 是 | 返回 copyresult 数组。copyResult 为复制操作失败的返回信息；复制成功无返回信息。 | 1757 1758**示例：** 1759 1760```ts 1761import { BusinessError } from '@ohos.base'; 1762// 以内置存储目录为例 1763// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 1764// 开发者应根据自己实际获取的uri进行开发 1765let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1766let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1767// fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1768let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1769try { 1770 if (fileAccessHelper != undefined) { 1771 fileAccessHelper.copy(sourceFile, destFile, async (err: BusinessError, copyResult: Array<fileAccess.CopyResult>) => { 1772 if (err) { 1773 console.error("copy failed, errCode:" + err.code + ", errMessage:" + err.message); 1774 } 1775 if (copyResult.length === 0) { 1776 console.log("copy success"); 1777 } else { 1778 for (let i = 0; i < copyResult.length; i++) { 1779 console.error("errCode" + copyResult[i].errCode); 1780 console.error("errMsg" + copyResult[i].errMsg); 1781 console.error("sourceUri" + copyResult[i].sourceUri); 1782 console.error("destUri" + copyResult[i].destUri); 1783 } 1784 } 1785 }); 1786 } 1787} catch (err) { 1788 let error: BusinessError = err as BusinessError; 1789 console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); 1790} 1791``` 1792 1793### copy<sup>10+</sup> 1794 1795copy(sourceUri: string, destUri: string, force: boolean, callback: AsyncCallback<Array<CopyResult>>) : void 1796 1797复制文件或目录，使用 callback 异步回调。 1798 1799**系统能力**：SystemCapability.FileManagement.UserFileService 1800 1801**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1802 1803**参数：** 1804 1805| 参数名 | 类型 | 必填 | 说明 | 1806| --------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 1807| sourceUri | string | 是 | 待拷贝的源文件(夹)的 uri。例如：file://docs/storage/Users/currentUser/Download/1.txt。 | 1808| destUri | string | 是 | 目标文件夹的 uri。例如：file://docs/storage/Users/currentUser/Download/test。 | 1809| force | boolean | 是 | 含有同名文件时是否强制覆盖文件。force 为 true 时强制覆盖文件；force 为空或 false 时不强制覆盖文件。 | 1810| callback | AsyncCallback<Array<[CopyResult](#copyresult10)>> | 是 | 返回 copyresult 数组。copyResult 为复制操作失败的返回信息；复制成功无返回信息。 | 1811 1812**示例：** 1813 1814```ts 1815import { BusinessError } from '@ohos.base'; 1816// 以内置存储目录为例 1817// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 1818// 开发者应根据自己实际获取的uri进行开发 1819let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1820let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1821// fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1822let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1823try { 1824 if (fileAccessHelper != undefined) { 1825 fileAccessHelper.copy(sourceFile, destFile, true, async (err: BusinessError, copyResult: Array<fileAccess.CopyResult>) => { 1826 if (err) { 1827 console.error("copy failed, errCode:" + err.code + ", errMessage:" + err.message); 1828 } 1829 if (copyResult.length === 0) { 1830 console.log("copy success"); 1831 } else { 1832 for (let i = 0; i < copyResult.length; i++) { 1833 console.error("errCode" + copyResult[i].errCode); 1834 console.error("errMsg" + copyResult[i].errMsg); 1835 console.error("sourceUri" + copyResult[i].sourceUri); 1836 console.error("destUri" + copyResult[i].destUri); 1837 } 1838 } 1839 }); 1840 } 1841} catch (err) { 1842 let error: BusinessError = err as BusinessError; 1843 console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); 1844} 1845``` 1846 1847### copyFile<sup>11+</sup> 1848 1849copyFile(sourceUri: string, destUri: string, fileName: string): Promise<string> 1850 1851复制文件并传入备用文件名，使用Promise异步回调。 1852 1853**模型约束**：此接口仅可在Stage模型下使用。 1854 1855**系统能力**：SystemCapability.FileManagement.UserFileService 1856 1857**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1858 1859**参数：** 1860 1861| 参数名 | 类型 | 必填 | 说明 | 1862| --------- | ------- | ---- | ------------------------------------------------------------ | 1863| sourceUri | string | 是 | 待拷贝的源文件(夹)的 uri。例如：file://docs/storage/Users/currentUser/Download/1.txt。 | 1864| destUri | string | 是 | 目标文件夹的 uri。例如：file://docs/storage/Users/currentUser/Download/test。 | 1865| fileName | string | 是 | 如果目标目录中有1.txt文件，就是用fileName 作为文件名进行复制。 | 1866 1867**返回值：** 1868 1869| 类型 | 说明 | 1870| :------------------------------------------------------ | :----------------------------------------------------------- | 1871| Promise<string> | 返回一个复制成功的文件的uri。 | 1872 1873**示例 1** 1874 1875```ts 1876import { BusinessError } from '@ohos.base'; 1877// 以内置存储目录为例 1878// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 1879// 开发者应根据自己实际获取的uri进行开发 1880async function copyFunc01() { 1881 let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1882 let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1883 let fileName: string = "2.txt"; 1884 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1885 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1886 try { 1887 if (fileAccessHelper != undefined) { 1888 let copyResult = await fileAccessHelper.copyFile(sourceFile, destFile, fileName); 1889 console.log("copyResult uri: " + copyResult); 1890 } 1891 } catch (err) { 1892 let error: BusinessError = err as BusinessError; 1893 console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); 1894 } 1895} 1896``` 1897 1898### copyFile<sup>11+</sup> 1899 1900copyFile(sourceUri: string, destUri: string, fileName: string, callback: AsyncCallback<string>) : void 1901 1902复制文件并传入备用文件名，使用callback异步回调。 1903 1904**模型约束**：此接口仅可在Stage模型下使用。 1905 1906**系统能力**：SystemCapability.FileManagement.UserFileService 1907 1908**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1909 1910**参数：** 1911 1912| 参数名 | 类型 | 必填 | 说明 | 1913| --------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 1914| sourceUri | string | 是 | 待拷贝的源文件(夹)的 uri。例如：file://docs/storage/Users/currentUser/Download/1.txt。 | 1915| destUri | string | 是 | 目标文件夹的 uri。例如：file://docs/storage/Users/currentUser/Download/test。 | 1916| fileName | string | 是 | 如果目标目录中有1.txt文件。就是用fileName 作为文件名进行复制。 | 1917| callback | AsyncCallback<string> | 是 | 返回一个复制成功的文件的uri。 | 1918 1919**示例：** 1920 1921```ts 1922import { BusinessError } from '@ohos.base'; 1923// 以内置存储目录为例 1924// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 1925// 开发者应根据自己实际获取的uri进行开发 1926let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 1927let destFile: string = "file://docs/storage/Users/currentUser/Download/test"; 1928let fileName: string = "2.txt"; 1929// fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1930let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1931try { 1932 if (fileAccessHelper != undefined) { 1933 fileAccessHelper.copyFile(sourceFile, destFile, fileName, async (copyResult: string) => { 1934 console.log("copyResult uri: " + copyResult); 1935 }); 1936 } 1937} catch (err) { 1938 let error: BusinessError = err as BusinessError; 1939 console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); 1940} 1941``` 1942 1943### registerObserver<sup>10+</sup> 1944 1945registerObserver(uri: string, notifyForDescendants: boolean, callback: Callback<NotifyMessage>): void 1946 1947注册指定uri的callback。uri与callback可以为多对多的关系，推荐使用一个callback监听一个uri。 1948 1949**系统能力**：SystemCapability.FileManagement.UserFileService 1950 1951**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 1952 1953**参数：** 1954 1955| 参数名 | 类型 | 必填 | 说明 | 1956| -------------------- | ------------------------------------------------- | ---- | ------------------------------ | 1957| uri | string | 是 | 文件或目录的uri。 | 1958| notifyForDescendants | boolean | 是 | 监听目录时，是否监听子文件变化。true为监听；false为不监听。 | 1959| callback | Callback<[NotifyMessage](#notifymessage10)> | 是 | 返回通知信息。 | 1960 1961**示例1：注册一个callback对一个uri的监听** 1962 1963```ts 1964import { BusinessError } from '@ohos.base'; 1965async function registerObserver01() { 1966 let DirUri: string = 'file://docs/storage/Users/currentUser/Documents'; 1967 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 1968 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 1969 try { 1970 if (fileAccessHelper != undefined) { 1971 let dirUri1 = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR1'); 1972 let dirUri2 = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR2'); 1973 // 因注册时notifyForDescendants参数为true所以期待收到两次通知 1974 // uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE'，事件类型为NOTIFY_MOVED_FROM 1975 // uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE'，事件类型为NOTIFY_MOVE_SELF 1976 const callbackDir1 = (NotifyMessageDir: fileAccess.NotifyMessage) => { 1977 if (NotifyMessageDir != undefined) { 1978 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 1979 } else { 1980 console.error("NotifyMessageDir is undefined"); 1981 } 1982 } 1983 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR2/SUB_FILE'，事件类型为NOTIFY_MOVED_TO 1984 const callbackDir2 = (NotifyMessageDir: fileAccess.NotifyMessage) => { 1985 if (NotifyMessageDir != undefined) { 1986 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 1987 } else { 1988 console.error("NotifyMessageDir is undefined"); 1989 } 1990 } 1991 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE'，事件类型为NOTIFY_MOVE_SELF 1992 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE'，事件类型为NOTIFY_MOVED_FROM 1993 const callbackFile = (NotifyMessageDir: fileAccess.NotifyMessage) => { 1994 if (NotifyMessageDir != undefined) { 1995 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 1996 } else { 1997 console.error("NotifyMessageDir is undefined"); 1998 } 1999 } 2000 let fileUri = await fileAccessHelper.createFile(dirUri1, 'SUB_FILE'); 2001 fileAccessHelper.registerObserver(dirUri1, true, callbackDir1); 2002 fileAccessHelper.registerObserver(dirUri2, true, callbackDir2); 2003 // 如果不监听被移动文件本身，将不会触发NOTIFY_MOVE_SELF事件 2004 fileAccessHelper.registerObserver(fileUri, true, callbackFile); 2005 let moveFileUri = await fileAccessHelper.move(fileUri, dirUri2); 2006 // 注册完不应立即解注册，可能存在解注册先于通知返回的情景，这将收不到通知事件 2007 fileAccessHelper.unregisterObserver(dirUri1, callbackDir1); 2008 fileAccessHelper.unregisterObserver(dirUri2, callbackDir2); 2009 fileAccessHelper.unregisterObserver(fileUri, callbackFile); 2010 } 2011 } catch (err) { 2012 let error: BusinessError = err as BusinessError; 2013 console.error("registerObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2014 } 2015} 2016``` 2017 2018**示例2：使用相同uri、notifyForDescendants、callback重复注册** 2019 2020```ts 2021import { BusinessError } from '@ohos.base'; 2022async function registerObserver02() { 2023 let DirUri: string = 'file://docs/storage/Users/currentUser/Documents'; 2024 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2025 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2026 try { 2027 if (fileAccessHelper != undefined) { 2028 let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR'); 2029 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/SUB_DIR'，事件类型为NOTIFY_ADD 2030 const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2031 if (NotifyMessageDir != undefined) { 2032 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2033 } else { 2034 console.error("NotifyMessageDir is undefined"); 2035 } 2036 } 2037 fileAccessHelper.registerObserver(dirUri, true, callbackDir); 2038 // 返回注册成功，仅在log中提示重复注册 2039 fileAccessHelper.registerObserver(dirUri, true, callbackDir); 2040 let subDirUri = await fileAccessHelper.mkDir(dirUri, 'SUB_DIR'); 2041 // 注册完不应立即解注册，可能存在解注册先于通知返回的情景，这将收不到通知事件 2042 fileAccessHelper.unregisterObserver(dirUri, callbackDir); 2043 } 2044 } catch (err) { 2045 let error: BusinessError = err as BusinessError; 2046 console.error("registerObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2047 } 2048} 2049``` 2050 2051**示例3：使用相同uri、callback及不同notifyForDescendants重复注册会重置notifyForDescendants** 2052 2053```ts 2054import { BusinessError } from '@ohos.base'; 2055async function registerObserver03() { 2056 let DirUri: string = 'file://docs/storage/Users/currentUser/Documents'; 2057 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2058 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2059 try { 2060 if (fileAccessHelper != undefined) { 2061 let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR'); 2062 // 期待第一次收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/SUB_FILE_1'，事件类型为NOTIFY_ADD 2063 // 期待无第二次返回 2064 const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2065 if (NotifyMessageDir != undefined) { 2066 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2067 } else { 2068 console.error("NotifyMessageDir is undefined"); 2069 } 2070 } 2071 fileAccessHelper.registerObserver(dirUri, true, callbackDir); 2072 let subFile1 = await fileAccessHelper.createFile(dirUri, 'SUB_FILE_1'); 2073 // 注册成功修改notifyForDescendants为false,不感知子文件的变化 2074 fileAccessHelper.registerObserver(dirUri, false, callbackDir); 2075 let subFile2 = await fileAccessHelper.createFile(dirUri, 'SUB_FILE_2'); 2076 // 注册完不应立即解注册，可能存在解注册先于通知返回的情景，这将收不到通知事件 2077 fileAccessHelper.unregisterObserver(dirUri, callbackDir); 2078 } 2079 } catch (err) { 2080 let error: BusinessError = err as BusinessError; 2081 console.error("registerObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2082 } 2083} 2084``` 2085 2086**示例4：注册监听设备上下线** 2087 2088```ts 2089import { BusinessError } from '@ohos.base'; 2090async function UnregisterObserver03() { 2091 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2092 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2093 try { 2094 const callbackDir1 = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2095 if (NotifyMessageDir != undefined) { 2096 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2097 } else { 2098 console.error("NotifyMessageDir is undefined"); 2099 } 2100 } 2101 if (fileAccessHelper != undefined) { 2102 // 监听设备的上下线 2103 fileAccessHelper.registerObserver(fileAccess.DEVICES_URI, true, callbackDir1); 2104 // 取消监听设备的上下线 2105 fileAccessHelper.unregisterObserver(fileAccess.DEVICES_URI); 2106 } 2107 } catch (err) { 2108 let error: BusinessError = err as BusinessError; 2109 console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2110 } 2111} 2112``` 2113 2114### unregisterObserver<sup>10+</sup> 2115 2116 unregisterObserver(uri: string, callback?: Callback<NotifyMessage>): void 2117 2118取消注册指定的uri和callback。 2119 2120**系统能力**：SystemCapability.FileManagement.UserFileService 2121 2122**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2123 2124**参数：** 2125 2126| 参数名 | 类型 | 必填 | 说明 | 2127| -------- | ------------------------------------------------- | ---- | ------------------------- | 2128| uri | string | 是 | 文件或目录的uri。 | 2129| callback | Callback<[NotifyMessage](#notifymessage10)> | 否 | 解注册uri下对应的callback。如果该参数不填，则解注册对应的所有callbackback。 | 2130 2131**示例1: 解注册监听uri的一个callback** 2132 2133```ts 2134import { BusinessError } from '@ohos.base'; 2135async function UnregisterObserver01() { 2136 let DirUri: string = 'file://docs/storage/Users/currentUser/Documents'; 2137 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2138 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2139 try { 2140 if (fileAccessHelper != undefined) { 2141 let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR'); 2142 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR'，事件类型为NOTIFY_DELETE 2143 const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2144 if (NotifyMessageDir != undefined) { 2145 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2146 } else { 2147 console.error("NotifyMessageDir is undefined"); 2148 } 2149 } 2150 fileAccessHelper.registerObserver(dirUri, true, callbackDir); 2151 await fileAccessHelper.delete(dirUri); 2152 // 注册完不应立即解注册，可能存在解注册先于通知返回的情景，这将收不到通知事件 2153 fileAccessHelper.unregisterObserver(dirUri, callbackDir); 2154 } 2155 } catch (err) { 2156 let error: BusinessError = err as BusinessError; 2157 console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2158 } 2159} 2160``` 2161 2162**示例2：对监听uri的某一callback重复解注册** 2163 2164```ts 2165import { BusinessError } from '@ohos.base'; 2166async function UnregisterObserver02() { 2167 let DirUri: string = 'file://docs/storage/Users/currentUser/Documents'; 2168 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2169 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2170 try { 2171 if (fileAccessHelper != undefined) { 2172 let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR'); 2173 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR'，事件类型为NOTIFY_DELETE 2174 const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2175 if (NotifyMessageDir != undefined) { 2176 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2177 } else { 2178 console.error("NotifyMessageDir is undefined"); 2179 } 2180 } 2181 fileAccessHelper.registerObserver(dirUri, true, callbackDir); 2182 await fileAccessHelper.delete(dirUri); 2183 // 注册完不应立即解注册，可能存在解注册先于通知返回的情景，这将收不到通知事件 2184 fileAccessHelper.unregisterObserver(dirUri, callbackDir); 2185 // 解注册失败，抛出错误码 E_CAN_NOT_FIND_URI 2186 fileAccessHelper.unregisterObserver(dirUri, callbackDir); 2187 } 2188 } catch (err) { 2189 let error: BusinessError = err as BusinessError; 2190 console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2191 } 2192} 2193``` 2194 2195**示例3：解注册监听uri的所有callback** 2196 2197```ts 2198import { BusinessError } from '@ohos.base'; 2199async function UnregisterObserver03() { 2200 let DirUri: string = 'file://docs/storage/Users/currentUser/Documents'; 2201 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2202 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2203 try { 2204 if (fileAccessHelper != undefined) { 2205 let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR'); 2206 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/SUB_FILE'，事件类型为NOTIFY_MOVED_FROM 2207 // 期待收到uri为'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/RENAME_FILE'，事件类型为NOTIFY_MOVED_TO 2208 const callbackDir1 = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2209 if (NotifyMessageDir != undefined) { 2210 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2211 } else { 2212 console.error("NotifyMessageDir is undefined"); 2213 } 2214 } 2215 // 期待收不到任何事件 2216 const callbackDir2 = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2217 if (NotifyMessageDir != undefined) { 2218 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2219 } else { 2220 console.error("NotifyMessageDir is undefined"); 2221 } 2222 } 2223 let fileUri = await fileAccessHelper.createFile(dirUri, 'SUB_FILE'); 2224 fileAccessHelper.registerObserver(dirUri, true, callbackDir1); 2225 // 此处注册为不关注下一级，将收不到关于下一级的事件 2226 fileAccessHelper.registerObserver(dirUri, false, callbackDir2); 2227 let renameUri = await fileAccessHelper.rename(fileUri, 'RENAME_FILE'); 2228 // 取消注册监听dirUri的所有callback(callbackDir1、callbackDir2) 2229 // 注册完不应立即解注册，可能存在解注册先于通知返回的情景，这将收不到通知事件 2230 fileAccessHelper.unregisterObserver(dirUri); 2231 await fileAccessHelper.delete(dirUri); 2232 } 2233 } catch (err) { 2234 let error: BusinessError = err as BusinessError; 2235 console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2236 } 2237} 2238``` 2239 2240**示例4：解注册监听设备的上下线** 2241 2242```ts 2243import { BusinessError } from '@ohos.base'; 2244async function UnregisterObserver03() { 2245 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2246 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2247 try { 2248 const callbackDir1 = (NotifyMessageDir: fileAccess.NotifyMessage) => { 2249 if (NotifyMessageDir != undefined) { 2250 console.log('NotifyType: ' + NotifyMessageDir.type + 'NotifyUri:' + NotifyMessageDir.uris[0]); 2251 } else { 2252 console.error("NotifyMessageDir is undefined"); 2253 } 2254 } 2255 if (fileAccessHelper != undefined) { 2256 // 监听设备的上下线 2257 fileAccessHelper.registerObserver(fileAccess.DEVICES_URI, true, callbackDir1); 2258 // 取消监听设备的上下线 2259 fileAccessHelper.unregisterObserver(fileAccess.DEVICES_URI); 2260 } 2261 } catch (err) { 2262 let error: BusinessError = err as BusinessError; 2263 console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message); 2264 } 2265} 2266``` 2267 2268### moveItem<sup>11+</sup> 2269 2270moveItem(sourceUri: string, destUri: string, force?: boolean) : Promise<Array<MoveResult>> 2271 2272以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用Promise异步回调。 2273 2274当存在同名文件时，可以选择强制覆盖文件。 2275 2276目前仅支持设备内移动，跨设备不支持移动。 2277 2278**模型约束**：此接口仅可在Stage模型下使用。 2279 2280**系统能力**：SystemCapability.FileManagement.UserFileService 2281 2282**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2283 2284**参数：** 2285 2286| 参数名 | 类型 | 必填 | 说明 | 2287| --------- | ------- | ---- | ------------------------------------------------------------ | 2288| sourceUri | string | 是 | 待移动的源文件(夹)的uri。 | 2289| destUri | string | 是 | 目标文件夹的uri。 | 2290| force | boolean | 否 | 选择当存在同名文件时，是否强制覆盖文件。当force为true时，强制覆盖文件；为false时不强制覆盖文件。该参数不填，默认为false。 | 2291 2292**返回值：** 2293 2294| 类型 | 说明 | 2295| ------------------------------------------------------- | ------------------------------------------------------------ | 2296| Promise<Array<[MoveResult](#moveresult11)>> | 返回 moveresult 数组。moveResult 为移动操作失败的返回信息；复制成功无返回信息。 | 2297 2298**错误码：** 2299 2300接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 2301 2302**示例 1：force 为空** 2303 2304```ts 2305import { BusinessError } from '@ohos.base'; 2306// 以内置存储目录为例 2307// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 2308// 开发者应根据自己实际获取的uri进行开发 2309async function moveItemFunc01() { 2310 let sourceUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 2311 let destUri: string = "file://docs/storage/Users/currentUser/Download/test"; 2312 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2313 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2314 try { 2315 if (fileAccessHelper != undefined) { 2316 let moveResult = await fileAccessHelper.moveItem(sourceUri, destUri); 2317 if (moveResult.length === 0) { 2318 console.log("moveItem success"); 2319 } else { 2320 for (let i = 0; i < moveResult.length; i++) { 2321 console.error("errCode" + moveResult[i].errCode); 2322 console.error("errMsg" + moveResult[i].errMsg); 2323 console.error("sourceUri" + moveResult[i].sourceUri); 2324 console.error("destUri" + moveResult[i].destUri); 2325 } 2326 } 2327 } 2328 } catch (err) { 2329 let error: BusinessError = err as BusinessError; 2330 console.error("moveItem failed, errCode:" + error.code + ", errMessage:" + error.message); 2331 } 2332} 2333``` 2334 2335**示例 2：force 为 true** 2336 2337```ts 2338import { BusinessError } from '@ohos.base'; 2339// 以内置存储目录为例 2340// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 2341// 开发者应根据自己实际获取的uri进行开发 2342async function moveItemFunc02() { 2343 let sourceUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 2344 let destUri: string = "file://docs/storage/Users/currentUser/Download/test"; 2345 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2346 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2347 try { 2348 if (fileAccessHelper != undefined) { 2349 let moveResult = await fileAccessHelper.moveItem(sourceUri, destUri, true); 2350 if (moveResult.length === 0) { 2351 console.log("moveItem success"); 2352 } else { 2353 for (let i = 0; i < moveResult.length; i++) { 2354 console.error("errCode" + moveResult[i].errCode); 2355 console.error("errMsg" + moveResult[i].errMsg); 2356 console.error("sourceUri" + moveResult[i].sourceUri); 2357 console.error("destUri" + moveResult[i].destUri); 2358 } 2359 } 2360 } 2361 } catch (err) { 2362 let error: BusinessError = err as BusinessError; 2363 console.error("moveItem failed, errCode:" + error.code + ", errMessage:" + error.message); 2364 } 2365} 2366``` 2367 2368### moveItem<sup>11+</sup> 2369 2370moveItem(sourceUri: string, destUri: string, callback: AsyncCallback<Array<MoveResult>>) : void 2371 2372以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用callback异步回调。 2373 2374当前仅支持设备内移动，不支持跨设备移动。 2375 2376**模型约束**：此接口仅可在Stage模型下使用。 2377 2378**系统能力**：SystemCapability.FileManagement.UserFileService 2379 2380**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2381 2382**参数：** 2383 2384| 参数名 | 类型 | 必填 | 说明 | 2385| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2386| sourceUri | string | 是 | 待移动的源文件(夹)的uri。 | 2387| destUri | string | 是 | 目标文件夹的uri。 | 2388| callback | AsyncCallback<Array<[MoveResult](#moveresult11)>> | 是 | 回调返回MoveResult数组。MoveResult为移动操作失败的返回信息；移动成功无返回信息。 | 2389 2390**示例：** 2391 2392```ts 2393import { BusinessError } from '@ohos.base'; 2394// 以内置存储目录为例 2395// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 2396// 开发者应根据自己实际获取的uri进行开发 2397let sourceUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 2398let destUri: string = "file://docs/storage/Users/currentUser/Download/test"; 2399// fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2400let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2401try { 2402 if (fileAccessHelper != undefined) { 2403 fileAccessHelper.moveItem(sourceUri, destUri, async (err: BusinessError, moveResult: Array<fileAccess.MoveResult>) => { 2404 if (err) { 2405 console.error("moveItem failed, errCode:" + err.code + ", errMessage:" + err.message); 2406 } 2407 if (moveResult.length === 0) { 2408 console.log("moveItem success"); 2409 } else { 2410 for (let i = 0; i < moveResult.length; i++) { 2411 console.error("errCode" + moveResult[i].errCode); 2412 console.error("errMsg" + moveResult[i].errMsg); 2413 console.error("sourceUri" + moveResult[i].sourceUri); 2414 console.error("destUri" + moveResult[i].destUri); 2415 } 2416 } 2417 }); 2418 } 2419} catch (err) { 2420 let error: BusinessError = err as BusinessError; 2421 console.error("moveItem failed, errCode:" + error.code + ", errMessage:" + error.message); 2422} 2423``` 2424 2425### moveItem<sup>11+</sup> 2426 2427moveItem(sourceUri: string, destUri: string, force: boolean, callback: AsyncCallback<Array<MoveResult>>) : void 2428 2429以异步方法移动文件(夹)，返回移动后文件(夹)的uri。使用callback异步回调。 2430 2431当存在同名文件时，可以选择强制覆盖文件。 2432 2433当前仅支持设备内移动，不支持跨设备移动。 2434 2435**模型约束**：此接口仅可在Stage模型下使用。 2436 2437**系统能力**：SystemCapability.FileManagement.UserFileService 2438 2439**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2440 2441**参数：** 2442 2443| 参数名 | 类型 | 必填 | 说明 | 2444| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2445| sourceUri | string | 是 | 待移动的源文件(夹)的uri。 | 2446| destUri | string | 是 | 目标文件夹的uri。 | 2447| force | boolean | 是 | 选择当存在同名文件时，是否强制覆盖文件。当force为true时，强制覆盖文件；为false时不强制覆盖文件。该参数不填，默认为false。 | 2448| callback | AsyncCallback<Array<[MoveResult](#moveresult11)>> | 是 | 回调返回MoveResult数组。MoveResult为移动操作失败的返回信息；移动成功无返回信息。 | 2449 2450**示例：** 2451 2452```ts 2453import { BusinessError } from '@ohos.base'; 2454// 以内置存储目录为例 2455// 示例代码中的sourceFile表示Download目录下的源文件(夹)，destFile表示Download目录下的目标文件夹，该uri对应fileInfo中的uri 2456// 开发者应根据自己实际获取的uri进行开发 2457let sourceUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 2458let destUri: string = "file://docs/storage/Users/currentUser/Download/test"; 2459// fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2460let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2461try { 2462 if (fileAccessHelper != undefined) { 2463 fileAccessHelper.moveItem(sourceUri, destUri, true, async (err: BusinessError, moveResult: Array<fileAccess.MoveResult>) => { 2464 if (err) { 2465 console.error("moveItem failed, errCode:" + err.code + ", errMessage:" + err.message); 2466 } 2467 if (moveResult.length === 0) { 2468 console.log("moveItem success"); 2469 } else { 2470 for (let i = 0; i < moveResult.length; i++) { 2471 console.error("errCode" + moveResult[i].errCode); 2472 console.error("errMsg" + moveResult[i].errMsg); 2473 console.error("sourceUri" + moveResult[i].sourceUri); 2474 console.error("destUri" + moveResult[i].destUri); 2475 } 2476 } 2477 }); 2478 } 2479} catch (err) { 2480 let error: BusinessError = err as BusinessError; 2481 console.error("moveItem failed, errCode:" + error.code + ", errMessage:" + error.message); 2482} 2483``` 2484 2485### moveFile<sup>11+</sup> 2486 2487moveFile(sourceUri: string, destUri: string, fileName: string) : Promise<string> 2488 2489以异步方法移动文件，返回移动后文件的uri。使用Promise异步回调。 2490 2491当存在同名文件时（即发生文件移动冲突时），可以重命名待移动的文件，再保存到目标文件夹。 2492 2493目前仅支持设备内移动，跨设备不支持移动。 2494 2495**模型约束**：此接口仅可在Stage模型下使用。 2496 2497**系统能力**：SystemCapability.FileManagement.UserFileService 2498 2499**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2500 2501**参数：** 2502 2503| 参数名 | 类型 | 必填 | 说明 | 2504| ---------- | ------ | ---- | ------------------- | 2505| sourceFile | string | 是 | 待移动源文件的uri。 | 2506| destFile | string | 是 | 目标文件夹的uri。 | 2507| fileName | string | 是 | 冲突文件的新名称。 | 2508 2509**返回值：** 2510 2511| 类型 | 说明 | 2512| --------------------- | ------------------- | 2513| Promise<string> | 新路径下的文件uri。 | 2514 2515**错误码：** 2516 2517接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 2518 2519**示例：** 2520 2521 ```ts 2522 import { BusinessError } from '@ohos.base'; 2523 async function moveFile01() { 2524 // 以内置存储目录为例 2525 // 示例代码sourceUri destUri表示Download目录下文件和文件夹，该uri是对应的fileInfo中uri 2526 // 开发者应根据自己实际获取的uri进行开发 2527 let sourceUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 2528 let destUri: string = "file://docs/storage/Users/currentUser/Download/test"; 2529 let fileName: string = "2.txt"; 2530 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2531 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2532 try { 2533 if (fileAccessHelper != undefined) { 2534 let fileUri = await fileAccessHelper.moveFile(sourceUri, destUri, fileName); 2535 console.log("moveFile success, fileUri: " + JSON.stringify(fileUri)); 2536 } 2537 } catch (err) { 2538 let error: BusinessError = err as BusinessError; 2539 console.error("moveFile failed, errCode:" + error.code + ", errMessage:" + error.message); 2540 } 2541 } 2542 ``` 2543 2544### moveFile<sup>11+</sup> 2545 2546moveFile(sourceUri: string, destUri: string, fileName: string, callback: AsyncCallback<string>) : void 2547 2548以异步方法移动文件，返回移动后文件的uri。使用callback异步回调。 2549 2550当存在同名文件时（即发生文件移动冲突时），可以重命名待移动的文件，再保存到目标文件夹。 2551 2552当前仅支持设备内移动，不支持跨设备移动。 2553 2554**模型约束**：此接口仅可在Stage模型下使用。 2555 2556**系统能力**：SystemCapability.FileManagement.UserFileService 2557 2558**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2559 2560**参数：** 2561 2562| 参数名 | 类型 | 必填 | 说明 | 2563| ---------- | --------------------------- | ---- | --------------------- | 2564| sourceFile | string | 是 | 待移动的源文件的uri。 | 2565| destFile | string | 是 | 目标文件夹的uri。 | 2566| fileName | string | 是 | 冲突文件的新名称。 | 2567| callback | AsyncCallback<string> | 是 | 新路径下的文件uri。 | 2568 2569**错误码：** 2570 2571接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 2572 2573**示例：** 2574 2575 ```ts 2576 import { BusinessError } from '@ohos.base'; 2577 // 以内置存储目录为例 2578 // 示例代码sourceUri destUri表示Download目录下文件和文件夹，该uri是对应的fileInfo中uri 2579 // 开发者应根据自己实际获取的uri进行开发 2580 let sourceUri: string = "file://docs/storage/Users/currentUser/Download/1.txt"; 2581 let destUri: string = "file://docs/storage/Users/currentUser/Download/test"; 2582 let fileName: string = "2.txt"; 2583 // fileAccessHelper 参考 fileAccess.createFileAccessHelper 示例代码获取 2584 let fileAccessHelper : fileAccess.FileAccessHelper|undefined; 2585 try { 2586 if (fileAccessHelper != undefined) { 2587 fileAccessHelper.moveFile(sourceUri, destUri, fileName, (err: BusinessError, fileUri: string) => { 2588 if (err) { 2589 console.error("Failed to moveFile in async, errCode:" + err.code + ", errMessage:" + err.message); 2590 } 2591 console.log("moveFile success, fileUri: " + JSON.stringify(fileUri)); 2592 }); 2593 } 2594 } catch (err) { 2595 let error: BusinessError = err as BusinessError; 2596 console.error("moveFile failed, errCode:" + error.code + ", errMessage:" + error.message); 2597 } 2598 ``` 2599 2600## CopyResult<sup>10+</sup> 2601 2602表示复制操作失败时的返回信息，复制成功时则没有返回信息。 2603 2604**系统能力**：SystemCapability.FileManagement.UserFileService 2605 2606**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2607 2608| 名称 | 类型 | 只读 | 可选 | 说明 | 2609| --------- | ------ | ---- | ---- | ----------------- | 2610| sourceUri | string | 否 | 否 | 源文件(夹) uri。 | 2611| destUri | string | 否 | 否 | 产生冲突的目标文件的 uri。如果非冲突导致的错误，则为空。 | 2612| errCode | number | 否 | 否 | 错误码。 | 2613| errMsg | string | 否 | 否 | 错误信息。 | 2614 2615## OPENFLAGS 2616 2617枚举，目前支持的文件打开的标志位。 2618 2619**模型约束**：此接口仅可在Stage模型下使用。 2620 2621**系统能力** ：SystemCapability.FileManagement.UserFileService 2622 2623| 名称 | 值 | 说明 | 2624| ----- | ------ | ------ | 2625| READ | 0o0 | 读模式。 | 2626| WRITE | 0o1 | 写模式。 | 2627| WRITE_READ | 0o2 | 读写模式。 | 2628 2629## FILEKEY<sup>10+</sup> 2630 2631枚举，支持查询的键。 2632 2633**模型约束**：此接口仅可在Stage模型下使用。 2634 2635**系统能力** ：SystemCapability.FileManagement.UserFileService 2636 2637| 名称 | 值 | 说明 | 2638| ------------- | ------------- | ----------------------------------- | 2639| DISPLAY_NAME | 'display_name' | 文件名。 | 2640| DATE_ADDED | 'date_added' | 文件创建的日期。例如1501925454。 | 2641| DATE_MODIFIED | 'date_modified' | 文件的修改日期。例如1665310670。 | 2642| RELATIVE_PATH | 'relative_path' | 相对路径。例如Pictures/Screenshots/。 | 2643| FILE_SIZE | 'size' | 文件（夹）大小（单位：字节）。 | 2644 2645## NotifyType<sup>10+</sup> 2646 2647枚举，通知类型。 2648 2649**模型约束**：此接口仅可在Stage模型下使用。 2650 2651**系统能力**：SystemCapability.FileManagement.UserFileService 2652 2653| 名称 | 值 | 说明 | 2654| ----------------- | ---- | ------------------------------------------------------------ | 2655| NOTIFY_ADD | 0 | 表示新增文件（详见registerObserver接口的示例2、示例3）。 | 2656| NOTIFY_DELETE | 1 | 表示删除文件（详见unregisterObserver(uri: string, callback: Callback<NotifyMessage>)接口的示例1、示例2）。 | 2657| NOTIFY_MOVED_TO | 2 | 表示移动至该文件（对目录下子文件或目录执行rename操作，或外部文件或目录执行move操作到本文件。详见registerObserver接口的示例1，及unregisterObserver(uri: string)接口的示例1）。| 2658| NOTIFY_MOVED_FROM | 3 | 表示自该文件移出（对目录下子文件或目录执行rename操作，或子文件（夹）执行move操作从该文件夹内移出。详见registerObserver接口的示例1，及unregisterObserver(uri: string)接口的示例1）。 | 2659| NOTIFY_MOVE_SELF | 4 | 表示本文件被移动（如对文件或文件夹执行rename或move操作时，监听该文件（夹）的callback收到该事件，详见registerObserver接口的示例1）。 | 2660| NOTIFY_DEVICE_ONLINE<sup>11+</sup> | 5 | 表示设备上线。 | 2661| NOTIFY_DEVICE_OFFLINE<sup>11+</sup> | 6 | 表示设备下线。 | 2662 2663## NotifyMessage<sup>10+</sup> 2664 2665通知回调函数的值。 2666 2667**模型约束**：此接口仅可在Stage模型下使用。 2668 2669**系统能力**：SystemCapability.FileManagement.UserFileService 2670 2671**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2672 2673| 名称 | 类型 | 只读 | 可选 | 说明 | 2674| ---- | --------------------------- | ---- | ---- | --------------------------------------------------------- | 2675| type | [NotifyType](#notifytype10) | 否 | 否 | 变更的通知类型。 | 2676| uris | Array<string> | 否 | 否 | 所变更文件的uri集合，目前仅支持单条通知，后序支持多条通知。 | 2677 2678## MoveResult<sup>11+</sup> 2679 2680表示移动操作失败时的返回信息，移动成功时则没有返回信息。 2681 2682**模型约束**：此接口仅可在Stage模型下使用。 2683 2684**系统能力**：SystemCapability.FileManagement.UserFileService 2685 2686**需要权限**：ohos.permission.FILE_ACCESS_MANAGER 2687 2688| 名称 | 类型 | 只读 | 可选 | 说明 | 2689| --------- | ------ | ---- | ---- | ------------------------------------------------------------ | 2690| sourceUri | string | 否 | 否 | 源文件(夹) uri。 | 2691| destUri | string | 否 | 否 | 产生冲突的目标文件的 uri。如果非冲突导致的错误，则为空。 | 2692| errCode | number | 否 | 否 | 错误码。接口抛出错误码的详细介绍请参见[文件管理错误码](errorcode-filemanagement.md)。 | 2693| errMsg | string | 否 | 否 | 错误信息。 | 2694
