目录

HandwriteComponent (Handwriting Suite Components)

This module provides the handwriting suite components, including the canvas and toolbar, which are integrated to quickly implement the handwriting capability.

You need to provide entrances and callbacks to the handwriting canvas. The canvas will trigger a callback when the initialization, loading, and saving actions are complete. You can customize app behavior in the callback.

Since: 5.0.0(12)

Modules to Import

import { HandwriteController,HandwriteComponent, PenHspInfo, PenType, HiddenToolType, HiddenConfig } from '@kit.Penkit';

HandwriteComponent

Model restriction: This API can be used only in the stage model.

Decorator: @Component

System capability: SystemCapability.Stylus.Handwrite

Since: 5.0.0(12)

Name Type Read-Only Optional Description
handwriteController HandwriteController No No Instance of the handwriting suite function class.
onInit InitCallback No Yes InitCallback:() => void, callback for suite initialization.
onScale ScaleCallback No Yes ScaleCallback: (scale: number) => void, callback for canvas scaling. The parameter of the callback method is the scaling factor of the current canvas.
defaultPenType PenType No Yes

Sets the default brush feature. In version 5.1.0(18), only parameters of the number type can be passed. The supported brushes are:

1: pen

2: ballpoint pen

3: pencil

4: marker

5: highlighter

7: mosaic pen

8: rubber

9: lasso

10: laser pointer

Since: 5.1.0(18)
defaultPenInfo PenHspInfo[] No Yes

Sets the default width of each brush.

Since: 5.1.0(18)
widthRatio number No Yes

Canvas width ratio. The value range is [0, 1]. The default value is 1.

Since: 6.0.0(20)
heightRatio number No Yes

Canvas height ratio. The value range is [0, 1]. The default value is 1.

Since: 6.0.0(20)
maxCanvasHeight number No Yes

Maximum height of the long canvas. The unit is vp. The value must be greater than 0. The default value is infinite.

Since: 6.1.0(23)
scaleDisabled boolean No Yes

Indicates whether to disable canvas scaling. The options are true (yes) and false (no). The default value is false. When scaleDisabled is set to true, users cannot zoom in or out on the canvas using gestures. This is applicable to scenarios where a fixed aspect ratio is required.

Since: 6.1.0(23)
onDidScroll DidScrollCallback No Yes

Callback for canvas scrolling. This callback id used to listen for the canvas scrolling position.

Since: 6.1.0(23)
hiddenTools HiddenConfig No Yes

Customizes handwriting tools. (Hides unnecessary handwriting tools.)

Since: 26.0.0

[h2]build

build(): void

Default constructor of a struct. This method cannot be directly called.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 5.0.0(12)

InitCallback

type InitCallback = () => void

Callback for suite initialization. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 5.1.0(18)

ScaleCallback

type ScaleCallback = (scale: number) => void

Callback for canvas scaling. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 5.1.0(18)

Parameters:

Parameter Type Mandatory Description
scale number Yes Callback used to return the scaling factor of the current canvas.

DidScrollCallback

type DidScrollCallback = (yOffset: number) => void

Callback for canvas scrolling. This callback is triggered when the canvas is scrolled to obtain the offset of the current canvas. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 6.1.0(23)

Parameters:

Parameter Type Mandatory Description
yOffset number Yes Offset of the current canvas. The unit is vp.

PenType

Brush types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 5.1.0(18)

Name Value Description
PEN 1 Pen.
BALLPOINT_PEN 2 Ballpoint pen.
PENCIL 3 Pencil.
MARKER 4 Marker.
HIGHLIGHTER_BRUSH 5 Highlighter.
MOSAIC 7 Mosaic pen.
RUBBER 8 Rubber.
LASSO 9 Lasso.
LASER 10 Laser pointer.

PenHspInfo

Brush type and width.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 5.1.0(18)

Parameters:

Name Type Read-Only Optional Description
penType PenType No No Brush type. In version 5.1.0(18), only parameters of the number type can be passed.
penWidth number No No

Brush width. The default width and value range of each brush are as follows:

- Pen 4(2-10)

- Ballpoint pen 4(2-10)

- Pencil 8(4-20)

- Marker 32(16-80)

- Highlighter 32(16-80)

- Mosaic pen 40(8-40)

- Rubber 50(10-120)

- Laser pointer 20(8-48)

HiddenConfig

Hides a specific tool on the toolbar. This API is applicable to the scenario of building a handwriting toolbar for an app.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 26.0.0

Name Type Read-Only Optional Description
hiddenOptionalTools HiddenToolType[] No Yes Collection of tools that can be hidden. The default value is [].
hiddenArcBox boolean No Yes Sets whether to hide the handwriting radial menu. The options are true (hidden) and false (not hidden). The default value is false.

HiddenToolType

Enumeration of types of handwriting tools that can be hidden. This API is applicable to the scenario of building a handwriting toolbar for an app.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Stylus.Handwrite

Since: 26.0.0

Name Value Description
PEN 1 Pen.
PENCIL 3 Pencil.
MARKER 4 Marker.
HIGHLIGHTER_BRUSH 5 Highlighter.
MOSAIC 7 Mosaic pen.
LASSO 1048576 Lasso.
LASER 3145728 Laser pointer.
GRAPHICS_TOOLS 4194304 Graphic tool.

Example:

import {
  HandwriteController,
  HandwriteComponent,
  PenType,
  PenHspInfo,
  HiddenToolType,
  HiddenConfig
} from '@kit.Penkit';

@Entry
@Component
struct HandWriteDemoComp {
  controller: HandwriteController = new HandwriteController();
  // Obtain the path for storing the handwritten file based on the app's storage rule. The path is for reference only.
  initPath: string = this.getUIContext().getHostContext()?.filesDir + '/aa';
  penWidth: number = 5;
  ballpointPenWidth: number = 6;
  @State yOffset: number = 0;

  aboutToAppear() {
    // Set the callback for the completion of the saving action during loading.
    this.controller.onLoad(this.callback);
  }

  // Callback triggered once the handwritten file is loaded and rendered on the screen. You will be notified of the result and can then customize actions here.
  callback = () => {
    // Custom action, for example, displaying the user operation guide after the file is loaded.
  }

  build() {
    Row() {
      Stack({ alignContent: Alignment.TopStart }) {
        HandwriteComponent({
          handwriteController: this.controller,
          defaultPenType: PenType.PEN, // (Optional) Default brush.
          defaultPenInfo: [{ penType: PenType.PEN, penWidth: this.penWidth },
            { penType: PenType.BALLPOINT_PEN, penWidth: this.ballpointPenWidth }] as PenHspInfo[], // (Optional) Default width of each brush.
          widthRatio: 1, // (Optional) Width ratio of the custom canvas size (ranging from 0 to 1).
          heightRatio: 1, // (Optional) Height ratio of the custom canvas size (ranging from 0 to 1).
          maxCanvasHeight: 5000, // (Optional) Maximum height of the custom canvas.
          scaleDisabled: false, // (Optional) Whether to disable scaling.
          hiddenTools: {
            hiddenOptionalTools: [HiddenToolType.PENCIL], // (Optional) Collection of tools to be hidden.
            hiddenArcBox: false // (Optional) Whether to hide the radial menu.
          } as HiddenConfig, // (Optional) Hide unnecessary handwriting tools.
          onInit: () => {
            // Callback triggered once the canvas initialization is complete. In this case, you can call the API to load and display the note content.
            this.controller?.load(this.initPath);
          },
          onScale: (scale: number) => {
            // Callback triggered when the canvas is scaled. The scaling factor of the current handwriting control is returned. Custom actions can be performed here.
          },
          onDidScroll: (yOffset: number) => {
            // Callback triggered when the canvas is scrolled. The vertical coordinate of the current scrolling position is returned. Custom actions can be performed here.
            this.yOffset = yOffset;
          }
        })
        // (Optional) Save and obtain the thumbnail. You can adjust or delete this component as required.
        Button('save')
          .onClick(async () => {
            // Obtain the path for storing the handwritten file based on the app's storage rule. The path is for reference only.
            const path = this.getUIContext().getHostContext()?.filesDir + '/aa';
            await this.controller?.save(path).then().catch((error: Error) => {
              console.error('err: ' + error);
            })
            // Obtain the thumbnail.
            this.controller.getThumbnail(this.controller?.getContentRange())?.then((pixelMap: PixelMap) => {
              if (pixelMap) {
                pixelMap.release();
                console.info('getThumbnail success');
              }
            })
          })
        // Set the scrolling position of the long canvas. The maximum scrolling distance is px2vp (1000000) minus the height of the list component.
        Search()
          .searchButton('scrollTo').onSubmit((value: string) => {
          if (!Number.isNaN(Number(value))) {
            this.controller.scrollTo(Number(value));
          }
        }).margin({ top: 100 }).width(220)
        // Offset of the current canvas.
        Text('onDidScroll: ' + this.yOffset)
          .margin({ top: 150 }).width(220)
      }
      .width('100%')
    }
    .height('100%')
  }
}

The methods in HandwriteController need to be executed in the canvas control initialization callback or in custom methods in the preceding example.

Set context information before using the method.

For details about the complete sample code, please refer to Penkit (ArkTS).