跳转至

交互模态架构

{
  "scope": "global",
  "triggers": {
    "interaction": ["INV1", "INV2", "INV3", "INV4", "INV7", "INV8", "INV11"]
  },
  "concerns": {
    "modality-tracking": {
      "names": [
        "useInteractionModalityTracking",
        "useInteractionModalityTrackingFor",
        "trackInteractionModalityIn",
        "getInteractionModality"
      ],
      "patterns": ["addEventListener\\(\\s*['\"](?:pointerdown|keydown)['\"]"],
      "claims": ["INV1", "INV2", "INV3"]
    },
    "focus-return": {
      "names": [
        "focusForLastInput",
        "isFocusDetached",
        "useFocusReturnVisibility"
      ],
      "claims": ["INV1"]
    },
    "press-tracking": {
      "names": ["createActionGroupTracker", "useMenuPress"],
      "claims": ["INV13", "INV14"]
    }
  }
}

目的

Astryx 组件在人们于键盘、指针、触摸、触控笔和编程式焦点之间切换时,行为保持可预测。必要操作保持可感知、可触达,同时其受控状态或任务上下文得以呈现;较新的用户意图始终优先于陈旧工作;每种 Core 与 Lab 手势(无论是拖拽还是滚动)读取相同的释放速度;滚动关联动画读取单一的滚动进度。本记录定义了这些共享交互不变量、唯一手势速度来源、唯一滚动进度来源、共享模态状态、模态与组件焦点所有权之间的边界,以及任何一项发生变化时所需的证据。

它不定义焦点环外观、悬停绘制、按压处理或新的组件 API。这些仍归属于设计约定、主题令牌以及所属组件家族。

系统模型

Astryx 将最后输入模态跟踪为单一共享状态:

  • 不按住 Meta、Alt 或 Control 的按键设置 keyboard;
  • 指针按压(包括鼠标、触摸或触控笔)设置 pointer;
  • 按住 Meta、Alt 或 Control 的按键不改变模态;且
  • 在任何输入之前,状态为 keyboard,因此初始或恢复的焦点保持可感知。

同一状态记录自上次指针按压以来,每个按键是否输入到文本输入字段。这些按键仍设置 keyboard;只有触摸触发的焦点守卫读取该记录,因为屏幕键盘会为每个输入的字符发送一次按键。该记录仅读取页面自身窗口中的文本输入字段。

编程式焦点不会创建新模态。其焦点指示器跟随最后输入模态:指针输入后隐藏,键盘输入后显示。组件使用浏览器的 :focus-visible 行为,并结合共享模态状态,用于 :focus-visible 单独无法区分发起输入的场景。

模态回答共享焦点指示器是否应可见。组件所有权回答哪个元素绘制它。语义焦点所有者可以在自身上绘制、委托给所属包装器绘制,或在可聚焦元素被有意隐藏时绘制在视觉代理上。该所有权不改变模态状态。

悬停能力与模态历史分离。悬停行为仅对支持悬停的指针可用,并且始终是键盘、单击和触摸路径之上的增强。触摸和触控笔按压参与指针模态,即使某个组件家族赋予它们不同的手势行为。

禁用、忙碌、只读、有意隐藏和有意不可用的语义与模态分离。其当前组件、组件家族或系统契约决定操作是否存在、可聚焦或可操作;模态仅控制合格焦点所有者上的焦点指示器。

当某个操作是唯一受支持的控件,能够在提供其组件所属上下文供交互的点位上继续、反转、关闭或改变该上下文时,该操作即为对受支持状态和模态为必要。布局和组合可以移动或代理该操作,但 MUST NOT 移除或隔离所有受支持路径与该交互点位之间的联系。这并不要求操作保持持续在屏、粘性悬挂或视觉突出。普通滚动是有效的,除非受支持组合将受控上下文保持于交互点位同时使其唯一操作孤立。

当前组件和组件家族契约定义可接受的意图、所有者替换、待定呈现,以及哪些关闭、取消、禁用或卸载转换接管同一交互结果。一旦该所有者定义接管,较旧的待定、延迟或异步工作的完成 MUST NOT 更改当前结果的内容、选择、状态或公告、可见性、焦点或激活。该规则不取消或重新指派无关的后台工作。

边界与不变量

  • INV1 — 最后输入拥有编程式焦点可见性。 编程式焦点保留当前模态。在指针输入之后,它不显示共享焦点指示器;在键盘输入之后则显示。若某个包装器的内容会遮挡它所绘制的焦点环(例如作为自身堆叠上下文的遮罩滚动器),它将以焦点所有者覆盖层(privateAttributes/focusOwner.stylex.ts 中的 focusWithinOwnerOverlay)绘制共享焦点环,并按照 INV3 所述以所有者属性为键。
  • INV2 — 模态与焦点所有权保持分离。 共享模态决定可见性。每个组件家族决定语义焦点所有者以及代表其绘制的元素。
  • INV3 — 一次焦点移动只有一个所属指示器。 包装器或视觉代理可以为语义所有者绘制,但同级控件绘制自己的焦点,替换内容不能静默移除所有者的指示器。为其他 Tab 停靠位之外的某个主要控件绘制焦点环的 Core 包装器,从 privateAttributes/focusOwner.stylex.ts 取用唯一的共享焦点所有者样式和所有者属性,因此仅在该控件持有键盘焦点时包装器显示焦点环,而嵌套所有者或同级控件则自行显示焦点环;没有组件自行写入该属性或其选择器。当布局将控件置于下一层时(例如编号 Item 中,其自身的按钮或链接位于标记旁边的单元格内),包装器使用模块的组属性标记该单元格,使焦点环仍能到达控件。实现差距:可点击和可选择的卡片、Thumbnail、MultiSelector、SideNavItem 以及 ChatComposer 的主体自行编写其焦点环条件。
  • INV4 — 每种模态都有可操作路径。 键盘、指针以及触摸或触控笔均可到达每个受支持的交互。悬停绝不是唯一的发现或激活路径。工具提示的滚动溢出是唯一例外,如 spec:AST-025 FR12 所述:工具提示在 ARIA 工具提示模式下从不获取焦点,因此超出视口高度的内容在其中内部滚动且没有键盘路径;其完整内容通过触发器的可访问描述对辅助技术保持可用,长内容或必要内容应属于 HoverCard 或 Popover。如果工具提示标注的操作触发器的可访问名称已携带其文本,则不是一个独立交互,因此点按该触发器执行操作而不打开工具提示;仅提示、不执行任何操作的触发器在默认 touchTrigger="auto" 下于点按后打开其工具提示,而信息图标后面的帮助通过 component:InfoTip(component:Tooltip DEC-1)固定显示。
  • INV5 — 现有状态语义优先。 禁用控件不会因模态而变为可交互。只读和忙碌控件保留其文档化的焦点与激活行为。
  • INV6 — 模态保持内部实现。 组件从共享浏览器输入状态派生模态。公开的焦点可见性或模态 prop 需要单独的公共 API 决策。
  • INV7 — 必要操作保持可触达。 在组件提供必要操作的受控上下文的交互点位处,每种受支持模态都有可感知且可操作的路径到达该操作。布局、滚动、溢出、重排、响应式组合、替换内容或自定义渲染器接缝 MUST NOT 将所有路径与该上下文分离。这不要求持续可见、粘性行为或增加突出程度。当前组件、组件家族或系统契约 MAY 在命名状态中有意隐藏、禁用或使操作不可用。
  • INV8 — 较新的所有者接受意图拥有当前结果。 当前组件和组件家族契约定义同一交互结果的意图接受、待定呈现和接管。一旦被接管,较早工作的完成 MUST NOT 更改当前结果的内容、选择、状态或公告、可见性、焦点或激活。无关的后台工作保留其现有所有者与生命周期。
  • INV9 — 交互发现需要可观察的损害。 共享交互违规需要可复现的受支持状态和模态中的具体用户损害。证据指明丢失或陈旧的结果,并验证具有代表性的正常或遗留路径在补救后保持不变。审美偏好、推测的不受支持状态,以及仅声称操作本可以更容易被发现,不构成交互违规。这并不阻止已由当前组件、组件家族、设计、主题或客观可访问性权威确定下来的视觉修正;该修正使用渲染像素证据及其直接所有者,而非重新定性为交互可触达性。
  • INV10 — 手势速度只有一个所有者。 在 @astryxdesign/core 中,一个内部速度跟踪器拥有手势的指针采样并报告速度,其唯一个释放过滤器是 Core 组件读取的唯一抬升速度(spec:AST-100)。该过滤器是 iOS 的实测混合:平移速度为最新间隔速度的 0.2 倍加上上一间隔速度的 0.8 倍,在每次移动采样时更新;滚动表面的释成为最新平移值的 0.25 倍加上上一值的 0.75 倍;在抬升前停留超过静止间隔的接触读取为 0。它不对外导出。没有 Core 组件维护自己的采样缓冲区、速度数学或替代释放过滤器;组件的甩动阈值比较跟踪器的释放速度。Lab 不保留其副本:没有 Lab 组件拥有自己的采样缓冲区、速度数学或释放过滤器,因此对于相同运动,Lab 与 Core 报告相同的速度。
  • INV11 — 悬停意图是识别器设置。 悬停识别器 HoverGestureRecognizer 接受 intent: {enterMs, exitMs, group}:一个针对刷过悬停的进入延迟(所有者的记录可将其设为零)、一个退出守卫,以及一个组,指针从一个打开的触发器移动到下一个触发器时立即显示下一个。键盘焦点立即显示,手指永远不会被其门控或服务:意图仅回答鼠标和触控笔悬停。悬停识别器仅对支持悬停的指针附加,因为手指无法悬停,并且不注册触摸监听器。useTooltip、useHoverCard 和 useMenuHover 从中获取其悬停计时;useContainerReveal 保留其纯 CSS 停留(component:Thumbnail PR1),仅从所有者的意图中取其延迟值。进入和退出动画、悬停色调以及默认延迟本身保留在其所有者处。该设置不添加模块且为内部实现(spec:AST-017 FR21)。

  • INV12 — 原生滚动报告进度。 原生滚动模块同样报告进度:progress(range) 将滚动位置转换为某个范围(一个元素的跨度或一段距离)内从 0 到 1 的值,并包含其边界;订阅会在渲染路径之外将其传递给动画器或 CSS 自定义属性,绝不经过 React state。在平台支持时优先使用原生 animation-timeline: scroll(),本方案作为回退。在减弱动效下,进度仍会报告,而它所驱动的位移会在每条路径上停止——无论经由动画器还是 CSS 自定义属性。滚动吸附与动量保持原生行为。它不新增模块,且为内部实现(spec:AST-017 FR21)。

  • INV13 — 跨组按压跟踪只有一个所有者。 在 @astryxdesign/core 中,一个内部模块 actionGroupTracker 为 family:action-groups 中除菜单以及 Selector 和 MultiSelector 的选项之外的所有成员跟踪跨其动作的按住指针;后者的跟踪和公开的 menuPressStep 属于 module:DropdownMenu/useMenuPress(OQ1;实现缺口:MultiSelector 尚未挂载它)。其他任何成员都不保留自己的跟踪副本。它不被导出(spec:AST-017 FR21)。

  • INV14 — 沿单轴选择的分组沿其轴跟踪按压。 一个可选择的分组,其选项位于一行或一列中,并且抬起会选中其中一个,可以沿该轴跟踪按压(tracksAlong)。按钮组和菜单不这样做:family:action-groups FR3 仍然约束它们。随后 actionGroupTracker 会将按住指针计入分组的中心线上,并限制在其两端。指针偏离分组从不取消按压:沿轴方向上指针位置下的选项保持高亮,抬起时选中它。只有取消才会结束按压且不产生选择:浏览器接管指针(pointercancel),或用户按下 Escape。此时高亮随即立即恢复。SegmentedControl 是该系列中唯一命名的例外分组(spec:AST-020 DEC-6)。

允许的变体

组件系列保持其交付的交互模型:

  • 操作可以在可聚焦的操作上绘制共享轮廓;
  • 带边框的字段可以在所属包装器上绘制其既定的字段聚焦样式;
  • 隐藏的原生输入可以让属主代码在可见指示器上绘制;
  • 菜单可以通过鼠标悬停移动焦点,使指针和键盘共享同一个高亮项;以及
  • 空间控件可以在指针手势期间移动焦点,而不显示键盘焦点指示器。

这些是属主和行为选择,并非替代性模态定义。新的视觉呈现仍需设计评审;本记录不授权任何新的视觉呈现。

恢复性变更路由

只有 architecture:knowledge-contracts 定义变更处置。INV7 和 INV8 可以提供某项变更所恢复的当前结果,但并不能授权另一个可观察的公开增量。新的 API、例外、默认值、交互模型、图标或控件尺寸、粘性行为、调用方拥有的布局以及新的视觉呈现,仍由其当前直接所有者负责,除非有证据证明该确切机制是恢复该不变量所必需的,并且代表性的未受影响路径保持不变。可分离的增量会在请求此交互恢复承载新决策之前被移除或拆分,但未声明的公开 API 行除外——它会进入人工评审以由所有者做决定,而非由评审移除或拆分(architecture:knowledge-contracts 变更耦合步骤 6)。

变更耦合

  • 对模态跟踪、焦点返回可见性、共享焦点样式或视觉代理所有权的变更,会在同一个拉取请求中更新相关的代表性测试。
  • 移动组件的语义焦点属主或绘制属主时,需验证键盘顺序、两种模态之后的程序化焦点、单一指示器属主,并在适用时验证禁用、忙碌和只读行为。
  • 添加依赖指针的行为时,需按适用情况验证鼠标、触摸和笔,包括非悬停路径。
  • 移动、隐藏、裁剪、替换或异步更新关键操作时,需在受影响状态下验证每种受支持的模态,并在适用时验证关闭与取代,以及一个代表性的未受影响状态。
  • 被呈现为交互恢复的变更,需要盘点每一个额外的公开行为增量。未被证明必要的布局、尺寸、API、默认值和例外变更,仍应单独走流程。
  • 更改焦点外观仍与 Design Conventions 和主题验证相耦合。通过公开 API 暴露模态仍与 architecture:public-component-api 相耦合。

属主代码

  • utils/interactionModality.ts — 记录并公开共享的最后输入模态。
  • utils/focusOutline.stylex.ts 和焦点 tokens — 提供共享的焦点指示器机制和主题接缝,而不选择组件属主。
  • privateAttributes/focusOwner.stylex.ts — 拥有私有焦点属主属性、其选择器,以及供 INV3 的主要控件属主使用的单一共享包装环;它不会从包中导出。
  • hooks/useFocusReturnVisibility.ts — 当焦点从自适应表面返回时,应用最后输入可见性。
  • hooks/useIndicatorFocusRing.tsx — 让语义属主保证在可替换的可视指示器上完成绘制。
  • 当前的组件与组件系列记录定义了焦点目的地、键盘与指针行为、关键操作可用性、被接受的意图、取代、待处理生命周期以及焦点绘制属主。
  • architecture:react-component-runtime 拥有共享的生命周期与资源机制。本记录只拥有以下横切需求:模态路径、无陈旧交互结果、手势速度来源、悬停意图(INV11)、滚动进度来源(INV12)以及分组按压跟踪(INV13、INV14)。
  • Core 速度跟踪器及其发布过滤器(INV10)— 是 Core 组件手势速度的唯一来源;不导出。
  • 悬停识别器 HoverGestureRecognizer 及其 intent 设置(INV11)— 是 Core 组件悬停显示时机的唯一来源;不导出。
  • 原生滚动模块的进度及其订阅(INV12)— 是 Core 组件滚动进度的唯一来源;不导出。
  • 操作组跟踪器(INV13)— 是菜单以及 Selector 和 MultiSelector 选项之外的操作组的唯一按压跟踪器,具有其单轴跟踪(INV14);不导出。
  • Layer/useTouchTrigger.ts 中的 useTapStop — 吞掉在不得响应轻触的控件上触摸按压之后紧随而来的 click 或 mousedown;不导出。Tokenizer 在每次按压时运行它,并且只有在手指按住且键盘按下之后,才会把一个 token 的移除按钮的 mousedown 传递给它。笔的按压保持其默认行为,鼠标的按压也是如此。

规格决策

spec:AST-100/DEC-1 决定每种表面类型的一种发布速度(INV10),spec:AST-094/DEC-17 决定每个操作组的一种按压跟踪方式(INV13)。spec:AST-020/DEC-6 决定单轴跟踪(INV14)。除此之外,没有其他单独的规格变更此记录。最后输入规则由 cixzhang 于 2026-08-30 批准为系统架构决策。关键操作可达性、较新意图优先级以及证据/范围守卫由 cixzhang 于 2026-09-10 批准。

验证

不变量 证据 失败信号
INV1, INV2 代表性组件测试中键盘和指针输入后的编程式焦点场景 编程式焦点凭空引入一种模态,或指针历史绘制出键盘指示器
INV3 直接所有者、包装所有者、可替换指示器和嵌套操作场景,包括 Item 内的 Token 和卡片内的控件;FocusRingOwner.a11y.chromium.spec.ts 覆盖 Selector 中的共享模块,而差距中列出的其他包装器尚未被覆盖 无指示器、两个指示器、可选择退出的替换内容,或组件自行写入 focus-owner 属性或选择器
INV4 适用情况下的键盘、鼠标、触摸和触控笔浏览器路径;在带标签工具提示的操作触发器上以及 touchTrigger="auto" 下的仅提示触发器上的点击场景 仅悬停行为、粘性触摸悬停、不可达操作、点击操作触发器后打开其标签工具提示,或没有触摸路径的仅提示信息
INV5 禁用、忙碌和只读的 DOM 与激活断言 非活动控件产生反应、符合条件的控件失去焦点,或状态随模态改变
INV6 公共 API 审查与代表性源代码检查 组件未经单独的 API 决策便添加调用方控制的模态
INV7 跨几何、裁剪、滚动、命中测试、内置和自定义渲染器路径的渲染浏览器受影响状态检查 在提供的交互点上,一种模态失去所有关键路径,或证据以类相等性替代可达性/可感知性
INV8 所有者定义的意图顺序、待处理、关闭、取消、禁用和卸载变更 在所有者定义的取代之后,较早的工作更改了当前内容、选择、状态或公告、可见性、焦点或激活
INV9 具体损害的重现、代表性正常/旧版/无新属性路径,以及重合的公共差异清单 不受支持或审美偏好被视为损害、未受影响的行为发生变化,或 API、布局、尺寸、默认值、粘性或异常差异超出直接权限范围
INV10 对 Core 和 Lab 进行源码边界检查,在一条录制流上进行 Lab 与 Core 的对比,并对录制的 iOS 平移和滚动视图流进行释放过滤器单元测试 Core 组件带有自己的采样缓冲区、速度计算或释放过滤器;Lab 组件带有自己的采样缓冲区、速度计算或释放过滤器;Lab 组件对同一条流报告的速率与 Core 不同;导出跟踪器;静止暂停后出现非零释放
INV11 证据缺口:尚未实现;共享悬停识别器及其采用者迁移到该识别器的工作尚未完成。随后:对悬停识别器意图的单元测试,以及使用鼠标、手写笔、手指和键盘对其采用者进行的浏览器测试 出现不包含所有者进入延迟的显示;组内交接遗漏;延迟的键盘显示;悬停显示的浮层在指针到达前关闭;该识别器服务于手指操作;或第二个悬停计时实现失败
INV12 原生滚动进度的单元测试,以及其采用者的真实浏览器验证 进度经由 React 状态路由;缺少边界;在 Reduce Motion 下移动;在支持原生滚动驱动动画的地方使用;或公共导出失败
INV13 对 Core 以及每个家族成员的指针流测试进行源码边界检查 菜单及 Selector 和 MultiSelector 的选项之外的成员使用自己的代码跨其操作跟踪按住的指针,或跟踪器的公共导出失败
INV14 actionGroupTracker.test.ts 的单轴用例,以及 SegmentedControl 的漂移、越过末尾、取消和 Escape 浏览器用例 单轴组在漂移离开时取消按下、越过末尾后丢失其末端操作、或在取消或 Escape 后仍保持高亮,则失败

当行为依赖于 :focus-visible、指针能力、触摸或手写笔合成、渲染后的焦点归属、滚动、裁剪、命中测试,或某个必要控件在受支持的呈现方式中是否仍可感知时,需要真实浏览器证据。单元测试可以证明事件路由、DOM 状态和确定性的意图排序,但不能取代这些浏览器结果。

组合式编辑器表面是该记录的验证基准:它涵盖键盘拥有的编辑器焦点、指针抑制、在指针按下时清除已有键盘指示器,以及保持内部操作焦点由该操作拥有。该基准还会在行为被视为完成之前,验证键盘和指针输入之后的程序化编辑器焦点。基准用于演示这些不变量;它并不为它们提供权威依据。

开放问题

  • OQ1 — 菜单以及 Selector 和 MultiSelector 的选项何时迁移到共享跟踪器? (engineering) 开放。

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