增量搜索结果系统规范¶
意图¶
在 typeahead 中输入的人会立即看到与其输入匹配的结果,这些结果来自页面已经持有的数据;来自服务器的结果到达时,也会加入同一查询的同一列表。每次按键最多改变列表一次;服务器结果只会在已显示行下方添加行,因此指针或高亮下方不会有任何移动,屏幕阅读器用户每个查询只听一次结果数量,而不是每次结果到达都听一次。
一个搜索源用一个或多个列表应答一个查询。每个列表都是源在当时给出的完整应答;本地与远程结果如何合并、去重和排序由源全权负责。typeahead 展示当前查询的最新列表,并负责过期查询剔除、高亮、加载反馈和播报。
非目标¶
- 在针对后续列表的仅追加规则(FR2)范围内,源如何查找本地匹配、缓存较早查询、合并、去重或排序结果。这一切由源全权负责(DEC-1)。
bootstrap()。它只用一个列表来应答。- 源何时发送其远程请求。先显示本地结果并希望延迟远程请求的源会自行延迟它。
- 不带上下文调用
search(query)的组件:CommandPalette和ChatComposerInput会触发菜单。它们展示已定稿的列表(FR10)。PowerSearch值编辑器渲染 Typeahead 和 Tokenizer,并通过它们获得此行为。 - 查询待定时的 Escape。
component:BaseTypeaheadFR3 负责它;部分列表遵循与已定稿列表相同的规则。 - 满足此契约的等价内部实现仍然有效。
需求¶
- FR1 — 每个列表都是源的完整应答。
search(query, context)接收一个可选的SearchContext,其update(items)会替换为该查询显示的结果。源通过update或作为其返回值给出的每个列表,在当时都是该查询的完整、有序且不含重复id的列表。typeahead 原样显示每个非空列表,最多到其结果上限;空的update会使已显示的行保持不变(FR5)。它从不合并、重排或去重列表。Tokenizer 会从每个列表(无论是部分列表还是最终列表)中移除已提交的值,如component:TokenizerFR13 所要求。其创建行跟在各行之后,并且对于已搜索的查询,只在查询定稿后出现,因此它绝不会提供一个待定服务器结果即将显示的值。 - FR2 — 每次按键只回流一次;后续列表只能追加。 为某个查询显示的第一个列表可以替换此前显示的行。同一查询的每个后续非空列表(包括最终列表)都会保留已显示的行:按
id识别,放在最前,顺序与 typeahead 当前显示的一致;每个新行都显示在它们之后。typeahead 先显示未分组行,然后按首次出现的顺序显示每个分组,因此新行只能加入最后显示的分组,或者在其后开启一个新分组。后续列表绝不会移除、重排或在已显示行上方显示新行,即使某个结果本应排名更高。id返回了更新数据的行会留在原处。当后续列表违反此规则时,typeahead 会原样显示它,并在开发环境中警告:源移动了、移除了或在已显示行上方插入了行。 - FR3 — 返回值使查询定稿。 源返回的数组,或其 promise 解析出的值,就是该查询的最终列表。它按 FR2 替换任何更早的列表,结束查询的忙碌状态,并且是该查询最后显示的列表。查询定稿后调用
update不会有任何效果。 - FR4 — 只展示当前查询。 针对已不再是当前查询的列表会被丢弃,无论它来自
update还是来自返回值。当用户输入更新的查询、选择某个结果、清空输入框,或源被替换、typeahead 卸载时,查询即不再是当前查询。 - FR5 — 待定查询显示其部分列表。 查询待定时,非空的
update会显示其行并打开弹出层。空的update会使已显示的行保持不变。控件保持忙碌状态并显示加载指示器,直到查询定稿。空结果行只在查询以空最终列表定稿时出现。查询待定期间弹出层被关闭后,部分列表会使弹出层保持关闭、控件保持不忙碌;下次打开时显示该查询的最新列表(component:BaseTypeaheadFR3)。 - FR6 — 高亮和滚动位置保持不动。 新查询显示的第一个列表会高亮其第一行。当同一查询的后续列表到达时,高亮项保持高亮,列表保持其滚动位置。后续列表绝不会把弹出层移到输入框的另一侧,也不会在屏幕上移动已显示的行:输入框上方的弹出层保持其高度,输入框下方的弹出层只在其下方空间内增长;超出该空间的行通过滚动列表来触达。当违反 FR2 的列表移动了高亮项时,高亮跟随该项;当它丢弃该项时,第一行被高亮。Enter 选择高亮项。
- FR7 — 项保持不变时,选项保持其身份。 当一个项仍位于某查询的列表中时,它的选项元素和它的
id保持不变。活动后代继续引用同一个选项,因此在它之后添加行时,辅助技术不会重新宣读高亮行。 - FR8 — 每个查询只播报一次结果。 typeahead 在每个查询定稿时播报一次结果数量。如果弹出层在查询定稿前被关闭,则在下次打开并显示该查询列表时播报一次数量(
component:BaseTypeaheadFR3)。部分列表不播报任何内容。忙碌开始按spec:AST-086FR6 和 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