1# @ohos.bundleState (设备使用信息统计) 2 3本模块提供设备使用信息统计能力。 4 5设备使用信息统计，系统应用可调用接口实现如下功能： 6 7- 查询设备上各应用在不同时间段的使用时长、各应用的事件（前台、后台、长时任务开始、长时任务结束）信息及各应用的通知次数信息。 8- 查询应用分组信息（仅限自身应用）。 9- 查询应用空闲状态（其他应用和自身应用）。 10 11三方应用可调用接口实现如下功能： 12 13- 查询应用空闲状态（仅限自身应用）。 14- 查询应用分组信息（仅限自身应用）。 15- 查询应用事件（仅限自身应用）。 16 17> **说明：** 18> 19> 从API version9开始，该接口不再维护，推荐使用新接口[@ohos.resourceschedule.usageStatistics(设备使用信息统计)](js-apis-resourceschedule-deviceUsageStatistics.md) 20> 21> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 22> 23 24 25## 导入模块 26 27```js 28import bundleState from '@ohos.bundleState' 29``` 30 31## bundleState.isIdleState 32 33isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void 34 35判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，查询其他应用空闲状态，需要申请权限ohos.permission.BUNDLE_ACTIVE_INFO，使用Callback形式返回。 36 37**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 38 39**参数**： 40 41| 参数名 | 类型 | 必填 | 说明 | 42| ---------- | ---------------------------- | ---- | ---------------------------------------- | 43| bundleName | string | 是 | 应用的bundleName。 | 44| callback | AsyncCallback<boolean> | 是 | 指定的callback回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | 45 46**示例**： 47 48```ts 49import { BusinessError } from '@ohos.base'; 50 51bundleState.isIdleState("com.ohos.camera", (err: BusinessError, res: boolean) => { 52 if (err) { 53 console.error('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); 54 } else { 55 console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); 56 } 57}); 58``` 59 60## bundleState.isIdleState 61 62isIdleState(bundleName: string): Promise<boolean> 63 64判断指定bundleName的应用当前是否是空闲状态，三方应用只能查询自身的空闲状态，查询其他应用空闲状态，需要申请权限ohos.permission.BUNDLE_ACTIVE_INFO，使用Promise形式返回。 65 66**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 67 68**参数**： 69 70| 参数名 | 类型 | 必填 | 说明 | 71| ---------- | ------ | ---- | -------------- | 72| bundleName | string | 是 | 应用的bundleName。 | 73 74**返回值**： 75 76| 类型 | 说明 | 77| ---------------------- | ---------------------------------------- | 78| Promise<boolean> | 指定的Promise回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | 79 80**示例**： 81 82```ts 83import { BusinessError } from '@ohos.base'; 84 85bundleState.isIdleState("com.ohos.camera").then((res: boolean) => { 86 console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); 87}).catch((err: BusinessError) => { 88 console.error('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code); 89}); 90``` 91 92## bundleState.queryAppUsagePriorityGroup 93 94queryAppUsagePriorityGroup(): Promise<number> 95 96查询当前应用的优先级分组。使用Promise形式返回其应用分组。 97 98**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 99 100**返回值**： 101 102| 类型 | 说明 | 103| --------------- | --------------------------- | 104| Promise<number> | 指定的Promise回调方法。返回查询的应用分组结果。 | 105 106**示例**： 107 108```ts 109import { BusinessError } from '@ohos.base'; 110 111bundleState.queryAppUsagePriorityGroup().then((res: number) => { 112 console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res)); 113}).catch((err: BusinessError) => { 114 console.error('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); 115}); 116``` 117 118## bundleState.queryAppUsagePriorityGroup 119 120queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void 121 122查询当前应用的优先级分组。使用callback形式返回其应用分组。 123 124**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 125 126**参数**： 127 128| 参数名 | 类型 | 必填 | 说明 | 129| -------- | --------------------- | ---- | -------------------------- | 130| callback | AsyncCallback<number> | 是 | 指定的CallBack回调方法。返回查询的应用分组。 | 131 132**示例**： 133 134```ts 135import { BusinessError } from '@ohos.base'; 136 137bundleState.queryAppUsagePriorityGroup((err: BusinessError, res: number) => { 138 if(err) { 139 console.error('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); 140 } else { 141 console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); 142 } 143}); 144``` 145 146## bundleState.queryBundleStateInfos 147 148queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<BundleActiveInfoResponse>): void 149 150通过指定起始和结束时间查询应用使用时长统计信息，使用Callback形式返回。 151 152**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO 153 154**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 155 156**系统API**：此接口为系统接口，三方应用不支持调用。 157 158**参数**： 159 160| 参数名 | 类型 | 必填 | 说明 | 161| -------- | ---------------------------------------- | ---- | --------------------------------------- | 162| begin | number | 是 | 起始时间，单位毫秒。 | 163| end | number | 是 | 结束时间，单位毫秒。 | 164| callback | AsyncCallback<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | 是 | 指定的callback回调方法。返回指定起始和结束时间内应用使用时长统计信息。 | 165 166**示例**： 167 168```ts 169import { BusinessError } from '@ohos.base'; 170 171bundleState.queryBundleStateInfos(0, 20000000000000, (err: BusinessError , 172 res: bundleState.BundleActiveInfoResponse ) => { 173 if (err) { 174 console.error('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code); 175 } else { 176 console.log('BUNDLE_ACTIVE queryBundleStateInfos callback success.'); 177 console.log('BUNDLE_ACTIVE queryBundleStateInfos callback result ' + JSON.stringify(res)); 178 } 179}); 180``` 181 182## bundleState.queryBundleStateInfos 183 184queryBundleStateInfos(begin: number, end: number): Promise<BundleActiveInfoResponse> 185 186通过指定起始和结束时间查询应用使用时长统计信息，使用Promise形式返回。 187 188**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO 189 190**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 191 192**系统API**：此接口为系统接口，三方应用不支持调用。 193 194**参数**： 195 196| 参数名 | 类型 | 必填 | 说明 | 197| ----- | ------ | ---- | ----- | 198| begin | number | 是 | 起始时间，单位毫秒。 | 199| end | number | 是 | 结束时间，单位毫秒。 | 200 201**返回值**： 202 203| 类型 | 说明 | 204| ---------------------------------------- | -------------------------------------- | 205| Promise<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | 指定的Promise回调方法。返回指定起始和结束时间内应用使用时长统计信息。 | 206 207**示例**： 208 209```ts 210import { BusinessError } from '@ohos.base'; 211 212bundleState.queryBundleStateInfos(0, 20000000000000).then((res: bundleState.BundleActiveInfoResponse) => { 213 console.log('BUNDLE_ACTIVE queryBundleStateInfos promise success.'); 214 console.log('BUNDLE_ACTIVE queryBundleStateInfos promise result ' + JSON.stringify(res)); 215}).catch((err: BusinessError) => { 216 console.error('BUNDLE_ACTIVE queryBundleStateInfos promise failed, because: ' + err.code); 217}); 218``` 219 220## bundleState.queryBundleStateInfoByInterval 221 222queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStateInfo>>): void 223 224通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Callback形式返回。 225 226**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO 227 228**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 229 230**系统API**：此接口为系统接口，三方应用不支持调用。 231 232**参数**： 233 234| 参数名 | 类型 | 必填 | 说明 | 235| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 236| byInterval | [IntervalType](#intervaltype) | 是 | 查询类型。 | 237| begin | number | 是 | 起始时间，单位毫秒。 | 238| end | number | 是 | 结束时间，单位毫秒。 | 239| callback | AsyncCallback<Array<[BundleStateInfo](#bundlestateinfo)>> | 是 | 指定的callback回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | 240 241**示例**： 242 243```ts 244import { BusinessError } from '@ohos.base'; 245 246bundleState.queryBundleStateInfoByInterval(bundleState.IntervalType.BY_OPTIMIZED, 0, 20000000000000, (err: BusinessError, res: Array<bundleState.BundleStateInfo>) => { 247 if (err) { 248 console.error('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); 249 } else { 250 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback success.'); 251 for (let i = 0; i < res.length; i++) { 252 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback number : ' + (i + 1)); 253 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback result ' + JSON.stringify(res[i])); 254 } 255 } 256}); 257``` 258 259## bundleState.queryBundleStateInfoByInterval 260 261queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise<Array<BundleStateInfo>> 262 263通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Promise形式返回。 264 265**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO 266 267**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 268 269**系统API**：此接口为系统接口，三方应用不支持调用。 270 271**参数**： 272 273| 参数名 | 类型 | 必填 | 说明 | 274| ---------- | ----------------------------- | ---- | ----- | 275| byInterval | [IntervalType](#intervaltype) | 是 | 查询类型。 | 276| begin | number | 是 | 起始时间，单位毫秒。 | 277| end | number | 是 | 结束时间，单位毫秒。 | 278 279**返回值**： 280 281| 类型 | 说明 | 282| ---------------------------------------- | ---------------------------------------- | 283| Promise<Array<[BundleStateInfo](#bundlestateinfo)>> | 指定的Promise回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | 284 285**示例**： 286 287```ts 288import { BusinessError } from '@ohos.base'; 289 290bundleState.queryBundleStateInfoByInterval(bundleState.IntervalType.BY_OPTIMIZED, 0, 20000000000000).then((res: Array<bundleState.BundleStateInfo>) => { 291 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.'); 292 for (let i = 0; i < res.length; i++) { 293 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise number : ' + (i + 1)); 294 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise result ' + JSON.stringify(res[i])); 295 } 296}).catch((err: BusinessError) => { 297 console.error('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise failed, because: ' + err.code); 298}); 299``` 300 301## bundleState.queryBundleActiveStates 302 303queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void 304 305通过指定起始和结束时间查询所有应用的事件集合，使用Callback形式返回。 306 307**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO 308 309**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 310 311**系统API**：此接口为系统接口，三方应用不支持调用。 312 313**参数**： 314 315| 参数名 | 类型 | 必填 | 说明 | 316| -------- | ---------------------------------------- | ---- | --------------------------------------- | 317| begin | number | 是 | 起始时间，单位毫秒。 | 318| end | number | 是 | 结束时间，单位毫秒。 | 319| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询所有应用的事件集合。 | 320 321**示例**： 322 323```ts 324import { BusinessError } from '@ohos.base'; 325 326bundleState.queryBundleActiveStates(0, 20000000000000, (err: BusinessError, res: Array<bundleState.BundleActiveState>) => { 327 if (err) { 328 console.error('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code); 329 } else { 330 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback success.'); 331 for (let i = 0; i < res.length; i++) { 332 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback number : ' + (i + 1)); 333 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback result ' + JSON.stringify(res[i])); 334 } 335 } 336}); 337``` 338 339## bundleState.queryBundleActiveStates 340 341queryBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>> 342 343通过指定起始和结束时间查询所有应用的事件集合，使用Promise形式返回。 344 345**需要权限**：ohos.permission.BUNDLE_ACTIVE_INFO 346 347**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 348 349**系统API**：此接口为系统接口，三方应用不支持调用。 350 351**参数**： 352 353| 参数名 | 类型 | 必填 | 说明 | 354| ----- | ------ | ---- | ----- | 355| begin | number | 是 | 起始时间，单位毫秒。 | 356| end | number | 是 | 结束时间，单位毫秒。 | 357 358**返回值**： 359 360| 类型 | 说明 | 361| ---------------------------------------- | -------------------------------------- | 362| Promise<Array<[BundleActiveState](#bundleactivestate)>> | 指定的Promise回调方法。返回指定起始和结束时间查询所有应用的事件集合。 | 363 364**示例**： 365 366```ts 367import { BusinessError } from '@ohos.base'; 368 369bundleState.queryBundleActiveStates(0, 20000000000000).then((res: Array<bundleState.BundleActiveState>) => { 370 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise success.'); 371 for (let i = 0; i < res.length; i++) { 372 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise number : ' + (i + 1)); 373 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise result ' + JSON.stringify(res[i])); 374 } 375}).catch((err: BusinessError) => { 376 console.error('BUNDLE_ACTIVE queryBundleActiveStates promise failed, because: ' + err.code); 377}); 378``` 379 380## bundleState.queryCurrentBundleActiveStates 381 382queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void 383 384通过指定起始和结束时间查询当前应用的事件集合，使用Callback形式返回。 385 386**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 387 388**参数**： 389 390| 参数名 | 类型 | 必填 | 说明 | 391| -------- | ---------------------------------------- | ---- | --------------------------------------- | 392| begin | number | 是 | 起始时间，单位毫秒。 | 393| end | number | 是 | 结束时间，单位毫秒。 | 394| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | 395 396**示例**： 397 398```ts 399import { BusinessError } from '@ohos.base'; 400 401bundleState.queryCurrentBundleActiveStates(0, 20000000000000, (err: BusinessError, res: Array<bundleState.BundleActiveState>) => { 402 if (err) { 403 console.error('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); 404 } else { 405 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.'); 406 for (let i = 0; i < res.length; i++) { 407 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1)); 408 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i])); 409 } 410 } 411}); 412``` 413 414## bundleState.queryCurrentBundleActiveStates 415 416queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>> 417 418通过指定起始和结束时间查询当前应用的事件集合，使用Promise形式返回。 419 420**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 421 422**参数**： 423 424| 参数名 | 类型 | 必填 | 说明 | 425| ----- | ------ | ---- | ----- | 426| begin | number | 是 | 起始时间，单位毫秒。 | 427| end | number | 是 | 结束时间，单位毫秒。 | 428 429**返回值**： 430 431| 类型 | 说明 | 432| ---------------------------------------- | -------------------------------------- | 433| Promise<Array<[BundleActiveState](#bundleactivestate)>> | 指定的Promise回调方法。返回指定起始和结束时间查询当前应用的事件集合。 | 434 435**示例**： 436 437```ts 438import { BusinessError } from '@ohos.base'; 439 440bundleState.queryCurrentBundleActiveStates(0, 20000000000000).then((res: Array<bundleState.BundleActiveState>) => { 441 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.'); 442 for (let i = 0; i < res.length; i++) { 443 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise number : ' + (i + 1)); 444 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise result ' + JSON.stringify(res[i])); 445 } 446}).catch((err: BusinessError) => { 447 console.error('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code); 448}); 449``` 450 451## BundleStateInfo 452 453提供应用使用时长的具体信息。 454 455### 属性 456 457**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App 458 459| 名称 | 类型 | 必填 | 说明 | 460| ------------------------ | ------ | ---- | ---------------------------------------- | 461| bundleName | string | 是 | 应用包名。 | 462| abilityPrevAccessTime | number | 是 | 应用最后一次使用的时间。 | 463| abilityInFgTotalTime | number | 是 | 应用在前台使用的总时间。 | 464| id | number | 否 | 用户id。| 465| abilityPrevSeenTime | number | 否 | 应用最后一次在前台可见的时间。| 466| abilitySeenTotalTime | number | 否 | 应用在前台可见的总时间。| 467| fgAbilityAccessTotalTime | number | 否 | 应用访问前台的总时间。| 468| fgAbilityPrevAccessTime | number | 否 | 应用最后一次访问前台的时间。| 469| infosBeginTime | number | 否 | BundleActiveInfo对象中第一条应用使用统计的记录时间。| 470| infosEndTime | number | 否 | BundleActiveInfo对象中最后一条应用使用统计的记录时间。| 471 472### merge<sup>(deprecated)</sup> 473 474merge(toMerge: BundleStateInfo): void 475 476合并相同包名的应用使用信息。 477 478**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 479 480**参数**： 481 482| 参数名 | 类型 | 必填 | 说明 | 483| -------- | -------- | -------- | -------- | 484| toMerge | [BundleStateInfo](#bundlestateinfo) | 是 | 相同包名的应用使用统计信息。| 485 486## BundleActiveState 487 488提供应用事件的具体信息。 489 490提供应用使用时长的具体信息。 491 492**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App 493 494| 名称 | 类型 | 必填 | 说明 | 495| --------------------- | ------ | ---- | ---------------------------------------- | 496| bundleName | string | 是 | 应用包名。 | 497| stateType | number | 是 | 应用事件类型。 | 498| stateOccurredTime | number | 是 | 应用事件发生的时间戳。 | 499| appUsagePriorityGroup | number | 否 | 应用程序的使用优先级组。| 500| indexOfLink | string | 否 | 快捷方式id。| 501| nameOfClass | string | 否 | 类名。| 502 503## BundleActiveInfoResponse 504 505提供应用使用时长的具体信息。 506 507**系统能力**：SystemCapability.ResourceSchedule.UsageStatistics.App 508 509| 参数名 | 类型 | 必填 | 说明 | 510| ------------------------------ | ---------------------------------------- | ---- | -------------- | 511| [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | 是 | 不同应用的使用时长统计信息。 | 512 513## IntervalType 514 515提供应用使用时长的查询类型。 516 517**系统能力**：以下各项对应的系统能力均为SystemCapability.ResourceSchedule.UsageStatistics.App 518 519| 名称 | 值 | 说明 | 520| ------------ | ---- | ---------------------------------------- | 521| BY_OPTIMIZED | 0 | 表示系统自行判断最合适的查询类型（天、周、月、年）去查询指定时间段间隔的应用使用时长信息。 | 522| BY_DAILY | 1 | 表示系统按照天去查询指定时间段间隔的应用使用时长信息。 | 523| BY_WEEKLY | 2 | 表示系统按照周去查询指定时间段间隔的应用使用时长信息。 | 524| BY_MONTHLY | 3 | 表示系统按照月去查询指定时间段间隔的应用使用时长信息。 | 525| BY_ANNUALLY | 4 | 表示系统按照年去查询指定时间段间隔的应用使用时长信息。 |