HarmonyOS RcTag 组件实战：技能标签墙与搜索热词

1.4 代码详解

SkillTag 接口设计

SkillTag 接口定义了四个字段：id 用字符串存储，作为 ForEach 的唯一 key；name 是显示的技能名称；type 的类型与 RcTag 的 rcTagType 完全匹配，可以直接透传；size 同样与 rcTagSize 匹配。这种让数据结构与 UI 组件 Props 对齐的设计，能最大限度地消除"数据到 UI 的映射转换"代码，数据字段可以几乎零转换地传给组件。

两种模式的状态驱动

isEditMode 是驱动双模式切换的唯一状态变量。当它为 false 时，rcTagClosable: this.isEditMode 等于 rcTagClosable: false，所有标签不显示关闭图标；为 true 时，所有标签出现关闭图标，同时 if (this.isEditMode) 分支渲染"+ 添加"标签。

标题栏右侧的切换文字通过三元表达式 this.isEditMode ? '完成' : '编辑' 动态展示，点击后执行 this.isEditMode = !this.isEditMode 取反切换模式。整套双模式逻辑只用了一个布尔变量，代码非常精简。

removeSkill 与 id 而非 name 的删除

removeSkill 接收的是 skill.id 而非 skill.name。使用 ID 删除的原因是：同名技能（如两个人都标记了"Java"）在同一个列表中虽然不常见，但理论上存在，若用名称删除可能误删。用 ID 则精确定位，不会有歧义。方法内使用 findIndex 找到对应 ID 的索引，然后 splice(idx, 1) 删除该项。由于 skills 是 @Local 状态变量，原地修改后 ArkTS 响应式系统会检测到变化，自动触发 ForEach 的差量更新。

ForEach 的 key 选择 id 字段

标签墙的 ForEach 使用 (skill: SkillTag) => skill.id 作为 key 函数，返回的是字符串型 ID。用 ID 而非 skill.name 作为 key 的优势在于：当用户删除某个技能时，ArkTS 框架通过 key 能精确判断哪条数据被移除，只卸载那一个标签节点，其他标签节点保持不变。若用名称作 key，在用户快速删除多个标签时可能因 key 对比不稳定导致不必要的重渲染。

"+ 添加"标签的设计

"+ 添加"标签使用 rcTagPlain: true 使其呈现为镂空描边样式，与实色填充的技能标签形成明显区分，用户能直觉感知"这个是按钮，不是标签"。rcTagShape: 'circle' 与其他技能标签保持一致，视觉风格统一。onRcTagClick 回调中留有注释提示"实际项目中打开添加弹窗"，说明这里只是展示交互入口，真实项目中会弹出输入弹窗或跳转到选择页面。

二、场景六：搜索热词标签云

2.1 场景描述

搜索页面展示热词与历史记录标签云，点击标签直接填入搜索框，支持清空历史。这是搜索功能的标配体验，几乎所有内容型 App 都有这个页面。搜索历史帮助用户快速回到上一次搜索，热门搜索则起到内容引导和发现的作用，两块区域的视觉处理也有所不同。

2.2 设计思路

历史标签与热词标签在视觉上做了明显区分。历史标签使用 rcTagType: 'info' + rcTagPlain: true 的灰色镂空样式，低调不抢眼，体现"历史"的次要属性。热词标签则将前三名设计为 rcTagType: 'error'（红色实色），其余使用 rcTagType: 'primary' + rcTagPlain: true（蓝色镂空），前三名的视觉强调对应其在热度榜上的头部地位，这是内容平台常用的排行视觉设计。

2.3 完整代码

import { RcTag } from 'rchoui'

@Entry
@ComponentV2
struct SearchHotTagDemo {
  @Local searchText: string = ''
  @Local historyTags: string[] = ['HarmonyOS', 'ArkTS 教程', '鸿蒙组件库', 'rchoui']
  private hotTags: string[] = ['HarmonyOS NEXT', 'ArkUI 布局', '鸿蒙开发入门', 'ComponentV2', 'AppStorageV2', '状态管理', '自定义组件', '生命周期']

  build() {
    Column({ space: 0 }) {
      // 搜索框
      Row({ space: 8 }) {
        TextInput({ placeholder: '搜索...', text: this.searchText }).fontSize(14).height(38).layoutWeight(1).borderRadius(19).backgroundColor('#f5f5f5').padding({ left: 16, right: 16 }).onChange((val) => {
          this.searchText = val
        })
        Text('搜索').fontSize(14).fontColor('#3c9cff').padding({ left: 4 })
      }.padding({ left: 16, right: 16, top: 12, bottom: 12 }).backgroundColor(Color.White)

      Scroll() {
        Column({ space: 20 }) {
          // 搜索历史
          if (this.historyTags.length > 0) {
            Column({ space: 10 }) {
              Row() {
                Text('搜索历史').fontSize(14).fontWeight(FontWeight.Medium).fontColor('#1a1a1a')
                Blank()
                Text('清空').fontSize(12).fontColor('#909399').onClick(() => {
                  this.historyTags = []
                })
              }.width('100%')
              Flex({ wrap: FlexWrap.Wrap }) {
                ForEach(this.historyTags, (tag: string) => {
                  RcTag({
                    rcTagText: tag,
                    rcTagType: 'info',
                    rcTagPlain: true,
                    rcTagShape: 'circle',
                    rcTagMargin: { right: 8, bottom: 8 },
                    onRcTagClick: () => {
                      this.searchText = tag
                    }
                  })
                }, (tag: string) => tag)
              }.alignItems(HorizontalAlign.Start).width('100%')
            }
          }

          // 热门搜索
          Column({ space: 10 }) {
            Text('热门搜索').fontSize(14).fontWeight(FontWeight.Medium).fontColor('#1a1a1a').width('100%')
            Flex({ wrap: FlexWrap.Wrap }) {
              ForEach(this.hotTags, (tag: string, idx: number) => {
                RcTag({
                  rcTagText: tag,
                  // 前三名用特殊颜色突出
                  rcTagType: idx < 3 ? 'error' : 'primary',
                  rcTagPlain: idx >= 3,
                  rcTagShape: 'circle',
                  rcTagMargin: { right: 8, bottom: 8 },
                  onRcTagClick: () => {
                    this.searchText = tag
                    // 加入历史
                    if (!this.historyTags.includes(tag)) {
                      this.historyTags.unshift(tag)
                      if (this.historyTags.length > 10) {
                        this.historyTags.pop()
                      }
                    }
                  }
                })
              }, (tag: string) => tag)
            }.alignItems(HorizontalAlign.Start).width('100%')
          }
        }.padding(16).width('100%')
      }.layoutWeight(1).backgroundColor('#f5f5f5')
    }.width('100%').height('100%')
  }
}

2.4 代码详解

状态变量分工

searchText 存储搜索框当前的文字，用 @Local 装饰以响应式更新输入框显示。historyTags 存储搜索历史数组，也是 @Local，对它的增删清空都能触发历史区域的重渲染。hotTags 是固定的热词数据，内容不会变化，因此用普通 private 存储，不需要响应式。

搜索框的设计

TextInput 的 borderRadius(19) 配合 height(38) 使输入框呈现胶囊形状，这是当前移动端搜索框的主流设计语言。backgroundColor('#f5f5f5') 给输入框一个浅灰色背景，与白色页面区分，使输入框有视觉边界感。旁边的"搜索"文字用 Text 而非 Button 实现，这是移动端搜索框的常见做法，视觉上更轻量，虽然本示例中"搜索"文字没有绑定实际的搜索逻辑，但留下了扩展入口。

历史区域的条件渲染

整个历史区域被包裹在 if (this.historyTags.length > 0) 条件中。当历史记录被清空后，historyTags 长度变为 0，历史区域整体从 DOM 树中移除，不留白，布局自动收缩，热词区域上移填充空间。这比用 visibility 隐藏或用 height(0) 折叠要干净。

清空历史的赋值方式

this.historyTags = [] 将状态变量重新赋值为一个空数组。与 splice(0, historyTags.length) 等原地清空方式相比，直接赋新数组更简洁，且在 ArkTS 的响应式系统中同样能被检测到变化并触发重渲染。

历史标签的点击回调

历史标签的 onRcTagClick: () => { this.searchText = tag } 直接将标签文字赋给 searchText，使搜索框填入该关键词。这里的 tag 来自 ForEach 的回调闭包，在闭包创建时已经捕获了当前迭代的标签文字，所以无论点击哪个标签，都能正确填入对应内容。

热词标签的索引驱动样式

热词的 ForEach 回调有两个参数 (tag: string, idx: number)，idx 是当前元素的索引（从 0 开始）。rcTagType: idx < 3 ? 'error' : 'primary' 和 rcTagPlain: idx >= 3 这两行通过索引完成了视觉分层：索引 0、1、2（前三名）使用红色实色；索引 3 及之后使用蓝色镂空。注意 rcTagPlain 和 rcTagType 之间的联动是有意设计的：前三名同时满足 rcTagType: 'error' 且 rcTagPlain: false，后几名同时满足 rcTagType: 'primary' 且 rcTagPlain: true，两者配合才能产生正确的视觉效果。

热词点击时的历史管理逻辑

点击热词时执行了三步操作：首先将搜索框填入该关键词；然后检查该词是否已在历史中，若不在则调用 unshift 插入到历史数组头部（最近搜索排最前）；最后检查历史数量是否超过 10 条，超出时调用 pop 移除末尾最旧的记录。这三步合起来实现了一个带上限的"最近搜索"队列，是搜索历史功能的标准实现模式。

Scroll 的 layoutWeight

搜索框位于顶部白色区域，内容区（历史 + 热词）位于 Scroll 中。Scroll 设置了 layoutWeight(1)，使其在父容器 Column 中占据搜索框以外的所有剩余高度，内容溢出时可以上下滑动。backgroundColor('#f5f5f5') 给内容区一个浅灰背景，与搜索框区域的白色形成分区，视觉层次清晰。

三、最佳实践总结

3.1 属性选择策略

在实际项目中，RcTag 的属性组合有一些规律性的用法。强调类状态标识（如"待支付"、"紧急"等）应使用实色 + medium 尺寸，确保用户第一时间注意到。次要状态标识（如"运输中"、"处理中"）可以降级为镂空填充 + mini，在保留语义的同时减少视觉干扰。筛选类标签建议统一使用胶囊形状（circle），符合移动端筛选条的视觉惯例，且选中时用实色、未选中时用镂空的切换方式最为直观。内容分类标签数量通常较多，推荐使用镂空填充 + square + mini，信息密度高但不杂乱。可删除的用户输入标签则适合使用实色 + circle + closable，实色提升存在感，胶囊形状更友好，关闭图标明确传达可操作性。

3.2 性能注意事项

在 build() 函数中多次调用同一个计算方法（如订单状态案例中多次调用 getStatusConfig）会在每次渲染时产生重复计算。对于配置类查询，建议在 ListItem 的渲染逻辑开始处声明局部变量缓存结果，后续复用局部变量。

ForEach 的 key 函数选择对差量更新性能影响显著。应当优先使用数据中的唯一 ID 字段作为 key，避免使用数组索引（因为删除操作会导致索引移位，进而引发不必要的节点重建）。

rcTagShow 与条件渲染（if）适用场景不同。rcTagShow 适合频繁切换显隐的标签，因为它不销毁节点，只控制可见性；条件渲染适合永久消失的标签（如从数组中删除），直接移除 DOM 节点更彻底。

3.3 多标签间距推荐

在使用 Flex + FlexWrap.Wrap 进行多标签自动换行布局时，推荐统一使用 rcTagMargin: { right: 8, bottom: 8 } 的组合。右边距控制同行标签间的水平间距，下边距控制换行后的行间距，这样无论标签在哪一行哪一位置，它与右侧和下方邻近元素的距离都是一致的，整体间距均匀、视觉整洁。在标签数量固定且不换行的情况下（如 Row 内排列少量标签），也可以直接用 Row({ space: 8 }) 统一控制间距，无需借助 rcTagMargin。

四、常见问题与解答

4.1 点击关闭按钮同时触发了 onRcTagClick

这种情况通常是误解导致的。RcTag 内部的关闭按钮点击处理已经调用了 event.stopPropagation()，阻止了事件冒泡，因此正常情况下点击关闭图标不会触发外层标签的 onRcTagClick。如果确实遇到了两个回调同时触发的情况，需要排查外层容器是否有额外的点击事件监听器，或者检查 rcTagClosable 是否正确设置为 true。

4.2 rcTagShow 绑定的状态变量不响应

原因是状态变量没有使用响应式装饰器声明。在 ComponentV2 中，只有用 @Local、@Param 等装饰器修饰的变量发生变化时，才会触发组件重新渲染。普通的 private 变量即使值变了，UI 也不会更新。

// 错误：普通变量不触发响应式更新
private show: boolean = true
// 正确：使用 @Local 装饰
@Local show: boolean = true

4.3 rcTagPlainFill 没有效果

rcTagPlainFill 必须与 rcTagPlain: true 同时使用才能生效。rcTagPlainFill 的作用是在镂空模式基础上增加浅色背景填充，若没有开启 rcTagPlain，标签处于实色模式，rcTagPlainFill 无法产生任何额外效果。

// 错误：缺少 rcTagPlain
RcTag({ rcTagText: '无效', rcTagPlainFill: true })
// 正确：两者同时设置
RcTag({ rcTagText: '有效', rcTagPlain: true, rcTagPlainFill: true })

4.4 ForEach 渲染标签时点击事件不更新

当在 ForEach 中使用索引 idx 判断选中状态时，若 idx 没有通过响应式路径传递，点击后 UI 不会更新。正确的做法是通过 rcTagName 将标识符携带到事件回调中，然后修改 @Local 状态变量，由状态变化驱动 UI 更新。

// 正确做法：通过 rcTagName 携带标识，在事件中更新状态
ForEach(this.options, (opt: string, idx: number) => {
  RcTag({
    rcTagText: opt,
    rcTagName: idx,
    rcTagPlain: this.selected !== idx,
    onRcTagClick: (name) => {
      this.selected = name as number
      // 修改 @Local 变量触发更新
    }
  })
}, (opt: string) => opt)

五、属性速查表

5.1 完整属性列表

5.2 事件说明

onRcTagClick 在用户点击标签时触发（禁用状态下不触发），回调参数为 rcTagName 的值。若未设置 rcTagName，回调参数为 undefined。

onRcTagClose 在用户点击关闭图标时触发（需同时设置 rcTagClosable: true，禁用状态下不触发），回调参数同样为 rcTagName 的值。关闭图标的点击事件不会冒泡到 onRcTagClick，两者相互独立。

总结

至此，RcTag 实战系列三篇文章通过六个真实业务场景，系统演示了 RcTag 在鸿蒙 App 开发中的完整应用范围：从纯展示的内容标签，到单选筛选的交互标签；从可增删的标签管理器，到配置表驱动的订单状态；从多尺寸混排的技能墙，到索引驱动差异化样式的搜索热词。RcTag 以极简的 API 设计覆盖了从简单到复杂的全场景需求，这正是半年磨一剑所沉淀的工程价值——用简洁的设计解决复杂的问题。