1# @ohos.measure (文本计算)
2
3本模块提供文本宽度、高度等相关计算。
4
5> **说明**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8>
9> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用,即不能在UIAbility的生命周期中调用,需要在创建组件实例后使用。
10>
11> 从API version 12开始,可以通过UIContext中的getMeasureUtils方法获取当前UI上下文关联的[MeasureUtils](js-apis-arkui-UIContext.md#measureutils12)实例。
12>
13> 如需更多测算文本参数,建议使用图形对应测算接口[Paragraph](../apis-arkgraphics2d/js-apis-graphics-text.md#paragraph)接口。
14>
15> 为保障时序正确,推荐需要测算文本的开发者自行监听字体缩放变化,保证测算结果的准确性。
16
17## 导入模块
18
19```ts
20import { MeasureText } from '@kit.ArkUI'
21```
22
23## MeasureText.measureText
24
25static measureText(options: MeasureOptions): number
26
27计算指定文本的宽度。
28
29**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
30
31**系统能力:** SystemCapability.ArkUI.ArkUI.Full
32
33**参数:**
34
35| 参数名     | 类型                              | 必填   | 说明        |
36| ------- | ------------------------------- | ---- | --------- |
37| options | [MeasureOptions](#measureoptions) | 是    | 被计算文本描述信息。 |
38
39**返回值:**
40
41| 类型          | 说明       |
42| ------------  | --------- |
43| number        | 文本宽度。<br/>单位:px |
44
45
46**示例:**
47
48> **说明**
49>
50>推荐通过[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getMeasureUtils](./js-apis-arkui-UIContext.md#getmeasureutils12)方法获取当前UI上下文关联的[MeasureUtils](js-apis-arkui-UIContext.md#measureutils12)实例
51
52```ts
53import { MeasureText } from '@kit.ArkUI'
54
55@Entry
56@Component
57struct Index {
58  @State textWidth: number = MeasureText.measureText({
59    // 建议使用 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
80计算指定文本的宽度和高度。
81
82**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
83
84**系统能力:** SystemCapability.ArkUI.ArkUI.Full
85
86**参数:**
87
88| 参数名     | 类型                              | 必填   | 说明        |
89| ------- | ------------------------------- | ---- | --------- |
90| options | [MeasureOptions](#measureoptions) | 是    | 被计算文本描述信息。 |
91
92**返回值:**
93
94| 类型          | 说明       |
95| ------------  | --------- |
96| [SizeOptions](arkui-ts/ts-types.md#sizeoptions)  | 返回文本所占布局宽度和高度。<br/>**说明:**  <br/>文本宽度以及高度返回值单位均为px。 |
97
98
99**示例:**
100
101> **说明**
102>
103>推荐通过[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getMeasureUtils](./js-apis-arkui-UIContext.md#getmeasureutils12)方法获取当前UI上下文关联的[MeasureUtils](js-apis-arkui-UIContext.md#measureutils12)实例
104
105```ts
106import { MeasureText } from '@kit.ArkUI'
107
108@Entry
109@Component
110struct Index {
111  textSize: SizeOptions = MeasureText.measureTextSize({
112    // 建议使用 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
132被计算文本属性。
133
134**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
135
136**系统能力:** SystemCapability.ArkUI.ArkUI.Full
137
138| 名称           | 类型                                                                                                | 必填 | 说明                      |
139| -------------- | -------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- |
140| textContent | string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource)                                                                                             | 是   | 设置被计算文本内容。                                  |
141| constraintWidth<sup>10+</sup> | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource)   | 否   | 设置被计算文本布局宽度。<br/>**说明:** <br/>默认单位为vp,不支持设置百分比字符串。若不设置,则文本SizeOption宽度为单行布局所占最大宽度值,若设置则为设置值。                             |
142| fontSize       | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource)               | 否   | 设置被计算文本字体大小,fontSize为number类型时,使用vp单位。<br/>默认值:16<br/>**说明:** <br/>不支持设置百分比字符串。<br/>从API version 12开始,fontSize为number类型时,使用fp单位。    |
143| fontStyle      | number&nbsp;\|&nbsp;[FontStyle](arkui-ts/ts-appendix-enums.md#fontstyle)                        | 否   | 设置被计算文本字体样式。<br>默认值:FontStyle.Normal            |
144| fontWeight     | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[FontWeight](arkui-ts/ts-appendix-enums.md#fontweight)  | 否   | 设置被计算文本的字体粗细,number类型取值[100,&nbsp;900],取值间隔为100,默认为400,取值越大,字体越粗。string类型仅支持number类型取值的字符串形式,例如"400",以及"bold"、"bolder"、"lighter"、"regular"、"medium",分别对应FontWeight中相应的枚举值。<br/>默认值:FontWeight.Normal|
145| fontFamily     | string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource)                                   | 否   | 设置被计算文本字体列表。默认字体'HarmonyOS Sans',且当前只支持这种字体。|
146| letterSpacing  | number&nbsp;\|&nbsp;string                                                                         | 否   | 设置被计算文本字符间距。|
147| textAlign<sup>10+</sup>  | number&nbsp;\|&nbsp;[TextAlign](arkui-ts/ts-appendix-enums.md#textalign)              | 否   | 设置被计算文本水平方向的对齐方式。<br/>默认值:TextAlign.Start|
148| overflow<sup>10+</sup>  | number&nbsp;\|&nbsp;[TextOverflow](arkui-ts/ts-appendix-enums.md#textoverflow)         | 否   | 设置被计算文本超长时的截断方式。|
149| maxLines<sup>10+</sup>  | number                                                                                    | 否   | 设置被计算文本最大行数。|
150| lineHeight<sup>10+</sup>  | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource)    | 否   | 设置被计算文本行高。|
151| baselineOffset<sup>10+</sup>  | number&nbsp;\|&nbsp;string                                                          | 否   | 设置被计算文本基线的偏移量。<br />默认值:0 |
152| textCase<sup>10+</sup>  | number&nbsp;\|&nbsp;[TextCase](arkui-ts/ts-appendix-enums.md#textcase)                 | 否   | 设置被计算文本大小写。<br />默认值:TextCase.Normal |
153| textIndent<sup>11+</sup> | number&nbsp;\|&nbsp;string  | 否  | 设置首行文本缩进,默认值0。 |
154| wordBreak<sup>11+</sup> | [WordBreak](arkui-ts/ts-appendix-enums.md#wordbreak11) | 否   | 设置断行规则。 <br />默认值:WordBreak.BREAK_WORD <br/>**说明:** <br/>WordBreak.BREAK_ALL与{overflow:&nbsp;TextOverflow.Ellipsis},`maxLines`组合使用可实现英文单词按字母截断,超出部分以省略号显示。 |