HarmonyOS 搜索体验优化实战：防抖请求、历史记录与空结果兜底

搜索页看起来只是一个输入框，实际最容易暴露体验细节：用户快速输入时请求乱序，删除关键词后旧结果还留着，历史记录保存了敏感内容，空结果页只有一句“暂无数据”，弱网下重复点击搜索导致页面闪烁。搜索体验要做稳，核心不是多调一个接口，而是把输入、请求、结果、历史、空态和错误恢复串成一条链路。

本文围绕一个目标展开：在 HarmonyOS 应用里搭建一个可迁移的搜索模块，让防抖、请求序号、历史记录、空结果和失败提示都有明确边界。

一、搜索页先拆成五个状态

不要只用一个 loading 控制搜索页。搜索至少有输入中、请求中、有结果、空结果、失败五种状态。

状态	触发条件	页面表现
editing	用户正在输入	展示联想或历史
searching	防抖结束并发起请求	展示轻量加载
result	返回非空列表	展示结果和筛选
empty	返回空列表	给出改词建议或热门入口
failed	请求失败	保留关键词并提供重试

如果状态不分清，页面最容易出现“空态盖住历史”“失败后关键词丢失”“旧请求覆盖新结果”。

二、资料与版本边界：本文写应用层搜索模块

本文示例面向 HarmonyOS NEXT / ArkTS / ArkUI 工程，重点在搜索体验的应用层实现：输入防抖、请求序号、结果模型、历史记录、隐私过滤、空结果兜底和验收排查。真实项目需要把这里的业务函数接入自己的网络库、数据源、权限策略和组件库。

搜索链路层	本文落地内容	接入时需要调整
输入层	防抖、关键词规范化	输入框组件和键盘事件
请求层	请求序号、乱序保护	网络库、取消请求能力
结果层	空态、错误、列表更新	后端搜索接口协议
历史层	去重、上限、隐私过滤	本地存储方式
验收层	快速输入、弱网、空结果	真机网络环境

搜索模块接入时先确认三个接口

搜索页要写稳，前端和后端接口边界必须先谈清楚。很多体验问题不是页面代码能单独解决的，比如后端不返回总数、空结果没有推荐词、接口不支持取消或 requestId，前端只能做有限兜底。

接口能力	页面依赖它做什么	如果暂时没有怎么办
keyword 规范	防止空关键词和过长关键词打到接口	前端先清洗并限制长度
requestId 或响应时间	判断响应是否过期	页面维护本地 sequence
total 或 hasMore	决定空态和分页入口	用列表长度做弱判断
推荐词	空结果给下一步	使用本地热门词兜底
敏感词规则	历史记录过滤	先维护前端黑名单，后续下发

搜索页的代码最好拆成 keyword、request、result、history 四块。这样改输入体验时不会动历史记录，改接口协议时也不会影响空态展示。

三、关键词规范化：先清理输入再搜索

搜索前要处理空格、长度、敏感输入和重复关键词。否则接口压力大，历史记录也会变脏。

export interface SearchKeywordResult {
  valid: boolean;
  keyword: string;
  reason: string;
}

export function normalizeSearchKeyword(input: string): SearchKeywordResult {
  const keyword = input.trim().replace(/\s+/g, ' ');
  if (keyword.length === 0) {
    return { valid: false, keyword: '', reason: '关键词为空' };
  }
  if (keyword.length > 40) {
    return { valid: false, keyword, reason: '关键词过长' };
  }
  return { valid: true, keyword, reason: '可以搜索' };
}

这段代码的边界是输入清洗。它不发请求，也不保存历史。这样可以保证请求层拿到的是可用关键词。

四、防抖计划：输入停顿后再发请求

搜索防抖要保留最后一次输入。下面用计划对象描述一次待触发搜索，便于页面状态和日志追踪。

export interface SearchDebouncePlan {
  keyword: string;
  delayMs: number;
  plannedAt: number;
}

export function buildSearchDebouncePlan(keyword: string): SearchDebouncePlan {
  return {
    keyword,
    delayMs: keyword.length <= 2 ? 500 : 300,
    plannedAt: Date.now()
  };
}

export function debounceReady(plan: SearchDebouncePlan, now: number): boolean {
  return now - plan.plannedAt >= plan.delayMs;
}

短关键词容易产生宽泛结果，可以延迟更久；较长关键词通常意图明确，可以更快请求。防抖策略不是为了省接口而牺牲体验，而是让输入和结果节奏更自然。

五、请求序号：旧结果不能覆盖新结果

搜索请求经常乱序返回。用户输入“华山”，旧请求“华”如果后返回，不能覆盖新结果。

export interface SearchRequestTicket {
  keyword: string;
  sequence: number;
  createdAt: number;
}

export class SearchRequestSequencer {
  private latestSequence = 0;

  create(keyword: string): SearchRequestTicket {
    this.latestSequence += 1;
    return {
      keyword,
      sequence: this.latestSequence,
      createdAt: Date.now()
    };
  }

  current(sequence: number): boolean {
    return sequence === this.latestSequence;
  }
}

请求序号的职责是判断响应是否还有效。网络层返回后先检查 current，只有最新请求才能更新页面。

六、结果模型：空结果也要能解释

空结果不是失败，但它需要引导。比如换关键词、查看热门、清除筛选。

export interface SearchItem {
  id: string;
  title: string;
  summary: string;
}

export interface SearchResultView {
  state: 'result' | 'empty';
  items: SearchItem[];
  suggestion: string;
}

export function buildSearchResultView(keyword: string, items: SearchItem[]): SearchResultView {
  if (items.length === 0) {
    return {
      state: 'empty',
      items: [],
      suggestion: `没有找到“${keyword}”，可以减少关键词或查看热门内容`
    };
  }
  return { state: 'result', items, suggestion: '' };
}

这段模型把空结果作为正常状态处理。页面不需要把空数组当错误，也不会给用户一个没有解释的空白区域。

七、历史记录：去重、上限和隐私过滤都要有

搜索历史是体验增强，也是隐私风险。手机号、身份证号、token 这类内容不应该进入历史。

export function keywordSafeForHistory(keyword: string): boolean {
  if (/^[0-9]{11}$/.test(keyword)) {
    return false;
  }
  if (/token/i.test(keyword)) {
    return false;
  }
  return keyword.length <= 30;
}

export function updateSearchHistory(history: string[], keyword: string): string[] {
  if (!keywordSafeForHistory(keyword)) {
    return history;
  }
  const next = history.filter(item => item !== keyword);
  next.unshift(keyword);
  return next.slice(0, 10);
}

历史记录的边界是“可回看关键词”。它不应该保存敏感输入，也不应该无限增长。

八、搜索体验问题排查表

搜索页表现	先看哪个环节	定位方法	修复动作
快速输入结果错乱	旧请求覆盖新请求	查看 SearchRequestTicket.sequence	响应前校验是否最新
输入空格也发请求	关键词未规范化	检查 normalizeSearchKeyword	trim 后再判断
空结果没有引导	空数组被当作普通列表	查看 SearchResultView.state	给出换词和热门入口
历史记录暴露手机号	未做隐私过滤	搜索历史中查纯数字	加入 keywordSafeForHistory
弱网下加载闪烁	每次输入立即请求	查看防抖计划	按关键词长度调整延迟
删除关键词后旧结果还在	清空输入未清状态	检查 editing 状态	清空结果并展示历史

排查时先复现快速输入，再模拟弱网，最后测试敏感关键词。搜索页的问题往往在边界输入里出现。

九、搜索上线前验收表

搜索验收路径	页面应达到的结果
输入防抖	连续输入不会每个字符都请求
请求乱序	旧响应不会覆盖新结果
空结果	有解释、有改词建议、有热门入口
历史记录	去重、限制数量、过滤敏感关键词
失败恢复	保留当前关键词并允许重试
清空输入	结果清除，历史或推荐正常展示
真机测试	弱网和快速输入都有测试记录

搜索页至少要测试三类关键词：短词、长词、无结果词。只测热门词，很容易忽略空态和失败恢复。

弱网与快输入场景要单独留证据

搜索体验最容易在办公室网络下“看起来没问题”，到了真机弱网才暴露旧结果覆盖新结果。建议在页面状态里记录最近一次搜索的关键词、序号和耗时，问题出现时可以快速判断是防抖没生效，还是响应乱序。

export interface SearchDebugSnapshot {
  keyword: string;
  sequence: number;
  startedAt: number;
  finishedAt: number;
  resultCount: number;
  fromCache: boolean;
}

export function searchSnapshotCost(snapshot: SearchDebugSnapshot): number {
  return snapshot.finishedAt - snapshot.startedAt;
}

这段快照不参与业务展示，只用于复盘。读者接入时可以把它写入调试日志或开发面板：如果同一个关键词反复出现多个 sequence，说明防抖间隔太短；如果旧 sequence 的完成时间晚于新 sequence，就必须依赖请求序号保护页面更新。

搜索页的接入顺序不要反过来

第一步先做关键词规范化。空字符串、全空格、过长关键词都在本地拦住，避免无意义请求进入后端。

第二步做防抖和 sequence。这个阶段不追求结果页多漂亮，只验证快速输入 h、ha、har 时最终只展示最后一次关键词结果。

第三步接空态。空结果不是失败，页面要给用户下一步：换词、清除筛选、查看热门搜索，或者回到历史记录。

第四步接历史记录。历史记录只保存有效关键词，而且要过滤手机号、身份证、token 这类敏感内容。用户清空输入后，历史记录要能正常展示。

第五步做弱网复盘。打开网络限速，连续输入两组关键词，观察旧响应是否能被拦截。这个步骤能直接暴露请求乱序问题。

十、搜索体验相关官方资料

1. 华为开发者文档：ArkUI 文本输入
   https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-textinput
2. 华为开发者文档：ArkUI 列表组件
   https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list
3. 华为开发者文档：Stage 模型应用开发
   https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/stage-model-development-overview
4. 华为开发者文档：网络管理
   https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/net-connection-overview

十一、让搜索结果跟得上用户输入

搜索体验的稳定性来自“输入节奏”和“响应顺序”的管理。关键词先规范化，防抖计划控制请求时机，序号保护最新结果，空态给出下一步，历史记录做隐私过滤。

搜索链路问题	推荐落地方式
什么时候请求	输入合法并且防抖完成
哪个响应能更新页面	只有最新 sequence 可以更新
空结果怎么办	展示解释、建议和热门入口
历史记录怎么存	去重、限量、过滤敏感内容
弱网怎么恢复	保留关键词，允许用户重试