跳转至

双向性设计规范

{
  "scope": "global",
  "triggers": {
    "accessibility": ["DR1", "DR2", "DR8", "DR10", "DR11", "DR12"],
    "interaction": ["DR1", "DR6", "DR8", "DR10", "DR11", "DR12", "DR13"],
    "layering": ["DR7", "DR10"],
    "layout": ["DR1", "DR2", "DR3", "DR7", "DR9", "DR10"],
    "navigation": ["DR1", "DR3", "DR4", "DR5", "DR6", "DR10", "DR11"],
    "react-runtime": ["DR9"],
    "responsive": ["DR1", "DR3", "DR10", "DR14"],
    "scrolling": ["DR1", "DR6", "DR10", "DR13"],
    "styling": ["DR3", "DR4", "DR5", "DR9", "DR10"],
    "visual": ["DR1", "DR4", "DR5", "DR10"]
  }
}

用户意图

人们应当能够理解和操作相同的 Astryx 界面,无论其页面、区域或内容是从左到右还是从右到左流动。RTL 支持不是对每个像素的机械镜像。它保留当前书写方向下的含义、阅读顺序、空间关系、目标大小和交互行为。

设计原则

  • DR1 — 保留含义而非坐标。 RTL 呈现 MUST 保留与 LTR 相同的任务含义和可供性关系。物理上的左/右实现细节并非设计要求,除非内容本身具有物理意义。
  • DR2 — 内容方向与布局方向是不同概念。 页面或区域具有环境方向,而文本、代码、URL、标识符和用户内容可能带有自身方向。混合方向内容 MUST 保留可读的字符顺序和标点,而不会移动到不同的语义位置。
  • DR3 — 阅读顺序关系遵循行内起点和终点。 导航、有序递进、主要/辅助通道、前导/尾随内容以及起点/终点对齐 MUST 遵循包含区域的方向。
  • DR4 — 方向性图形只处理一次。 水平图标或装饰性字形,其含义为上一个、下一个、后退、前进、起点、终点或递进,MUST 镜像或交换一次。Unicode bidi 算法已经镜像的图形 MUST NOT 再进行第二次手动镜像。
  • DR5 — 方向中立和物理内容保持稳定。 垂直、对称、品牌、媒体、图表、地图、时钟、硬件以及其他具有物理意义的内容 MUST 保持不变,除非其特定语义角色是方向性的。将调用方提供的左/右字形几何作为数据暴露的参考样例保留该几何;同样的字形如果用作上一个、下一个或递进提示,则遵循 DR4。
  • DR6 — 交互遵循视觉关系。 水平键盘移动、拖动/调整大小的计算、轮播或滚动递进、范围导航以及侧边放置 MUST 产生 RTL 视觉状态所指示的动作。
  • DR7 — 覆盖层保持与其逻辑属主相连。 菜单、对话框、工具提示、弹出框、抽屉和其他分层表面 MUST 保留其起点/终点对齐方式,以及在其触发器所在区域中与触发器的关系。
  • DR8 — 命中目标跟随可见控件。 指针或触摸目标 MUST 在两个方向上保持以可见控件为中心,并且 MUST 保留组件所需的目标尺寸。镜像 MUST NOT 使可见控件移位、缩小或仅部分可点击。
  • DR9 — 方向变化不得闪现错误的关系。 服务器和首次绘制输出 SHOULD 与文档或区域方向一致。当平台布局能够表达方向相关的关系时,该关系 MUST NOT 等待渲染后的 JavaScript 修正。
  • DR10 — 例外需要语义依据,而非便利性。 组件只有在该方向承载稳定的用户含义时,才可以保持物理方向。实现难度、当前 LTR 行为或全 N/A 审计不构成例外。

构成与层级

双向性适用于关系,而非某个共享的 DOM 结构。

角色 用途 所需关系
环境区域 建立布局和浏览器文本流向方向 后代遵循其 dir,除非嵌套的内容区域建立了另一个方向
有序序列 传达递进或阅读顺序 第一个/上一个/起点与最后一个/下一个/终点在 RTL 下交换物理侧
方向性控件 沿行内轴移动、揭示或指向 图形与行为在经过恰好一次方向性处理后保持一致
方向性装饰 在不具备交互行为的情况下传达层级或递进 当其 UI 角色为方向性时,恰好镜像一次
方向中立内容 携带独立于行内方向的视觉含义 保持其方向
交互目标 接收指针、触摸或键盘输入 与可见可供性保持对齐并保持所需尺寸
嵌套 bidi 内容 携带方向与周围区域不同的文本 保留其自身的字符顺序、标点和可读隔离

状态表示

状态 所需表示 允许的变体
LTR 区域 行内推进从左开始,到右结束 组件特定的间距与装饰
RTL 区域 行内推进从右开始,到左结束 组件特定的间距与装饰
显式方向覆盖 即使区域设置(locale)通常暗示另一方向,所选方向仍支配该子树 覆盖的测试与产品原因
嵌套的反向区域 局部内容流向改变,而无需将该区域移至另一语义槽位 由所属布局契约选择的对齐方式
混合文本、代码、URL 或标识符 字符顺序与结尾标点保持可读 浏览器 bidi 行为,并在需要时进行显式隔离
手动镜像字形或图标 一次水平镜像或一次成对字形交换 CSS 变换或语义字形对
Unicode 双向镜像字形 浏览器镜像未更改的字形 精确的字形选择
垂直、对称、品牌或实体图形 方向保持不变 缩放、颜色与主题处理
粗指针控件 目标保持居中,并满足组件的最小目标尺寸 超出该最小值的不可见命中区域形状

响应式与输入行为

  • DR11 — 键盘方向在交互时解析。 左/右行为 MUST 遵循当前渲染区域,包括嵌套区域和运行时方向变化。标签保持语义化(previous、next、start、end),而不是变成物理的左/右指令。
  • DR12 — 指针与触摸几何在质量上与方向无关。 可见控件、原生输入和有效命中区域 MUST 在 LTR 和 RTL 中于组件声明的容差内共享同一个中心,并且 MUST 保持所属组件声明的最小目标尺寸。仅证明居中是不够的。WCAG 2.5.8 目标尺寸的归属与例外仍由 AST-020 以及组件/组合契约负责。
  • DR13 — 拖拽、缩放和滚动结果镜像。 朝向逻辑“下一个/末尾”的手势 MUST 在两个方向上都移向逻辑“下一个/末尾”。物理增量可以反转,而用户可见的操作保持等效。
  • DR14 — 响应式重排保留逻辑归属。 将内容移入抽屉、面板、溢出菜单或替代布局时,MUST 保留哪些内容是前导/尾随内容,以及焦点如何返回其逻辑触发器。

无障碍意图

  • 无障碍名称描述语义动作,而非物理图标方向。请使用“上个月”和“下个月”,而不是“左箭头”和“右箭头”。
  • DOM dir 必须描述浏览器实际的区域方向,以便文本流、标点、原生控件行为、焦点/导航顺序以及无障碍 API 与视觉呈现保持一致。
  • 当浏览器推断无法保持弱标点、数字或 URL 的可读性时,混合方向的用户内容需要显式的局部方向或隔离。
  • RTL 支持必须保持焦点可见性、键盘可达性、目标尺寸和播报含义。焦点或触摸几何发生偏移的镜像画面并不是等效行为。
  • 自动生成的全 N/A 输出并不能证明组件已为 RTL 就绪。证据策略由 RTL 审计架构另行负责。

代表性示例

示例 必需结果
层级项目之间的面包屑斜杠 作为递进装饰进行镜像;日期、路径、分数或散文中的 / 则不镜像
日历的上一个/下一个按钮 按钮交换左右位置,箭头指向其动作方向,语义标签保持为“上一个/下一个”
粗指针上的 Checkbox、Radio 和 Switch 原生输入保持位于可见控件中心,并在两个方向上保持所属组件的最小目标尺寸
轮播的“下一个”操作 控件位置、图标和滚动增量在逻辑“下一个”上保持一致
包含 URL 的阿拉伯语句子 阿拉伯语文本按 RTL 流动,URL 保持 LTR 可读,标点始终附着于预期内容
原始字形登记表参考样本 调用方提供的左/右几何数据保持原样不变;不暗示任何方向控制行为
品牌标志或照片 不会仅仅因为周围布局为 RTL 就镜像

视觉参考

本记录不需要规范性截图。仓库自有的组件 stories 和基于关系的 LTR/RTL 审计输出提供实现证据;它们不能替代本记录中的人为意图。

当前没有任何组件记录链接到本记录。显式的全局路由为组件和模块审查提供匹配的 RTL 关系,而无需每个组件提供反向链接。视觉变化承载视觉素材的含义和例外;导航、交互和滚动则连同语义例外边界一起承载各自的方向性结果。这些路由不会让每个字形都具有方向性、不要求特定实现,也不会解决下方开放问题。

组件、模块和家族契约拥有各自的本地语义关系:哪些视觉素材是导航提示而非数据、哪些部分是 leading/trailing、它们暴露哪些键盘/滚动操作、支持的状态、目标尺寸要求,以及证明这些结果的测试。当本地需求或例外需要某种共享 DR 关系时,它们会引用特定的共享 DR;它们不会复制通用的 RTL 检查清单,也不会重新定义共享规则。

评审会为确切差异确定直接负责人,并且只在声明的范围内应用匹配的共享声明。本地例外需要根据 DR5/DR10 提供一致的语义理由,而不是隐式覆盖当前权威。运行时/helper 的责任仍属于 architecture:internationalization;RTL 审计证据和经过审慎考虑的 D1 豁免审查仍属于 architecture:rtl-audit-evidence。

决策日志

DEC-1 — 采用 DR1–DR14 作为共享的双向关系

参考: design:bidirectionality/DEC-1 决策者: nynexman4464,2026-10-15

当组件遵循 DR1–DR14 时,无论从哪个方向阅读,人们都能获得相同的任务含义、阅读顺序和交互结果。审计准入和实现证据仍由各自负责人管理,下方开放问题保持未决。

开放问题

  • OQ1 — 物理方向例外词汇。 组件是否需要一种共享的显式方式,用于记录物理/世界导向的视觉素材例外,还是组件本地的决策就足够?
  • OQ3 — 混合内容 fixtures。 哪些可公开安全使用的混合阿拉伯语/希伯来语以及 URL/数字/标点 fixtures 应成为必需的代表性 stories?
  • OQ4 — 方向变化转场。 运行时的 dir 变化是否应有明确的禁止动画规则,或者当产生的中间关系仍然可理解时,组件是否可以进行动画?

内容边界

本文件不定义 provider API、CSS 或 hook 实现、lint 规则、当前审计分数、verified-N/A admission 或消费者示例。它链接到这些所有者。

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