# 属性字符串方便灵活应用文本样式的对象，可通过TextController中的[setStyledString](./ts-basic-components-text.md#setstyledstring12)方法与Text组件绑定，可通过RichEditorStyledStringController中的[setStyledString](ts-basic-components-richeditor.md#setstyledstring12)方法与RichEditor组件绑定。 > **说明：** > > 从API version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 > > 属性字符串目前不支持在worker线程中使用。 > > 属性字符串通过controller绑定时，需要等待布局完成后，绑定生效。当[measure](../js-apis-arkui-frameNode.md#measure12)和setStyledString同时使用，开发者需要通过[@ohos.arkui.inspector (布局回调)](../js-apis-arkui-inspector.md)判断布局完成，再绑定属性字符串。 ## 规则说明 * 当组件样式和属性字符串中的样式冲突时，冲突部分以属性字符串设置的样式为准，未冲突部分则生效组件的样式。 * 当属性字符串和[Text](./ts-basic-components-text.md)子组件冲突时，属性字符串优先级高，即当Text组件中绑定了属性字符串，忽略Text组件下包含[Span](./ts-basic-components-span.md)等子组件的情况。 * 不支持@State修饰。 * 建议将StyledString定义为成员变量，从而避免应用退后台后被销毁。 * 不支持在[loadContent()](../arkts-apis-window-Window.md#loadcontent9)之前创建。 ## StyledString ### constructor constructor(value: string | ImageAttachment | CustomSpan , styles?: Array\) 属性字符串的构造函数。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | value | string \| [ImageAttachment](#imageattachment) \| [CustomSpan](#customspan) | 是 | 属性字符串文本内容。
**说明：**
当value值为ImageAttachment或CustomSpan时，styles参数不生效。
需要设置styles时，通过[insertStyledString](#insertstyledstring)实现。 | | styles | Array<[StyleOptions](#styleoptions对象说明)> | 否 | 属性字符串初始化选项。
**说明：**
start为异常值时，按默认值0处理。
当start的值合法且length为异常值时，length的值为属性字符串长度与start的值的差值。
StyledStringKey与StyledStringValue不匹配时，不生效。
styledKey参数无默认值。 | ### 属性 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 只读 | 可选 | 说明 | | ------ | ------ | ------ | ------ | -------------- | | length | number | 是 | 否 | 属性字符串字符的长度。
**说明：**
当属性字符串中包含图片或者CustomSpan时，其返回的长度按1计算。 | ### getString getString(): string 获取字符串信息。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **返回值：** | 类型 |说明 | | ------- | --------------------------------- | | string | 属性字符串文本内容。
**说明：**
当属性字符串中包含图片时，其返回的结果用空格表示。 | ### equals equals(other: StyledString): boolean 判断两个属性字符串是否相等。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------------------- | ---- | ------------------------------------------------------------ | | other | [StyledString](#styledstring) | 是 | StyledString类型的比较对象。 | **返回值：** | 类型 | 说明 | | ------- | --------------------------------- | | boolean | 两个属性字符串是否相等。
true表示相等，false表示不相等。
**说明：**
当属性字符串的文本及样式均一致，视为相等。
不比较GestureStyle，当属性字符串配置了不同事件，文本和其他样式相同时，亦视为相等。
当比较CustomSpan时，比较的是地址，地址相等，视为相等。 | ### subStyledString subStyledString(start: number, length?: number): StyledString 获取属性字符串的子字符串。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------------------- | ---- | ------------------------------------------------------------ | | start | number | 是 | 子属性字符串开始位置的下标。 | | length | number | 否 | 子属性字符串的长度。 | **返回值：** | 类型 | 说明 | | ------- | --------------------------------- | | [StyledString](#styledstring) | 子属性字符串。
**说明：**
当start为合法入参时，length的默认值是被查询属性字符串对象的长度与start的值的差。
当start和length越界或者必填传入undefined时，会抛出异常。| **错误码**：以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | ### getStyles getStyles(start: number , length: number , styledKey?: StyledStringKey): Array\ 获取指定范围属性字符串的样式集合。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | --------------------------------- | ---- | ------------------------------------------------------------ | | start | number | 是 | 指定范围属性字符串的下标。 | | length | number | 是 | 指定范围属性字符串的长度。 | | styledKey | [StyledStringKey](#styledstringkey枚举说明) | 否 | 指定范围属性字符串样式的枚举值。 | **返回值：** | 类型 | 说明 | | ------- | --------------------------------- | | Array<[SpanStyle](#spanstyle对象说明)> | 各样式对象的数组。
**说明：**
当指定范围属性字符串未设置任何样式，则返回空数组。
当start和length越界或者必填传入undefined时，会抛出异常；
当styledKey传入异常值或undefined时，会抛出异常。
当styledKey为CustomSpan时，返回的是创建CustomSpan时传入的样式对象，即修改该样式对象也会影响实际的显示效果。 | **错误码**：以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 | 错误码ID | 错误信息 | | ------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | ### fromHtml static fromHtml(html: string): Promise\ 将HTML格式字符串转换成属性字符串，当前支持转换的HTML标签范围：\

~~This is b strong em i u ~~del~~ s~~ ~~www.example red span ^superscript and _subscript~~

"; @State spanString: StyledString | undefined = undefined; @State resultText: string = ""; // 保存结果文本的状态 controller: TextController = new TextController; build() { Column() { // 显示转换后的spanString Text(undefined, { controller: this.controller }).height(100) // TextArea显示每个步骤的结果 TextArea({ text: this.html }) .width("100%") .height(100) .margin(5) // 按钮1:将HTML转换为SpanString Button("将HTML转换为SpanString").onClick(async () => { this.spanString = await StyledString.fromHtml(this.html); this.controller.setStyledString(this.spanString); this.resultText = "Converted HTML to SpanString successfully."; }).margin(5) // 按钮2:将SpanString转换为HTML Button("将SpanString转换为HTML").onClick(() => { if (this.spanString) { // 将spanString转换为HTML并替换当前的HTML状态 const newHtml = StyledString.toHtml(this.spanString); if (newHtml !== this.html) { // 通过检查内容是否已经相同来防止重复 this.html = newHtml; } this.resultText = "Converted SpanString to HTML successfully."; } else { this.resultText = "SpanString is undefined."; } }).margin(5) // 按钮3:将HTML转换回SpanString Button("将HTML转换回SpanString").onClick(async () => { this.spanString = await StyledString.fromHtml(this.html); this.controller.setStyledString(this.spanString); this.resultText = "Converted HTML back to SpanString successfully."; }).margin(5) // 重置：重置HTML和SpanString Button("重置").onClick(() => { this.html = "
This is b strong em i u ~~del~~ s www.example red span ^superscript and _subscript
"; this.spanString = undefined; this.controller.setStyledString(new StyledString("")); // 使用空的StyledString实例 this.resultText = "Reset HTML and SpanString successfully."; }).margin(5) }.width("100%").padding(20) } } ``` ![](figures/styledString_13.gif) ### 示例13（多装饰线与加粗装饰线）从API version 20开始，该示例通过[DecorationStyle](#decorationstyle)中设置enableMultiType、thicknessScale接口，实现多装饰线显示与加粗装饰线的效果。 ``` ts // xxx.ets import { LengthMetrics } from '@kit.ArkUI' @Entry @Component struct styled_string_set_decorationstyle_demo { @State styledString : StyledString | undefined = undefined controller : TextController = new TextController thickness: number = 2.0 mutableStyledString1: MutableStyledString = new MutableStyledString("1234567890", [ { start: 0, length: 10, styledKey: StyledStringKey.FONT, styledValue: new TextStyle({ fontColor: Color.Orange, fontSize: LengthMetrics.vp(30) }) }, { start: 0, length: 4, styledKey: StyledStringKey.DECORATION, styledValue: new DecorationStyle({type: TextDecorationType.LineThrough, thicknessScale: this.thickness}, {enableMultiType: true}) }, { start: 2, length: 5, styledKey: StyledStringKey.DECORATION, styledValue: new DecorationStyle({type: TextDecorationType.Underline, thicknessScale: this.thickness}, {enableMultiType: true}) }, { start: 0, length: 4, styledKey: StyledStringKey.DECORATION, styledValue: new DecorationStyle({type: TextDecorationType.Overline, thicknessScale: this.thickness}, {enableMultiType: true}) }, { start: 6, length: 2, styledKey: StyledStringKey.DECORATION, styledValue: new DecorationStyle({type: TextDecorationType.LineThrough}) }, { start: 7, length: 2, styledKey: StyledStringKey.DECORATION, styledValue: new DecorationStyle({type: TextDecorationType.LineThrough, color: Color.Green}, {enableMultiType: true}) }, { start: 8, length: 2, styledKey: StyledStringKey.DECORATION, styledValue: new DecorationStyle({type: TextDecorationType.Overline, color: Color.Green}, {enableMultiType: true}) } ]); build() { Column({ space:3 }) { Text(undefined, { controller: this.controller }) .height(100) .copyOption(CopyOptions.LocalDevice) .onAppear(()=>{ this.styledString = this.mutableStyledString1 this.controller.setStyledString(this.mutableStyledString1) }) }.width("100%") } } ``` ![](figures/styledString_14.png)