1# @ohos.measure (文本计算) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @hddgzw--> 5<!--Designer: @pssea--> 6<!--Tester: @jiaoaozihao--> 7<!--Adviser: @HelloCrease--> 8 9本模块提供文本宽度、高度等相关计算。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。 16> 17> 如需更多测算文本参数，建议使用图形对应测算接口[Paragraph](../apis-arkgraphics2d/js-apis-graphics-text.md#paragraph)接口。 18> 19> 调用文本计算接口时，不推荐同时用[ApplicationContext.setFontSizeScale](../apis-ability-kit/js-apis-inner-application-applicationContext.md#applicationcontextsetfontsizescale13)设置应用字体大小缩放比例。为了确保时序正确性，建议开发者自行监听字体缩放变化，以保证测算结果的准确性。 20> 21> 在测算裁剪后的文本时，由于某些Unicode字符（如emoji）的码位长度大于1，直接按字符串长度裁剪会导致不准确的结果。建议基于Unicode码点进行迭代处理，避免错误截断字符，确保测算结果准确。 22 23## 导入模块 24 25```ts 26import { MeasureText } from '@kit.ArkUI'; 27``` 28 29## MeasureText.measureText<sup>(deprecated)</sup> 30 31static measureText(options: MeasureOptions): number 32 33计算指定文本的宽度。 34 35> **说明：** 36> 37> 从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMeasureUtils](arkts-apis-uicontext-uicontext.md#getmeasureutils12)获取[MeasureUtils](arkts-apis-uicontext-measureutils.md)实例，再通过此实例调用替代方法[measureText](arkts-apis-uicontext-measureutils.md#measuretext12)。 38> 39> 从API version 12开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMeasureUtils](arkts-apis-uicontext-uicontext.md#getmeasureutils12)方法获取当前UI上下文关联的[MeasureUtils](arkts-apis-uicontext-measureutils.md)对象。 40 41**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.ArkUI.ArkUI.Full 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| ------- | ------------------------------- | ---- | --------- | 49| options | [MeasureOptions](#measureoptions) | 是 | 被计算文本描述信息。 | 50 51**返回值：** 52 53| 类型 | 说明 | 54| ------------ | --------- | 55| number | 文本宽度。<br/>单位：px | 56 57 58**示例：** 59 60> **说明** 61> 62> 直接使用MeasureText可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，推荐通过[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMeasureUtils](./arkts-apis-uicontext-uicontext.md#getmeasureutils12)方法获取当前UI上下文关联的[MeasureUtils](arkts-apis-uicontext-measureutils.md)实例。 63 64```ts 65import { MeasureText } from '@kit.ArkUI'; 66 67@Entry 68@Component 69struct Index { 70 @State textWidth: number = MeasureText.measureText({ 71 // 建议使用 this.getUIContext().getMeasureUtils().measureText()接口 72 textContent: "Hello World", 73 fontSize: '50px' 74 }); 75 76 build() { 77 Row() { 78 Column() { 79 Text(`The width of 'Hello World': ${this.textWidth}`) 80 } 81 .width('100%') 82 } 83 .height('100%') 84 } 85} 86``` 87 88## MeasureText.measureTextSize<sup>(deprecated)</sup> 89 90static measureTextSize(options: MeasureOptions): SizeOptions 91 92计算指定文本的宽度和高度。 93 94> **说明：** 95> 96> 从API version 10开始支持，从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMeasureUtils](arkts-apis-uicontext-uicontext.md#getmeasureutils12)获取[MeasureUtils](arkts-apis-uicontext-measureutils.md)实例，再通过此实例调用替代方法[measureTextSize](arkts-apis-uicontext-measureutils.md#measuretextsize12)。 97> 98> 从API version 12开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMeasureUtils](arkts-apis-uicontext-uicontext.md#getmeasureutils12)方法获取当前UI上下文关联的[MeasureUtils](arkts-apis-uicontext-measureutils.md)对象。 99 100**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 101 102**系统能力：** SystemCapability.ArkUI.ArkUI.Full 103 104**参数：** 105 106| 参数名 | 类型 | 必填 | 说明 | 107| ------- | ------------------------------- | ---- | --------- | 108| options | [MeasureOptions](#measureoptions) | 是 | 被计算文本描述信息。 | 109 110**返回值：** 111 112| 类型 | 说明 | 113| ------------ | --------- | 114| [SizeOptions](arkui-ts/ts-types.md#sizeoptions) | 返回文本所占布局宽度和高度。<br/>**说明:** <br/>文本宽度以及高度返回值单位均为px。 | 115 116 117**示例：** 118 119> **说明** 120> 121> 直接使用MeasureText可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，推荐通过[UIContext](arkts-apis-uicontext-uicontext.md)中的[getMeasureUtils](./arkts-apis-uicontext-uicontext.md#getmeasureutils12)方法获取当前UI上下文关联的[MeasureUtils](arkts-apis-uicontext-measureutils.md)实例。 122 123```ts 124import { MeasureText } from '@kit.ArkUI'; 125 126@Entry 127@Component 128struct Index { 129 textSize: SizeOptions = MeasureText.measureTextSize({ 130 // 建议使用 this.getUIContext().getMeasureUtils().measureTextSize()接口 131 textContent: "Hello World", 132 fontSize: '50px' 133 }); 134 135 build() { 136 Row() { 137 Column() { 138 Text(`The width of 'Hello World': ${this.textSize.width}`) 139 Text(`The height of 'Hello World': ${this.textSize.height}`) 140 } 141 .width('100%') 142 } 143 .height('100%') 144 } 145} 146``` 147 148## MeasureOptions 149 150被计算文本属性。 151 152**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 153 154**系统能力：** SystemCapability.ArkUI.ArkUI.Full 155 156| 名称 | 类型 | 只读 | 可选 | 说明 | 157| -------------- | ------------------------- | ---- | ---- | ----------------------------- | 158| textContent | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 否 | 设置被计算文本内容。 | 159| constraintWidth<sup>10+</sup> | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 设置被计算文本布局宽度。<br/>**说明：** <br/>默认单位为vp，不支持设置百分比字符串。若不设置，则文本SizeOption宽度为单行布局所占最大宽度值，若设置则为设置值。 | 160| fontSize | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 设置被计算文本字体大小，fontSize为number类型时，使用vp单位。<br/>默认值：16<br/>**说明：** <br/>不支持设置百分比字符串。<br/>从API version 12开始，fontSize为number类型时，使用fp单位。 | 161| fontStyle | number \| [FontStyle](arkui-ts/ts-appendix-enums.md#fontstyle) | 否 | 是 | 设置被计算文本字体样式。<br>默认值：FontStyle.Normal<br/>number类型取值范围为[0,1]，取值间隔为1，依次对应FontStyle中的枚举值。 | 162| 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| 163| fontFamily | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 设置被计算文本字体列表。默认字体'HarmonyOS Sans'，且当前只支持这种字体。| 164| letterSpacing | number \| string | 否 | 是 | 设置被计算文本字符间距。<br/>默认值：0 | 165| textAlign<sup>10+</sup> | number \| [TextAlign](arkui-ts/ts-appendix-enums.md#textalign) | 否 | 是 | 设置被计算文本水平方向的对齐方式。<br/>默认值：TextAlign.Start<br/>number类型取值范围为[0,3]，取值间隔为1，依次对应TextAlign中的枚举值。 | 166| overflow<sup>10+</sup> | number \| [TextOverflow](arkui-ts/ts-appendix-enums.md#textoverflow) | 否 | 是 | 设置被计算文本超长时的截断方式。<br/>默认值：1<br/>number类型取值范围为[0,3]，取值间隔为1，依次对应TextOverflow中的枚举值。 | 167| maxLines<sup>10+</sup> | number | 否 | 是 | 设置被计算文本最大行数。<br/>取值范围：[0, INT32_MAX] | 168| lineHeight<sup>10+</sup> | number \| string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 设置被计算文本行高。| 169| baselineOffset<sup>10+</sup> | number \| string | 否 | 是 | 设置被计算文本基线的偏移量。<br />默认值：0 | 170| textCase<sup>10+</sup> | number \| [TextCase](arkui-ts/ts-appendix-enums.md#textcase) | 否 | 是 | 设置被计算文本大小写。<br />默认值：TextCase.Normal<br/>number类型取值范围为[0,2]，取值间隔为1，依次对应TextCase中的枚举值。 | 171| textIndent<sup>11+</sup> | number \| string | 否 | 是 | 设置首行文本缩进，默认值为0。 | 172| 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`组合使用可实现英文单词按字母截断，超出部分以省略号显示。 |