diff --git a/zh-cn/application-dev/device-usage-statistics/Readme-CN.md b/zh-cn/application-dev/device-usage-statistics/Readme-CN.md index 96a1726affb32fa51885bb8d46d749fdc278d9b9..8bf4192276362ea60ff3069f3b5534b9b283c75d 100644 --- a/zh-cn/application-dev/device-usage-statistics/Readme-CN.md +++ b/zh-cn/application-dev/device-usage-statistics/Readme-CN.md @@ -1,4 +1,5 @@ # 设备使用信息统计 - [设备使用信息统计概述](device-usage-statistics-overview.md) -- [设备使用信息统计开发指导](device-usage-statistics-dev-guide.md) \ No newline at end of file +- [设备使用信息统计开发指导(待废弃)](device-usage-statistics-dev-guide.md) +- [设备使用信息统计开发指导(新版本)](device-usage-statistics-use-guide.md) \ No newline at end of file diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md index 18c8143806545696068a51a76f06a34f7e34e9df..83c58762b85814da18f16687a8325a8dddad2f70 100644 --- a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md @@ -22,18 +22,6 @@ import stats from '@ohos.bundleState'; | function queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void | 查询当前应用的使用优先级群组。callback形式。 | | function queryAppUsagePriorityGroup(): Promise<number>; | 查询当前应用的使用优先级群组。promise形式。 | | function isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void | 判断指定Bundle Name的应用当前是否是空闲状态。 | -| function getRecentlyUsedModules(callback: AsyncCallback<BundleActiveModuleInfo>): void | 查询FA使用记录，返回不超过1000条FA使用记录。 | -| function getRecentlyUsedModules(maxNum: number, callback: AsyncCallback<BundleActiveModuleInfo>): void | 根据maxNum，查询FA使用记录，返回不超过maxNum条FA使用记录。 maxNum不超过1000| -| function queryAppNotificationNumber(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveEventState>>): void | 通过指定起始和结束时间查询所有应用的通知次数。 | -| function queryBundleActiveEventStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveEventState>>): void | 通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | -| function queryAppUsagePriorityGroup(bundleName : string, callback: AsyncCallback<number>): void | 查询指定应用的使用优先级群组。callback形式。 | -| function queryAppUsagePriorityGroup(bundleName? : string): Promise<number>; | 查询当前调用者应用或者指定应用的使用优先级群组。promise形式。 | -| function setBundleGroup(bundleName : string, newGroup: GroupType, callback: AsyncCallback>boolean>): void | 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功，以callback形式返回。 | -| function setBundleGroup(bundleName : string, newGroup : GroupType): Promise>boolean>; | 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功，以promise形式返回。 | -| function registerGroupCallBack(groupCallback: Callback>BundleActiveGroupCallbackInfo>, callback: AsyncCallback>boolean>): void | 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息，以callback形式返回。 | -| function registerGroupCallBack(groupCallback: Callback>BundleActiveGroupCallbackInfo>): Promise>boolean>; | 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息，以promise形式返回。 | -| function unRegisterGroupCallBack(callback: AsyncCallback>boolean>): void | 解除应用分组监听回调，以callback形式返回。 | -| function unRegisterGroupCallBack(): Promise>boolean>; | 解除应用分组监听回调，以promise形式返回。 | ## 开发步骤 @@ -218,225 +206,6 @@ import stats from '@ohos.bundleState'; } }); ``` - -8. 查询FA使用记录。返回数量最大不超过maxNum设置的值，若不传入maxNum参数，则默认maxNum为1000。config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 - - ```js - import stats from '@ohos.bundleState' - - // 异步方法promise方式 - stats.getRecentlyUsedModules(1000).then(res => { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i])); - } - }).catch(err=> { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code); - }); - - // 无maNum参数异步方法promise方式 - stats.getRecentlyUsedModules().then(res => { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i])); - } - }).catch( err=> { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code); - }); - - // 异步方法callback方式 - stats.getRecentlyUsedModules(1000, (err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i])); - } - } - }); - - // 无maNum参数异步方法callback方式 - stats.getRecentlyUsedModules((err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i])); - } - } - }); - ``` - -9. 通过指定起始和结束时间查询所有应用的通知次数，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 - - ```js - import stats from '@ohos.bundleState' - - // 异步方法promise方式 - stats.queryAppNotificationNumber(0, 20000000000000).then(res => { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise success.'); - console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise result ' + JSON.stringify(res)); - }).catch(err => { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise failed, because: ' + err.code); - }); - - // 异步方法callback方式 - stats.queryAppNotificationNumber(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback success.'); - console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback result ' + JSON.stringify(res)); - } - }); - ``` - -10. 通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 - - ```js - import stats from '@ohos.bundleState' - - // 异步方法promise方式 - stats.queryBundleActiveEventStates(0, 20000000000000).then(res => { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise success.'); - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise result ' + JSON.stringify(res)); - }).catch(err => { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise failed, because: ' + err.code); - }); - - // 异步方法callback方式 - stats.queryBundleActiveEventStates(0, 20000000000000, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback success.'); - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback result ' + JSON.stringify(res)); - } - }); - ``` - -11. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。查询（有参）指定应用的使用优先级群组，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 - - ```js - import stats from '@ohos.bundleState' - - // 无bundleName异步方法promise方式 - stats.queryAppUsagePriorityGroup().then(res => { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res)); - }).catch(err => { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code); - }); - - // 无bundleName异步方法callback方式 - stats.queryAppUsagePriorityGroup((err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); - } - }); - let bundleName = "com.ohos.camera"; - // 有bundleName异步promise方式 - stats.queryAppUsagePriorityGroup(bundleName).then(res => { - console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res)); - }).catch(err => { - console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); - }); - - // 有bundleName异步方法callback方式 - stats.queryAppUsagePriorityGroup(bundleName, (err, res) => { - if (err) { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); - } - }); - ``` - -11. 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功 - - ```javascript - import stats from '@ohos.bundleState' - - // 异步方法promise - stats.setBundleGroup(this.bundleName, this.newGroup).then(() => { - console.log('BUNDLE_ACTIVE SetBundleGroup promise succeeded.'); - }).catch( err => { - console.log('BUNDLE_ACTIVE SetBundleGroup promise failed. because: ' + err.code); - }); - // 异步方法callback - stats.setBundleGroup(this.bundleName, this.newGroup, (err) => { - if (err) { - console.log('BUNDLE_ACTIVE SetBundleGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE SetBundleGroup callback succeeded.'); - } - }); - ``` - -12. 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息 - - ```javascript - import stats from '@ohos.bundleState' - - // 异步方法promise形式 - let onBundleGroupChanged = (err,res) => { - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result oldGroup is : ' + res.oldGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result newGroup is : ' + res.newGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result changeReason is : ' + res.newGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result userId is : ' + res.userId); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result bundleName is : ' + res.bundleName); - }; - stats.registerGroupCallBack(onBundleGroupChanged).then(() => { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise succeeded.'); - }).catch(err => { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise failed. because: ' + err.code); - }); - // 异步方法callback形式 - let onBundleGroupChanged = (err,res) => { - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s oldGroup is : ' + res.oldGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s newGroup is : ' + res.newGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s changeReason is : ' + res.newGroup); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s userId is : ' + res.userId); - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result‘s bundleName is : ' + res.bundleName); - }; - stats.registerGroupCallBack(onBundleGroupChanged, (err) => { - if (err) { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback success.'); - } - }); - ``` - -13. 解除应用分组监听回调 - - ```javascript - import stats from '@ohos.bundleState' - - // promise - stats.unRegisterGroupCallBack().then(() => { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise succeeded.'); - }).catch(err => { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise failed. because: ' + err.code); - }); - // callback - stats.unRegisterGroupCallBack((err) => { - if (err) { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback success.'); - } - }); - ``` ## 相关实例 针对设备使用信息统计，有以下相关实例可供参考： - [`DeviceUsageStatistics`：设备使用信息统计（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/DeviceUsageStatistics) diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-use-guide.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-use-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..543bdf908746c03b6023ddadd595c2c0b9186b4e --- /dev/null +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-use-guide.md @@ -0,0 +1,550 @@ +# 设备使用信息统计 + +## 场景介绍 + +设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（app group）情况。 +部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。 + +## 接口说明 +注册相关接口包导入： +```js +import usageStatistics from '@ohos.resourceschedule.usageStatistics'; +``` + +**表1** 设备使用信息统计主要接口 + +| 接口名 | 描述 | +| -------- | -------- | +| function queryBundleEvents(begin: number, end: number, callback: AsyncCallback<Array<BundleEvents>>): void | 通过指定起始和结束时间查询所有应用的事件集合。 | +| function queryBundleStatsInfos(begin: number, end: number, callback: AsyncCallback<BundleStatsMap>): void | 通过指定起始和结束时间查询应用使用时长统计信息。 | +| function queryCurrentBundleEvents(begin: number, end: number, callback: AsyncCallback<Array<BundleEvents>>): void | 通过指定起始和结束时间查询当前应用的事件集合。 | +| function queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStatsInfo>>): void | 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | +| function queryAppGroup(callback: AsyncCallback<number>): void | 查询当前应用的使用优先级群组。callback形式。 | +| function queryAppGroup(): Promise<number>; | 查询当前应用的使用优先级群组。promise形式。 | +| function queryAppGroup(bundleName : string, callback: AsyncCallback<number>): void | 查询指定应用的使用优先级群组。callback形式。 | +| function queryAppGroup(bundleName : string): Promise<number>; | 查询当前调用者应用或者指定应用的使用优先级群组。promise形式。 | +| function isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void | 判断指定Bundle Name的应用当前是否是空闲状态。 | +| function queryModuleUsageRecords(callback: AsyncCallback<HapModuleInfo>): void | 查询FA使用记录，返回不超过1000条FA使用记录。 | +| function queryModuleUsageRecords(maxNum: number, callback: AsyncCallback<HapModuleInfo>): void | 根据maxNum，查询FA使用记录，返回不超过maxNum条FA使用记录。 maxNum不超过1000| +| function queryNotificationEventStats(begin: number, end: number, callback: AsyncCallback<Array<NotificationEventStats>>): void | 通过指定起始和结束时间查询所有应用的通知次数。 | +| function queryDeviceEventStats(begin: number, end: number, callback: AsyncCallback<Array<DeviceEventStats>>): void | 通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | +| function setAppGroup(bundleName : string, newGroup: GroupType, callback: AsyncCallback>boolean>): void | 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功，以callback形式返回。 | +| function setAppGroup(bundleName : string, newGroup : GroupType): Promise>boolean>; | 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功，以promise形式返回。 | +| function registerAppGroupCallBack(groupCallback: Callback>AppGroupCallbackInfo>, callback: AsyncCallback>boolean>): void | 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息，以callback形式返回。 | +| function registerAppGroupCallBack(groupCallback: Callback>AppGroupCallbackInfo>): Promise>boolean>; | 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息，以promise形式返回。 | +| function unRegisterAppGroupCallBack(callback: AsyncCallback>boolean>): void | 解除应用分组监听回调，以callback形式返回。 | +| function unRegisterAppGroupCallBack(): Promise>boolean>; | 解除应用分组监听回调，以promise形式返回。 | + +## 开发步骤 + +1. 在config.json文件中配置设备使用信息统计权限。 + + ```json + "module": { + "package": "com.example.deviceUsageStatistics", + ..., + "reqPermissions": [ + { + "name": "ohos.permission.BUNDLE_ACTIVE_INFO" + } + ] + } + ``` + +2. 通过指定起始和结束时间查询所有应用的事件集合，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryBundleEvents(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryBundleEvents promise success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleEvents promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleEvents promise result ' + JSON.stringify(res[i])); + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryBundleEvents promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryBundleEvents(0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryBundleEvents callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryBundleEvents callback success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleEvents callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleEvents callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +3. 通过指定起始和结束时间查询应用使用时长统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryBundleStatsInfos(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise success.'); + let i = 1; + for(let key in res){ + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise number : ' + i); + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise result ' + JSON.stringify(res[key])); + i++; + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryBundleStatsInfos(0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback success.'); + let i = 1; + for(let key in res){ + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback number : ' + i); + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback result ' + JSON.stringify(res[key])); + i++; + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +4. 通过指定起始和结束时间查询当前应用的事件集合，config.json中不需要配置权限。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryCurrentBundleEvents(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise result ' + JSON.stringify(res[i])); + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryCurrentBundleEvents(0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +5. 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise result ' + JSON.stringify(res[i])); + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +6. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // promise方式 + try{ + usageStatistics.queryAppGroup().then( res => { + console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('BUNDLE_ACTIVE queryAppGroup promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // callback方式 + try{ + usageStatistics.queryAppGroup((err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryAppGroup callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +7. 判断指定Bundle Name的应用当前是否是空闲状态，config.json中不需要配置权限，三方应用只能查询自身的空闲状态。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.isIdleState("com.ohos.camera").then( res => { + console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('BUNDLE_ACTIVE isIdleState promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.isIdleState("com.ohos.camera", (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE isIdleState callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); + } + }); + } catch(error) { + console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +8. 查询FA使用记录。返回数量最大不超过maxNum设置的值，若不传入maxNum参数，则默认maxNum为1000。config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryModuleUsageRecords(1000).then( res => { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); + } + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 无maNum参数异步方法promise方式 + try{ + usageStatistics.queryModuleUsageRecords().then( res => { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); + } + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryModuleUsageRecords(1000, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 无maNum参数异步方法callback方式 + try{ + usageStatistics.queryModuleUsageRecords((err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +9. 通过指定起始和结束时间查询所有应用的通知次数，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryNotificationEventStats(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryNotificationEventStats promise success.'); + console.log('BUNDLE_ACTIVE queryNotificationEventStats promise result ' + JSON.stringify(res)); + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryNotificationEventStats promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryNotificationEventStats(0, 20000000000000, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryNotificationEventStats callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryNotificationEventStats callback success.'); + console.log('BUNDLE_ACTIVE queryNotificationEventStats callback result ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +10. 通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise方式 + try{ + usageStatistics.queryDeviceEventStats(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryDeviceEventStates promise success.'); + console.log('BUNDLE_ACTIVE queryDeviceEventStates promise result ' + JSON.stringify(res)); + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryDeviceEventStats promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback方式 + try{ + usageStatistics.queryDeviceEventStats(0, 20000000000000, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryDeviceEventStats callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryDeviceEventStats callback success.'); + console.log('BUNDLE_ACTIVE queryDeviceEventStats callback result ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +11. 查询（无参）当前调用者应用的使用优先级群组，config.json中不需要配置权限。查询（有参）指定应用的使用优先级群组，config.json中需要配置权限：ohos.permission.BUNDLE_ACTIVE_INFO。 + + ```js + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 有bundleName异步promise方式 + let bundleName = "com.ohos.camera"; + try{ + usageStatistics.queryAppGroup(bundleName).then( res => { + console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('BUNDLE_ACTIVE queryAppGroup promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 有bundleName异步方法callback方式 + let bundleName = "com.ohos.camera"; + try{ + usageStatistics.queryAppGroup(bundleName, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryAppGroup callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +11. 给应用名是bundleName的应用分组设置成newGroup，返回设置结果是否成功 + + ```javascript + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise + let bundleName = "com.example.deviceUsageStatistics"; + let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY; + + try{ + usageStatistics.setAppGroup(bundleName, newGroup).then( () => { + console.log('BUNDLE_ACTIVE setAppGroup promise succeeded.'); + }).catch( err => { + console.log('BUNDLE_ACTIVE setAppGroup promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback + let bundleName = "com.example.deviceUsageStatistics"; + let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY; + + try{ + usageStatistics.setAppGroup(bundleName, newGroup, (err) => { + if(err) { + console.log('BUNDLE_ACTIVE setAppGroup callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE setAppGroup callback succeeded.'); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +12. 注册应用分组变化监听回调，返回注册是否成功，当应用分组发生变化时，会给所有已注册的监听者返回回调信息 + + ```javascript + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // 异步方法promise形式 + let onBundleGroupChanged = (res) =>{ + console.log('BUNDLE_ACTIVE registerAppGroupCallBack RegisterGroupCallBack callback success.'); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); + }; + try{ + usageStatistics.registerAppGroupCallBack(onBundleGroupChanged).then( () => { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise succeeded.'); + }).catch( err => { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // 异步方法callback形式 + let onBundleGroupChanged = (err, res) =>{ + console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); + }; + try{ + usageStatistics.registerAppGroupCallBack(onBundleGroupChanged, error => { + if(error) { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback success.'); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +13. 解除应用分组监听回调 + + ```javascript + import usageStatistics from '@ohos.resourceschedule.usageStatistics' + + // promise + try{ + usageStatistics.unRegisterAppGroupCallBack().then( () => { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack promise succeeded.'); + }).catch( err => { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } + + // callback + try{ + usageStatistics.unRegisterAppGroupCallBack(error => { + if(error) { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack callback success.'); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` +## 相关实例 +针对设备使用信息统计，有以下相关实例可供参考： +- [`DeviceUsageStatistics`：设备使用信息统计（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/master/device/DeviceUsageStatistics) + diff --git a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md index 6b99171e10220d85932ad78e8f3b33bc48c4aa1a..31180d10ce0cdf57d4e57d8ed7a4d714ae33543f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md +++ b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @@ -5,11 +5,8 @@ 设备使用信息统计，系统应用可调用接口实现如下功能： - 查询设备上各应用在不同时间段的使用时长、各应用的事件（前台、后台、长时任务开始、长时任务结束）信息及各应用的通知次数信息。 -- 查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 -- 查询应用分组信息（其他应用和自身应用）。 +- 查询应用分组信息（仅限自身应用）。 - 查询应用空闲状态（其他应用和自身应用）。 -- 设置应用分组信息（其他应用）。 -- 注册和解除注册应用分组变化监听。 三方应用可调用接口实现如下功能： @@ -432,634 +429,6 @@ queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array< }); ``` -## bundleState.getRecentlyUsedModules9+ - -getRecentlyUsedModules(maxNum?: number): Promise<Array<BundleActiveModuleInfo>> - -据maxNum，查询FA使用记录，使用Promise形式返回不超过maxNum条FA使用记录，FA使用记录由近及远排序，maxNum最大为1000。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ---------------------------------- | -| maxNum | number | 否 | 返回条目的最大数量，最多支持1000条。若不填写，则默认为1000。 | - -**返回值**： - -| 类型 | 说明 | -| ---------------------------------------- | ---------------------------------- | -| Promise<Array<[BundleActiveModuleInfo](#bundleactivemoduleinfo9)>> | 指定的Promise回调方法。返回不超过maxNum条FA使用记录。 | - -**示例**： - - ```js - bundleState.getRecentlyUsedModules(1000).then( res => { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i])); - } - }).catch( err=> { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code); - }); - - // 无maxNum参数调用方式 - bundleState.getRecentlyUsedModules().then( res => { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i])); - } - }).catch( err=> { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code); - }); - ``` - -## bundleState.getRecentlyUsedModules9+ - -getRecentlyUsedModules(callback: AsyncCallback<Array<BundleActiveModuleInfo>>): void - -查询FA使用记录。使用CallBack形式返回数量不超过1000条FA使用记录（FA记录按时间由近及远排序）。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------------------------------- | -| callback | AsyncCallback<Array<[BundleActiveModuleInfo](#bundleactivemoduleinfo9)>> | 是 | 指定的CallBack回调方法。返回不超过maxNum条FA使用记录。 | - -**示例**： - - ```js - bundleState.getRecentlyUsedModules((err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i])); - } - } - }); - ``` - -## bundleState.getRecentlyUsedModules9+ - -getRecentlyUsedModules(maxNum: number, callback: AsyncCallback<Array<BundleActiveModuleInfo>>): void - -查询FA使用记录。使用CallBack形式返回数量最大不超过maxNum设置的值，FA使用记录由近及远排序，maxNum最大为1000。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------------------------------- | -| maxNum | number | 是 | 返回FA记录的最大数量，maxNum最大为1000。| -| callback | AsyncCallback<Array<[BundleActiveModuleInfo](#bundleactivemoduleinfo9)>> | 是 | 指定的CallBack回调方法。返回不超过maxNum条FA使用记录。 | - -**示例**： - - ```js - bundleState.getRecentlyUsedModules(1000,(err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.'); - for (let i = 0; i < res.length; i++) { - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1)); - console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i])); - } - } - }); - ``` - -## bundleState.queryAppUsagePriorityGroup9+ - -queryAppUsagePriorityGroup(bundleName? : string): Promise<number> - -可选参数。有参则查询指定bundleName的应用的分组。无参数时查询当前应用的分组。使用Promise形式返回其应用分组结果。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ---------------------------------------- | -| bundleName | string | 否 | 可选参数。有参则查询指定bundleName的应用的分组。无参数时查询当前应用的分组。 | - -**返回值**： - -| 类型 | 说明 | -| --------------- | --------------------------- | -| Promise<number> | 指定的Promise回调方法。返回查询的应用分组结果。 | - -**示例**： - -```javascript -//有bundleName的promise -let bundleName = "com.ohos.camera"; -bundleState.queryAppUsagePriorityGroup(bundleName).then( res => { - console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res)); -}).catch( err => { - console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); -}); -//无bundleName的promise -bundleState.queryAppUsagePriorityGroup().then( res => { - console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res)); -}).catch( err => { - console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); -}); -``` - -## bundleState.queryAppUsagePriorityGroup9+ - -queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void - -查询当前应用的分组。使用callback形式返回其应用分组。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------- | ---- | ---------------------------------------- | -| callback | AsyncCallback<number> | 是 | 指定的CallBack回调方法。返回当前应用的分组。 | - -**示例**： - -```javascript -bundleState.queryAppUsagePriorityGroup((err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); - } -}); -``` - -## bundleState.queryAppUsagePriorityGroup9+ - -queryAppUsagePriorityGroup(bundleName : string, callback: AsyncCallback<number>): void - -查询指定bundleName对应应用的分组。使用callback形式返回其应用分组。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------------------- | ---- | ---------------------------------------- | -| bundleName | string | 是 | 查询指定bundleName对应应用的分组。 | -| callback | AsyncCallback<number> | 是 | 指定的CallBack回调方法。返回制指定bundleName的应用分组。| - -**示例**： - -```javascript -let bundleName = "com.ohos.camera"; -bundleState.queryAppUsagePriorityGroup(bundleName, (err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); - } -}); -``` - -## bundleState.setBundleGroup9+ - -setBundleGroup(bundleName: string, newGroup: GroupType): Promise<void> - -将指定bundleName的应用的分组设置为newGroup，使用Promise形式返回设置是否成功。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | --------- | ---- | ---- | -| bundleName | string | 是 | 应用名称 | -| newGroup | [GroupType](#grouptype) | 是 | 应用分组 | - -**返回值**： - -| 类型 | 说明 | -| ------------- | ------------------------- | -| Promise<void> | 指定的Promise回调方法。返回本次设置是否成功 | - -**示例**： - -```javascript -let bundleName = "com.example.deviceUsageStatistics"; -let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY; - -bundleState.setBundleGroup(bundleName, newGroup).then( () => { - console.log('BUNDLE_ACTIVE SetBundleGroup promise succeeded.'); -}).catch( err => { - console.log('BUNDLE_ACTIVE SetBundleGroup promise failed. because: ' + err.code); -}); -``` - -## bundleState.setBundleGroup9+ - -setBundleGroup(bundleName: string, newGroup: GroupType, callback: AsyncCallback<void>): void - -将指定bundleName的应用的分组设置为newGroup，使用CallBack形式返回设置是否成功。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ---------- | ------------------- | ---- | ------------------------- | -| bundleName | string | 是 | 应用名称 | -| newGroup | [GroupType](#grouptype) | 是 | 应用分组 | -| callback | AsyncCallback<void> | 是 | 指定的CallBack回调方法。返回设置是否成功。 | - -**示例**： - -```javascript -let bundleName = "com.example.deviceUsageStatistics"; -let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY; - -bundleState.setBundleGroup(bundleName, newGroup, (err) => { - if(err) { - console.log('BUNDLE_ACTIVE SetBundleGroup callback failed. because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE SetBundleGroup callback succeeded.'); - } -}); -``` - -## bundleState.registerGroupCallBack9+ - -registerGroupCallBack(groupCallback: Callback<BundleActiveGroupCallbackInfo>): Promise<void> - -应用注册分组变化监听，待用户名下的某个应用分组发生变化时，通过callback形式向所有已注册分组变化监听的应用返回[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)信息。使用Promise形式返回注册是否成功。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | -| callback | Callback<[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)> | 是 | 指定的callback函数，返回应用分组变化的信息 | - -**返回值**： - -| 类型 | 说明 | -| ------------- | ----------------------- | -| Promise<void> | 指定的Promise回调方法。返回注册监听是否成功 | - -**示例**： - -```javascript -let onBundleGroupChanged = (err,res) =>{ - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageOldGroup is : ' + res.appUsageOldGroup); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageNewGroup is : ' + res.appUsageNewGroup); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result changeReason is : ' + res.changeReason); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result userId is : ' + res.userId); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result bundleName is : ' + res.bundleName); -}; -bundleState.registerGroupCallBack(onBundleGroupChanged).then( () => { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise succeeded.'); -}).catch( err => { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise failed. because: ' + err.code); -}); -``` - -## bundleState.registerGroupCallBack9+ - -registerGroupCallBack(groupCallback: Callback<BundleActiveGroupCallbackInfo>, callback: AsyncCallback<void>): void - -应用注册分组变化监听，待用户名下的某个应用分组发生变化时，通过callback形式向所有已注册分组变化监听的应用返回[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)信息。使用异步callback形式返回注册监听是否成功。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | -| callback | Callback<[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)> | 是 | 指定的callback函数，返回应用分组变化的信息 | -| callback | AsyncCallback<void> | 是 | 指定的异步callback函数，返回注册监听是否成功 | - -**示例**： - -```javascript -let onBundleGroupChanged = (err,res) =>{ - console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageOldGroup is : ' + res.appUsageOldGroup); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageNewGroup is : ' + res.appUsageNewGroup); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result changeReason is : ' + res.changeReason); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result userId is : ' + res.userId); - console.log('BUNDLE_ACTIVE RegisterGroupCallBack result bundleName is : ' + res.bundleName); -}; -bundleState.registerGroupCallBack(onBundleGroupChanged, (err)=>{ - if(err) { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback success.'); - } -}); -``` - -## bundleState.unRegisterGroupCallBack9+ - -unRegisterGroupCallBack(): Promise<void> - -应用解除分组变化监听，解除通过调用注册接口生成的监听。使用Promise形式返回解除监听是否成功。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**：无参数 - -**返回值**： - -| 类型 | 说明 | -| ------------- | ------------------------ | -| Promise<void> | 指定的Promise回调方法。返回解除监听是否成功 | - -**示例**： - -```javascript -bundleState.unRegisterGroupCallBack().then( () => { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise succeeded.'); -}).catch( err => { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise failed. because: ' + err.code); -}); -``` - -## bundleState.unRegisterGroupCallBack9+ - -unRegisterGroupCallBack(callback: AsyncCallback<void>): void; - -应用解除分组变化监听，解除通过调用注册接口生成的监听。使用异步callback形式返回解除监听是否成功。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------- | ---- | -------------- | -| callback | AsyncCallback<void> | 是 | 解除监听是否成功的异步回调函数 | - -**示例**： - -```javascript -bundleState.unRegisterGroupCallBack((err)=>{ - if(err) { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback success.'); - } -}); -``` - -## bundleState.queryBundleActiveEventStates9+ - -queryBundleActiveEventStates(begin: number, end: number): Promise<Array<BundleActiveEventState>> - -通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，使用Promise形式返回。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | - -**返回值**： - -| 类型 | 说明 | -| ---------------------------------------- | ---------------------------------------- | -| Promise<Array<[BundleActiveEventState](#bundleactiveeventstate9)>> | 指定的Promise回调方法。返回指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | - -**示例**： - - ```js - bundleState.queryBundleActiveEventStates(0, 20000000000000).then( res => { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise success.'); - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise result ' + JSON.stringify(res)); - }).catch( err=> { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise failed, because: ' + err.code); - }); - ``` - -## bundleState.queryBundleActiveEventStates9+ - -queryBundleActiveEventStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveEventState>>): void - -通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，使用Callback形式返回。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ---------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | -| callback | AsyncCallback<Array<[BundleActiveEventState](#bundleactiveeventstate9)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | - -**示例**： - - ```js - bundleState.queryBundleActiveEventStates(0, 20000000000000, (err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback success.'); - console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback result ' + JSON.stringify(res)); - } - }); - ``` - -## bundleState.queryAppNotificationNumber9+ - -queryAppNotificationNumber(begin: number, end: number): Promise<Array<BundleActiveEventState>> - -通过指定起始和结束时间查询所有应用的通知次数信息，使用Promise形式返回。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | - -**返回值**： - -| 类型 | 说明 | -| ---------------------------------------- | ---------------------------------------- | -| Promise<Array<[BundleActiveEventState](#bundleactiveeventstate9)>> | 指定的Promise回调方法。返回指定起始和结束时间查询所有应用的通知次数信息。 | - -**示例**： - - ```js - bundleState.queryAppNotificationNumber(0, 20000000000000).then( res => { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise success.'); - console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise result ' + JSON.stringify(res)); - }).catch( err=> { - console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise failed, because: ' + err.code); - }); - ``` - -## bundleState.queryAppNotificationNumber9+ - -queryAppNotificationNumber(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveEventState>>): void - -通过指定起始和结束时间查询所有应用的通知次数信息，使用Callback形式返回。 - -**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO - -**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ---------------------------------------- | -| begin | number | 是 | 起始时间。 | -| end | number | 是 | 结束时间。 | -| callback | AsyncCallback<Array<[BundleActiveEventState](#bundleactiveeventstate9)>> | 是 | 指定的callback回调方法。返回通过指定起始和结束时间查询所有应用的通知次数信息。 | - -**示例**： - - ```js - bundleState.queryAppNotificationNumber(0, 20000000000000, (err, res) => { - if(err) { - console.log('BUNDLE_ACTIVE queryAppNotificationNumberCallBack callback failed, because: ' + err.code); - } else { - console.log('BUNDLE_ACTIVE queryAppNotificationNumberCallBack callback success.'); - console.log('BUNDLE_ACTIVE queryAppNotificationNumberCallBack callback result ' + JSON.stringify(res)); - } - }); - ``` - -## BundleActiveModuleInfo9+ -FA的使用信息的属性集合。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -| 参数名 | 类型 | 必填 | 说明 | -| -------------------- | ---------------------------------------- | ---- | ----------------------------- | -| deviceId | string | 否 | FA所属deviceId。 | -| bundleName | string | 是 | FA所属应用包名。 | -| moduleName | string | 是 | FA所属module名。 | -| abilityName | string | 否 | FA的MainAbility名。 | -| appLabelId | number | 否 | FA的应用labelId。 | -| labelId | number | 否 | FA所属module的labelId。 | -| descriptionId | number | 否 | FA所属的应用descriptionId。 | -| abilityLableId | number | 否 | FA的MainAbility labelId。 | -| abilityDescriptionId | number | 否 | FA的MainAbility descriptionId。 | -| abilityIconId | number | 否 | FA的MainAbility iconId。 | -| launchedCount | number | 是 | FA的启动次数。 | -| lastModuleUsedTime | number | 是 | FA的上一次使用时间。 | -| formRecords | Array<[BundleActiveFormInfo](#bundleactiveforminfo9)> | 是 | FA中卡片的使用记录。 | - -## BundleActiveFormInfo9+ -FA卡片的使用信息的属性集合。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -| 参数名 | 类型 | 必填 | 说明 | -| ---------------- | ------ | ---- | ----------- | -| formName | string | 是 | 卡片名称。 | -| formDimension | number | 是 | 卡片尺寸。 | -| formId | number | 是 | 卡片Id。 | -| formLastUsedTime | number | 是 | 卡片的上一次点击时间。 | -| count | number | 是 | 卡片的点击次数。 | - -## BundleActiveGroupCallbackInfo9+ - -应用分组变化回调返回的属性集合 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -| 参数名 | 类型 | 必填 | 说明 | -| ---------------- | ------ | ---- | ---------------- | -| appUsageOldGroup | number | 是 | 变化前的应用分组 | -| appUsageNewGroup | number | 是 | 变化后的应用分组 | -| userId | number | 是 | 用户id | -| changeReason | number | 是 | 分组变化原因 | -| bundleName | string | 是 | 应用名称 | - ## BundleStateInfo 提供应用使用时长的具体信息。 @@ -1106,20 +475,6 @@ FA卡片的使用信息的属性集合。 | ------------------------------ | ---------------------------------------- | ---- | -------------- | | [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | 是 | 不同应用的使用时长统计信息。 | -## BundleActiveEventState9+ - -提供通知、系统事件的统计信息。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ----------------- | -| name | string | 是 | 通知应用包名或者系统事件名。 | -| eventId | number | 是 | 通知、系统事件类型。 | -| count | number | 是 | 应用通知次数或者系统事件触发次数。 | - ## IntervalType 提供应用使用时长的查询类型。 @@ -1132,21 +487,4 @@ FA卡片的使用信息的属性集合。 | BY_DAILY | 1 | 表示系统按照天去查询指定时间段间隔的应用使用时长信息。 | | BY_WEEKLY | 2 | 表示系统按照周去查询指定时间段间隔的应用使用时长信息。 | | BY_MONTHLY | 3 | 表示系统按照月去查询指定时间段间隔的应用使用时长信息。 | -| BY_ANNUALLY | 4 | 表示系统按照年去查询指定时间段间隔的应用使用时长信息。 | - -## GroupType9+ - -提供应用分组的设置类型。 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.AppGroup - -**系统API**：此接口为系统接口，三方应用不支持调用。 - -| 名称 | 默认值 | 说明 | -| ------------------ | ---- | ----------------- | -| ACTIVE_GROUP_ALIVE | 10 | 活跃分组。 | -| ACTIVE_GROUP_DAILY | 20 | 经常使用，但当前并未在活跃态。 | -| ACTIVE_GROUP_FIXED | 30 | 常用分组，定期使用，但不是每天使用。 | -| ACTIVE_GROUP_RARE | 40 | 极少使用分组，不经常使用。 | -| ACTIVE_GROUP_LIMIT | 50 | 受限使用分组。 | -| ACTIVE_GROUP_NEVER | 60 | 从未使用分组，安装但是从未运行过。 | \ No newline at end of file +| BY_ANNUALLY | 4 | 表示系统按照年去查询指定时间段间隔的应用使用时长信息。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-resourceschedule-deviceUsageStatistics.md b/zh-cn/application-dev/reference/apis/js-apis-resourceschedule-deviceUsageStatistics.md new file mode 100644 index 0000000000000000000000000000000000000000..87f958d21fa50879186735c925dad964b4eb565c --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-resourceschedule-deviceUsageStatistics.md @@ -0,0 +1,1267 @@ +# 设备使用信息统计 + +本模块提供设备使用信息统计能力。 + +设备使用信息统计，系统应用可调用接口实现如下功能： + +- 查询设备上各应用在不同时间段的使用时长、各应用的事件（前台、后台、长时任务开始、长时任务结束）信息及各应用的通知次数信息。 +- 查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 +- 查询应用分组信息（其他应用和自身应用）。 +- 查询应用空闲状态（其他应用和自身应用）。 +- 设置应用分组信息（其他应用）。 +- 注册和解除注册应用分组变化监听。 + +三方应用可调用接口实现如下功能： + +- 查询应用空闲状态（仅限自身应用）。 +- 查询应用分组信息（仅限自身应用）。 +- 查询应用事件（仅限自身应用）。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +``` +import usageStatistics from '@ohos.resourceschedule.usageStatistics' +``` + +## usageStatistics.isIdleState + +isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void + +判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，使用Callback形式返回。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------- | ---- | ---------------------------------------- | +| bundleName | string | 是 | 应用的bundleName。 | +| callback | AsyncCallback<boolean> | 是 | 指定的callback回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | + +**示例**： + + ``` + try{ + usageStatistics.isIdleState("com.ohos.camera", (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE isIdleState callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); + } + }); + } catch(error) { + console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## bundleState.isIdleState + +isIdleState(bundleName: string): Promise<boolean> + +判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，使用Promise形式返回。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | -------------- | +| bundleName | string | 是 | 应用的bundleName。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------- | ---------------------------------------- | +| Promise<boolean> | 指定的Promise回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | + +**示例**： + + ```js + try{ + usageStatistics.isIdleState("com.ohos.camera").then( res => { + console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('BUNDLE_ACTIVE isIdleState promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryAppGroup + +queryAppGroup(): Promise<number> + +查询当前应用的优先级分组。使用Promise形式返回其应用分组。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**返回值**： + +| 类型 | 说明 | +| --------------- | --------------------------- | +| Promise<number> | 指定的Promise回调方法。返回查询的应用分组结果。 | + +**示例**： + +```javascript + try{ + usageStatistics.queryAppGroup().then( res => { + console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('BUNDLE_ACTIVE queryAppGroup promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.queryAppGroup + +queryAppGroup(callback: AsyncCallback<number>): void + +查询当前应用的优先级分组。使用callback形式返回其应用分组。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | -------------------------- | +| callback | AsyncCallback<number> | 是 | 指定的CallBack回调方法。返回查询的应用分组。 | + +**示例**： + +```javascript + try{ + usageStatistics.queryAppGroup((err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryAppGroup callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.queryBundleStatsInfos + +queryBundleStatsInfos(begin: number, end: number, callback: AsyncCallback<BundleStatsMap>): void + +通过指定起始和结束时间查询应用使用时长统计信息，使用Callback形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------------------------------------- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | +| callback | AsyncCallback<[BundleStatsMap](#bundlestatsmap)> | 是 | 指定的callback回调方法。返回指定起始和结束时间内应用使用时长统计信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryBundleStatsInfos(0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback success.'); + let i = 1; + for(let key in res){ + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback number : ' + i); + console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback result ' + JSON.stringify(res[key])); + i++; + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryBundleStatsInfos + +queryBundleStatsInfos(begin: number, end: number): Promise<BundleStatsMap> + +通过指定起始和结束时间查询应用使用时长统计信息，使用Promise形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------------------- | +| Promise<[BundleStatsMap](#bundlestatsmap)> | 指定的Promise回调方法。返回指定起始和结束时间内应用使用时长统计信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryBundleStatsInfos(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise success.'); + let i = 1; + for(let key in res){ + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise number : ' + i); + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise result ' + JSON.stringify(res[key])); + i++; + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryBundleStatsInfoByInterval + +queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStatsInfo>>): void + +通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Callback形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | +| byInterval | [IntervalType](#intervaltype) | 是 | 查询类型。 | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | +| callback | AsyncCallback<Array<[BundleStatsInfo](#bundlestatsinfo)>> | 是 | 指定的callback回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryBundleStatsInfoByInterval + +queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise<Array<BundleStatsInfo>> + +通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Promise形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ----------------------------- | ---- | ----- | +| byInterval | [IntervalType](#intervaltype) | 是 | 查询类型。 | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | ---------------------------------------- | +| Promise<Array<[BundleStatsInfo](#bundlestatsinfo)>> | 指定的Promise回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise result ' + JSON.stringify(res[i])); + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryBundleEvents + +queryBundleEvents(begin: number, end: number, callback: AsyncCallback<Array<BundleEvents>>): void + +通过指定起始和结束时间查询所有应用的事件集合，使用Callback形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------------------------------------- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | +| callback | AsyncCallback<Array<[BundleEvents](#bundleevents)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询所有应用的事件集合。 | + +**示例**： + + ```js + try{ + usageStatistics.queryBundleEvents(0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryBundleEvents callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryBundleEvents callback success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleEvents callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleEvents callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryBundleEvents + +queryBundleEvents(begin: number, end: number): Promise<Array<BundleEvents>> + +通过指定起始和结束时间查询所有应用的事件集合，使用Promise形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------------------- | +| Promise<Array<[BundleEvents](#bundleevents)>> | 指定的Promise回调方法。返回指定起始和结束时间查询所有应用的事件集合。 | + +**示例**： + + ```js + try{ + usageStatistics.queryBundleEvents(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryBundleEvents promise success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryBundleEvents promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryBundleEvents promise result ' + JSON.stringify(res[i])); + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryBundleEvents promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryCurrentBundleEvents + +queryCurrentBundleEvents(begin: number, end: number, callback: AsyncCallback<Array<BundleEvents>>): void + +通过指定起始和结束时间查询当前应用的事件集合，使用Callback形式返回。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------------------------------------- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | +| callback | AsyncCallback<Array<[BundleEvents](#bundleevents)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | + +**示例**： + + ```js + try{ + usageStatistics.queryCurrentBundleEvents(0, 20000000000000, (err, res) => { + if (err) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryCurrentBundleEvents + +queryCurrentBundleEvents(begin: number, end: number): Promise<Array<BundleEvents>> + +通过指定起始和结束时间查询当前应用的事件集合，使用Promise形式返回。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------------------- | +| Promise<Array<[BundleEvents](#bundleevents)>> | 指定的Promise回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | + +**示例**： + + ```js + try{ + usageStatistics.queryCurrentBundleEvents(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise success.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise result ' + JSON.stringify(res[i])); + } + }).catch( err => { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryModuleUsageRecords + +queryModuleUsageRecords(): Promise<Array<HapModuleInfo>> + +使用Promise形式返回不超过1000条FA使用记录，FA使用记录由近及远排序。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | ---------------------------------- | +| Promise<Array<[HapModuleInfo](#hapmoduleinfo9)>> | 指定的Promise回调方法。返回不超过1000条FA使用记录。 | + +**示例**： + + ```js + // 无maxNum参数调用方式 + try{ + usageStatistics.queryModuleUsageRecords().then( res => { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); + } + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryModuleUsageRecords + +queryModuleUsageRecords(callback: AsyncCallback<Array<HapModuleInfo>>): void + +查询FA使用记录。使用CallBack形式返回数量不超过1000条FA使用记录（FA记录按时间由近及远排序）。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------------------------------- | +| callback | AsyncCallback<Array<[HapModuleInfo](#hapmoduleinfo9)>> | 是 | 指定的CallBack回调方法。返回不超过maxNum条FA使用记录。 | + +**示例**： + + ```js + try{ + usageStatistics.queryModuleUsageRecords((err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryModuleUsageRecords + +queryModuleUsageRecords(maxNum: number): Promise<Array<HapModuleInfo>> + +据maxNum，查询FA使用记录，使用Promise形式返回不超过maxNum条FA使用记录，FA使用记录由近及远排序，maxNum最大为1000。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------------------- | +| maxNum | number | 是 | 返回条目的最大数量，最多支持1000条。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | ---------------------------------- | +| Promise<Array<[HapModuleInfo](#hapmoduleinfo9)>> | 指定的Promise回调方法。返回不超过maxNum条FA使用记录。 | + +**示例**： + + ```js + try{ + usageStatistics.queryModuleUsageRecords(1000).then( res => { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); + } + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryModuleUsageRecords + +queryModuleUsageRecords(maxNum: number, callback: AsyncCallback<Array<HapModuleInfo>>): void + +查询FA使用记录。使用CallBack形式返回数量最大不超过maxNum设置的值，FA使用记录由近及远排序，maxNum最大为1000。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------------------------------- | +| maxNum | number | 是 | 返回FA记录的最大数量，maxNum最大为1000。| +| callback | AsyncCallback<Array<[HapModuleInfo](#hapmoduleinfo9)>> | 是 | 指定的CallBack回调方法。返回不超过maxNum条FA使用记录。 | + +**示例**： + + ```js + try{ + usageStatistics.queryModuleUsageRecords(1000, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); + for (let i = 0; i < res.length; i++) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); + console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); + } + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryAppGroup + +queryAppGroup(bundleName : string): Promise<number> + +查询指定bundleName的应用的优先级分组。使用Promise形式返回其应用分组结果。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ---------------------------------------- | +| bundleName | string | 是 | 查询指定bundleName的应用的优先级分组。 | + +**返回值**： + +| 类型 | 说明 | +| --------------- | --------------------------- | +| Promise<number> | 指定的Promise回调方法。返回查询的应用分组结果。 | + +**示例**： + +```javascript +//有bundleName的promise + let bundleName = "com.ohos.camera"; + try{ + usageStatistics.queryAppGroup(bundleName).then( res => { + console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('BUNDLE_ACTIVE queryAppGroup promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.queryAppGroup + +queryAppGroup(bundleName : string, callback: AsyncCallback<number>): void + +查询指定bundleName对应应用的分组。使用callback形式返回其应用分组。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | --------------------- | ---- | ---------------------------------------- | +| bundleName | string | 是 | 查询指定bundleName对应应用的分组。 | +| callback | AsyncCallback<number> | 是 | 指定的CallBack回调方法。返回制指定bundleName的应用分组。| + +**示例**： + +```javascript + let bundleName = "com.ohos.camera"; + try{ + usageStatistics.queryAppGroup(bundleName, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryAppGroup callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } +}); +``` + +## usageStatistics.setAppGroup + +setAppGroup(bundleName: string, newGroup: GroupType): Promise<void> + +将指定bundleName的应用的分组设置为newGroup，使用Promise形式返回设置是否成功。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | --------- | ---- | ---- | +| bundleName | string | 是 | 应用名称 | +| newGroup | [GroupType](#grouptype) | 是 | 应用分组 | + +**返回值**： + +| 类型 | 说明 | +| ------------- | ------------------------- | +| Promise<void> | 指定的Promise回调方法。返回本次设置是否成功 | + +**示例**： + +```javascript + let bundleName = "com.example.deviceUsageStatistics"; + let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY; + + try{ + usageStatistics.setAppGroup(bundleName, newGroup).then( () => { + console.log('BUNDLE_ACTIVE setAppGroup promise succeeded.'); + }).catch( err => { + console.log('BUNDLE_ACTIVE setAppGroup promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.setAppGroup + +setAppGroup(bundleName: string, newGroup: GroupType, callback: AsyncCallback<void>): void + +将指定bundleName的应用的分组设置为newGroup，使用CallBack形式返回设置是否成功。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------- | ---- | ------------------------- | +| bundleName | string | 是 | 应用名称 | +| newGroup | [GroupType](#grouptype) | 是 | 应用分组 | +| callback | AsyncCallback<void> | 是 | 指定的CallBack回调方法。返回设置是否成功。 | + +**示例**： + +```javascript + let bundleName = "com.example.deviceUsageStatistics"; + let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY; + + try{ + usageStatistics.setAppGroup(bundleName, newGroup, (err) => { + if(err) { + console.log('BUNDLE_ACTIVE setAppGroup callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE setAppGroup callback succeeded.'); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.registerAppGroupCallBack + +registerAppGroupCallBack(groupCallback: Callback<AppGroupCallbackInfo>): Promise<void> + +应用注册分组变化监听，待用户名下的某个应用分组发生变化时，通过callback形式向所有已注册分组变化监听的应用返回[AppGroupCallbackInfo](#appgroupcallbackinfo9)信息。使用Promise形式返回注册是否成功。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | +| callback | Callback<[AppGroupCallbackInfo](#appgroupcallbackinfo9)> | 是 | 指定的callback函数，返回应用分组变化的信息 | + +**返回值**： + +| 类型 | 说明 | +| ------------- | ----------------------- | +| Promise<void> | 指定的Promise回调方法。返回注册监听是否成功 | + +**示例**： + +```javascript + let onBundleGroupChanged = (res) =>{ + console.log('BUNDLE_ACTIVE registerAppGroupCallBack RegisterGroupCallBack callback success.'); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); + }; + try{ + usageStatistics.registerAppGroupCallBack(onBundleGroupChanged).then( () => { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise succeeded.'); + }).catch( err => { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.registerAppGroupCallBack + +registerAppGroupCallBack(groupCallback: Callback<AppGroupCallbackInfo>, callback: AsyncCallback<void>): void + +应用注册分组变化监听，待用户名下的某个应用分组发生变化时，通过callback形式向所有已注册分组变化监听的应用返回[AppGroupCallbackInfo](#appgroupcallbackinfo9)信息。使用异步callback形式返回注册监听是否成功。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | +| groupCallback | Callback<[AppGroupCallbackInfo](#appgroupcallbackinfo9)> | 是 | 指定的callback函数，返回应用分组变化的信息 | +| callback | AsyncCallback<void> | 是 | 指定的异步callback函数，返回注册监听是否成功 | + +**示例**： + +```javascript + let onBundleGroupChanged = (err, res) =>{ + console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); + console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); + }; + try{ + usageStatistics.registerAppGroupCallBack(onBundleGroupChanged, error => { + if(error) { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback success.'); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.unRegisterAppGroupCallBack + +unRegisterAppGroupCallBack(): Promise<void> + +应用解除分组变化监听，解除通过调用注册接口生成的监听。使用Promise形式返回解除监听是否成功。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**：无参数 + +**返回值**： + +| 类型 | 说明 | +| ------------- | ------------------------ | +| Promise<void> | 指定的Promise回调方法。返回解除监听是否成功 | + +**示例**： + +```javascript + try{ + usageStatistics.unRegisterAppGroupCallBack().then( () => { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack promise succeeded.'); + }).catch( err => { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.unRegisterAppGroupCallBack + +unRegisterAppGroupCallBack(callback: AsyncCallback<void>): void; + +应用解除分组变化监听，解除通过调用注册接口生成的监听。使用异步callback形式返回解除监听是否成功。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------- | +| callback | AsyncCallback<void> | 是 | 解除监听是否成功的异步回调函数 | + +**示例**： + +```javascript + try{ + usageStatistics.unRegisterAppGroupCallBack(error => { + if(error) { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack callback success.'); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE unRegisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); + } +``` + +## usageStatistics.queryDeviceEventStats + +queryDeviceEventStats(begin: number, end: number): Promise<Array<DeviceEventStats>> + +通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，使用Promise形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | ---------------------------------------- | +| Promise<Array<[DeviceEventStats](#deviceeventstats9)>> | 指定的Promise回调方法。返回指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryDeviceEventStats(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryDeviceEventStates promise success.'); + console.log('BUNDLE_ACTIVE queryDeviceEventStates promise result ' + JSON.stringify(res)); + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryDeviceEventStats promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryDeviceEventStats + +queryDeviceEventStats(begin: number, end: number, callback: AsyncCallback<Array<DeviceEventStats>>): void + +通过指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息，使用Callback形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | +| callback | AsyncCallback<Array<[DeviceEventStats](#deviceeventstats9)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询系统事件（休眠、唤醒、解锁、锁屏）统计信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryDeviceEventStats(0, 20000000000000, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryDeviceEventStats callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryDeviceEventStats callback success.'); + console.log('BUNDLE_ACTIVE queryDeviceEventStats callback result ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryNotificationEventStats + +queryNotificationEventStats(begin: number, end: number): Promise<Array<NotificationEventStats>> + +通过指定起始和结束时间查询所有应用的通知次数信息，使用Promise形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------- | ---------------------------------------- | +| Promise<Array<[NotificationEventStats](#notificationeventstats9)>> | 指定的Promise回调方法。返回指定起始和结束时间查询所有应用的通知次数信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryNotificationEventStats(0, 20000000000000).then( res => { + console.log('BUNDLE_ACTIVE queryNotificationEventStats promise success.'); + console.log('BUNDLE_ACTIVE queryNotificationEventStats promise result ' + JSON.stringify(res)); + }).catch( err=> { + console.log('BUNDLE_ACTIVE queryNotificationEventStats promise failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## usageStatistics.queryNotificationEventStats + +queryNotificationEventStats(begin: number, end: number, callback: AsyncCallback<Array<NotificationEventStats>>): void + +通过指定起始和结束时间查询所有应用的通知次数信息，使用Callback形式返回。 + +**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| begin | number | 是 | 起始时间。 | +| end | number | 是 | 结束时间。 | +| callback | AsyncCallback<Array<[NotificationEventStats](#notificationeventstats9)>> | 是 | 指定的callback回调方法。返回通过指定起始和结束时间查询所有应用的通知次数信息。 | + +**示例**： + + ```js + try{ + usageStatistics.queryNotificationEventStats(0, 20000000000000, (err, res) => { + if(err) { + console.log('BUNDLE_ACTIVE queryNotificationEventStats callback failed. errCode is: ' + err.errCode + ',message is: ' + err.errMessage); + } else { + console.log('BUNDLE_ACTIVE queryNotificationEventStats callback success.'); + console.log('BUNDLE_ACTIVE queryNotificationEventStats callback result ' + JSON.stringify(res)); + } + }); + } catch (error) { + console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); + } + ``` + +## HapModuleInfo +FA的使用信息的属性集合。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 参数名 | 类型 | 必填 | 说明 | +| -------------------- | ---------------------------------------- | ---- | ----------------------------- | +| deviceId | string | 否 | FA所属deviceId。 | +| bundleName | string | 是 | FA所属应用包名。 | +| moduleName | string | 是 | FA所属module名。 | +| abilityName | string | 否 | FA的MainAbility名。 | +| appLabelId | number | 否 | FA的应用labelId。 | +| labelId | number | 否 | FA所属module的labelId。 | +| descriptionId | number | 否 | FA所属的应用descriptionId。 | +| abilityLableId | number | 否 | FA的MainAbility labelId。 | +| abilityDescriptionId | number | 否 | FA的MainAbility descriptionId。 | +| abilityIconId | number | 否 | FA的MainAbility iconId。 | +| launchedCount | number | 是 | FA的启动次数。 | +| lastModuleUsedTime | number | 是 | FA的上一次使用时间。 | +| formRecords | Array<[HapFormInfo](#hapforminfo9)> | 是 | FA中卡片的使用记录。 | + +## HapFormInfo +FA卡片的使用信息的属性集合。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 参数名 | 类型 | 必填 | 说明 | +| ---------------- | ------ | ---- | ----------- | +| formName | string | 是 | 卡片名称。 | +| formDimension | number | 是 | 卡片尺寸。 | +| formId | number | 是 | 卡片Id。 | +| formLastUsedTime | number | 是 | 卡片的上一次点击时间。 | +| count | number | 是 | 卡片的点击次数。 | + +## AppGroupCallbackInfo + +应用分组变化回调返回的属性集合 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 参数名 | 类型 | 必填 | 说明 | +| ---------------- | ------ | ---- | ---------------- | +| appOldGroup | number | 是 | 变化前的应用分组 | +| appNewGroup | number | 是 | 变化后的应用分组 | +| userId | number | 是 | 用户id | +| changeReason | number | 是 | 分组变化原因 | +| bundleName | string | 是 | 应用名称 | + +## BundleStatsInfo + +提供应用使用时长的具体信息。 + +### 属性 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------------------------ | ------ | ---- | ---------------------------------------- | +| bundleName | string | 是 | 应用包名。 | +| abilityPrevAccessTime | number | 是 | 应用最后一次使用的时间。 | +| abilityInFgTotalTime | number | 是 | 应用在前台使用的总时间。 | +| id | number | 否 | 用户id。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| abilityPrevSeenTime | number | 否 | 应用最后一次在前台可见的时间。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| abilitySeenTotalTime | number | 否 | 应用在前台可见的总时间。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| fgAbilityAccessTotalTime | number | 否 | 应用访问前台的总时间。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| fgAbilityPrevAccessTime | number | 否 | 应用最后一次访问前台的时间。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| infosBeginTime | number | 否 | BundleActiveInfo对象中第一条应用使用统计的记录时间。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| infosEndTime | number | 否 | BundleActiveInfo对象中最后一条应用使用统计的记录时间。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | + +## BundleEvents + +提供应用事件的具体信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +| 参数名 | 类型 | 必填 | 说明 | +| --------------------- | ------ | ---- | ---------------------------------------- | +| bundleName | string | 是 | 应用包名。 | +| eventId | number | 是 | 应用事件类型。 | +| eventOccurredTime | number | 是 | 应用事件发生的时间戳。 | +| appGroup | number | 否 | 应用程序的使用优先级组。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| indexOfLink | string | 否 | 快捷方式id。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | +| nameOfClass | string | 否 | 类名。
本接口在OpenHarmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 | + +## BundleStatsMap + +提供应用使用时长的具体信息。 + +**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App + +| 参数名 | 类型 | 必填 | 说明 | +| ------------------------------ | ---------------------------------------- | ---- | -------------- | +| [key: string]: BundleStatsInfo | [key: string]: [BundleStatsInfo](#bundlestatsinfo) | 是 | 不同应用的使用时长统计信息。 | + +## DeviceEventStats + +提供通知、系统事件的统计信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ----------------- | +| name | string | 是 | 通知应用包名或者系统事件名。 | +| eventId | number | 是 | 通知、系统事件类型。 | +| count | number | 是 | 应用通知次数或者系统事件触发次数。 | + +## NotificationEventStats + +提供通知事件的统计信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ----------------- | +| name | string | 是 | 通知应用包名。 | +| eventId | number | 是 | 通知事件类型。 | +| count | number | 是 | 应用通知次数。 | + +## IntervalType + +提供应用使用时长的查询类型。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App + +| 名称 | 默认值 | 说明 | +| ------------ | ---- | ---------------------------------------- | +| BY_OPTIMIZED | 0 | 表示系统自行判断最合适的查询类型（天、周、月、年）去查询指定时间段间隔的应用使用时长信息。 | +| BY_DAILY | 1 | 表示系统按照天去查询指定时间段间隔的应用使用时长信息。 | +| BY_WEEKLY | 2 | 表示系统按照周去查询指定时间段间隔的应用使用时长信息。 | +| BY_MONTHLY | 3 | 表示系统按照月去查询指定时间段间隔的应用使用时长信息。 | +| BY_ANNUALLY | 4 | 表示系统按照年去查询指定时间段间隔的应用使用时长信息。 | + +## GroupType + +提供应用分组的设置类型。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**系统API**：此接口为系统接口，三方应用不支持调用。 + +| 名称 | 默认值 | 说明 | +| ------------------ | ---- | ----------------- | +| ALIVE_GROUP | 10 | 活跃分组。 | +| DAILY_GROUP | 20 | 经常使用，但当前并未在活跃态。 | +| FIXED_GROUP | 30 | 常用分组，定期使用，但不是每天使用。 | +| RARE_GROUP | 40 | 极少使用分组，不经常使用。 | +| LIMITED_GROUP | 50 | 受限使用分组。 | +| NEVER_GROUP | 60 | 从未使用分组，安装但是从未运行过。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errcode-DeviceUsageStatistics.md b/zh-cn/application-dev/reference/errorcodes/errcode-DeviceUsageStatistics.md new file mode 100644 index 0000000000000000000000000000000000000000..b0ca4dd639a5a76ac233130492012ff5125320fc --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errcode-DeviceUsageStatistics.md @@ -0,0 +1,127 @@ +# DeviceUsageStatistics错误码 + +## 201 权限校验失败 + +### 错误信息 +Permission denied. + +### 可能原因 +该错误码表示权限校验失败，可能原因是未配置对应权限或者是不能修改自身应用信息。 + +### 处理步骤 +配置权限ohos.permission.BUNDLE_ACTIVE_INFO。 + +## 401 参数检查错误 + +### 错误信息 +The parameter check failed. + +### 可能原因 +该错误码表示入参检查错误，可能原因调用接口的时候输入参数有误（类型或者数值）。 + +### 处理步骤 +调用接口时先检查入参类型和数值是否为合法。 + +## 10000001 内存操作失败 + +### 错误信息 +Memory operation failed. + +### 可能原因 +该错误码表示系统服务工作异常，可能原因如下。 +内存不足导致创建对象失败。 + +### 处理步骤 +请检查内存是否泄漏。 + +## 10000002 IPC parcel write failed + +### 错误信息 +Parcel operation failed. Failed to write the parcel. + +### 可能原因 +写入对象失败。 + +### 处理步骤 +请检查对象值是否正常。 + +## 10000003 系统服务操作失败 + +### 错误信息 +System service operation failed. + +### 可能原因 +依赖的服务进程出现问题。 + +### 处理步骤 +系统服务内部工作异常，请稍后重试，或者重启设备尝试。 + +## 10000004 IPC通信失败 + +### 错误信息 +IPC communication failed. + +### 可能原因 +系统服务异常或者IPC通信数据异常。 + +### 处理步骤 +系统服务内部工作异常，请稍后重试，或者重启设备尝试。 + +## 10000005 应用未安装 + +### 错误信息 +The application is not installed. + +### 可能原因 +应用未安装或者已经卸载 + +### 处理步骤 +操作应用信息时请先检查应用是否已安装且并未卸载。 + +## 10000006 获取应用信息失败 + +### 错误信息 +Get application info failed. + +### 可能原因 +1. beginTime或者endTime输入不合法。 +2. 应用未安装或者已经被卸载了。 +2. intervalType输入不合法。 + +### 处理步骤 +请检查入参合法性以及应用是否安装且并未卸载。 + +## 10000007 时间操作失败 + +### 错误信息 +Get system or actual time operation failed. + +### 可能原因 +系统异常。 + +### 处理步骤 +系统服务内部工作异常，请稍后重试，或者重启设备尝试。 + +## 10100001 应用分组信息操作重复 + +### 错误信息 +Application group operation failed. The application group are the the same and do not need te be updated. + +### 可能原因 +重复设置应用分组或者重复注册分组变化监听和重复取消分组变化监听。 + +### 处理步骤 +请勿重复设置应用分组、注册监听和取消监听。 + +## 10100002 获取应用分组信息失败 + +### 错误信息 +Get application group info failed. The application group infomation cannot be found. + +### 可能原因 +1、应用输入bundleName错误。 +2、应用可能没有安装或者已经卸载 + +### 处理步骤 +请检查入参bundleName的正确性。 +