ArkTS 属性字符串 (StyledString MutableStyledString) 详解

ArkTS 属性字符串 (StyledString / MutableStyledString) 详解

鸿蒙第四期开发者活动

一、StyledString 到底是什么？为什么要用它？

在平常的 UI 里我们用组件 Text 显示一段字符串，但它只能控制整段文字的统一样式。
StyledString 是一种“可带样式的数据对象”，用来表示一段文本中不同区间可以拥有不同样式、事件、段落行为的文本。Gitee

它的用途比单纯的 Text 更强：

文本中部分内容字体、颜色、粗体/斜体不一样
插入图片/图标到文本中（图文混排）
文本局部可响应点击或长按事件
不同段落有不同对齐/行高/缩进等规则

说白了：当一个普通的 Text 做不出你想要的“富文本效果”时，就用 StyledString。Gitee

二、StyledString 的核心对象和构成

StyledString 有两个相关类型：

类型	说明
`StyledString`	不可变的属性字符串，一旦创建样式就固定
`MutableStyledString`	可变属性字符串，在创建后可以追加、修改样式

两者都可以附加到 Text 组件的 TextController 上去渲染。Gitee

三、基本使用步骤（从无到有）

下面是使用 StyledString 的“完整路线图”：

Step 1 — 创建 StyledString 或 MutableStyledString

// 如果不需要后续修改样式，可以直接用 StyledString
let simpleStyled = new StyledString("Hello 富文本 World");

// 如果需要在创建后再追加样式、文字、图片
let mutable = new MutableStyledString("Hello Native");

MutableStyledString 继承自 StyledString，比它更灵活。Gitee

Step 2 — 创建 TextController 并设置属性字符串

需要一个 TextController 绑定到 Text 组件上，然后把 StyledString 通过 setStyledString() 传给它：

textController: TextController = new TextController();

// 页面显示时或 onPageShow 里绑定属性字符串
this.textController.setStyledString(mutable);

推荐在页面显示生命周期（如 onPageShow）里设置，否则文本组件可能还没完全渲染导致样式不生效。CSDN

Step 3 — 在 `Text` 中关联控制器

Text(undefined, { controller: this.textController })
  .fontSize(16)   // 可以再配合基础 Text 属性

这种写法让 Text 不直接写字符串，而是从 TextController 获取并渲染 StyledString。华为开发者

四、怎么设置不同样式？（属性对象详解）

属性字符串的威力来自于“给文本区间指定不同的样式对象”。这种机制是用一个由 { start, length, styledKey, styledValue } 对象数组来描述的。Gitee

1) 文本样式 `TextStyle`

用于设置字体样式（颜色、粗体/斜体、大小等）：

import { TextStyle } from '@kit.ArkUI';

let attrs: TextStyle = new TextStyle({ fontSize: 18, fontColor: Color.Red, fontWeight: FontWeight.Bold });

创建好后，你可以在 MutableStyledString 初始化时绑定：

new MutableStyledString("说明文字", [
  { start: 0, length: 2, styledKey: StyledStringKey.FONT, styledValue: attrs }
]);

同一段文字可以被映射成多个不同风格的区间。Gitee

2) 文本阴影 `TextShadowStyle`

为部分文本加阴影效果，让文本更有层次感：

import { TextShadowStyle, ShadowType } from '@kit.ArkUI';

new TextShadowStyle({ radius: 4, type: ShadowType.COLOR, color: Color.Gray });

这段阴影效果可以附加到特定区间。Gitee

3) 装饰线（如删除线、下划线） `DecorationStyle`

装饰线样式也可以独立设置：

new DecorationStyle({ type: TextDecorationType.LineThrough, color: Color.Gray });

比如把价格中原价涂掉用删除线展示，就用这个。Gitee

4) 段落样式 ParagraphStyle

如果你的文本里有多个段落（换行 \n），你可以用段落样式控制文本对齐、缩进、间距等：

import { ParagraphStyle } from '@kit.ArkUI';

let paraStyle = new ParagraphStyle({ textAlign: TextAlign.Center, textIndent: LengthMetrics.vp(15) });

再把这个样式对象附加到某段区间上。Gitee

5) 其他样式（字符间距、基线偏移等）

还包括：

BaselineOffsetStyle —— 控制文本基线偏移
LineHeightStyle —— 控制单行文本高度
LetterSpacingStyle —— 控制字符间距

这些都是更细粒度的文本控制。Gitee

五、图文混排（不是 RichEditor，但很像）

你也可以在属性字符串中插入图片：

import { ImageAttachment, ImageFit, ImageSpanAlignment } from '@kit.ArkUI';

new ImageAttachment({
  value: pixelMap,
  size: { width: 100, height: 80 },
  verticalAlign: ImageSpanAlignment.BASELINE,
  objectFit: ImageFit.Fill
});

然后 append 到现有的属性字符串里，实现图、文字混合显示。Gitee

真实项目多见于商品卡片中“图 + 文并排又不想单独用 Row/Column”场景。Gitee

六、事件/交互文本

属性字符串还能让文本具备可点击区域并响应事件：

import { GestureStyle } from '@kit.ArkUI';

let clickStyle = new GestureStyle({
  onClick: () => promptAction.showToast({ message: "点击了文本片段" })
});

再把这种 GestureStyle 绑定在特定区间内，就实现了“文本某个字可响应点击”。华为开发者

七、真项目里怎么用？几个真实例子

场景 1：让一段话里一部分文字变色强调

let discountText = new MutableStyledString("限时优惠5折起", [
  { start: 3, length: 2, styledKey: StyledStringKey.FONT,
    styledValue: new TextStyle({ fontColor: Color.Red, fontWeight: FontWeight.Bold }) }
]);

这种写法比多个 Text 组件拼更清爽、维护也更简单。Gitee

场景 2：商品原价和折扣价 Text 里只给原价加删除线

let styledPrice = new MutableStyledString("原价 ¥199 现价 ¥99", [
  { start: 3, length: 6, styledKey: StyledStringKey.DECORATION,
    styledValue: new DecorationStyle({ type: TextDecorationType.LineThrough, color: Color.Gray }) }
]);

在单个 Text 控件里搞定比拆成两个 Text 视觉更一致。Gitee

场景 3：标题 + 副标题不同样式混合

let titleSentence = new MutableStyledString("主题标题\n副标题说明", [
  { start: 0, length: 5, styledKey: StyledStringKey.FONT,
    styledValue: new TextStyle({ fontSize: LengthMetrics.vp(24), fontWeight: FontWeight.Bold }) },
  { start: 6, length: 4, styledKey: StyledStringKey.FONT,
    styledValue: new TextStyle({ fontSize: LengthMetrics.vp(14), fontColor: Color.Gray }) }
]);

这种控制段落级别文本样式的写法，在大标题 + 小说明里特别常用。Gitee

八、容易踩的坑

. 属性字符串不会自动继承 Text 属性

属性字符串本身带样式，不会自动继承 Text 外层设置的基础属性，比如 Text.fontSize()，要在 StyledString 中明确写出来。Gitee

2. 索引从 0 开始，容易算错区间

数组里每条样式定义都有 start 和 length，必须确保这些值不会越界，否则可能导致样式叠加错位。Gitee

3. 刷新属性字符串后要重新 setStyledString

如果你修改了 MutableStyledString 的样式（append/replaceStyle），需要重新执行：

textController.setStyledString(mutableStyledString);

才会触发 UI 更新，否则不会生效。Gitee

posted @ 2025-12-22 08:54 想喝冰咖啡阅读(0) 评论(0) 收藏举报

刷新页面返回顶部