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