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