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> Since API version 12, you can use the **getMeasureUtils** API in **UIContext** to obtain the [MeasureUtils](js-apis-arkui-UIContext.md#measureutils12) object associated with the current UI context. 12> 13> 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). 14> 15> To ensure the correct sequence of events and the accuracy of the measurement results, listen for changes in font scaling whenever possible. 16 17## Modules to Import 18 19```ts 20import { MeasureText } from '@kit.ArkUI' 21``` 22 23## MeasureText.measureText 24 25static measureText(options: MeasureOptions): number 26 27Measures the width of the given text. 28 29**Atomic service API**: This API can be used in atomic services since API version 12. 30 31**System capability**: SystemCapability.ArkUI.ArkUI.Full 32 33**Parameters** 34 35| Name | Type | Mandatory | Description | 36| ------- | ------------------------------- | ---- | --------- | 37| options | [MeasureOptions](#measureoptions) | Yes | Information about the measured text.| 38 39**Return value** 40 41| Type | Description | 42| ------------ | --------- | 43| number | Text width.<br>Unit: px| 44 45 46**Example** 47 48> **NOTE** 49> 50>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. 51 52```ts 53import { MeasureText } from '@kit.ArkUI' 54 55@Entry 56@Component 57struct Index { 58 @State textWidth: number = MeasureText.measureText({ 59 // You are advised to this.getUIContext().getMeasureUtils().measureText(). 60 textContent: "Hello World", 61 fontSize: '50px' 62 }) 63 64 build() { 65 Row() { 66 Column() { 67 Text(`The width of 'Hello World': ${this.textWidth}`) 68 } 69 .width('100%') 70 } 71 .height('100%') 72 } 73} 74``` 75 76## MeasureText.measureTextSize<sup>10+</sup> 77 78static measureTextSize(options: MeasureOptions): SizeOptions 79 80Measures the width and height of the given text. 81 82**Atomic service API**: This API can be used in atomic services since API version 12. 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86**Parameters** 87 88| Name | Type | Mandatory | Description | 89| ------- | ------------------------------- | ---- | --------- | 90| options | [MeasureOptions](#measureoptions) | Yes | Information about the measured text.| 91 92**Return value** 93 94| Type | Description | 95| ------------ | --------- | 96| [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.| 97 98 99**Example** 100 101> **NOTE** 102> 103>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. 104 105```ts 106import { MeasureText } from '@kit.ArkUI' 107 108@Entry 109@Component 110struct Index { 111 textSize: SizeOptions = MeasureText.measureTextSize({ 112 // You are advised to this.getUIContext().getMeasureUtils().measureText(). 113 textContent: "Hello World", 114 fontSize: '50px' 115 }) 116 117 build() { 118 Row() { 119 Column() { 120 Text(`The width of 'Hello World': ${this.textSize.width}`) 121 Text(`The height of 'Hello World': ${this.textSize.height}`) 122 } 123 .width('100%') 124 } 125 .height('100%') 126 } 127} 128``` 129 130## MeasureOptions 131 132Provides attributes of the measured text. 133 134**Atomic service API**: This API can be used in atomic services since API version 12. 135 136**System capability**: SystemCapability.ArkUI.ArkUI.Full 137 138| Name | Type | Mandatory| Description | 139| -------------- | -------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- | 140| textContent | string \| [Resource](arkui-ts/ts-types.md#resource) | Yes | Content of the measured text. | 141| 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. | 142| 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. | 143| 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 | 144| 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**| 145| 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.| 146| letterSpacing | number \| string | No | Letter spacing of the measured text.| 147| 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| 148| 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| 149| maxLines<sup>10+</sup> | number | No | Maximum number of lines in the measured text.| 150| lineHeight<sup>10+</sup> | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | No | Line height of the measured text.| 151| baselineOffset<sup>10+</sup> | number \| string | No | Baseline offset of the measured text.<br>Default value: **0**| 152| 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| 153| textIndent<sup>11+</sup> | number \| string | No | Indentation of the first line.<br>Default value: **0**| 154| 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 (...).| 155