跳转至

增量搜索结果系统规范

意图

在 typeahead 中输入的人会立即看到与其输入匹配的结果,这些结果来自页面已经持有的数据;来自服务器的结果到达时,也会加入同一查询的同一列表。每次按键最多改变列表一次;服务器结果只会在已显示行下方添加行,因此指针或高亮下方不会有任何移动,屏幕阅读器用户每个查询只听一次结果数量,而不是每次结果到达都听一次。

一个搜索源用一个或多个列表应答一个查询。每个列表都是源在当时给出的完整应答;本地与远程结果如何合并、去重和排序由源全权负责。typeahead 展示当前查询的最新列表,并负责过期查询剔除、高亮、加载反馈和播报。

非目标

  • 在针对后续列表的仅追加规则(FR2)范围内,源如何查找本地匹配、缓存较早查询、合并、去重或排序结果。这一切由源全权负责(DEC-1)。
  • bootstrap()。它只用一个列表来应答。
  • 源何时发送其远程请求。先显示本地结果并希望延迟远程请求的源会自行延迟它。
  • 不带上下文调用 search(query) 的组件:CommandPalette 和 ChatComposerInput 会触发菜单。它们展示已定稿的列表(FR10)。PowerSearch 值编辑器渲染 Typeahead 和 Tokenizer,并通过它们获得此行为。
  • 查询待定时的 Escape。component:BaseTypeahead FR3 负责它;部分列表遵循与已定稿列表相同的规则。
  • 满足此契约的等价内部实现仍然有效。

需求

  • FR1 — 每个列表都是源的完整应答。 search(query, context) 接收一个可选的 SearchContext,其 update(items) 会替换为该查询显示的结果。源通过 update 或作为其返回值给出的每个列表,在当时都是该查询的完整、有序且不含重复 id 的列表。typeahead 原样显示每个非空列表,最多到其结果上限;空的 update 会使已显示的行保持不变(FR5)。它从不合并、重排或去重列表。Tokenizer 会从每个列表(无论是部分列表还是最终列表)中移除已提交的值,如 component:Tokenizer FR13 所要求。其创建行跟在各行之后,并且对于已搜索的查询,只在查询定稿后出现,因此它绝不会提供一个待定服务器结果即将显示的值。
  • FR2 — 每次按键只回流一次;后续列表只能追加。 为某个查询显示的第一个列表可以替换此前显示的行。同一查询的每个后续非空列表(包括最终列表)都会保留已显示的行:按 id 识别,放在最前,顺序与 typeahead 当前显示的一致;每个新行都显示在它们之后。typeahead 先显示未分组行,然后按首次出现的顺序显示每个分组,因此新行只能加入最后显示的分组,或者在其后开启一个新分组。后续列表绝不会移除、重排或在已显示行上方显示新行,即使某个结果本应排名更高。id 返回了更新数据的行会留在原处。当后续列表违反此规则时,typeahead 会原样显示它,并在开发环境中警告:源移动了、移除了或在已显示行上方插入了行。
  • FR3 — 返回值使查询定稿。 源返回的数组,或其 promise 解析出的值,就是该查询的最终列表。它按 FR2 替换任何更早的列表,结束查询的忙碌状态,并且是该查询最后显示的列表。查询定稿后调用 update 不会有任何效果。
  • FR4 — 只展示当前查询。 针对已不再是当前查询的列表会被丢弃,无论它来自 update 还是来自返回值。当用户输入更新的查询、选择某个结果、清空输入框,或源被替换、typeahead 卸载时,查询即不再是当前查询。
  • FR5 — 待定查询显示其部分列表。 查询待定时,非空的 update 会显示其行并打开弹出层。空的 update 会使已显示的行保持不变。控件保持忙碌状态并显示加载指示器,直到查询定稿。空结果行只在查询以空最终列表定稿时出现。查询待定期间弹出层被关闭后,部分列表会使弹出层保持关闭、控件保持不忙碌;下次打开时显示该查询的最新列表(component:BaseTypeahead FR3)。
  • FR6 — 高亮和滚动位置保持不动。 新查询显示的第一个列表会高亮其第一行。当同一查询的后续列表到达时,高亮项保持高亮,列表保持其滚动位置。后续列表绝不会把弹出层移到输入框的另一侧,也不会在屏幕上移动已显示的行:输入框上方的弹出层保持其高度,输入框下方的弹出层只在其下方空间内增长;超出该空间的行通过滚动列表来触达。当违反 FR2 的列表移动了高亮项时,高亮跟随该项;当它丢弃该项时,第一行被高亮。Enter 选择高亮项。
  • FR7 — 项保持不变时,选项保持其身份。 当一个项仍位于某查询的列表中时,它的选项元素和它的 id 保持不变。活动后代继续引用同一个选项,因此在它之后添加行时,辅助技术不会重新宣读高亮行。
  • FR8 — 每个查询只播报一次结果。 typeahead 在每个查询定稿时播报一次结果数量。如果弹出层在查询定稿前被关闭,则在下次打开并显示该查询列表时播报一次数量(component:BaseTypeahead FR3)。部分列表不播报任何内容。忙碌开始按 spec:AST-086 FR6 和 FR8 的要求,每个查询播报一次。
  • FR9 — 失败的远程应答保留已显示的内容。 当源的 promise 在当前查询的非空 update 之后拒绝时,最后一个非空列表得以保留,查询定稿,并播报其数量。当它拒绝且当前查询没有非空 update 时,查询以空列表定稿并显示空结果行。在弹出层关闭时,紧随 typeahead 自身的 cancel() 发生的拒绝不是失败应答:不播报任何内容,查询以当前查询的最后一个非空列表定稿;如果没有这样的列表,则不保留任何行,下一次按键会再次搜索。
  • FR10 — 单个应答仍然是完整应答。 从不调用 update 的源会在查询定稿时为每个查询显示一个列表。不传递上下文的调用者调用 search(query),并且只显示已定稿的列表,FR1 使其成为完整列表。

平台支持

  • 支持的功能/引擎下限:该包所支持的浏览器。契约不会使用超出 search() 已使用的平台功能。
  • 不支持的行为:无。
  • 浏览器证据:对行、高亮、活动后代、忙碌状态和播报通道进行 DOM 与无障碍树检查,覆盖部分列表及其落定后的列表。

当前状态影响

  • SearchSource.search 增加了一个可选第二参数,即带有 update(items) 的上下文。createStaticSource 和所有现有 source 均保持原样继续工作。
  • component:BaseTypeahead:FR3 和 PR1 在此通过 FR4 覆盖部分列表;AR4 在此通过 FR8 对每次查询播报一次;选项 id 在单次查询内遵循条目身份(FR7);开发警告会报告破坏 FR2 的后续列表。
  • component:Tokenizer:FR13 适用于每个部分列表和最终列表;创建行会等待搜索的查询落定(FR1)。Typeahead 和 Tokenizer 通过 BaseTypeahead 继承此行为,并且不新增 props。
  • family:input-fields:忙碌反馈保持不变;在部分列表显示期间,未决查询保持忙碌。
  • 用户文档:SearchSource 参考和 Typeahead 文档描述了 update,以及一个先显示本地结果的 source 如何与 debounceMs={0} 搭配,并延迟其自身的远程请求。

验证

Contract 验证 代表性状态 变更或失败预期
FR1, FR3 BaseTypeahead source 契约测试 同步更新后跟 promise、多次更新、上限小于列表 合并列表、对列表重新排序、超出上限或在落定后发生更改的行均失败
FR2 使用延迟 source 的追加式测试,以及开发警告 本地列表随后服务器列表,在已显示 id 下出现较新数据,分组结果中追加到最后一组或新组的行,以及后续列表对更早一组进行重新排序、移除、在其上方插入或向其添加 已显示的行移动、较新的行改变位置,或破坏性列表没有警告时失败
FR4 使用延迟 source 的过期查询测试 较新的查询、选择、清除、source 替换、卸载 被取代查询的列表出现时失败
FR5 未决状态测试 首个部分列表、空的部分列表、落定后的空列表 忙碌过早结束、未决期间出现空行,或空更新清除行时失败
FR6, FR7 键盘测试以及真实浏览器布局与无障碍树 高亮在第一行,高亮由箭头移动,已滚动列表接收追加的行,字段上方的弹窗接收追加的行,字段下方的弹窗其追加行超出下方空间 高亮、滚动位置、字段一侧或已显示行的屏幕位置移动,或同一项的活动后代 id 改变时失败
FR8 播报通道测试 先部分后落定,仅落定 对一次查询出现第二次计数播报,或在落定时没有播报,则失败
FR9 拒绝测试 在非空更新后拒绝;在前一查询的行仍显示时仅空更新后拒绝;没有更新时拒绝;弹窗关闭并取消后拒绝;当前查询有非空更新和无非空更新两种情况 非空更新后已显示的行被清除、前一查询的行作为当前查询的行落定、缺少播报,或弹窗关闭后出现播报,均失败
FR10 现有 Typeahead、Tokenizer、CommandPalette 测试套件 单答案 source、无上下文调用方 从不调用 update 的 source 出现任何行为变化均失败

决策日志

DEC-1 — 搜索源自行合并其结果

参考: spec:AST-092/DEC-1 决策人: cixzhang, 2026-10-22

“我认为合并服务器结果应该是搜索源的工作。”搜索源知道哪些结果是本地的、哪些是远程的、它们如何去重,以及用户应该按什么顺序看到它们,因此它给出的每个列表都是它的完整答案。输入提示仍然只是当前查询最新列表的渲染器。

被否决的方案:由输入提示合并独立的本地答案和远程答案,这会使一种合并与排序规则成为每个输入提示的一部分。

DEC-2 — 部分列表通过 update 到达;返回值保持为最终结果

参考: spec:AST-092/DEC-2 决策人: cixzhang, 2026-10-22

search() 的返回值保持其含义——最终列表,而可选上下文用于添加部分列表。每个等待数组的调用方都仍然会得到一个数组;搜索源可以在返回之前同步显示本地匹配项,而 promise 的 settled 状态标志着返回的 promise 的结束。

被否决的方案:search() 返回异步可迭代对象,这会破坏每个等待数组的调用方,而且无法同步交付它的第一个列表。

DEC-3 — 服务器结果只能追加

参考: spec:AST-092/DEC-3 决策人: cixzhang, 2026-10-22

“服务器结果绝不应导致输入提示中已经出现的项目发生重排。”“当服务器结果返回时,我们只应追加。每次按键只允许一次重排。”用户把指针或高亮对准他们能看到的一行;如果在对准之后该行发生移动,就会让他们选错人。因此,每次按键最多只改变一次列表,并且该查询的每一个后续列表都保持已显示行的位置不变,只在它们下方追加(FR2)。

被否决的方案:把排名更高的服务器结果放到已显示行的上方,这会使用户正准备选择的那一行发生移动。

未解决的问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx