1# @ohos.measure (Text Measurement) 2 3The **measure** module provides APIs for measuring text metrics, such as text height and width. 4 5> **NOTE** 6> 7> 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. 8> 9> This module cannot be used in the file declaration of the [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md). 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. 10> 11> To perform more complex text measurements, you are advised to call the corresponding graphics measurement API, specifically [Paragraph](../apis-arkgraphics2d/js-apis-graphics-text.md#paragraph). 12> 13> To ensure the correct sequence of events and the accuracy of the measurement results, listen for changes in font scaling whenever possible. 14 15## Modules to Import 16 17```ts 18import { MeasureText } from '@kit.ArkUI' 19``` 20 21## MeasureText.measureText<sup>(deprecated)</sup> 22 23static measureText(options: MeasureOptions): number 24 25Measures the width of the given text. 26 27> **NOTE** 28> 29> This API is deprecated since API version 18. You are advised to use [measureText](js-apis-arkui-UIContext.md#measuretext12) instead on the obtained [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) object. 30> 31> Since API version 12, you can use the [getMeasureUtils](js-apis-arkui-UIContext.md#getmeasureutils12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) object associated with the current UI context. 32 33**Atomic service API**: This API can be used in atomic services since API version 12. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37**Parameters** 38 39| Name | Type | Mandatory | Description | 40| ------- | ------------------------------- | ---- | --------- | 41| options | [MeasureOptions](#measureoptions) | Yes | Information about the measured text.| 42 43**Return value** 44 45| Type | Description | 46| ------------ | --------- | 47| number | Text width.<br>Unit: px| 48 49 50**Example** 51 52> **NOTE** 53> 54>You are advised to use the [getMeasureUtils](./js-apis-arkui-UIContext.md#getmeasureutils12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) instance associated with the current UI context. 55 56```ts 57import { MeasureText } from '@kit.ArkUI' 58 59@Entry 60@Component 61struct Index { 62 @State textWidth: number = MeasureText.measureText({ 63 // You are advised to this.getUIContext().getMeasureUtils().measureText(). 64 textContent: "Hello World", 65 fontSize: '50px' 66 }) 67 68 build() { 69 Row() { 70 Column() { 71 Text(`The width of 'Hello World': ${this.textWidth}`) 72 } 73 .width('100%') 74 } 75 .height('100%') 76 } 77} 78``` 79 80## MeasureText.measureTextSize<sup>(deprecated)</sup> 81 82static measureTextSize(options: MeasureOptions): SizeOptions 83 84Measures the width and height of the given text. 85 86> **NOTE** 87> 88> This API is supported since API version 10 and deprecated since API version 18. You are advised to use [measureTextSize](js-apis-arkui-UIContext.md#measuretextsize12) instead on the obtained [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) object. 89> 90> Since API version 12, you can use the [getMeasureUtils](js-apis-arkui-UIContext.md#getmeasureutils12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) object associated with the current UI context. 91 92**Atomic service API**: This API can be used in atomic services since API version 12. 93 94**System capability**: SystemCapability.ArkUI.ArkUI.Full 95 96**Parameters** 97 98| Name | Type | Mandatory | Description | 99| ------- | ------------------------------- | ---- | --------- | 100| options | [MeasureOptions](#measureoptions) | Yes | Information about the measured text.| 101 102**Return value** 103 104| Type | Description | 105| ------------ | --------- | 106| [SizeOptions](arkui-ts/ts-types.md#sizeoptions) | Layout width and height occupied by the text.<br>**NOTE**<br>The return values for text width and height are both in px.| 107 108 109**Example** 110 111> **NOTE** 112> 113>You are advised to use the [getMeasureUtils](./js-apis-arkui-UIContext.md#getmeasureutils12) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) instance associated with the current UI context. 114 115```ts 116import { MeasureText } from '@kit.ArkUI' 117 118@Entry 119@Component 120struct Index { 121 textSize: SizeOptions = MeasureText.measureTextSize({ 122 // You are advised to this.getUIContext().getMeasureUtils().measureText(). 123 textContent: "Hello World", 124 fontSize: '50px' 125 }) 126 127 build() { 128 Row() { 129 Column() { 130 Text(`The width of 'Hello World': ${this.textSize.width}`) 131 Text(`The height of 'Hello World': ${this.textSize.height}`) 132 } 133 .width('100%') 134 } 135 .height('100%') 136 } 137} 138``` 139 140## MeasureOptions 141 142Provides attributes of the measured text. 143 144**Atomic service API**: This API can be used in atomic services since API version 12. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148| Name | Type | Mandatory| Description | 149| -------------- | -------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- | 150| textContent | string \| [Resource](arkui-ts/ts-types.md#resource) | Yes | Content of the measured text. | 151| constraintWidth<sup>10+</sup> | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | No | Layout width of the measured text.<br>**NOTE**<br>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. | 152| fontSize | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | No | Font size of the text to be measured. When **fontSize** is of the number type, the unit is vp.<br>Default value: **16**<br>**NOTE**<br>The value cannot be a percentage.<br>Since API version 12, the fp unit is used when **fontSize** is of the number type. | 153| fontStyle | number \| [FontStyle](arkui-ts/ts-appendix-enums.md#fontstyle) | No | Font style of the measured text.<br>Default value: **FontStyle.Normal**<br>Value range for the number type: [0, 1], with intervals of 1, corresponding to the values in the **FontStyle** enum | 154| fontWeight | number \| string \| [FontWeight](arkui-ts/ts-appendix-enums.md#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**.<br>Default value: **FontWeight.Normal**| 155| fontFamily | string \| [Resource](arkui-ts/ts-types.md#resource) | No | Font family of the measured text. Default value: **'HarmonyOS Sans'**<br>Only the default font is supported.| 156| letterSpacing | number \| string | No | Letter spacing of the measured text.| 157| textAlign<sup>10+</sup> | number \| [TextAlign](arkui-ts/ts-appendix-enums.md#textalign) | No | Horizontal alignment mode of the measured text.<br>Default value: **TextAlign.Start**<br>Value range for the number type: [0, 3], with intervals of 1, corresponding to the values in the **TextAlign** enum| 158| overflow<sup>10+</sup> | number \| [TextOverflow](arkui-ts/ts-appendix-enums.md#textoverflow) | No | Display mode when the measured text is too long.<br>Default value: **1**<br>Value range for the number type: [0, 3], with intervals of 1, corresponding to the values in the **TextOverflow** enum| 159| maxLines<sup>10+</sup> | number | No | Maximum number of lines in the measured text.| 160| lineHeight<sup>10+</sup> | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | No | Line height of the measured text.| 161| baselineOffset<sup>10+</sup> | number \| string | No | Baseline offset of the measured text.<br>Default value: **0**| 162| textCase<sup>10+</sup> | number \| [TextCase](arkui-ts/ts-appendix-enums.md#textcase) | No | Case of the measured text.<br>Default value: **TextCase.Normal**<br>Value range for the number type: [0, 2], with intervals of 1, corresponding to the values in the **TextCase** enum| 163| textIndent<sup>11+</sup> | number \| string | No | Indentation of the first line.<br>Default value: **0**| 164| wordBreak<sup>11+</sup> | [WordBreak](arkui-ts/ts-appendix-enums.md#wordbreak11) | No | Line break rule.<br>Default value: **WordBreak.BREAK_WORD**<br>**NOTE**<br>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 (...).| 165