diff --git a/zh-cn/application-dev/reference/apis/js-apis-userFileManager.md b/zh-cn/application-dev/reference/apis/js-apis-userFileManager.md index d4630b1829c4d6ca578ea92d806b9a92e118c534..5d30b9ea83b1c3112dbecf852034a6c21c41bac0 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-userFileManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-userFileManager.md @@ -619,6 +619,8 @@ on(type: ChangeEvent, callback: Callback<void>): void 打开文件管理库变更通知，使用callback方式返回异步结果。 +此接口即将废弃，请使用[on10+](#on10)的新接口 + **系统能力**：SystemCapability.FileManagement.UserFileManager.Core **参数：** @@ -664,6 +666,8 @@ off(type: ChangeEvent, callback?: Callback<void>): void 关闭文件管理库变更通知，使用callback方式返回异步结果。 +此接口即将废弃，请使用[off10+](#off10)的新接口 + **系统能力**：SystemCapability.FileManagement.UserFileManager.Core **参数：** @@ -898,6 +902,112 @@ async function example() { } ``` +### on10+ + +on(uri: string, forSubUri: boolean, callback: Callback<ChangeData>) : void + +打开对指定uri的监听，使用callback方式返回异步结果。 + +**系统能力**：SystemCapability.FileManagement.UserFileManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| uri | string | 是 | FileAsset的uri, Album的uri或[DefaultChangeUri](#defaultchangeuri10)的值。 | +| forSubUri | boolean | 是 | 是否模糊监听，uri为相册uri时，forSubUri 为true能监听到相册中文件的变化，如果是false只能监听相册本身变化。uri为fileAsset时，forSubUri 为true、false没有区别，uri为DefaultChangeUri时，forSubUri必须为true，如果为false将找不到该uri，收不到任何消息。 | +| callback | Callback<[ChangeData](#changedata10)> | 是 | 返回要监听的[ChangeData](#changedata10)。注：uri可以注册多个不同的callback监听，[off10+](#off10)可以关闭该uri所有监听，也可以关闭指定callback的监听。 | + +**示例：** + +```ts +async function example() { + console.info('onDemo'); + let predicates = new dataSharePredicates.DataSharePredicates(); + let fetchOptions = { + fetchColumns: [], + predicates: predicates + }; + let fetchResult = await mgr.getPhotoAssets(fetchOptions); + let fileAsset = await fetchResult.getFirstObject(); + if (fileAsset != undefined) { + console.info('fileAsset.displayName : ' + fileAsset.displayName); + } + let onCallback1 = (changeData) => { + console.info('onCallback1 success, changData: ' + JSON.stringify(changeData)); + //file had changed, do something + } + let onCallback2 = (changeData) => { + console.info('onCallback2 success, changData: ' + JSON.stringify(changeData)); + //file had changed, do something + } + // 注册onCallback1监听 + mgr.on(fileAsset.uri, false, onCallback1); + // 注册onCallback2监听 + mgr.on(fileAsset.uri, false, onCallback2); + + fileAsset.favorite(true, (err) => { + if (err == undefined) { + console.info('favorite successfully'); + } else { + console.error('favorite failed with error:' + err); + } + }); +} +``` + +### off10+ + + off(uri: string, callback?: Callback<ChangeData>): void + +关闭指定uri的监听，一个uri可以注册多个监听，存在多个callback监听时，可以取消指定注册的callback的监听；不指定callback时解除该uri的所有监听。 + +**系统能力**：SystemCapability.FileManagement.UserFileManager.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| uri | string | 是 | FileAsset的uri, Album的uri或[DefaultChangeUri](#defaultchangeuri10)的值。 | +| callback | Callback<[ChangeData](#changedata10)> | 否 | 解除[on10+](#on10)注册时的callback的监听，不填时，解除该uri的所有监听。注：off指定注册的callback后不会进入此回调。 | + +**示例：** + +```ts +async function example() { + console.info('offDemo'); + let predicates = new dataSharePredicates.DataSharePredicates(); + let fetchOptions = { + fetchColumns: [], + predicates: predicates + }; + let fetchResult = await mgr.getPhotoAssets(fetchOptions); + let fileAsset = await fetchResult.getFirstObject(); + if (fileAsset != undefined) { + console.info('fileAsset.displayName : ' + fileAsset.displayName); + } + let onCallback1 = (changeData) => { + console.info('onCallback1 on'); + } + let onCallback2 = (changeData) => { + console.info('onCallback2 on'); + } + // 注册onCallback1监听 + mgr.on(fileAsset.uri, false, onCallback1); + // 注册onCallback2监听 + mgr.on(fileAsset.uri, false, onCallback2); + // 关闭onCallback1监听，onCallback2 继续监听 + mgr.off(fileAsset.uri, onCallback1); + fileAsset.favorite(true, (err) => { + if (err == undefined) { + console.info('favorite successfully'); + } else { + console.error('favorite failed with error:' + err); + } + }); +} +``` + ## FileAsset 提供封装文件属性的方法。 @@ -2461,3 +2571,41 @@ async function example() { | 名称 | 类型 | 可读 | 可写 | 说明 | | ---------------------- | ------------------- | ---- |---- | ------------------------------------------------ | | predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md) | 是 | 是 | 谓词查询，显示过滤条件 | + +## ChangeData10+ + +监听器回调函数的值。 + +**系统能力**：SystemCapability.FileManagement.UserFileManager.Core + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | --------------------------- | ---- | ---- | ------------------------------------------------------------ | +| type | [NotifyType](#notifytype10) | 是 | 否 | ChangeData的通知类型。 | +| uris | Array<string> | 是 | 否 | 相同[NotifyType](#notifytype10)的所有uri，可以是FileAsset或Album。 | +| subUris | Array<string> | 是 | 否 | 相册中变动文件的uri数组。 | + +## NotifyType10+ + +枚举，通知事件的类型。 + +**系统能力**：SystemCapability.FileManagement.UserFileManager.Core + +| 名称 | 值 | 说明 | +| ------------------------- | ---- | -------------------------------- | +| NOTIFY_ADD | 0 | 添加文件集或相册通知的类型。 | +| NOTIFY_UPDATE | 1 | 文件集或相册的更新通知类型。 | +| NOTIFY_REMOVE | 2 | 删除文件集或相册的通知类型。 | +| NOTIFY_ALBUM_ADD_ASSET | 3 | 在相册中添加的文件集的通知类型。 | +| NOTIFY_ALBUM_REMOVE_ASSET | 4 | 在相册中删除的文件集的通知类型。 | + +## DefaultChangeUri10+ + +枚举，DefaultChangeUri子类型。 + +**系统能力**：SystemCapability.FileManagement.UserFileManager.Core + +| 名称 | 值 | 说明 | +| ----------------- | ----------------------- | ------------------------------------------------------------ | +| DEFAULT_PHOTO_URI | file://media/Photo | 默认PhotoAsset的Uri，与forSubUri{true}一起使用，将接收所有PhotoAsset的更改通知。 | +| DEFAULT_ALBUM_URI | file://media/PhotoAlbum | 默认相册的Uri，与forSubUri{true}一起使用，将接收所有相册的更改通知。 | +| DEFAULT_AUDIO_URI | file://media/Audio | 默认AudioAsset的Uri，与forSubUri{true}一起使用，将接收所有AudioAsset的更改通知。 |