1# @ohos.bundleState (设备使用信息统计) 2 3本模块提供设备使用信息统计能力。 4 5> **说明：** 6> 7> 从API version9开始，该接口不再维护，替代接口仅向系统应用开放。 8> 9> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10 11 12## 导入模块 13 14```js 15import bundleState from '@ohos.bundleState' 16``` 17 18## bundleState.isIdleState 19 20isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void 21 22判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，查询其他应用空闲状态，需要申请权限ohos.permission.BUNDLE_ACTIVE_INFO，使用Callback形式返回。 23 24**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 25 26**参数**： 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ---------- | ---------------------------- | ---- | ---------------------------------------- | 30| bundleName | string | 是 | 应用的bundleName。 | 31| callback | AsyncCallback<boolean> | 是 | 指定的callback回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | 32 33**示例**： 34 35```ts 36import { BusinessError } from '@ohos.base'; 37 38bundleState.isIdleState("com.ohos.camera", (err: BusinessError, res: boolean) => { 39 if (err) { 40 console.error('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); 41 } else { 42 console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); 43 } 44}); 45``` 46 47## bundleState.isIdleState 48 49isIdleState(bundleName: string): Promise<boolean> 50 51判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，查询其他应用空闲状态，需要申请权限ohos.permission.BUNDLE_ACTIVE_INFO，使用Promise形式返回。 52 53**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 54 55**参数**： 56 57| 参数名 | 类型 | 必填 | 说明 | 58| ---------- | ------ | ---- | -------------- | 59| bundleName | string | 是 | 应用的bundleName。 | 60 61**返回值**： 62 63| 类型 | 说明 | 64| ---------------------- | ---------------------------------------- | 65| Promise<boolean> | 指定的Promise回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | 66 67**示例**： 68 69```ts 70import { BusinessError } from '@ohos.base'; 71 72bundleState.isIdleState("com.ohos.camera").then((res: boolean) => { 73 console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); 74}).catch((err: BusinessError) => { 75 console.error('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code); 76}); 77``` 78 79## bundleState.queryAppUsagePriorityGroup 80 81queryAppUsagePriorityGroup(): Promise<number> 82 83查询当前应用的优先级分组。使用Promise形式返回其应用分组。 84 85**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 86 87**返回值**： 88 89| 类型 | 说明 | 90| --------------- | --------------------------- | 91| Promise<number> | 指定的Promise回调方法。返回查询的应用分组结果。 | 92 93**示例**： 94 95```ts 96import { BusinessError } from '@ohos.base'; 97 98bundleState.queryAppUsagePriorityGroup().then((res: number) => { 99 console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res)); 100}).catch((err: BusinessError) => { 101 console.error('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); 102}); 103``` 104 105## bundleState.queryAppUsagePriorityGroup 106 107queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void 108 109查询当前应用的优先级分组。使用callback形式返回其应用分组。 110 111**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 112 113**参数**： 114 115| 参数名 | 类型 | 必填 | 说明 | 116| -------- | --------------------- | ---- | -------------------------- | 117| callback | AsyncCallback<number> | 是 | 指定的CallBack回调方法。返回查询的应用分组。 | 118 119**示例**： 120 121```ts 122import { BusinessError } from '@ohos.base'; 123 124bundleState.queryAppUsagePriorityGroup((err: BusinessError, res: number) => { 125 if(err) { 126 console.error('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); 127 } else { 128 console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); 129 } 130}); 131``` 132 133## bundleState.queryCurrentBundleActiveStates 134 135queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void 136 137通过指定起始和结束时间查询当前应用的事件集合，使用Callback形式返回。 138 139**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 140 141**参数**： 142 143| 参数名 | 类型 | 必填 | 说明 | 144| -------- | ---------------------------------------- | ---- | --------------------------------------- | 145| begin | number | 是 | 起始时间，单位毫秒。 | 146| end | number | 是 | 结束时间，单位毫秒。 | 147| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | 148 149**示例**： 150 151```ts 152import { BusinessError } from '@ohos.base'; 153 154bundleState.queryCurrentBundleActiveStates(0, 20000000000000, (err: BusinessError, res: Array<bundleState.BundleActiveState>) => { 155 if (err) { 156 console.error('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); 157 } else { 158 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.'); 159 for (let i = 0; i < res.length; i++) { 160 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1)); 161 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i])); 162 } 163 } 164}); 165``` 166 167## bundleState.queryCurrentBundleActiveStates 168 169queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>> 170 171通过指定起始和结束时间查询当前应用的事件集合，使用Promise形式返回。 172 173**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 174 175**参数**： 176 177| 参数名 | 类型 | 必填 | 说明 | 178| ----- | ------ | ---- | ----- | 179| begin | number | 是 | 起始时间，单位毫秒。 | 180| end | number | 是 | 结束时间，单位毫秒。 | 181 182**返回值**： 183 184| 类型 | 说明 | 185| ---------------------------------------- | -------------------------------------- | 186| Promise<Array<[BundleActiveState](#bundleactivestate)>> | 指定的Promise回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | 187 188**示例**： 189 190```ts 191import { BusinessError } from '@ohos.base'; 192 193bundleState.queryCurrentBundleActiveStates(0, 20000000000000).then((res: Array<bundleState.BundleActiveState>) => { 194 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.'); 195 for (let i = 0; i < res.length; i++) { 196 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise number : ' + (i + 1)); 197 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise result ' + JSON.stringify(res[i])); 198 } 199}).catch((err: BusinessError) => { 200 console.error('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code); 201}); 202``` 203 204## BundleStateInfo 205 206提供应用使用时长的具体信息。 207 208### 属性 209 210**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App 211 212| 名称 | 类型 | 必填 | 说明 | 213| ------------------------ | ------ | ---- | ---------------------------------------- | 214| bundleName | string | 否 | 应用包名。 | 215| abilityPrevAccessTime | number | 否 | 应用最后一次使用的时间。 | 216| abilityInFgTotalTime | number | 否 | 应用在前台使用的总时间。 | 217| id | number | 是 | 用户id。| 218| abilityPrevSeenTime | number | 否 | 应用最后一次在前台可见的时间。| 219| abilitySeenTotalTime | number | 否 | 应用在前台可见的总时间。| 220| fgAbilityAccessTotalTime | number | 否 | 应用访问前台的总时间。| 221| fgAbilityPrevAccessTime | number | 否 | 应用最后一次访问前台的时间。| 222| infosBeginTime | number | 否 | BundleActiveInfo对象中第一条应用使用统计的记录时间。| 223| infosEndTime | number | 否 | BundleActiveInfo对象中最后一条应用使用统计的记录时间。| 224 225### merge<sup>(deprecated)</sup> 226 227merge(toMerge: BundleStateInfo): void 228 229合并相同包名的应用使用信息。 230 231**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 232 233**参数**： 234 235| 参数名 | 类型 | 必填 | 说明 | 236| -------- | -------- | -------- | -------- | 237| toMerge | [BundleStateInfo](#bundlestateinfo) | 是 | 相同包名的应用使用统计信息。| 238 239## BundleActiveState 240 241提供应用事件的具体信息。 242 243提供应用使用时长的具体信息。 244 245**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App 246 247| 名称 | 类型 | 必填 | 说明 | 248| --------------------- | ------ | ---- | ---------------------------------------- | 249| bundleName | string | 否 | 应用包名。 | 250| stateType | number | 否 | 应用事件类型。 | 251| stateOccurredTime | number | 否 | 应用事件发生的时间戳。 | 252| appUsagePriorityGroup | number | 否 | 应用程序的使用优先级组。| 253| indexOfLink | string | 否 | 快捷方式id。| 254| nameOfClass | string | 否 | 类名。| 255 256## BundleActiveInfoResponse 257 258提供应用使用时长的具体信息。 259 260**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 261 262| 参数名 | 类型 | 必填 | 说明 | 263| ------------------------------ | ---------------------------------------- | ---- | -------------- | 264| [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | 是 | 不同应用的使用时长统计信息。 | 265 266## IntervalType 267 268提供应用使用时长的查询类型。 269 270**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App 271 272| 名称 | 值 | 说明 | 273| ------------ | ---- | ---------------------------------------- | 274| BY_OPTIMIZED | 0 | 表示系统自行判断最合适的查询类型（天、周、月、年）去查询指定时间段间隔的应用使用时长信息。 | 275| BY_DAILY | 1 | 表示系统按照天去查询指定时间段间隔的应用使用时长信息。 | 276| BY_WEEKLY | 2 | 表示系统按照周去查询指定时间段间隔的应用使用时长信息。 | 277| BY_MONTHLY | 3 | 表示系统按照月去查询指定时间段间隔的应用使用时长信息。 | 278| BY_ANNUALLY | 4 | 表示系统按照年去查询指定时间段间隔的应用使用时长信息。 |