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