• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
10## Modules to Import
11
12```
13import measure from '@ohos.measure'
14```
15
16## measure.measureText
17
18measureText(options: MeasureOptions): number
19
20Measures the width of the given single-line text.
21
22**System capability**: SystemCapability.ArkUI.ArkUI.Full
23
24**Parameters**
25
26| Name    | Type                             | Mandatory  | Description       |
27| ------- | ------------------------------- | ---- | --------- |
28| options | [MeasureOptions](#measureoptions) | Yes   | Information about the measured text.|
29
30**Return value**
31
32| Type         | Description      |
33| ------------  | --------- |
34| number        | Text width.<br>The unit is px.|
35
36
37**Example**
38
39```ts
40import measure from '@ohos.measure'
41@Entry
42@Component
43struct Index {
44  @State message: string = 'Hello World'
45  @State textWidth : number = measure.measureText({
46    textContent: "Hello word",
47    fontSize: '50px'
48  })
49  build() {
50    Row() {
51      Column() {
52        Text("The width of 'Hello World': " + this.textWidth)
53      }
54      .width('100%')
55    }
56    .height('100%')
57  }
58}
59```
60
61## measure.measureTextSize<sup>10+</sup>
62
63measureTextSize(options: MeasureOptions): SizeOptions
64
65Measures the width of the given single-line text.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Full
68
69**Parameters**
70
71| Name    | Type                             | Mandatory  | Description       |
72| ------- | ------------------------------- | ---- | --------- |
73| options | [MeasureOptions](#measureoptions) | Yes   | Information about the measured text.|
74
75**Return value**
76
77| Type         | Description      |
78| ------------  | --------- |
79| SizeOptions   | Layout width and height occupied by the text.<br>The unit is px.|
80
81
82**Example**
83
84```ts
85import measure from '@ohos.measure'
86@Entry
87@Component
88struct Index {
89  @State message: string = 'Hello World'
90  textSize : SizeOptions = measure.measureTextSize({
91    textContent: "Hello word",
92    fontSize: '50px'
93  })
94  build() {
95    Row() {
96      Column() {
97        Text("The width of 'Hello World': " + this.textSize.width)
98        Text("The height of 'Hello World': " + this.textSize.height)
99      }
100      .width('100%')
101    }
102    .height('100%')
103  }
104}
105```
106
107## MeasureOptions
108
109Provides attributes of the measured text.
110
111**System capability**: SystemCapability.ArkUI.ArkUI.Full
112
113| Name          | Type                                                                                               | Mandatory| Description                     |
114| -------------- | -------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- |
115| textContent | string                                                                                             | Yes  | Content of the measured text.                                 |
116| constraintWidth<sup>10+</sup> | number \| string \| [Resource](../arkui-ts/ts-types.md#resource)   | No  | Layout width of the measured text.<br>The default unit is vp.                              |
117| fontSize       | number \| string \| [Resource](../arkui-ts/ts-types.md#resource)               | No  | Font size of the measured text. If the value is of the number type, the unit fp is used.<br>Default value: **16fp**<br>**NOTE**<br>The value cannot be a percentage.   |
118| fontStyle      | number \| [FontStyle](../arkui-ts/ts-appendix-enums.md#fontstyle)                        | No  | Font style of the measured text.<br>Default value: **FontStyle.Normal**           |
119| fontWeight     | number \| string \| [FontWeight](../arkui-ts/ts-appendix-enums.md#fontweight)  | No  | Font width of the measured text.<br>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**.<br>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**|
120| 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.|
121| letterSpacing  | number \| string                                                                         | No  | Letter spacing of the measured text.|
122| 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**|
123| overflow<sup>10+</sup>  | number \| [TextOverflow](../arkui-ts/ts-appendix-enums.md#textoverflow)         | No  | Display mode when the measured text is too long.|
124| maxLines<sup>10+</sup>  | number                                                                                    | No  | Maximum number of lines in the measured text.|
125| lineHeight<sup>10+</sup>  | number \| string \| [Resource](../arkui-ts/ts-types.md#resource)    | No  | Line height of the measured text.|
126| baselineOffset<sup>10+</sup>  | number \| string                                                          | No  | Baseline offset of the measured text.<br>Default value: **0**|
127| textCase<sup>10+</sup>  | number \| [TextCase](../arkui-ts/ts-appendix-enums.md#textcase)                 | No  | Case of the measured text.<br>Default value: **TextCase.Normal**|
128