harmony 鸿蒙Crown Event (Recommended for Circular Screens)

2025-06-12
浏览 (4)

Crown Event (Recommended for Circular Screens)

The crown event, supported since API version 18, is triggered by the rotation of the watch crown and reports changes in the rotation angle based on the hardware sampling frequency.

The distribution of crown events depends on the application focus. Only the component that currently has focus can receive the event. Therefore, the component that receives the event must manage its focus status. You can customize focus events. Some built-in components already support interaction with the watch crown. For example, rotating the crown scrolls the scrollbar. In addition, applications can be notified of crown events through a specific API. Currently, the following components support crown events by default: Slider, DatePicker, TextPicker, TimePicker, Scroll, List, Grid, WaterFlow, ArcList, Refresh, and Swiper.

NOTE

Only circular screens support crown events.

When a crown event occurs, the onDigitalCrown callback is invoked.

onDigitalCrown(event: (event?: CrownEvent) => void)

The event parameter provides the following information: timestamp, rotation angular velocity, rotation angle, and crown action.

To enable a component to obtain information such as the rotation angle, use the onDigitalCrown API for receiving the crown event. The following example uses the Text component to illustrate how to develop a crown event and the precautions to take during development.

Ensure the component focus.

Use APIs such as focusable, defaultFocus, and focusOnTouch to ensure that the target component can receive focus. For details about focus control, see Focus Control.
```
Text(this.message)
  .fontSize(20)
  .fontColor(Color.White)
  .backgroundColor("#262626")
  .textAlign(TextAlign.Center)
  .focusable(true)
  .focusOnTouch(true)
  .defaultFocus(true)
```
Register the crown event callback.

To receive a crown event, you need to register a crown event callback. When a crown event is triggered, the callback function is executed.
```
.onDigitalCrown((event: CrownEvent) => {})
```

Understand event fields.

The crown event provides the timestamp, rotation angular velocity, rotation angle, and crown action. To prevent the event from bubbling up, use stopPropagation.

event.stopPropagation();
this.message = "CrownEvent\n\n" + JSON.stringify(event);
console.debug("action:%d, angularVelocity:%f, degree:%f, timestamp:%f",
event.action, event.angularVelocity, event.degree, event.timestamp);

Example

// xxx.ets
@Entry
@Component
struct CityList {
  @State message: string = "onDigitalCrown";

  build() {
    Column() {
      Row(){
        Stack() {
          Text(this.message)
            .fontSize(20)
            .fontColor(Color.White)
            .backgroundColor("#262626")
            .textAlign(TextAlign.Center)
            .focusable(true)
            .focusOnTouch(true)
            .defaultFocus(true)
            .borderWidth(2)
            .width(223).height(223)
            .borderRadius(110)
            .onDigitalCrown((event: CrownEvent) => {
              event.stopPropagation();
              this.message = "CrownEvent\n\n" + JSON.stringify(event);
              console.debug("action:%d, angularVelocity:%f, degree:%f, timestamp:%f",
                event.action, event.angularVelocity, event.degree, event.timestamp);
            })
        }.width("100%").height("100%")
      }.width("100%").height("100%")
    }
  }
}