From ca7bab1a64dcb4ea1392322fbf94b60d45f65d45 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Fri, 11 Aug 2023 16:42:42 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../apis/js-apis-photoAccessHelper.md | 182 ++++++- .../reference/apis/js-apis-userFileManager.md | 445 +++++++++--------- 2 files changed, 391 insertions(+), 236 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-photoAccessHelper.md b/en/application-dev/reference/apis/js-apis-photoAccessHelper.md index 288dd14f4a..808334727b 100644 --- a/en/application-dev/reference/apis/js-apis-photoAccessHelper.md +++ b/en/application-dev/reference/apis/js-apis-photoAccessHelper.md @@ -4,7 +4,7 @@ The **photoAccessHelper** module provides APIs for album management, including c > **NOTE** > -> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -341,7 +341,7 @@ For details about the error codes, see [File Management Error Codes](../errorcod | ID| Error Message| | -------- | ---------------------------------------- | -| 202 | Called by non-system application. | +| 202 | Called by non-system application. | | 401 | if type displayName is not string. | | 14000001 | if type of displayName is invalid. | @@ -401,9 +401,9 @@ async function example() { let options = { title: 'testPhoto' } - phAccessHelper.createAsset(photoType, extension, options, (err, photoAsset) => { - if (photoAsset != undefined) { - console.info('createAsset file displayName' + photoAsset.displayName); + phAccessHelper.createAsset(photoType, extension, options, (err, uri) => { + if (uri != undefined) { + console.info('createAsset uri' + uri); console.info('createAsset successfully'); } else { console.error('createAsset failed, message = ', err); @@ -445,9 +445,9 @@ async function example() { console.info('createAssetDemo'); let photoType = photoAccessHelper.PhotoType.IMAGE; let extension = 'jpg'; - phAccessHelper.createAsset(photoType, extension, (err, photoAsset) => { - if (photoAsset != undefined) { - console.info('createAsset file displayName' + photoAsset.displayName); + phAccessHelper.createAsset(photoType, extension, (err, uri) => { + if (uri != undefined) { + console.info('createAsset uri' + uri); console.info('createAsset successfully'); } else { console.error('createAsset failed, message = ', err); @@ -499,8 +499,8 @@ async function example() { let options = { title: 'testPhoto' } - let photoAsset = await phAccessHelper.createAsset(photoType,extension, options); - console.info('createAsset file displayName' + photoAsset.displayName); + let uri = await phAccessHelper.createAsset(photoType, extension, options); + console.info('createAsset uri' + uri); console.info('createAsset successfully'); } catch (err) { console.error('createAsset failed, message = ', err); @@ -1077,15 +1077,15 @@ async function example() { //file had changed, do something } // Register onCallback1. - phAccessHelper.registerChange(photoAsset.uri, false, onCallback1); + phAccessHelper.registerChange(photoAsset.uri, false, onCallback1); // Register onCallback2. phAccessHelper.registerChange(photoAsset.uri, false, onCallback2); - photoAsset.favorite(true, (err) => { + photoAsset.setFavorite(true, (err) => { if (err == undefined) { - console.info('favorite successfully'); + console.info('setFavorite successfully'); } else { - console.error('favorite failed with error:' + err); + console.error('setFavorite failed with error:' + err); } }); } @@ -1145,11 +1145,11 @@ async function example() { phAccessHelper.registerChange(photoAsset.uri, false, onCallback2); // Unregister the listening of onCallback1. phAccessHelper.unRegisterChange(photoAsset.uri, onCallback1); - photoAsset.favorite(true, (err) => { + photoAsset.setFavorite(true, (err) => { if (err == undefined) { - console.info('favorite successfully'); + console.info('setFavorite successfully'); } else { - console.error('favorite failed with error:' + err); + console.error('setFavorite failed with error:' + err); } }); } @@ -1539,7 +1539,7 @@ For details about the error codes, see [Universal Error Codes](../errorcodes/err | -------- | ---------------------------------------- | | 401 | if values to commit is invalid. | -**Example** +**Example** ```ts import dataSharePredicates from '@ohos.data.dataSharePredicates'; @@ -2839,7 +2839,7 @@ Obtains image and video assets. This API uses an asynchronous callback to return | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ---------- | -| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the album files.| +| options | [FetchOptions](#fetchoptions) | Yes | Options for fetching the albums.| | callback | AsyncCallback<[FetchResult](#fetchresult)<[PhotoAsset](#photoasset)>> | Yes | Callback invoked to return the image and video assets obtained.| **Error codes** @@ -2856,17 +2856,17 @@ For details about the error codes, see [Universal Error Codes](../errorcodes/err import dataSharePredicates from '@ohos.data.dataSharePredicates'; async function example() { - console.info('albumGetPhotoAssetsDemoCallback'); - + console.info('albumGetAssetsDemoCallback'); let predicates = new dataSharePredicates.DataSharePredicates(); let albumFetchOptions = { + fetchColumns: [], predicates: predicates }; let fetchOption = { fetchColumns: [], predicates: predicates }; - const albumList = await phAccessHelper.getAlbums(albumFetchOptions); + const albumList = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); const album = await albumList.getFirstObject(); album.getAssets(fetchOption, (err, albumFetchResult) => { if (albumFetchResult != undefined) { @@ -2914,17 +2914,18 @@ For details about the error codes, see [Universal Error Codes](../errorcodes/err import dataSharePredicates from '@ohos.data.dataSharePredicates'; async function example() { - console.info('albumGetPhotoAssetsDemoPromise'); + console.info('albumGetAssetsDemoPromise'); let predicates = new dataSharePredicates.DataSharePredicates(); let albumFetchOptions = { + fetchColumns: [], predicates: predicates }; let fetchOption = { fetchColumns: [], predicates: predicates }; - const albumList = await phAccessHelper.getAlbums(albumFetchOptions); + const albumList = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); const album = await albumList.getFirstObject(); album.getAssets(fetchOption).then((albumFetchResult) => { console.info('album getPhotoAssets successfully, getCount: ' + albumFetchResult.getCount()); @@ -2967,9 +2968,10 @@ async function example() { console.info('albumCommitModifyDemo'); let predicates = new dataSharePredicates.DataSharePredicates(); let albumFetchOptions = { + fetchColumns: [], predicates: predicates }; - const albumList = await phAccessHelper.getAlbums(albumFetchOptions); + const albumList = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); const album = await albumList.getFirstObject(); album.albumName = 'hello'; album.commitModify((err) => { @@ -3015,9 +3017,10 @@ async function example() { console.info('albumCommitModifyDemo'); let predicates = new dataSharePredicates.DataSharePredicates(); let albumFetchOptions = { + fetchColumns: [], predicates: predicates }; - const albumList = await phAccessHelper.getAlbums(albumFetchOptions); + const albumList = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC, albumFetchOptions); const album = await albumList.getFirstObject(); album.albumName = 'hello'; album.commitModify().then(() => { @@ -3496,6 +3499,131 @@ async function example() { } ``` +### setCoverUri + +setCoverUri(uri: string, callback: AsyncCallback<void>): void; + +Sets the album cover. This API uses an asynchronous callback to return the result. + +**NOTE**
This API can be used to set the user album cover, but not the system album cover. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO + +**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| uri | string | Yes | URI of the file to be set as the album cover.| +| callback | AsyncCallback<void> | Yes | Callback that returns no value.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +| 202 | Called by non-system application. | +| 401 | if parameter is invalid. | + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +async function example() { + try { + console.info('setCoverUriDemoCallback'); + let predicates = new dataSharePredicates.DataSharePredicates(); + let fetchOption = { + fetchColumns: [], + predicates: predicates + }; + let albumFetchResult = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); + let album = await albumFetchResult.getFirstObject(); + let fetchResult = await album.getAssets(fetchOption); + let asset = await fetchResult.getFirstObject(); + album.setCoverUri(asset.uri, (err) => { + if (err === undefined) { + console.info('album setCoverUri successfully'); + } else { + console.error('album setCoverUri failed with error: ' + err); + } + }); + } catch (err) { + console.error('setCoverUriDemoCallback failed with error: ' + err); + } +} +``` + +### setCoverUri + +setCoverUri(uri: string): Promise<void>; + +Sets the album cover. This API uses a promise to return the result. + +**NOTE**
This API can be used to set the user album cover, but not the system album cover. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.WRITE_IMAGEVIDEO + +**System capability**: SystemCapability.FileManagement.PhotoAccessHelper.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ---------- | +| uri | string | Yes | URI of the file to be set as the album cover.| + +**Return value** + +| Type | Description | +| --------------------------------------- | ----------------- | +|Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +| 202 | Called by non-system application. | +| 401 | if parameter is invalid. | + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +async function example() { + try { + console.info('setCoverUriDemoCallback'); + let predicates = new dataSharePredicates.DataSharePredicates(); + let fetchOption = { + fetchColumns: [], + predicates: predicates + }; + let albumFetchResult = await phAccessHelper.getAlbums(photoAccessHelper.AlbumType.USER, photoAccessHelper.AlbumSubtype.USER_GENERIC); + let album = await albumFetchResult.getFirstObject(); + let fetchResult = await album.getAssets(fetchOption); + let asset = await fetchResult.getFirstObject(); + album.setCoverUri(asset.uri, (err) => { + if (err === undefined) { + console.info('album setCoverUri successfully'); + } else { + console.error('album setCoverUri failed with error: ' + err); + } + }); + } catch (err) { + console.error('setCoverUriDemoCallback failed with error: ' + err); + } +} +``` + ## MemberType Enumerates the member types. @@ -3597,6 +3725,7 @@ Defines the key information about an image or video file. | POSITION | 'position' | File location type. **System API**: This is a system API. | | DATE_TRASHED | 'date_trashed' | Date when the file was deleted. The value is the number of seconds between the time when the file is deleted and January 1, 1970. **System API**: This is a system API. | | HIDDEN | 'hidden' | Whether the file is hidden. **System API**: This is a system API. | +| CAMERA_SHOT_KEY | 'camera_shot_key' | Key for the Untra Snamshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.)
**System API**: This is a system API. | ## AlbumKeys @@ -3618,6 +3747,7 @@ Defines the options for creating an image or video asset. | Name | Type | Mandatory| Description | | ---------------------- | ------------------- | ---- | ------------------------------------------------ | | subtype | [PhotoSubtype](#photosubtype) | No | Subtype of the image or video. **System API**: This is a system API. | +| cameraShotKey | string | No | Key for the Untra Snamshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.)
**System API**: This is a system API. | ## CreateOptions diff --git a/en/application-dev/reference/apis/js-apis-userFileManager.md b/en/application-dev/reference/apis/js-apis-userFileManager.md index ea449c8820..d3732ddaf1 100644 --- a/en/application-dev/reference/apis/js-apis-userFileManager.md +++ b/en/application-dev/reference/apis/js-apis-userFileManager.md @@ -481,113 +481,6 @@ async function example() { } ``` -### getPhotoAlbums - -getPhotoAlbums(options: AlbumFetchOptions, callback: AsyncCallback<FetchResult<Album>>): void; - - -Obtains image and video albums. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.FileManagement.UserFileManager.Core - -**Required permissions**: ohos.permission.READ_IMAGEVIDEO - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | ------------------------ | ---- | ------------------------- | -| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. | -| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | Yes | Callback invoked to return the image and video albums obtained.| - -**Error codes** - -For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). - -| ID| Error Message| -| -------- | ---------------------------------------- | -| 13900020 | if type options is not AlbumFetchOptions. | - -**Example** - -```ts -import dataSharePredicates from '@ohos.data.dataSharePredicates'; - -async function example() { - console.info('getPhotoAlbumsDemo'); - let predicates = new dataSharePredicates.DataSharePredicates(); - let albumFetchOptions = { - predicates: predicates - }; - - mgr.getPhotoAlbums(albumFetchOptions, (err, fetchResult) => { - if (fetchResult != undefined) { - console.info('albums.count = ' + fetchResult.getCount()); - fetchResult.getFirstObject((err, album) => { - if (album != undefined) { - console.info('first album.albumName = ' + album.albumName); - } else { - console.error('album is undefined, err = ', err); - } - }); - } else { - console.error('getPhotoAlbums fail, message = ', err); - } - }); -} -``` - -### getPhotoAlbums - -getPhotoAlbums(options: AlbumFetchOptions): Promise<FetchResult<Album>>; - -Obtains image and video albums. This API uses a promise to return the result. - -**System capability**: SystemCapability.FileManagement.UserFileManager.Core - -**Required permissions**: ohos.permission.READ_IMAGEVIDEO - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | ------------------------ | ---- | ------------------------- | -| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. | - -**Return value** - -| Type | Description | -| --------------------------- | -------------- | -| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise used to return the image and video albums obtained.| - -**Error codes** - -For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). - -| ID| Error Message| -| -------- | ---------------------------------------- | -| 13900020 | if type options is not AlbumFetchOptions. | - -**Example** - -```ts -import dataSharePredicates from '@ohos.data.dataSharePredicates'; - -async function example() { - console.info('getPhotoAlbumsDemo'); - let predicates = new dataSharePredicates.DataSharePredicates(); - let albumFetchOptions = { - predicates: predicates - }; - try { - let fetchResult = await mgr.getPhotoAlbums(albumFetchOptions); - console.info('album.count = ' + fetchResult.getCount()); - const album = await fetchResult.getFirstObject(); - console.info('first album.albumName = ' + album.albumName); - } catch (err) { - console.error('getPhotoAlbums fail, message = ' + err); - } -} -``` - ### createAlbum10+ createAlbum(name: string, callback: AsyncCallback<Album>): void; @@ -935,12 +828,124 @@ async function example() { } ``` +### getPhotoAlbums + +getPhotoAlbums(options: AlbumFetchOptions, callback: AsyncCallback<FetchResult<Album>>): void; + +Obtains image and video albums. This API uses an asynchronous callback to return the result. + +This API will be deprecated. Use [getAlbums10+](#getalbums10) instead. + +**System capability**: SystemCapability.FileManagement.UserFileManager.Core + +**Required permissions**: ohos.permission.READ_IMAGEVIDEO + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------ | ---- | ------------------------- | +| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. | +| callback | AsyncCallback<[FetchResult](#fetchresult)<[Album](#album)>> | Yes | Callback invoked to return the image and video albums obtained.| + +**Error codes** + +For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +| 13900020 | if type options is not AlbumFetchOptions. | + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +async function example() { + console.info('getPhotoAlbumsDemo'); + let predicates = new dataSharePredicates.DataSharePredicates(); + let albumFetchOptions = { + predicates: predicates + }; + + mgr.getPhotoAlbums(albumFetchOptions, (err, fetchResult) => { + if (fetchResult != undefined) { + console.info('albums.count = ' + fetchResult.getCount()); + fetchResult.getFirstObject((err, album) => { + if (album != undefined) { + console.info('first album.albumName = ' + album.albumName); + } else { + console.error('album is undefined, err = ', err); + } + }); + } else { + console.error('getPhotoAlbums fail, message = ', err); + } + }); +} +``` + +### getPhotoAlbums + +getPhotoAlbums(options: AlbumFetchOptions): Promise<FetchResult<Album>>; + +Obtains image and video albums. This API uses a promise to return the result. + +This API will be deprecated. Use [getAlbums10+](#getalbums10) instead. + +**System capability**: SystemCapability.FileManagement.UserFileManager.Core + +**Required permissions**: ohos.permission.READ_IMAGEVIDEO + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------ | ---- | ------------------------- | +| options | [AlbumFetchOptions](#albumfetchoptions) | Yes | Options for fetching the albums. | + +**Return value** + +| Type | Description | +| --------------------------- | -------------- | +| Promise<[FetchResult](#fetchresult)<[Album](#album)>> | Promise used to return the image and video albums obtained.| + +**Error codes** + +For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +| 13900020 | if type options is not AlbumFetchOptions. | + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates'; + +async function example() { + console.info('getPhotoAlbumsDemo'); + let predicates = new dataSharePredicates.DataSharePredicates(); + let albumFetchOptions = { + predicates: predicates + }; + try { + let fetchResult = await mgr.getPhotoAlbums(albumFetchOptions); + console.info('album.count = ' + fetchResult.getCount()); + const album = await fetchResult.getFirstObject(); + console.info('first album.albumName = ' + album.albumName); + } catch (err) { + console.error('getPhotoAlbums fail, message = ' + err); + } +} +``` + ### getPrivateAlbum getPrivateAlbum(type: PrivateAlbumType, callback: AsyncCallback<FetchResult<PrivateAlbum>>): void; Obtains the system album. This API uses an asynchronous callback to return the result. +This API will be deprecated. Use [getAlbums10+](#getalbums10) instead. + **System capability**: SystemCapability.FileManagement.UserFileManager.Core **Required permissions**: ohos.permission.READ_IMAGEVIDEO @@ -982,6 +987,8 @@ getPrivateAlbum(type: PrivateAlbumType): Promise<FetchResult<PrivateAlbum& Obtains the system album. This API uses a promise to return the result. +This API will be deprecated. Use [getAlbums10+](#getalbums10) instead. + **System capability**: SystemCapability.FileManagement.UserFileManager.Core **Required permissions**: ohos.permission.READ_IMAGEVIDEO @@ -1252,102 +1259,6 @@ async function example() { } ``` -### on - -on(type: ChangeEvent, callback: Callback<void>): void - -Subscribes to changes of the file management library. This API uses a callback to return the result. - -This API will be deprecated. Use [on10+](#on10) instead. - -**System capability**: SystemCapability.FileManagement.UserFileManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------------------------------------------ | -| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.
**deviceChange** indicates the device change.
**albumChange** indicates the album change.
**imageChange** indicates the image change.
**audioChange** indicates the audio file change.
**videoChange** indicates the video file change.
**remoteFileChange** indicates the file change on the registered device.| -| callback | Callback<void> | Yes | Callback that returns no value. | - -**Example** - -```ts -async function example() { - console.info('onDemo'); - let count = 0; - mgr.on('imageChange', () => { - count++; - // Image file changed. Do something. - }); - try { - let testFileName = 'testFile' + Date.now() + '.jpg'; - let fileAsset = await mgr.createPhotoAsset(testFileName); - console.info('createPhotoAsset file displayName' + fileAsset.displayName); - console.info('createPhotoAsset successfully'); - } catch (err) { - console.error('createPhotoAsset failed, message = ' + err); - } - // Sleep 1s. - if (count > 0) { - console.info('onDemo success'); - } else { - console.error('onDemo fail'); - } - mgr.off('imageChange', () => { - // Unsubscription succeeds. - }); -} -``` - -### off - -off(type: ChangeEvent, callback?: Callback<void>): void - -Unsubscribes from changes of the file management library. This API uses a callback to return the result. - -This API will be deprecated. Use [off10+](#off10) instead. - -**System capability**: SystemCapability.FileManagement.UserFileManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | -------------------- | ---- | ------------------------------------------------------------ | -| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.
**deviceChange** indicates the device change.
**albumChange** indicates the album change.
**imageChange** indicates the image change.
**audioChange** indicates the audio file change.
**videoChange** indicates the video file change.
**remoteFileChange** indicates the change of the file on a registered device.| -| callback | Callback<void> | No | Callback that returns no value. | - -**Example** - -```ts -async function example() { - console.info('offDemo'); - let count = 0; - mgr.on('imageChange', () => { - count++; - // Image file changed. Do something. - }); - - mgr.off('imageChange', () => { - // Unsubscription succeeds. - }); - - try { - let testFileName = 'testFile' + Date.now() + '.jpg'; - let fileAsset = await mgr.createPhotoAsset(testFileName); - console.info('createPhotoAsset file displayName' + fileAsset.displayName); - console.info('createPhotoAsset successfully'); - } catch (err) { - console.error('createPhotoAsset failed, message = ' + err); - } - // Sleep 1s. - if (count == 0) { - console.info('offDemo success'); - } else { - console.error('offDemo fail'); - } -} -``` - ### getActivePeers getActivePeers(callback: AsyncCallback<Array<PeerInfo>>): void; @@ -1427,7 +1338,7 @@ Obtains information about all peer devices. This API uses an asynchronous callba | Name | Type | Mandatory| Description | | -------- | --------------------------------- | ---- | ------------ | -| callback | AsyncCallback<Array<[PeerInfo](#peerinfo)>> | Yes | Callback invoked to return the information obtained.| +| callback | AsyncCallback<Array<[PeerInfo](#peerinfo)>> | Yes | Callback invoked to return the peer device information obtained.| **Example** @@ -1545,7 +1456,7 @@ async function example() { on(uri: string, forSubUri: boolean, callback: Callback<ChangeData>) : void -Enables listening for the specified URI. This API uses a callback to return the result. +Registers a listener for the specified URI. **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -1591,7 +1502,7 @@ async function example() { // File changed. Do something. } // Register onCallback1. - mgr.on(fileAsset.uri, false, onCallback1); + mgr.on(fileAsset.uri, false, onCallback1); // Register onCallback2. mgr.on(fileAsset.uri, false, onCallback2); @@ -1609,7 +1520,7 @@ async function example() { off(uri: string, callback?: Callback<ChangeData>): void -Disables listening for the specified URI. Multiple callbacks can be registered for a URI for listening. You can use **off()** to disable the listening of the specified callbacks or all callbacks. +Unregisters the listener for the specified URI. Multiple callbacks can be registered for a URI for listening. You can use this API to unregister the specified callbacks or all callbacks. **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -1618,7 +1529,7 @@ Disables listening for the specified URI. Multiple callbacks can be registered f | Name | Type | Mandatory| Description | | -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | | uri | string | Yes | URI of the file asset or album, or [DefaultChangeUri](#defaultchangeuri10).| -| callback | Callback<[ChangeData](#changedata10)> | No | Callback registered by [on10+](#on10). If this parameter is not specified, all callbacks registered for the URI will be unregistered.
**NOTE**: The specified callback will not be invoked.| +| callback | Callback<[ChangeData](#changedata10)> | No | Callback registered by [on10+](#on10). If this parameter is not specified, all listener callbacks registered for the URI will be unregistered.
**NOTE**: The specified callback will not be invoked.| **Error codes** @@ -1667,6 +1578,102 @@ async function example() { } ``` +### on + +on(type: ChangeEvent, callback: Callback<void>): void + +Subscribes to changes of the file management library. This API uses a callback to return the result. + +This API will be deprecated. Use [on10+](#on10) instead. + +**System capability**: SystemCapability.FileManagement.UserFileManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------------------------------------------ | +| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.
**deviceChange** indicates the device change.
**albumChange** indicates the album change.
**imageChange** indicates the image change.
**audioChange** indicates the audio file change.
**videoChange** indicates the video file change.
**remoteFileChange** indicates the file change on the registered device.| +| callback | Callback<void> | Yes | Callback that returns no value. | + +**Example** + +```ts +async function example() { + console.info('onDemo'); + let count = 0; + mgr.on('imageChange', () => { + count++; + // Image file changed. Do something. + }); + try { + let testFileName = 'testFile' + Date.now() + '.jpg'; + let fileAsset = await mgr.createPhotoAsset(testFileName); + console.info('createPhotoAsset file displayName' + fileAsset.displayName); + console.info('createPhotoAsset successfully'); + } catch (err) { + console.error('createPhotoAsset failed, message = ' + err); + } + // Sleep 1s. + if (count > 0) { + console.info('onDemo success'); + } else { + console.error('onDemo fail'); + } + mgr.off('imageChange', () => { + // Unsubscription succeeds. + }); +} +``` + +### off + +off(type: ChangeEvent, callback?: Callback<void>): void + +Unsubscribes from changes of the file management library. This API uses a callback to return the result. + +This API will be deprecated. Use [off10+](#off10) instead. + +**System capability**: SystemCapability.FileManagement.UserFileManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------------------------------------------ | +| type | [ChangeEvent](#changeevent) | Yes | Type of event to subscribe to.
**deviceChange** indicates the device change.
**albumChange** indicates the album change.
**imageChange** indicates the image change.
**audioChange** indicates the audio file change.
**videoChange** indicates the video file change.
**remoteFileChange** indicates the change of the file on a registered device.| +| callback | Callback<void> | No | Callback that returns no value. | + +**Example** + +```ts +async function example() { + console.info('offDemo'); + let count = 0; + mgr.on('imageChange', () => { + count++; + // Image file changed. Do something. + }); + + mgr.off('imageChange', () => { + // Unsubscription succeeds. + }); + + try { + let testFileName = 'testFile' + Date.now() + '.jpg'; + let fileAsset = await mgr.createPhotoAsset(testFileName); + console.info('createPhotoAsset file displayName' + fileAsset.displayName); + console.info('createPhotoAsset successfully'); + } catch (err) { + console.error('createPhotoAsset failed, message = ' + err); + } + // Sleep 1s. + if (count == 0) { + console.info('offDemo success'); + } else { + console.error('offDemo fail'); + } +} +``` + ## FileAsset Provides APIs for encapsulating file asset attributes. @@ -1818,7 +1825,7 @@ Commits the modification on the file metadata to the database. This API uses a p | ------------------- | ---------- | | Promise<void> | Promise that returns no value.| -**Example** +**Example** ```ts import dataSharePredicates from '@ohos.data.dataSharePredicates'; @@ -3488,6 +3495,8 @@ async function example() { Provides APIs for managing the system albums. +This API will be discarded. Use [Album](#album) instead. + ### Attributes **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3506,6 +3515,8 @@ getPhotoAssets(options: FetchOptions, callback: AsyncCallback<FetchResult< Obtains image and video assets from a system album. This API uses an asynchronous callback to return the result. +This API will be deprecated. Use [Album.getPhotoAssets](#getphotoassets-2) instead. + **Required permissions**: ohos.permission.READ_IMAGEVIDEO **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3557,6 +3568,8 @@ getPhotoAssets(options: FetchOptions): Promise<FetchResult<FileAsset>&g Obtains image and video assets from a system album. This API uses a promise to return the result. +This API will be deprecated. Use [Album.getPhotoAssets](#getphotoassets-3) instead. + **Required permissions**: ohos.permission.READ_IMAGEVIDEO **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3607,6 +3620,8 @@ delete(uri: string, callback: AsyncCallback<void>): void; Deletes files from a system album. +This API will be deprecated. Use [Album.deletePhotoAssets](#deletephotoassets10) instead. + **Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3651,6 +3666,8 @@ delete(uri: string): Promise<void>; Deletes files from a system album. +This API will be deprecated. Use [Album.deletePhotoAssets](#deletephotoassets10) instead. + **Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3689,7 +3706,7 @@ async function example() { }).catch((err) => { console.error('trashAlbum.delete failed, message = ', err); }); -} +} ``` ### recover @@ -3698,6 +3715,8 @@ recover(uri: string, callback: AsyncCallback<void>): void; Recovers files in a system album. +This API will be deprecated. Use [Album.recoverPhotoAssets](#recoverphotoassets10) instead. + **Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3742,6 +3761,8 @@ recover(uri: string): Promise<void>; Recovers files in a system album. +This API will be deprecated. Use [Album.recoverPhotoAssets](#recoverphotoassets10) instead. + **Required permissions**: ohos.permission.READ_IMAGEVIDEO, ohos.permission.WRITE_IMAGEVIDEO or ohos.permission.READ_AUDIO, and ohos.permission.WRITE_AUDIO **System capability**: SystemCapability.FileManagement.UserFileManager.Core @@ -3890,6 +3911,8 @@ Enumerate the album subtypes. Enumerates the system album types. +This API will be deprecated. Use [AlbumType](#albumtype10) and [AlbumSubType](#albumsubtype10) instead. + **System capability**: SystemCapability.FileManagement.UserFileManager.Core | Name | Value| Description | @@ -3938,6 +3961,7 @@ Defines the key information about an image or video file. | POSITION10+ | position | File location type. | | DATE_TRASHED10+ | date_trashed | Date when the file was deleted. The value is the number of seconds between the time when the file is deleted and January 1, 1970. | | HIDDEN10+ | hidden | Whether the file is hidden. | +| CAMERA_SHOT_KEY10+ | camera_shot_key | Key for the Untra Snamshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.) | ## AlbumKey @@ -3962,6 +3986,7 @@ Options for creating an image or video asset. | Name | Type | Mandatory| Description | | ---------------------- | ------------------- | ---- | ------------------------------------------------ | | subType | [PhotoSubType](#photosubtype10) | No | Subtype of the image or video. | +| cameraShotKey | string | No | Key for the Untra Snamshot feature, which allows the camera to take photos or record videos with the screen off. (This parameter is available only for the system camera, and the key value is defined by the system camera.) | ## FetchOptions -- GitLab