鸿蒙ArkTS多形态图标组件设计：从类型系统到RcIcon实战

1. 从需求到设计：RcIcon这个组件到底在解决什么问题

鸿蒙客户端项目做到第六个月的时候，我彻底被图标这件事烦透了。页面上同时存在png图标、svg图标、字体图标、远端图片、甚至还有几处需要走自定义绘制的场景，而项目里的图标组件分了三套：一套是自绘的Canvas方案，一套是Image组件包了一层，还有一套是Text+字体映射搞出来的。每次视觉改版，我是真的要从三个文件里找对应的图标代码，改一个换一套组件API，心态直接在崩塌边缘。

于是就有了RcIcon这个念头：能不能用一个组件吃掉所有图标形态？让调用方传入一个对象描述，组件自己判断是图片、符号、字体还是自定义绘制，剩下的交给我内部处理。这个方向定下来之后，类型系统的问题随之而来——因为不同形态的入参差异很大，图片要传source和resizeMode，字体要传fontFamily和codePoint，自定义绘制要传render函数。如果只是用 @Prop 接收一个宽泛的Object，调用方的智能提示基本就废了，写错参数也不会在编译期报错。

HarmonyOS 6的ArkTS虽然保留了一部分TypeScript的类型体操能力，但运行时约束和装饰器机制跟Web端差异很大。直接照搬React/Vue的思路是行不通的。这个标题叫“半年磨一剑”，真不是夸张——前面四个月我都在做其他业务功能，RcIcon是断断续续打磨的，最后两个月集中攻坚类型系统和多形态渲染的兼容问题。

这篇文章主要面向HarmonyOS应用开发者和对ArkTS类型系统感兴趣的工程师。如果你正在为组件库设计统一API，或者被“一个组件适配多种资源形态”这类需求缠住，那这篇内容应该能帮上忙。我会把设计思路、类型方案、实现细节和踩坑记录全部摊开讲。

2. 多形态支持的底层思路与整体架构拆解

2.1 图标形态的统一抽象：从三个组件收敛到一个模型

多形态支持的第一步不是写代码，而是把“形态”这个概念定义清楚。我这里的分类标准不是技术实现，而是使用方的直觉：资源来自哪里，希望怎么控制渲染。

最终我把图标分成了五类：

• image：本地图片资源，包括png、webp、jpg，重点是支持resizeMode和圆角裁剪。
• symbol：系统符号，对应HarmonyOS的SymbolGlyph，支持层级颜色和fontWeight设置。
• text：字体图标，需要指定fontFamily、codePoint（或者直接传字符串字形）、fontSize和颜色。
• font：跟text类似但更偏“动态字体”，支持通过远端配置加载的字体文件或自定义字体集合。
• builder：自定义绘制，调用方传入一个 @Builder 函数或自定义组件构造器，完全接管内容区渲染。

这个分类本身不是拍脑袋定的，而是从现有业务代码里统计出来的。高频场景是image和text，symbol是HarmonyOS 6原生推荐的形态，font是给动态换主题用的，builder则是兜底方案——比如Logo需要加渐变、加描边、加特殊动效的时候，写死成图片反而不好扩展。

2.2 为什么选择“对象参数+联合类型”而不是多个子组件

最开始我考虑过拆成 RcIconImage、RcIconSymbol、RcIconText 这种方案，每个组件各自维护一套参数。这种方式实现简单，但调用方的代码会变得很割裂——同一个页面里一会儿 RcIconImage 一会儿 RcIconSymbol，视觉切图的时候要来回改组件名。

另一个方案是做“自动判断组件”，但ArkTS没有Web端那种运行时字符串到组件的动态解析，也不太方便做模板层面的动态组件映射。所以在RcIcon里我选择了“单一入口+对象描述+运行时路由”的组合方式：

typescript复制// 调用方写法
RcIcon({
  params: {
    type: 'image',
    source: $r('app.media.tab_home'),
    size: 24,
    color: '#FF0000'
  } as ImageIconParams
})

这种写法对调用方来说最友好的一点是：换形态的时候只需要改 type 和对应的业务字段，外层结构完全不变。视觉调整的时候，即使在代码评审里也一眼能看出来这图标要什么效果。

当然，这个方案对类型系统的压力是最大的。因为 params 不能是普通联合类型——如果是普通的联合类型，ArkTS的IDE提示会把所有形态的字段全部列出来，写代码的时候依然容易用错字段。所以这里必须上“可辨识联合” + “泛型约束” + “函数重载”三件套，让编译器根据 type 字段自动收窄可用的字段范围。

2.3 形态与渲染资源的映射关系表

在设计里，每一个形态最终都会映射到一个具体的渲染节点。RcIcon内部维护了一张“形态-渲染器”的映射表：

这张表我建议所有做组件库的人都建一张，哪怕你不是鸿蒙开发。把“抽象形态”和“具体渲染实现”之间的映射关系固化下来，后续加新形态的时候只需要扩展表格和对应渲染器，不会把逻辑散落在各个页面里。

3. 类型系统设计：真正硬核的部分

3.1 ArkTS环境下做类型设计的限制与机会

做RcIcon类型系统之前，我先把ArkTS对TypeScript语法限制摸了一遍底。HarmonyOS 6的ArkTS整体上兼容了大部分TS语法，但有几条红线不能碰：

• 不能使用 any 或 unknown 做自由变量类型，必须显式标注。
• JSON.parse 这类运行时操作返回的类型默认不是结构化数据，需要自己断言。
• 装饰器对被装饰的属性类型有要求，不能随便用联合类型挂在 @Prop 上。
• 泛型约束是支持的，但是 infer 和复杂的条件类型支持有限，需要小心使用。

这些约束看似麻烦，但其实逼着我做了更严谨的设计。比如不能随便用 any，那么所有形态的参数类型就必须一处一处定义好；不能把联合类型直接挂装饰器，那就得把参数对象包装一层，让装饰器挂在外层容器上，内部再做类型收窄。

类型系统设计的目标很明确：调用方写 type: 'image' 之后，IDE只提示image相关的字段；写 type: 'symbol' 之后，IDE只提示symbol相关的字段；完全不相关的字段，比如在image形态下写 codePoint，编译期直接报错。

3.2 可辨识联合的落地：一个IconType打天下

可辨识联合（Discriminated Union）在这类场景下几乎是唯一正确的解法。核心是让每个形态的参数类型都包含一个唯一的 type 字段，这个字段作为判别式。

typescript复制export type IconType = 'image' | 'symbol' | 'text' | 'font' | 'builder';

export interface BaseIconParams {
  type: IconType;
  width?: number | string;
  height?: number | string;
  color?: ResourceColor;
}

export interface ImageIconParams extends BaseIconParams {
  type: 'image';
  source: ResourceStr;
  resizeMode?: ImageFit;
  borderRadius?: Length;
}

export interface SymbolIconParams extends BaseIconParams {
  type: 'symbol';
  symbolName: string;
  fontWeight?: number | string;
  fontColor?: Array<ResourceColor>;
}

export interface TextIconParams extends BaseIconParams {
  type: 'text';
  fontFamily: string;
  codePoint: string;
  fontSize?: number | string;
}

export interface FontIconParams extends BaseIconParams {
  type: 'font';
  fontUrl?: string;
  fontFamily: string;
  codePoint: string;
  fontSize?: number | string;
}

export interface BuilderIconParams extends BaseIconParams {
  type: 'builder';
  builder: () => void;
}

这里有一个细节：type 字段在父接口里是宽泛的 IconType，在子接口里被具体化成字符串字面量类型。TypeScript的可辨识联合特性要求判别式在每个成员里是“字面量类型”才能触发收窄，所以子接口里的 type 一定要写死成具体的字符串。

3.3 从联合类型到泛型约束：让IDE提示精准到字段

有了这个联合类型之后，RcIcon组件接收参数的时候不能直接定义成联合类型，否则在组件内部做渲染判断时，所有形态的字段都会被“摊开”在同一个对象上，类型安全性反而下降了。

我这里采用的方法是“泛型组件”：让组件实例化时锁定一个具体的 T，这个 T 是联合类型中的某一个成员。

typescript复制@Component
export struct RcIcon<T extends IconParamsMap> {
  @Prop params: T;

  build() {
    if (this.params.type === 'image') {
      // 这里 TS 自动把 this.params 收窄为 ImageIconParams
      Image(this.params.source)
        .objectFit(this.params.resizeMode ?? ImageFit.Contain)
    } else if (this.params.type === 'symbol') {
      // 这里自动收窄为 SymbolIconParams
      SymbolGlyph(this.params.symbolName)
    }
    // ... 其他形态
  }
}

在ArkTS的装饰器体系里，@Prop 是支持泛型的，但需要保证泛型参数是结构化的。这里定义 IconParamsMap 的意图就是约束 T 必须来自可辨识联合，防止外部传入奇怪的结构。

然后渲染入口通过一个普通函数来包装组件调用，利用函数重载让编译器在写 type 字段时自动匹配到对应的参数类型：

typescript复制export function RcIcon(params: ImageIconParams): void;
export function RcIcon(params: SymbolIconParams): void;
export function RcIcon(params: TextIconParams): void;
export function RcIcon(params: FontIconParams): void;
export function RcIcon(params: BuilderIconParams): void;
export function RcIcon(params: IconParamsMap) {
  // 实际返回组件的封装
}

3.4 条件类型与类型映射表的补充方案

可辨识联合解决了“传入参数的类型检查”，但还有一个需求没覆盖：当外部封装组件需要根据 type 推断出对应参数类型的时候，比如写一个配置驱动的图标任务队列：

typescript复制type ParamsByType<T extends IconType> =
  T extends 'image' ? ImageIconParams :
  T extends 'symbol' ? SymbolIconParams :
  T extends 'text' ? TextIconParams :
  T extends 'font' ? FontIconParams :
  T extends 'builder' ? BuilderIconParams :
  never;

这段代码的意思是：给一个 IconType，返回对应的参数类型。有了它，业务方可以写泛型工具函数，从一个图标配置列表里安全地取出每个条目的参数。这样做的收益是可组合性上了一个台阶，但代价是ArkTS对条件类型的推断能力没有Web端强，我建议这类写法只用在纯类型层面，不要依赖它去推导实际运行时的值。

4. 多形态渲染与状态管理的实操细节

4.1 组件框架结构：找好“稳定壳”和“易变核”

我一直认为好的组件应该做到“外稳内变”。RcIcon的外层是尺寸、颜色、边距这些通用排版属性，这些对所有形态一致；内层则是每个形态各自的渲染逻辑。

组件壳的部分长这样：

typescript复制@Component
export struct RcIconInner<T extends IconParamsMap> {
  @Prop params: T;
  @State private renderKey: string = '';
  private cacheSize: number = 24;

  aboutToAppear(): void {
    this.refreshRenderKey();
  }

  @Watch('params')
  onParamsChange(): void {
    this.refreshRenderKey();
  }

  private refreshRenderKey(): void {
    // 根据形态和关键参数生成缓存key
    this.renderKey = `${this.params.type}_${JSON.stringify(this.params)}`;
  }

  build() {
    Row() {
      this.renderByType()
    }
    .width(this.params.width ?? this.cacheSize)
    .height(this.params.height ?? this.cacheSize)
    .justifyContent(FlexAlign.Center)
    .alignItems(VerticalAlign.Center)
  }

  @Builder
  private renderByType() {
    if (this.params.type === 'image') {
      Image(this.params.source)
        .objectFit(this.params.resizeMode ?? ImageFit.Contain)
        .borderRadius(this.params.borderRadius ?? 0)
        .width('100%').height('100%')
    } else if (this.params.type === 'symbol') {
      SymbolGlyph(this.params.symbolName)
        .fontSize(this.params.fontSize ?? this.cacheSize)
        .fontColor(this.params.fontColor ?? ['#000000'])
        .fontWeight(this.params.fontWeight ?? FontWeight.Normal)
    }
    // ... 其他形态
  }
}

这里有几个经验点：

• @Builder 方法内部的 if/else 分支是允许的，Builder函数编译后会生成对应的渲染指令，HarmonyOS会按需执行渲染分支。
• 不要把通用属性写到每个形态的渲染分支里，放在外层 Row 上统一处理，减少重复代码。
• 宽度和高度默认值建议收敛到 cacheSize 这样一个变量中，所有形态共用，避免不同形态默认值不一致的毛病。

4.2 状态刷新链路：从外层数据变化到渲染重建

这个组件最容易出问题的点是状态刷新。之前我在测试的时候遇到过很多次：外层传入的新source没有生效，或者切换形态后旧渲染还留在界面上。

排查下来的核心原因是ArkUI的状态追踪机制对“对象内部字段变化”的监听并不是全自动的。@Prop 只会在父组件重新渲染并传入新对象时才触发更新，如果父组件直接改了对象里的某个字段，@Prop 很可能感知不到。

解决方案是我在上面代码里加了一个 @Watch 监听 params，当 params 被重新赋值时触发 refreshRenderKey() 刷新缓存。配合父组件在修改参数时新建对象，而不是原地改字段：

typescript复制// 正确写法：创建新对象
this.iconParams = {
  ...this.iconParams,
  source: newSource
}

// 错误写法：原地修改字段
this.iconParams.source = newSource; // 子组件可能感知不到

4.3 从“形态参数”到“渲染配置”的平衡计算

实际开发中还有个比较隐性但也比较重要的问题：同一形态的不同参数组合会带来不同的渲染结果。比如text形态，fontFamily 和 codePoint 都相同，但 fontSize 不同，渲染尺寸就不同。symbol形态，fontWeight 不同，渲染粗细就不同。

为了保证渲染缓存和状态判断的准确性，我实现了一个 getRenderSignature 方法，它对每个形态提取关键的“渲染签名”字段组合成字符串，作为判断是否需要重建渲染节点的依据：

typescript复制private getRenderSignature(params: IconParamsMap): string {
  switch (params.type) {
    case 'image':
      return `img:${params.source}:${params.resizeMode ?? ''}:${params.borderRadius ?? ''}`;
    case 'symbol':
      return `sym:${params.symbolName}:${params.fontWeight ?? ''}:${params.fontColor ?? ''}`;
    case 'text':
      return `txt:${params.fontFamily}:${params.codePoint}:${params.fontSize ?? ''}`;
    case 'font':
      return `font:${params.fontFamily}:${params.codePoint}:${params.fontUrl ?? ''}`;
    case 'builder':
      return `bld:${Date.now()}`; // builder每次都是新的，不缓存
    default:
      return '';
  }
}

这个签名的粒度需要把控好。太粗会导致参数变化但渲染没更新，太细会频繁重建影响性能。我的经验是对尺寸、颜色、字体这种高频变化的属性一定要纳入签名，对透明度、旋转角度这种由外层容器控制的属性不要纳入。

5. 完整实操：从零搭建RcIcon组件并接入业务

5.1 目录结构与组件基础骨架

写组件库之前，先把目录规划好。我这边是Stage模型下标准ets目录，组件单独放一个目录：

code复制entry/src/main/ets/components/
  rcicon/
    RcIcon.ets        // 组件主文件和入口函数
    RcIconTypes.ets   // 类型定义，可辨识联合和映射表
    RcIconRender.ets  // 各形态渲染逻辑，拆出去保持主文件干净
    RcIconCache.ets   // 缓存和签名计算

把类型定义单独放一个文件的目的是：业务方引用类型时不需要把整个组件文件import进来，减少编译依赖，IDE提示也更清晰。渲染拆出去是为了避免单文件过大，半年维护下来主线文件控制在200行左右最好维护。

5.2 类型定义文件：RcIconTypes.ets 完整实现

这个文件是整个组件类型系统的地基。可辨识联合的定义我前面已经列出来了，这里补充一个很重要的细节：所有字段必须显式写出完整类型，不能依赖自动推导，因为ArkTS的编译期检查更严格，自动推导有时候会推导成松散类型，导致装饰器报错。

typescript复制export type IconType = 'image' | 'symbol' | 'text' | 'font' | 'builder';

export interface BaseIconParams {
  type: IconType;
  width?: Length;
  height?: Length;
  color?: ResourceColor;
}

// 业务端封装时最常用的辅助类型
export type IconParamsMap =
  | ImageIconParams
  | SymbolIconParams
  | TextIconParams
  | FontIconParams
  | BuilderIconParams;

我在业务端见过不少人直接写：

typescript复制let p: ImageIconParams = { type: 'image', source: $r('app.media.xxx'), color: '#333' };

这个写法在RcIconTypes里已经可用，因为 type 字段被字面量收窄了，编译器能确认它就是ImageIconParams。

5.3 渲染文件：RcIconRender.ets 的分支实现

渲染文件我用 @Builder 做分支路由：

typescript复制@Builder
export function renderImage(params: ImageIconParams) {
  Image(params.source)
    .objectFit(params.resizeMode ?? ImageFit.Contain)
    .borderRadius(params.borderRadius ?? 0)
    .width('100%')
    .height('100%')
}

@Builder
export function renderSymbol(params: SymbolIconParams) {
  SymbolGlyph(params.symbolName)
    .fontSize(params.fontSize ?? 24)
    .fontColor(params.fontColor ?? ['#000000'])
    .fontWeight(params.fontWeight ?? FontWeight.Normal)
}

@Builder
export function renderText(params: TextIconParams) {
  Text(params.codePoint)
    .fontFamily(params.fontFamily)
    .fontSize(params.fontSize ?? 24)
    .fontColor(params.color ?? '#000000')
}

这里的 Image、SymbolGlyph、Text 都是ArkUI内置组件，@Builder 导出后可以在主组件里通过 this.renderImage(this.params) 调用。有个注意点：@Builder 函数作为独立文件导出时，引用 @Builder 的组件必须也导入对应的渲染函数，不能只依赖全局注册。

5.4 主组件封装：入口函数和组件实现

主组件文件里做了两件事：定义组件，以及提供便捷函数避免调用方写繁琐的Builder包装。

typescript复制@Component
export struct RcIconInner {
  @Prop params: IconParamsMap;

  build() {
    Row() {
      this.switchRender()
    }
    .width(this.params.width ?? 24)
    .height(this.params.height ?? 24)
    .justifyContent(FlexAlign.Center)
    .alignItems(VerticalAlign.Center)
  }

  @Builder
  private switchRender() {
    if (this.params.type === 'image') {
      renderImage(this.params as ImageIconParams)
    } else if (this.params.type === 'symbol') {
      renderSymbol(this.params as SymbolIconParams)
    } else if (this.params.type === 'text') {
      renderText(this.params as TextIconParams)
    }
    // ... 其他形态
  }
}

@Builder
export function RcIcon(params: IconParamsMap) {
  RcIconInner({ params: params })
}

入口函数 RcIcon 用了 @Builder 包装，业务方可以直接在页面里调用：

typescript复制RcIcon({ type: 'image', source: $r('app.media.tab_home'), size: 24, color: '#FF0000' })

类型重载方面，实际上在ArkTS里定义 @Builder 函数不支持直接写多个重载签名，所以我在调用层面用了函数重载会报错，这个在ArkTS中需要稍微调整。最终我选择在入口处保持宽松的参数类型，在 switchRender 里用 as 断言收窄，尽量在调用处给到IDE的字段提示。这个折中方案虽然不是100%的类型安全，但在可维护性和ArkTS的语法限制之间找到了平衡。

5.5 业务接入实例：一个真实的图标配置表驱动页面

接入RcIcon之后，我做的第一件事就是把原来页面里的三套图标调用统一替换。这是一个配置驱动的页面：

typescript复制interface PageIconItem {
  key: string;
  params: IconParamsMap;
  onClick?: () => void;
}

const ICON_LIST: Array<PageIconItem> = [
  {
    key: 'home',
    params: { type: 'image', source: $r('app.media.tab_home'), width: 24, height: 24 }
  },
  {
    key: 'setting',
    params: { type: 'symbol', symbolName: 'sys.settings', fontSize: 22, fontColor: ['#666666'] }
  },
  {
    key: 'arrow',
    params: { type: 'text', fontFamily: 'iconfont', codePoint: '\uE001', fontSize: 16, color: '#999999' }
  }
];

@Entry
@Component
struct IconDemoPage {
  build() {
    List({ space: 12 }) {
      ForEach(ICON_LIST, (item: PageIconItem) => {
        ListItem() {
          Row() {
            RcIcon(item.params)
            Text(item.key).fontSize(14).margin({ left: 8 })
          }
          .width('100%')
          .height(48)
          .onClick(() => {
            item.onClick?.()
          })
        }
      }, (item: PageIconItem) => item.key)
    }
    .padding(12)
  }
}

这个写法替换之后的效果很直接：页面代码量少了大概三分之一，原来需要记忆三套组件的API，现在只需要记忆 type 字段和对应参数。配置项的 key 还能用来做测试断言，遍历校验每个图标在页面里是否正确渲染。

6. 半年实战踩坑记录与排查思路

6.1 经典问题：切换type时页面不刷新，甚至闪白

这是RcIcon开发中被问得最多的一个Bug。现象是：从 image 切到 text，图标区域先是空白，再快速闪一下才出现新图标。

排查后的根本原因有两个。第一，@Builder 分支切换时，ArkUI的渲染节点释放和重建不是同步的，旧的Image节点销毁、新的Text节点挂载之间会有一段空窗期。第二，RcIconInner内部没有维护一个“上次渲染形态”的标志，导致Builder里对 if 分支的判断发生了意外的节点复用。

解决方案是给渲染区域加一个稳定的key，强制按签名重建：

typescript复制build() {
  Row() {
    this.switchRender()
  }
  .key(this.getRenderSignature(this.params))
  ...
}

key 变化时，ArkUI会丢弃旧节点并创建新节点，切形态时的空窗问题基本消除。这个 .key 的用法在官方文档里没有被重点强调，但实际上对“同容器内切换不同子组件”的场景非常有效。

6.2 状态追踪陷阱：给icon传对象却被缓存了旧引用

还有一个高频问题跟 @Prop 的特性相关。业务方可能会把一个全局配置对象里的某个字段传给RcIcon：

typescript复制RcIcon({ type: 'image', source: this.globalConfig.homeIcon, size: 24 })

这里 this.globalConfig.homeIcon 变了，但RcIcon的 @Prop params 收到的是整个对象。如果调用方没有重新创建 params 对象，而只是改了 globalConfig.homeIcon 字段，那 @Watch('params') 根本不会触发。

我的建议是业务侧统一走函数生成参数：

typescript复制build() {
  RcIcon(this.buildHomeIconParams())
}

private buildHomeIconParams(): ImageIconParams {
  return {
    type: 'image',
    source: this.globalConfig.homeIcon,
    width: 24,
    height: 24
  };
}

每次build时会生成新对象，@Watch 能稳定感知变化。如果担心频繁创建对象影响性能，可以用 @State 缓存参数对象，在配置变更的地方主动重建。

6.3 字体图标偶发方块：iconfont加载时序问题

text形态的图标字体，最典型的问题是偶发显示成方块。这个问题的根因不是RcIcon本身，而是字体文件加载完成之前就渲染了Text。

我在处理时给text形态加了“字体就绪”的内部状态：

typescript复制@State private fontReady: boolean = false;

aboutToAppear(): void {
  if (this.params.type === 'text' || this.params.type === 'font') {
    this.loadFontFamilyReady();
  }
}

private loadFontFamilyReady(): void {
  // 通过font.registerFont或业务自建设备字体加载机制
  // 加载完成后 set fontReady = true
}

然后在渲染text时，如果 fontReady 为false，先渲染一个等尺寸的占位块，加载完成后再替换成真实字形。这个处理也顺带解决了一个隐藏问题：在低端设备上，字体加载失败时不再出现大面积方块，而是保持占位，视觉上要好看很多。

6.4 缓存与性能：避免每个图标都重复计算Layout

RcIcon在半年迭代中还经历了一轮性能优化。最开始每个图标内都计算签名、解析尺寸、创建渲染节点，页面有上百个图标时，会出现掉帧。

优化动作有三个：

• 把签名的字符串拼接换成 Map<number, string> 缓存，相同的参数对象直接复用签名。
• 对于不需要动态变化的图标，外层套 @Builder 时不传入响应式状态，减少不必要的脏检查。
• 给图标容器增加 .constraintSize({ minWidth: size, minHeight: size })，减少布局系统在不同尺寸下反复计算的次数。

优化后，一个包含120个图标的复杂页面，从掉帧到稳定满帧，耗时从之前的32ms左右下降到18ms左右。具体数据跟设备型号也有关系，但整体效果是可感知的。

7. 常见问题速查表：直接抄作业

这张表里的每一条都来自实际踩坑，建议直接贴到项目Wiki里，团队其他人在用RcIcon遇到问题时能快速定位。

8. 一些想对你说的经验与建议

8.1 做成组件库之前，先用三个月在业务里验证

RcIcon并不是一开始就以“组件库”身份立项的。最开始就是在首页Demo里验证“object参数模型”的可行性，确认了image、symbol、text三个基础形态都能稳定渲染，才逐渐抽出独立组件文件。如果你也想做类似的多形态图标组件，建议先别急着“搞个大新闻”，先用实际页面磨需求，让真实业务逼着你补齐形态，这比凭空想象出来的API要可靠得多。

8.2 类型系统要做，但别过度设计

我在类型系统上花了非常多时间，最终方案里有一部分条件类型写法因为ArkTS的编译限制没有落地。回过头看，有一个更务实的做法是：先把可辨识联合和联合类型字段提示做好，这已经能覆盖90%的代码正确性收益。条件类型、泛型映射表这类高级技巧等你有了充足案例再考虑，避免做成“类型艺术展”，反而影响团队上手速度。

8.3 形态扩展时，先把“研磨接口”的时间留足

“半年磨一剑”这个标题里有半年，一大半时间都花在“让组件符合直觉”这件事上。比如text形态到底用 codePoint 还是 symbol 字段，image形态的borderRadius是放在Params还是单独抽个Style接口，这些细节看起来无关紧要，但每一个决策都会影响后续所有调用方的代码可读性。

我的体会是：做这种基础组件，多花一周做接口设计，比事后改三个月调用方代码划算得多。不要急着“先能用”，先把“用好”的标准想清楚。RcIcon最后能稳定落地，靠的就是这种在设计和实现之间反复打磨的过程。