跳转至

浏览器与平台支持系统规范

{
  "scope": "global",
  "triggers": {
    "platform": [
      "FR1",
      "FR3",
      "FR5",
      "FR6",
      "FR7",
      "FR8",
      "FR9",
      "FR10",
      "FR12",
      "FR13"
    ]
  }
}

意图

为稳定的 Astryx 网页组件确立浏览器支持、原生特性采用和降级回退的唯一负责人。组件规范继承这一共享基线,并且只记录明确的例外。

完整路径和回退路径都必须满足组件当前的无障碍契约,以及适用的 WCAG 2.2 Level AA 要求。辅助技术证据仍由单独的所有者负责。

非目标

  • 在用户结果等价时,不要求实现方式或像素级表现完全一致。
  • 不为每个缺失的浏览器特性提供 polyfill。
  • 不替换 AST-003 中的分层特定契约,或 AST-002 中的公共 API 准入规则。
  • 不在本规范拉取请求中实现生成行、消费者文档更新、CI 或发布工具。

要求

  • FR1 — 统一的滚动兼容模型。 当前 Web Platform Baseline 属于完整支持层级。Baseline 减去两年即为降级回退层级。Astryx 在该层级之下不作任何支持承诺。
  • FR2 — 兼容性行是生成的。 浏览器/版本行根据已批准的 Baseline 数据和权威浏览器发布数据生成;绝不会以手写的版本声明来维护。生成的行位于公开的 浏览器支持指南 中,并记录其来源和刷新日期。TypeScript 目标、构建目标和特性表都不能作为支持证据。
  • FR3 — 始终包含明确的浏览器支持行。 在生成的 Baseline 覆盖之外,Astryx 明确支持:
    • 桌面端的 Chrome 最新稳定版;
    • 最新稳定 iOS 版本上的 Safari;以及
    • 对于触控展示,最新稳定 Android 版本上的 Chrome (spec:AST-094)。

      “最新”指的是根据权威浏览器发布数据识别并刷新的当前稳定版本,而不是手写的版本。其他浏览器仍可由生成的 Baseline 兼容性行表示;该决定不会将桌面端 Safari 或 Firefox 列为额外的明确支持行。 - FR4 — 兼容性、显式支持与测试覆盖保持区分。 浏览器支持指南分别标注生成的 Baseline 兼容性、点名指出的显式支持以及当前的测试覆盖。某个浏览器被纳入生成的兼容性或显式支持,并不意味着该浏览器中有自动化测试通道,也不意味着每次拉取请求都要在该浏览器中验证。 - FR5 — 受支持的浏览器获得完整的必需行为。 完整支持层级中的每个浏览器,以及每个被点名的显式支持行,都获得组件当前的行为、无障碍、状态、渲染器和交互契约。缺失的原生特性不能悄悄收窄这些要求。 - FR6 — 原生特性通过能力检测。 组件检测其所使用的 API 或 CSS 能力,而不是根据浏览器名称来推断。仅当缺陷可复现、附带回归测试夹具并设有审查或移除条件时,才允许有限范围内的引擎特定绕过方案。 - FR7 — 降级回退保留任务。 在 Baseline 减去两年的层级中,组件要么提供等价行为,要么记录降级回退方案。回退方案只能省略点名指出的增强项,并且必须保留主要任务、适用的无障碍要求、稳定的状态和回调、清理逻辑以及重复使用能力。 - FR8 — 降级回退不得损坏。 它不能抛出错误、渲染无效的或 NaN 几何信息、隐藏必要内容、使控件不可达、让焦点游离或被困、阻塞周围页面、破坏受控状态、一直卡在 pending 状态,或者闪烁显示虚假的打开、关闭、加载、定位或样式状态。 - FR9 — SSR 与水合保持一致。 Core 组件具备 SSR 能力,除非其组件规范记录了 FR12 例外。客户端指令不会使组件获得豁免,因为框架会在服务器端渲染客户端组件。具备 SSR 能力的组件,在服务器渲染期间,或在为服务器标记进行水合的客户端渲染期间,不得读取浏览器能力、几何信息、输入模态、绘制时机或用户代理状态。水合渲染产生的标记必须与服务器相同。水合后的增强从可用状态开始,并且不引入不匹配、损坏的中间状态或可见的虚假状态。 - FR10 — 浏览器负责的行为需要真实浏览器证据。 源代码测试、单元测试和 jsdom 测试可以证明守卫逻辑和确定性状态。涉及布局、绘制、焦点、原生 Popover 或 Dialog 行为、顶层(top-layer)顺序、浏览器事件时序或水合呈现的更改,需要真实浏览器证据。当某项更改对指定浏览器提出主张、修复了只在该浏览器中复现的缺陷,或者改变了浏览器兼容性时,该证据必须来自主张所涵盖的实际浏览器。Chromium 不能代替 iOS Safari 的主张,Playwright WebKit 也不能证明 Safari 的行为。

显式支持是维护承诺,不是每次变更的证明义务。常规更改使用与其主张相称的证据,不需要在合并前证明每个受支持的浏览器。在明确支持的浏览器中复现的缺陷,仍然是 Astryx 负责调查和修复的责任;缺少自动化并不能收窄支持范围,也不能成为驳回的理由。

  • FR11 — 提高下限属于兼容性工作。 移除受支持的浏览器、将其从完整行为降为降级回退,或者移除已记录的降级回退方案,都需要负责人批准,按 spec:AST-017 要求进行分类和生命周期管理,提供用户影响与迁移说明,更新生成的行,提供兼容性主张所影响浏览器的真实浏览器证据,以及证明每个剩余的完整支持行和被点名的显式支持行仍然获得完整的必需行为。
  • FR12 — 组件规范继承基线。 组件规范链接 spec:AST-013,并且只记录更严格的要求或明确的例外。例外需要指明受影响的能力、可观察的缩减、保留的 FR7–FR9 义务、证据、负责人和审查条件。
  • FR13 — 服务器渲染的元素跳过其挂载动画。 服务器标记中已存在的元素以其稳定状态完成水合,并且不会播放它在挂载时播放的动画(其入场动画)。该挂载动画只会为客户端在水合之后挂载的元素播放,或在任何客户端专用根节点的首次绘制之后播放。已水合元素后续的打开、显示和状态转换不属于本要求范围,减少动态(reduced-motion)行为保持不变。

平台支持

  • 完整支持:当前 Web Platform Baseline,加上 FR3 中列出的明确支持行。
  • 降级回退:Baseline 减去两年,满足 FR7–FR9。
  • 不支持:低于 Baseline 减去两年;Astryx 不作任何支持承诺。
  • 浏览器证据:浏览器自身行为需要真实浏览器证据。针对特定浏览器的声明需要实际命名的浏览器,而不是作为每项变更的全面门槛。

当前状态影响

公开指南目前包含手写的 Baseline 层级和版本行。所要求的对生成的兼容性、明确支持和当前测试覆盖的三方面标注仍然是待实现的工作。当前的自动化浏览器覆盖主要运行 Chromium;该覆盖既不定义也不缩小支持范围。常规变更可以带着与其声明相称的证据落地。在明确支持的浏览器中复现的缺陷仍然可处理,无论是否存在自动化通道。

useEntryAnimation(以及通过它使用 FieldStatus 的情况)会根据首次渲染时捕获的首次绘制标志来决定是否播放动画。当标记在页面绘制后水合时,水合渲染会生成服务器未发送的入场动画类,而该 hook 的使用者文档说明其不支持服务端渲染。

其他已知的 FR9 和 FR13 差距:CodeBlock 的折叠箭头(chevron)会在页面加载时播放其展开动画;并且 CodeBlock 在渲染期间通过浏览器能力和 user-agent 检查在 token-span 与 Highlight API 标记之间进行选择,因此水合渲染可能与服务端标记不同。

验证

契约 所需证据 失败信号
FR1–FR5 生成行检查,并核对指南/包/支持/测试 手写/构建版本成为支持声明、明确支持行消失,或受支持行为被缩减
FR6–FR8 功能存在/缺失测试及活动回退测试夹具 浏览器嗅探选择普通行为,或回退不可用、不可访问、不稳定或明显损坏
FR9, FR13 先服务端渲染再水合:无水合警告或可恢复错误,水合后的属性等于服务端标记,水合后客户端挂载仍播放其挂载动画,外加真实浏览器的服务端渲染、水合和水合后测试夹具 标记不一致、在服务端或水合期间读取浏览器状态、服务端渲染的元素播放其挂载动画,或出现错误/损坏状态闪烁
FR10 针对浏览器自身行为的真实浏览器证据;针对具体声明的实际命名浏览器、仅浏览器缺陷和兼容性变更 浏览器自身行为被归功于 jsdom、另一个引擎代替了具名浏览器声明,或受支持浏览器缺陷因缺少测试通道而被驳回
FR11–FR12 发布审查和知识记录检查 底线/回退在未做兼容性处理的情况下消失,或组件静默覆盖 Baseline

决策日志

DEC-1 — 滚动 Baseline 层级及官方浏览器行

参考: spec:AST-013/DEC-1 决策者: cixzhang,2026-09-01

Astryx 将当前 Web Platform Baseline 用于完整支持,将 Baseline 减去两年用于降级回退,并且对该层级以下不作任何承诺。桌面端最新稳定版 Chrome 和最新稳定版 iOS 上的 Safari 始终作为官方支持和测试行包含在内,独立于生成的 Baseline 覆盖范围;触控演示还会在最新稳定版 Android 上加入 Chrome(spec:AST-094)。生成的兼容性行与具名的官方测试矩阵仍然是不同的公开事实。

DEC-2 — 明确支持不要求每次变更都提供证明

参考: spec:AST-013/DEC-2 决策者: cixzhang,2026-09-02

DEC-1 中具名的浏览器行是明确支持行,不是必需的自动化或按变更的测试矩阵。Astryx 会调查并修复在这些浏览器中复现的缺陷,但常规变更在落地前无需证明每个受支持的浏览器。当变更提出浏览器特定的声明、修复仅在该浏览器中复现的缺陷,或改变兼容性时,需要真实浏览器证据。缺少自动化既不会缩小支持范围,也不能成为驳回已复现缺陷的理由。

DEC-3 — 核心水合到服务端标记;服务端渲染的元素跳过其挂载动画

参考: spec:AST-013/DEC-3 决策者: cixzhang, 2026-10-15

核心组件在服务端与执行水合的客户端渲染中渲染出相同的标记,包括客户端组件;并且服务端渲染的元素保持静止状态,而不是播放其挂载动画。已拒绝:consumer-doc 的“不支持 SSR”例外,因为 FR12 仅在组件规范中记录例外。已拒绝:水合后变为 true 的“已绘制(has painted)”快照,因为它会对页面加载时已存在的元素进行动画处理。

开放问题

无。

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