HarmonyOS ArkUI 搜索页实战：构建完整的搜索交互体验

在移动应用开发中，搜索页（Search Page）是仅次于详情页的高频交互场景。一个优秀的搜索页不仅要有漂亮的
UI，更需要处理复杂的状态流转：从默认的“热门/历史”展示，到“输入中”的联想，再到“搜索后”的结果展示。

今天，我们将通过解析一个完整的 ArkUI
搜索页代码，带你深入理解如何构建一个工业级的搜索交互逻辑。这个案例涵盖了组件化封装、状态管理、列表渲染以及字符串处理等核心技能。

- 核心功能与界面概览

我们最终实现的应用包含以下三个核心状态和模块：

1. 顶部搜索栏 (SearchHeader)：包含返回按钮、输入框和搜索按钮，支持实时监听输入和提交。
2. 默认视图 (非搜索状态)：
   • 搜索历史 (SearchHistorySection)：展示标签云，支持单个删除和全部清空。
   • 热门搜索 (HotSearchSection)：展示带排名和热度的列表，前 3 名有特殊颜色标识。
3. 搜索结果视图 (搜索状态)：
   • 结果列表 (SearchResultSection)：展示卡片式列表，包含类型标签（不同颜色）和高亮关键词。

整个应用通过 @State isSearching 变量控制视图切换，实现了流畅的用户体验。

代码架构深度解析

我们将代码拆解为三个关键部分进行讲解：数据模型与状态、组件化通信 和 核心交互逻辑。

1. 数据模型与状态管理

代码开头定义了两个核心的 interface 来规范数据结构：

interface HotSearchItem {
  id: number;
  keyword: string;
  hot: number; // 热度值
  icon: string;
}

interface SearchResultItem {
  id: number;
  title: string;
  description: string;
  type: string; // 文档、视频等类型
  time: string;
}

在主组件 SearchPage 中，我们使用 @State 管理了以下核心状态：

• searchText: 绑定输入框的文本。
• isSearching: 核心状态变量。控制页面是显示“历史/热门”还是“搜索结果”。
• showHistory: 控制历史记录区域的显示隐藏（例如当搜索结果为空时可能需要隐藏历史）。
• searchHistory & hotSearches: 存储列表数据。

2. 组件化架构与父子通信

这是本项目最值得学习的设计模式。代码将页面拆分为多个独立的 @Component，实现了高内聚低耦合。

父子组件通信示意图：

父组件 (SearchPage)	传递给子组件的属性/事件	子组件 (SearchHeader / History等)
提供数据	@Prop searchText	接收并显示数据
提供回调	onSearchChange (函数)	触发并修改父组件状态

示例：搜索框的双向绑定
父组件将 searchText 作为 @Prop 传给 SearchHeader，同时传递一个 onSearchChange 函数。

// 父组件调用
SearchHeader({
  searchText: this.searchText,
  onSearchChange: (text: string) => { this.searchText = text; }
})

// 子组件接收并使用
@Component struct SearchHeader {
  @Prop searchText: string; // 接收值
  onSearchChange: (text: string) => void; // 接收函数

  build() {
    TextInput({ text: this.searchText })
      .onChange((value) => {
        this.onSearchChange(value); // 调用父组件函数更新状态
      })
  }
}

3. 核心交互逻辑详解

状态流转控制
主页面的 build 函数中，使用了三元逻辑来控制视图：

if (this.isSearching) {
  // 显示结果
  SearchResultSection(...)
} else {
  // 显示历史和热门
  Scroll { Column { ... } }
}

当用户点击搜索按钮时，onSearchSubmit 会将 isSearching 设为 true，页面瞬间切换。

搜索历史的处理 (addToHistory)
代码中 addToHistory 方法处理了两个细节：

1. 去重：如果搜索词已存在，先从原位置移除。
2. 置顶与截断：使用 unshift 将最新搜索词插入数组头部，并限制数组长度不超过 10。
   这模拟了真实 App 中“最新搜索词在最前”的逻辑。

热门搜索的格式化 (formatHotNumber)
在 HotSearchItemRow 中，有一个实用的工具函数 formatHotNumber。
它将过大的数字（如 9999）转换为更友好的显示（如 1.0w），这是提升 UI 体验的小技巧。

4. UI 细节与样式处理

动态标签颜色 (getTypeColor)
在搜索结果卡片中，不同类型的条目（文档、视频、项目）有不同的背景色。
代码使用了 Record<string, string>（类似字典）来映射类型和颜色，并通过 @Builder getTypeTag 方法动态生成带样式的标签组件。

关键词高亮 (highlightKeyword)
虽然目前的代码逻辑只是简单返回了原文本（因为 ArkUI 的 Text 组件对富文本支持有特定限制），但 highlightKeyword 函数展示了如何通过正则表达式 new RegExp(keyword, 'gi') 来匹配搜索词。在实际开发中，这里通常会结合 TextSpan 来实现真正的高亮变色效果。

📝 总结

通过深入解析这个搜索页案例，我们学习了以下 ArkUI 开发的核心技能：

1. 状态驱动 UI：利用 @State 和条件渲染（if/else）控制页面不同状态的展示。
2. 组件化设计：将 Header、List、Item 拆分为独立组件，通过 @Prop 和回调函数实现父子通信，使代码更易于维护。
3. 数据处理：掌握了数组的去重、截取以及数字格式化的实用技巧。

这个搜索页是一个非常标准的 HarmonyOS 应用开发模板，你可以直接将其作为基础，集成网络请求（替换 performSearch 中的 Mock 数据）来构建真实的应用功能。