diff --git a/en/application-dev/reference/apis/js-apis-filemanager.md b/en/application-dev/reference/apis/js-apis-filemanager.md index fe5143ca5a4415bc01cc388b2859f1c59800568c..b7e33e70ef01cec6ed41308fbc2f102ef2176c28 100644 --- a/en/application-dev/reference/apis/js-apis-filemanager.md +++ b/en/application-dev/reference/apis/js-apis-filemanager.md @@ -1,8 +1,9 @@ -# Public File Access and Management ->![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE:** +# User File Access and Management +>![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
> >- The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. >- The APIs of this module are system APIs and cannot be called by third-party applications. Currently, these APIs can be called only by **filepicker**. + ## Modules to Import ```js @@ -13,40 +14,40 @@ import filemanager from '@ohos.fileManager'; getRoot(options? : {dev? : DevInfo}) : Promise<FileInfo[]> -Obtains information about the files in the first-level directory in asynchronous mode. This method uses a promise to return the result. +Obtains information about the root album or directory in asynchronous mode. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.FileManagerService - Parameters | Name| Type| Mandatory| Description| | --- | --- | --- | -- | - | dev | [DevInfo](#devinfo) | No| Device name. The default value is **local**, which is the only value supported.| + | options | Object | No| The options are as follows:
-  **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| - Return value | Type| Description| | --- | -- | - | Promise<[FileInfo](#fileinfo)[]> | Promise used to return the file information obtained.| + | Promise<[FileInfo](#fileinfo)[]> | Promise used to return the root album or directory information obtained.| - Example -```js -filemanager.getRoot().then((fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log(JSON.Stringify(fileInfo)) - } - } -}).catch((err) => { - console.log(err) -}); -``` + ```js + filemanager.getRoot().then((fileInfo) => { + if(Array.isArray(fileInfo)) { + for (var i = 0; i < fileInfo.length; i++) { + console.log("file:"+JSON.stringify(fileInfo)); + } + } + }).catch((err) => { + console.log(err) + }); + ``` ## filemanager.getRoot getRoot(options? : {dev? : DevInfo}, callback : AsyncCallback<FileInfo[]>) : void -Obtains information about the files in the first-level directory in asynchronous mode. This method uses a callback to return the result. +Obtains information about the root album or directory in asynchronous mode. This API uses a callback to return the result. **System capability**: SystemCapability.FileManagement.FileManagerService @@ -54,71 +55,72 @@ Obtains information about the files in the first-level directory in asynchronous | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ----------------------------- | - | dev | [DevInfo](#devinfo) | No | Device name. The default value is **local**, which is the only value supported.| - | callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the file information obtained. | + | options | Object | No| The options are as follows:
-  **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| + | callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the root album or directory information obtained. | - Example -```js -filemanager.getRoot((err, fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log(JSON.Stringify(fileInfo)) - } - } -}) -``` + ```js + filemanager.getRoot((err, fileInfo) => { + if(Array.isArray(fileInfo)) { + for (var i = 0; i < fileInfo.length; i++) { + console.log("file:"+JSON.stringify(fileInfo)); + } + } + }); + ``` ## filemanager.listFile listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}) : Promise<FileInfo[]> -Obtains information about the files in the second-level directory in asynchronous mode. This method uses a promise to return the result. +Obtains information about the second-level album or files in asynchronous mode. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.FileManagerService - Parameters | Name| Type| Mandatory| Description| | --- | --- | --- | -- | - | type | string | Yes| Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.| | path | string | Yes| URI of the directory to query.| - | dev | [DevInfo](#devinfo) | Yes| Device name. The default value is **local**, which is the only value supported.| - | offset | number | No| Start position from which the files are to query.| - | count | number | No| Number of files to query.| - + | type | string | Yes| Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.| + | options | Object | No| The options are as follows:
-  **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.
-  **offset**: position to start the query. The value is a number.
-  **count**: number of files to query.| + - Return value | Type| Description| | --- | -- | - | Promise<FileInfo[]> | Promise used to return the file information obtained.| + | Promise<FileInfo[]> | Promise used to return the album or file information obtained.| - Error | Error Info| Error Code|Description| - | -- | --- | -- | - |No such file or directory | 2 | The directory or file of the specified URI does not exist.| - |No such process | 3 | Failed to obtain the FMS service.| - |Not a directory | 20 | The object specified by the URI is not a directory.| + | -- | --- | -- | + | No such file or directory | 2 | The directory or album of the specified URI does not exist.| + | No such process | 3 | Failed to obtain the FMS service.| + | Not a directory | 20 | The object specified by the URI is not a directory or album.| + +- Example + + ```js + // Obtain all files in the directory. + // Call listFile() and getRoot() to obtain the file URI. + let media_path = file.uri + filemanager.listFile(media_path, "file") + .then((fileInfo) => { + if(Array.isArray(fileInfo)) { + for (var i = 0; i < fileInfo.length; i++) { + console.log("file:"+JSON.stringify(fileInfo)); + } + } + }).catch((err) => { + console.log(err) + }); + ``` -```js -// Obtain all files in the directory. -// Call listFile() and getRoot() to obtain file URIs. -let media_path = file.uri -filemanager.listFile(media_path, "file") -.then((fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log(JSON.Stringify(fileInfo)) - } - } -}).catch((err) => { - console.log(err) -}) -``` ## filemanager.listFile listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}, callback : AsyncCallback<FileInfo[]>) : void -Obtains information about the files in the second-level directory in asynchronous mode. This method uses a callback to return the result. +Obtains information about the second-level album or files in asynchronous mode. This API uses a callback to return the result. **System capability**: SystemCapability.FileManagement.FileManagerService @@ -126,37 +128,37 @@ Obtains information about the files in the second-level directory in asynchronou | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ------------------------------------------------------------ | - | type | string | Yes | Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.| | path | string | Yes | URI of the directory to query. | - | dev | [DevInfo](#devinfo) | No| Device name. The default value is **local**, which is the only value supported.| - | offset | number | No| Start position from which the files are to query.| - | count | number | No| Number of files to query.| + | type | string | Yes | Type of the files to query. The file type can be **file**, **image**, **audio**, or **video**.| + | options | Object | No| The options are as follows:
-  **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.
-  **offset**: position to start the query. The value is a number.
-  **count**: number of files to query.| | callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the file information obtained. | - Error | Error Info | Error Code| Description | | ------------------------- | ------ | ------------------------- | - |No such file or directory | 2 | The directory or file of the specified URI does not exist.| - |No such process | 3 | Failed to obtain the FMS service. | - |Not a directory | 20 | The object specified by the URI is not a directory.| + | No such file or directory | 2 | The directory or album of the specified URI does not exist.| + | No such process | 3 | Failed to obtain the FMS service. | + | Not a directory | 20 | The object specified by the URI is not a directory or album.| -```js -// Call listFile() and getRoot() to obtain the file URIs. -let media_path = file.uri -filemanager.listFile(media_path, "file", (err, fileInfo) => { - if(Array.isArray(fileInfo)) { - for (var i = 0; i < fileInfo.length; i++) { - console.log(JSON.Stringify(fileInfo)) - } - } -}) -``` +- Example + + ```js + // Call listFile() and getRoot() to obtain the file URI. + let media_path = file.uri + filemanager.listFile(media_path, "file", (err, fileInfo) => { + if(Array.isArray(fileInfo)) { + for (var i = 0; i < fileInfo.length; i++) { + console.log("file:"+JSON.stringify(fileInfo)); + } + } + }); + ``` ## filemanager.createFile -filemanager.createFile(path : string, filename : string, options? : {dev? : DevInfo}) : promise<string> +filemanager.createFile(path : string, filename : string, options? : {dev? : DevInfo}) : Promise<string> -Creates a file in the specified path in asynchronous mode. This method uses a promise to return the result. +Creates a file in the specified path in asynchronous mode. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.FileManagerService @@ -165,7 +167,7 @@ Creates a file in the specified path in asynchronous mode. This method uses a pr | --- | --- | --- | -- | | filename | string | Yes| Name of the file to create.| | path | string | Yes| URI of the file to create.| - | dev | [DevInfo](#devinfo) | No| Device name. The default value is **local**, which is the only value supported.| + | options | Object | No| The options are as follows:
-  **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| - Return value @@ -177,28 +179,29 @@ Creates a file in the specified path in asynchronous mode. This method uses a pr | Error Info| Error Code|Description| | -- | --- | -- | | Operation not permitted | 1 | A file with the same name already exists.| - | No such file or directory | 2 | The directory or file of the specified URI does not exist.| + | No such file or directory | 2 | The directory or album of the specified URI does not exist.| | No such process | 3 | Failed to obtain the FMS service.| - | Not a directory | 20 | The object specified by the URI is not a directory.| + | Not a directory | 20 | The object specified by the URI is not a directory or album.| -```js -// Create a file. -let media_path = file.uri // Obtain the file URI using listFile() and getRoot(). -let name = "xxx.jpg" // File to be saved. -filemanager.createFile(media_path, name) -.then((uri) => { -// The URI of the file created is returned. -}) -.catch((err) => { - console.log(err) -}) -``` +- Example + + ```js + // Create a file. + let media_path = file.uri // Obtain the file URI using listFile() and getRoot(). + let name = "xxx.jpg" // File to be saved. + filemanager.createFile(media_path, name).then((uri) => { + // The URI of the file created is returned. + console.log("file uri:"+uri); + }).catch((err) => { + console.log(err); + }); + ``` ## filemanager.createFile createFile(path : string, filename: string, options? : {dev? : DevInfo}, callback : AsyncCallback<string>) : void -Creates a file in the specified path in asynchronous mode. This method uses a callback to return the result. +Creates a file in the specified path in asynchronous mode. This API uses a callback to return the result. **System capability**: SystemCapability.FileManagement.FileManagerService @@ -208,7 +211,7 @@ Creates a file in the specified path in asynchronous mode. This method uses a ca | -------- | ------------------------- | ---- | ----------------------------- | | filename | string | Yes | Name of the file to create. | | path | string | Yes | URI of the file to create. | - | dev | [DevInfo](#devinfo) | No| Device name. The default value is **local**, which is the only value supported.| + | options | Object | No| The options are as follows:
-  **dev**: See [DevInfo](#devinfo). It is **dev = {name: "local"}** by default if not specified. Currently, only 'local' is supported.| | callback | AsyncCallback<[FileInfo](#fileinfo)[]> | Yes | Callback invoked to return the file information obtained. | - Error @@ -216,20 +219,23 @@ Creates a file in the specified path in asynchronous mode. This method uses a ca | Error Info | Error Code| Description | | ------------------------- | ------ | ------------------------- | | Operation not permitted | 1 | A file with the same name already exists. | - | No such file or directory | 2 | The directory or file of the specified URI does not exist.| + | No such file or directory | 2 | The directory or album of the specified URI does not exist.| | No such process | 3 | Failed to obtain the FMS service. | - | Not a directory | 20 | The object specified by the URI is not a directory.| + | Not a directory | 20 | The object specified by the URI is not a directory or album.| -```js -// Create a file. -// Call listFile() and getRoot() to obtain the file URI. -let media_path = file.uri -// File to be saved. -let name = "xxx.jpg" -filemanager.createFile(media_path, name, (err, uri) => { -// The URI of the file created is returned. -}) -``` +- Example + + ```js + // Create a file. + // Call listFile() and getRoot() to obtain the file URI. + let media_path = file.uri + // File to be saved. + let name = "xxx.jpg" + filemanager.createFile(media_path, name, (err, uri) => { + // The URI of the file created is returned. + console.log("file uri:"+uri); + }); + ``` ## FileInfo Defines the file information returned by **getRoot()** or **listFile()**. @@ -248,12 +254,13 @@ Defines the file information returned by **getRoot()** or **listFile()**. | modifiedTime | number | Yes| No| Time when the file was modified.| ## DevInfo + Defines the device type. **System capability**: SystemCapability.FileManagement.FileManagerService ### Attributes - | Name| Type| Readable| Writable| Description| - | --- | -- | -- | -- | -- | - | name | string | Yes| Yes| Device name.| +| Name| Type | Readable| Writable| Description | +| ------ | ------ | ---- | ---- | -------- | +| name | string | Yes | Yes | Device name.|