辛宝Otto 的玄酒清谈

Quick HarmonyOS Developer Documentation Series:

• [[Quick HarmonyOS - From ets to view battery level information to API documentation, code structure]]

Assuming you, like me, are a newcomer to HarmonyOS and feel overwhelmed by the vast and unfamiliar knowledge system, you can refer to this series of documents. If you follow my approach, you should be able to gain insights into the HarmonyOS knowledge system in a straightforward manner.

Preparation#

The prerequisite knowledge here is to download and run the default Hello World application of HarmonyOS. If you do not master this part, you can skip the following sections for now.

What is the current battery level of the phone?#

Let’s ask a very classic question: how can we query the current battery level of the phone through the API?

Why do I say it’s classic? It is a typical system API that requires consulting the documentation to find, and it is grouped with other useful device information. I have mentioned this when sharing how to use UTS to learn Android and iOS.

First, let’s reveal the answer. The HarmonyOS documentation ohos.batteryInfo mentions the specific API usage.

import {batteryInfo} from '@kit.BasicServicesKit';

let batterySOCInfo: number = batteryInfo.batterySOC;
console.info("The batterySOCInfo is: " + batterySOCInfo);

Below is a complete page structure that allows for quick observation of the specific usage.

// Index.ets  
import {batteryInfo} from '@kit.BasicServicesKit'  
  
@Entry  
@Component  
struct Index {  
  @State message: string = 'Query Battery Level'  
  @State currentInfo: number = -1  
  
  build() {  
    Row() {  
      Column() {  
        Text('Current Battery Level: '+ this.currentInfo+'%')  
        Button() {  
          Text(this.message)  
            .fontSize(30)  
            .fontWeight(FontWeight.Bold)  
        }  
        .type(ButtonType.Capsule)  
        .margin({  
          top: 20  
        })  
        .backgroundColor('#0D9FFB')  
        .width('40%')  
        .height('5%')   
        .onClick(() => {  
          let batterySOCInfo: number = batteryInfo.batterySOC  
          this.currentInfo = batterySOCInfo  
  
        })  
      }  
      .width('100%')  
    }  
    .height('100%')  
  }  
}

So the goal is achieved, but it’s not over yet. Let’s take the opportunity to learn about the API writing style and documentation structure of ETS.

Code Structure#

ETS is very similar to TS, using the built-in module @kit.BasicServicesKit and the specific API batteryInfo.

In ETS, there are many such kit.xxx. By Ctrl-clicking on BasicServicesKit in the code, you can see the code definition, which is d.ts, and you can see many other kits.

You can understand that @kit.xxx corresponds to the api/kits/xxx/index.ts module. Further clicking in, you will see the code import batteryInfo from '@ohos.batteryInfo';

Not looking at the documentation, just the original definition is enough. I fed the d.ts to AI, and it automatically generated a table.

This is the content of batteryInfo.d.ts, organized into a table.

The result is quite good.

Documentation Structure#

Observe the left sidebar of the documentation. The battery information documentation is located in API Reference - System - Basic Functions - BasicServicesKit - Device Management Internal. There is also a checkbox at the top of the sidebar indicating whether the meta service is available. After switching, the color does not change to gray, indicating that the meta service is also available.

There are module descriptions and usage descriptions. Note that if you are a meta service user, the return values are limited unless explicitly supported; otherwise, the meta service is unavailable.

How is UTS Encapsulated?#

If you are a UTS user of UniApp, you can continue to observe how HarmonyOS adaptation is done.

Open the Uni-API open-source repository and locate uni-api/uni_modules/uni-getbatteryinfo

You can see that HarmonyOS APIs are also encapsulated in this way, importing @ohos.batteryInfo.

Summary#

Through this small case, it illustrates how to use the API, how to read it, and how to encapsulate it in UTS.