harmony 鸿蒙@ohos.measure (Text Measurement)

2025-06-12
浏览 (4)

@ohos.measure (Text Measurement)

The measure module provides APIs for measuring text metrics, such as text height and width.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

This module cannot be used in the file declaration of the UIAbility. In other words, the APIs of this module can be used only after a component instance is created; they cannot be called in the lifecycle of the UIAbility.

To perform more complex text measurements, you are advised to call the corresponding graphics measurement API, specifically Paragraph.

To ensure the correct sequence of events and the accuracy of the measurement results, listen for changes in font scaling whenever possible.

Modules to Import

import { MeasureText } from '@kit.ArkUI'

MeasureText.measureText^(deprecated)

static measureText(options: MeasureOptions): number

Measures the width of the given text.

NOTE

This API is deprecated since API version 18. You are advised to use measureText instead on the obtained MeasureUtils object.

Since API version 12, you can use the getMeasureUtils API in UIContext to obtain the MeasureUtils object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
options	MeasureOptions	Yes	Information about the measured text.

Return value

Type	Description
number	Text width. Unit: px

Example

NOTE

You are advised to use the getMeasureUtils API in UIContext to obtain the MeasureUtils instance associated with the current UI context.

import { MeasureText } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  @State textWidth: number = MeasureText.measureText({
    // You are advised to this.getUIContext().getMeasureUtils().measureText().
    textContent: "Hello World",
    fontSize: '50px'
  })

  build() {
    Row() {
      Column() {
        Text(`The width of 'Hello World': ${this.textWidth}`)
      }
      .width('100%')
    }
    .height('100%')
  }
}

MeasureText.measureTextSize^(deprecated)

static measureTextSize(options: MeasureOptions): SizeOptions

Measures the width and height of the given text.

NOTE

This API is supported since API version 10 and deprecated since API version 18. You are advised to use measureTextSize instead on the obtained MeasureUtils object.

Since API version 12, you can use the getMeasureUtils API in UIContext to obtain the MeasureUtils object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
options	MeasureOptions	Yes	Information about the measured text.

Return value

Type	Description
SizeOptions	Layout width and height occupied by the text. NOTE The return values for text width and height are both in px.

Example

NOTE

You are advised to use the getMeasureUtils API in UIContext to obtain the MeasureUtils instance associated with the current UI context.

import { MeasureText } from '@kit.ArkUI'

@Entry
@Component
struct Index {
  textSize: SizeOptions = MeasureText.measureTextSize({
    // You are advised to this.getUIContext().getMeasureUtils().measureText().
    textContent: "Hello World",
    fontSize: '50px'
  })

  build() {
    Row() {
      Column() {
        Text(`The width of 'Hello World': ${this.textSize.width}`)
        Text(`The height of 'Hello World': ${this.textSize.height}`)
      }
      .width('100%')
    }
    .height('100%')
  }
}

MeasureOptions

Provides attributes of the measured text.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
textContent	string \|Resource	Yes	Content of the measured text.
constraintWidth¹⁰⁺	number \|string \|Resource	No	Layout width of the measured text. NOTE The default unit is vp. The value cannot be a percentage. If this parameter is not set, the value of SizeOption is the maximum width allowed for the single-line text.
fontSize	number \|string \|Resource	No	Font size of the text to be measured. When fontSize is of the number type, the unit is vp. Default value: 16 NOTE The value cannot be a percentage. Since API version 12, the fp unit is used when fontSize is of the number type.
fontStyle	number \|FontStyle	No	Font style of the measured text. Default value: FontStyle.Normal Value range for the number type: [0, 1], with intervals of 1, corresponding to the values in the FontStyle enum
fontWeight	number \|string \|FontWeight	No	Font width of the measured text. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a heavier font weight. The default value is 400. For the string type, only strings of the number type are supported, for example, 400, “bold”, “bolder”, “lighter”, “regular”, and “medium”, which correspond to the enumerated values in FontWeight. Default value: FontWeight.Normal
fontFamily	string \|Resource	No	Font family of the measured text. Default value: ‘HarmonyOS Sans’ Only the default font is supported.
letterSpacing	number \|string	No	Letter spacing of the measured text.
textAlign¹⁰⁺	number \|TextAlign	No	Horizontal alignment mode of the measured text. Default value: TextAlign.Start Value range for the number type: [0, 3], with intervals of 1, corresponding to the values in the TextAlign enum
overflow¹⁰⁺	number \|TextOverflow	No	Display mode when the measured text is too long. Default value: 1 Value range for the number type: [0, 3], with intervals of 1, corresponding to the values in the TextOverflow enum
maxLines¹⁰⁺	number	No	Maximum number of lines in the measured text.
lineHeight¹⁰⁺	number \|string \|Resource	No	Line height of the measured text.
baselineOffset¹⁰⁺	number \|string	No	Baseline offset of the measured text. Default value: 0
textCase¹⁰⁺	number \|TextCase	No	Case of the measured text. Default value: TextCase.Normal Value range for the number type: [0, 2], with intervals of 1, corresponding to the values in the TextCase enum
textIndent¹¹⁺	number \|string	No	Indentation of the first line. Default value: 0
wordBreak¹¹⁺	WordBreak	No	Line break rule. Default value: WordBreak.BREAK_WORD NOTE When used with {overflow: TextOverflow.Ellipsis} and maxLines, WordBreak.BREAK_ALL can insert line breaks between letters when overflow occurs and display excess content with an ellipsis (…).