1# @system.file (文件存储) 2 3>  **说明：** 4> - 从API Version 6开始，该接口不再维护，推荐使用新接口[`@ohos.fileio`](js-apis-fileio.md)。 5> 6> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8 9## 导入模块 10 11 12``` 13import file from '@system.file'; 14``` 15 16 17## file.move 18 19move(Object): void 20 21将指定文件移动到其他指定位置。 22 23**系统能力：** SystemCapability.FileManagement.File.FileIO 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| -------- | -------- | -------- | -------- | 29| srcUri | string | 是 | 要移动的文件的uri。字符串最大长度为128，且不能包含“"\*+,:;<=>?[]\|\x7F”等特殊符号。 | 30| dstUri | string | 是 | 文件要移动到的位置的uri。字符串最大长度为128，且不能包含“"\*+,:;<=>?[]\|\x7F”等特殊符号。 | 31| success | Function | 否 | 接口调用成功的回调函数，返回文件要移动到的位置的uri。 | 32| fail | Function | 否 | 接口调用失败的回调函数。 | 33| complete | Function | 否 | 接口调用结束的回调函数。 | 34 35fail返回错误代码： 36 37| 错误码 | 说明 | 38| -------- | -------- | 39| 202 | 出现参数错误。 | 40| 300 | 出现I/O错误。 | 41| 301 | 文件或目录不存在。 | 42 43**示例：** 44 45``` 46export default { 47 move() { 48 file.move({ 49 srcUri: 'internal://app/myfiles1', 50 dstUri: 'internal://app/myfiles2', 51 success: function(uri) { 52 console.log('call success callback success'); 53 }, 54 fail: function(data, code) { 55 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 56 }, 57 }); 58 } 59} 60``` 61 62 63## file.copy 64 65copy(Object): void 66 67将指定文件拷贝并存储到指定位置。 68 69**系统能力：** SystemCapability.FileManagement.File.FileIO 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| -------- | -------- | -------- | -------- | 75| srcUri | string | 是 | 要拷贝的文件的uri。 | 76| dstUri | string | 是 | 文件要拷贝到的位置的uri。<br/>不支持用应用资源路径或tmp类型的uri。 | 77| success | Function | 否 | 接口调用成功的回调函数，返回文件要拷贝到的位置的uri。 | 78| fail | Function | 否 | 接口调用失败的回调函数。 | 79| complete | Function | 否 | 接口调用结束的回调函数。 | 80 81fail返回错误代码： 82 83| 错误码 | 说明 | 84| -------- | -------- | 85| 202 | 出现参数错误。 | 86| 300 | 出现I/O错误。 | 87| 301 | 文件或目录不存在。 | 88 89**示例：** 90 91``` 92export default { 93 copy() { 94 file.copy({ 95 srcUri: 'internal://app/file.txt', 96 dstUri: 'internal://app/file_copy.txt', 97 success: function(uri) { 98 console.log('call success callback success'); 99 }, 100 fail: function(data, code) { 101 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 102 }, 103 }); 104 } 105} 106``` 107 108 109## file.list 110 111list(Object): void 112 113获取指定路径下全部文件的列表。 114 115**系统能力：** SystemCapability.FileManagement.File.FileIO 116 117**参数：** 118 119| 参数名 | 类型 | 必填 | 说明 | 120| -------- | -------- | -------- | -------- | 121| uri | string | 是 | 目录uri。字符串最大长度为128，且不能包含“"\*+,:;<=>?[]\|\x7F”等特殊符号。 | 122| success | Function | 否 | 接口调用成功的回调函数。 | 123| fail | Function | 否 | 接口调用失败的回调函数。 | 124| complete | Function | 否 | 接口调用结束的回调函数。 | 125 126success返回值： 127 128| 参数名 | 类型 | 说明 | 129| -------- | -------- | -------- | 130| fileList | Array<FileInfo> | 获取的文件列表，其中每个文件的信息的格式为：<br/>{<br/>uri:'file1',<br/>lastModifiedTime:1589965924479,<br/>length:10240,<br/>type: 'file'<br/>} | 131 132**表1** FileInfo 133 134| 参数名 | 类型 | 说明 | 135| -------- | -------- | -------- | 136| uri | string | 文件的 uri。 | 137| lastModifiedTime | number | 文件上一次保存时的时间戳，显示从1970/01/01 00:00:00 GMT到当前时间的毫秒数。 | 138| length | number | 文件的大小，单位为字节。 | 139| type | string | 文件的类型，可选值为：<br/>- dir：目录；<br/>- file：文件。 | 140 141fail返回错误代码： 142 143| 错误码 | 说明 | 144| -------- | -------- | 145| 202 | 出现参数错误。 | 146| 300 | 出现I/O错误。 | 147| 301 | 文件或目录不存在。 | 148 149**示例：** 150 151``` 152export default { 153 list() { 154 file.list({ 155 uri: 'internal://app/pic', 156 success: function(data) { 157 console.log(JSON.stringify(data.fileList)); 158 }, 159 fail: function(data, code) { 160 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 161 }, 162 }); 163 } 164} 165``` 166 167 168## file.get 169 170get(Object): void 171 172获取指定本地文件的信息。 173 174**系统能力：** SystemCapability.FileManagement.File.FileIO 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| -------- | -------- | -------- | -------- | 180| uri | string | 是 | 文件的uri。 | 181| recursive | boolean | 否 | 是否进行递归获取子目录文件列表，缺省为false。 | 182| success | Function | 否 | 接口调用成功的回调函数。 | 183| fail | Function | 否 | 接口调用失败的回调函数。 | 184| complete | Function | 否 | 接口调用结束的回调函数。 | 185 186success返回值： 187 188| 参数名 | 类型 | 说明 | 189| -------- | -------- | -------- | 190| uri | string | 文件的uri。 | 191| length | number | 文件字节长。 | 192| lastModifiedTime | number | 文件保存时的时间戳，从1970/01/01 00:00:00到当前时间的毫秒数。 | 193| type | string | 文件类型，可选值为：<br/>- dir：目录；<br/>- file：文件。 | 194| subFiles | Array | 文件列表。 | 195 196fail返回错误代码： 197 198| 错误码 | 说明 | 199| -------- | -------- | 200| 202 | 出现参数错误。 | 201| 300 | 出现I/O错误。 | 202| 301 | 文件或目录不存在。 | 203 204**示例：** 205 206``` 207export default { 208 get() { 209 file.get({ 210 uri: 'internal://app/file', 211 success: function(data) { 212 console.log(data.uri); 213 }, 214 fail: function(data, code) { 215 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 216 }, 217 }); 218 } 219} 220``` 221 222 223## file.delete 224 225delete(Object): void 226 227删除本地文件。 228 229**系统能力：** SystemCapability.FileManagement.File.FileIO 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234| -------- | -------- | -------- | -------- | 235| uri | string | 是 | 删除文件的uri，不能是应用资源路径。 | 236| success | Function | 否 | 接口调用成功的回调函数。 | 237| fail | Function | 否 | 接口调用失败的回调函数。 | 238| complete | Function | 否 | 接口调用结束的回调函数。 | 239 240fail返回错误代码： 241 242| 错误码 | 说明 | 243| -------- | -------- | 244| 202 | 参数错误。 | 245| 300 | I/O错误。 | 246| 301 | 文件或目录不存在。 | 247 248**示例：** 249 250``` 251export default { 252 delete() { 253 file.delete({ 254 uri: 'internal://app/my_file', 255 success: function() { 256 console.log('call delete success.'); 257 }, 258 fail: function(data, code) { 259 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 260 }, 261 }); 262 } 263} 264``` 265 266 267## file.writeText 268 269writeText(Object): void 270 271写文本内容到指定文件。仅支持文本文档读写。 272 273**系统能力：** SystemCapability.FileManagement.File.FileIO 274 275**参数：** 276 277| 参数名 | 类型 | 必填 | 说明 | 278| -------- | -------- | -------- | -------- | 279| uri | string | 是 | 本地文件uri，如果文件不存在会创建文件。 | 280| text | string | 是 | 写入的字符串。 | 281| encoding | string | 否 | 编码格式，默认为UTF-8。 | 282| append | boolean | 否 | 是否追加模式，默认为false。 | 283| success | Function | 否 | 接口调用成功的回调函数。 | 284| fail | Function | 否 | 接口调用失败的回调函数。 | 285| complete | Function | 否 | 接口调用结束的回调函数。 | 286 287fail返回错误代码： 288 289| 错误码 | 说明 | 290| -------- | -------- | 291| 202 | 参数错误。 | 292| 300 | I/O错误。 | 293 294**示例：** 295 296``` 297export default { 298 writeText() { 299 file.writeText({ 300 uri: 'internal://app/test.txt', 301 text: 'Text that just for test.', 302 success: function() { 303 console.log('call writeText success.'); 304 }, 305 fail: function(data, code) { 306 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 307 }, 308 }); 309 } 310} 311``` 312 313 314## file.writeArrayBuffer 315 316writeArrayBuffer(Object): void 317 318写Buffer内容到指定文件。仅支持文本文档读写。 319 320**系统能力：** SystemCapability.FileManagement.File.FileIO 321 322**参数：** 323 324| 参数名 | 类型 | 必填 | 说明 | 325| -------- | -------- | -------- | -------- | 326| uri | string | 是 | 本地文件uri，如果文件不存在会创建文件。 | 327| buffer | Uint8Array | 是 | 写入的Buffer。 | 328| position | number | 否 | 文件开始写入数据的位置的偏移量，默认为0。 | 329| append | boolean | 否 | 是否追加模式，默认为false。当设置为true时，position参数无效。 | 330| success | Function | 否 | 接口调用成功的回调函数。 | 331| fail | Function | 否 | 接口调用失败的回调函数。 | 332| complete | Function | 否 | 接口调用结束的回调函数。 | 333 334fail返回错误代码： 335 336| 错误码 | 说明 | 337| -------- | -------- | 338| 202 | 出现参数错误。 | 339| 300 | 出现I/O错误。 | 340 341**示例：** 342 343``` 344export default { 345 writeArrayBuffer() { 346 file.writeArrayBuffer({ 347 uri: 'internal://app/test', 348 buffer: new Uint8Array(8), //buffer为Uint8Array类型 349 success: function() { 350 console.log('call writeArrayBuffer success.'); 351 }, 352 fail: function(data, code) { 353 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 354 }, 355 }); 356 } 357} 358``` 359 360 361## file.readText 362 363readText(Object): void 364 365从指定文件中读取文本内容。仅支持文本文档读写。 366 367**系统能力：** SystemCapability.FileManagement.File.FileIO 368 369**参数：** 370 371| 参数名 | 类型 | 必填 | 说明 | 372| -------- | -------- | -------- | -------- | 373| uri | string | 是 | 本地文件uri。 | 374| encoding | string | 否 | 编码格式，缺省为UTF-8。 | 375| position | number | 否 | 读取的起始位置，默认值为文件的起始位置。 | 376| length | number | 否 | 读取的长度，默认值为4096。 | 377| success | Function | 否 | 接口调用成功的回调函数。 | 378| fail | Function | 否 | 接口调用失败的回调函数。 | 379| complete | Function | 否 | 接口调用结束的回调函数。 | 380 381success返回值： 382 383| 参数名 | 类型 | 说明 | 384| -------- | -------- | -------- | 385| text | string | 读取到的文本内容。 | 386 387fail返回错误代码： 388 389| 错误码 | 说明 | 390| -------- | -------- | 391| 202 | 出现参数错误。 | 392| 300 | 出现I/O错误。 | 393| 301 | 文件或目录不存在。 | 394| 302 | 要读取的文件内容超过4KB。 | 395 396**示例：** 397 398``` 399export default { 400 readText() { 401 file.readText({ 402 uri: 'internal://app/text.txt', 403 success: function(data) { 404 console.log('call readText success: ' + data.text); 405 }, 406 fail: function(data, code) { 407 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 408 }, 409 }); 410 } 411} 412``` 413 414 415## file.readArrayBuffer 416 417readArrayBuffer(Object): void 418 419从指定文件中读取Buffer内容。仅支持文本文档读写。 420 421**系统能力：** SystemCapability.FileManagement.File.FileIO 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| -------- | -------- | -------- | -------- | 427| uri | string | 是 | 本地文件uri。 | 428| position | number | 否 | 读取的起始位置，缺省为文件的起始位置。 | 429| length | number | 否 | 需要读取的长度，缺省则读取到文件结尾。 | 430| success | Function | 否 | 接口调用成功的回调函数。 | 431| fail | Function | 否 | 接口调用失败的回调函数。 | 432| complete | Function | 否 | 接口调用结束的回调函数。 | 433 434success返回值： 435 436| 参数名 | 类型 | 说明 | 437| -------- | -------- | -------- | 438| buffer | Uint8Array | 读取到的文件内容。 | 439 440fail返回错误代码： 441 442| 错误码 | 说明 | 443| -------- | -------- | 444| 202 | 出现参数错误。 | 445| 300 | 出现I/O错误。 | 446| 301 | 文件或目录不存在。 | 447 448**示例：** 449 450``` 451export default { 452 readArrayBuffer() { 453 file.readArrayBuffer({ 454 uri: 'internal://app/test', 455 position: 10, 456 length: 200, 457 success: function(data) { 458 console.log('call readArrayBuffer success: ' + data.buffer); 459 }, 460 fail: function(data, code) { 461 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 462 }, 463 }); 464 } 465} 466``` 467 468 469## file.access 470 471access(Object): void 472 473判断指定文件或目录是否存在。 474 475**系统能力：** SystemCapability.FileManagement.File.FileIO 476 477**参数：** 478 479| 参数名 | 类型 | 必填 | 说明 | 480| -------- | -------- | -------- | -------- | 481| uri | string | 是 | 目录或文件uri。 | 482| success | Function | 否 | 接口调用成功的回调函数。 | 483| fail | Function | 否 | 接口调用失败的回调函数。 | 484| complete | Function | 否 | 接口调用结束的回调函数。 | 485 486fail返回错误代码： 487 488| 错误码 | 说明 | 489| -------- | -------- | 490| 202 | 出现参数错误。 | 491| 300 | 出现I/O 错误。 | 492| 301 | 文件或目录不存在。 | 493 494**示例：** 495 496``` 497export default { 498 access() { 499 file.access({ 500 uri: 'internal://app/test', 501 success: function() { 502 console.log('call access success.'); 503 }, 504 fail: function(data, code) { 505 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 506 }, 507 }); 508 } 509} 510``` 511 512 513## file.mkdir 514 515mkdir(Object): void 516 517创建指定目录。 518 519**系统能力：** SystemCapability.FileManagement.File.FileIO 520 521**参数：** 522 523| 参数名 | 类型 | 必填 | 说明 | 524| -------- | -------- | -------- | -------- | 525| uri | string | 是 | 目录的uri路径。 | 526| recursive | boolean | 否 | 是否递归创建该目录的上级目录，缺省为false。 | 527| success | Function | 否 | 接口调用成功的回调函数。 | 528| fail | Function | 否 | 接口调用失败的回调函数。 | 529| complete | Function | 否 | 接口调用结束的回调函数。 | 530 531fail返回错误代码： 532 533| 错误码 | 说明 | 534| -------- | -------- | 535| 202 | 出现参数错误。 | 536| 300 | 出现I/O 错误。 | 537 538**示例：** 539 540``` 541export default { 542 mkdir() { 543 file.mkdir({ 544 uri: 'internal://app/test_directory', 545 success: function() { 546 console.log('call mkdir success.'); 547 }, 548 fail: function(data, code) { 549 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 550 }, 551 }); 552 } 553} 554``` 555 556 557## file.rmdir 558 559rmdir(Object): void 560 561删除指定目录。 562 563**系统能力：** SystemCapability.FileManagement.File.FileIO 564 565**参数：** 566 567| 参数名 | 类型 | 必填 | 说明 | 568| -------- | -------- | -------- | -------- | 569| uri | string | 是 | 目录的uri路径。 | 570| recursive | boolean | 否 | 是否递归删除子文件和子目录，缺省为false。 | 571| success | Function | 否 | 接口调用成功的回调函数。 | 572| fail | Function | 否 | 接口调用失败的回调函数。 | 573| complete | Function | 否 | 接口调用结束的回调函数。 | 574 575fail返回错误代码： 576 577| 错误码 | 说明 | 578| -------- | -------- | 579| 202 | 出现参数错误。 | 580| 300 | 出现I/O 错误。 | 581| 301 | 文件或目录不存在。 | 582 583**示例：** 584 585``` 586export default { 587 rmdir() { 588 file.rmdir({ 589 uri: 'internal://app/test_directory', 590 success: function() { 591 console.log('call rmdir success.'); 592 }, 593 fail: function(data, code) { 594 console.error('call fail callback fail, code: ' + code + ', data: ' + data); 595 }, 596 }); 597 } 598} 599```
