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