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