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
25measureText(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({ // You are advised to use this.getUIContext().getMeasureUtils().measureText().
59    textContent: "Hello World",
60    fontSize: '50px'
61  })
62
63  build() {
64    Row() {
65      Column() {
66        Text(`The width of 'Hello World': ${this.textWidth}`)
67      }
68      .width('100%')
69    }
70    .height('100%')
71  }
72}
73```
74
75## MeasureText.measureTextSize<sup>10+</sup>
76
77measureTextSize(options: MeasureOptions): SizeOptions
78
79Measures the width and height of the given text.
80
81**Atomic service API**: This API can be used in atomic services since API version 12.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85**Parameters**
86
87| Name    | Type                             | Mandatory  | Description       |
88| ------- | ------------------------------- | ---- | --------- |
89| options | [MeasureOptions](#measureoptions) | Yes   | Information about the measured text.|
90
91**Return value**
92
93| Type         | Description      |
94| ------------  | --------- |
95| [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.|
96
97
98**Example**
99
100> **NOTE**
101>
102>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.
103
104```ts
105import { MeasureText } from '@kit.ArkUI'
106
107@Entry
108@Component
109struct Index {
110  textSize : SizeOptions = MeasureText.measureTextSize({ // You are advised to use this.getUIContext().getMeasureUtils().measureText().
111    textContent: "Hello World",
112    fontSize: '50px'
113  })
114  build() {
115    Row() {
116      Column() {
117        Text(`The width of 'Hello World': ${this.textSize.width}`)
118        Text(`The height of 'Hello World': ${this.textSize.height}`)
119      }
120      .width('100%')
121    }
122    .height('100%')
123  }
124}
125```
126
127## MeasureOptions
128
129Provides attributes of the measured text.
130
131**Atomic service API**: This API can be used in atomic services since API version 12.
132
133**System capability**: SystemCapability.ArkUI.ArkUI.Full
134
135| Name          | Type                                                                                               | Mandatory| Description                     |
136| -------------- | -------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- |
137| textContent | string \| [Resource](arkui-ts/ts-types.md#resource)                                                                                             | Yes  | Content of the measured text.                                 |
138| 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.                            |
139| 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.   |
140| fontStyle      | number \| [FontStyle](arkui-ts/ts-appendix-enums.md#fontstyle)                        | No  | Font style of the measured text.<br>Default value: **FontStyle.Normal**           |
141| 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**|
142| 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.|
143| letterSpacing  | number \| string                                                                         | No  | Letter spacing of the measured text.|
144| 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**|
145| overflow<sup>10+</sup>  | number \| [TextOverflow](arkui-ts/ts-appendix-enums.md#textoverflow)         | No  | Display mode when the measured text is too long.|
146| maxLines<sup>10+</sup>  | number                                                                                    | No  | Maximum number of lines in the measured text.|
147| lineHeight<sup>10+</sup>  | number \| string \| [Resource](arkui-ts/ts-types.md#resource)    | No  | Line height of the measured text.|
148| baselineOffset<sup>10+</sup>  | number \| string                                                          | No  | Baseline offset of the measured text.<br>Default value: **0**|
149| textCase<sup>10+</sup>  | number \| [TextCase](arkui-ts/ts-appendix-enums.md#textcase)                 | No  | Case of the measured text.<br>Default value: **TextCase.Normal**|
150| textIndent<sup>11+</sup> | number \| string  | No | Indentation of the first line.<br>Default value: **0**|
151| 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 (...).|
152