跳转至

Ref-first DOM styling target

Intent

使用方可以在同一个元素上使用 style、className 和 xstyle,并且该元素可以通过组件公开的 DOM ref 访问。当组件未暴露无前缀 ref 时,这些 props 作用于其唯一的最外层 DOM 元素。

命名部件样式和明确记录在案的兼容性豁免保留各自的目标。决定默认样式目标的是 ref 身份,而不是调用方是否提供了 ref 值。

Non-goals

  • 不要求每个组件都接受通用样式 props 或暴露 DOM ref。
  • 不新增、移动或选择公开 ref 目标来改变样式行为。
  • 不改变样式优先级、语义 props、事件、可访问性或 ref 行为。
  • 不替换命名部件样式或 input 系列禁止根元素样式的规定。
  • 不规定强制算法、注册表或 CI 拓扑。

Requirements

  • FR1 — 公开 DOM ref 优先。 接受 style、className 或 xstyle 中任意一种,并暴露无前缀 DOM ref 的稳定版 Core Web 组件,MUST 在每条受支持的渲染路径上,将其接受的每个通用样式 prop 应用于该 ref 的公开契约所承诺的元素,但下述明确列出的兼容性豁免除外。目标可以是内部控件或唯一的分离表面;DOM 祖先关系不得覆盖有效的公开 ref 目标。
  • FR2 — API 选择目标,而非调用点。 FR1 适用于调用方传入 ref、省略 ref、使用回调或对象 ref,或传入 null 的情况。暂时的 ref.current === null、已关闭的表面或未挂载的目标 MUST NOT 导致样式移动到另一个元素。当承诺的目标不存在时,在它渲染之前没有可被设置样式的元素。内部 ref 以及 contentRef、triggerRef、controlRef 等命名 ref 不会选择默认目标;它们保留各自单独命名的部件契约。
  • FR3 — 未暴露 ref 时回退到最外层。 只有公开 API 未暴露无前缀 ref 的组件,才使用其唯一的、组件自身拥有的最外层 DOM 元素。该组件没有组件自身拥有的 DOM 祖先;每当有任何自身拥有的 DOM 渲染时,组件的各棵树中 MUST 恰好存在一个自身拥有的根。单独的 portal 根元素符合条件;隐藏的测量对等元素、组合包装器和分离的公开表面都算作自身拥有的 DOM。使用方提供的子元素和外部 portal 宿主本身不算自身拥有的根。当没有自身拥有的 DOM 渲染时,通用样式不起作用,也不会移动到另一个元素。空路径不会为一个原本无头的组件建立目标保证。该回退不依赖运行时的 ref 存在性或值。
  • FR4 — 不可用的 ref 不等于缺失 ref。 解析到命令式句柄而非直接解析为 DOM 元素的无前缀 ref、含糊的公开 ref 契约,或暴露但未转发的 ref,均不提供默认可设置样式的元素。命令式句柄中某个值为 DOM 的成员并不会使该句柄成为 DOM ref。此类组件在具备有效目标契约之前 MUST NOT 引入通用样式 props。它可以改为暴露显式命名部件样式。它 MUST NOT 仅仅因为无法满足 FR1 就静默使用最外层回退。既有行为需要限定范围的豁免;普通的 ref 转发缺陷仍由其当前所有者承担为缺陷。
  • FR5 — 组合保留公开身份。 组合式或多态组件 MUST 保证其接受的每个通用样式输入都能到达所承诺的公开 DOM ref 元素;若未暴露 ref,则到达其唯一的最外层根。仅仅将 props 转发给不受限的使用方组件并不能证明这一保证。新增、移除、改变类型或重新指定公开 ref 的目标 MUST NOT 静默改变样式目标。
  • FR6 — 命名部件与系列排除保持完整。 命名部件样式使用 spec:AST-071 下的完整 <part>Xstyle、<part>ClassName 和 <part>Style 集合。family:input-fields FR10 与 DEC-7 继续禁止对 Field 组合组件进行根元素样式设置,并定义其 container* 与 control* 目标。拥有原生 input ref 并不会恢复被禁止的根元素样式;拥有命名 controlRef 也不会重新路由通用或命名样式。受 family:input-fields FR10 约束的组件不在本默认范围内,包括它们在 FR10 落地前仍接受的任何根元素样式。语义 props 保留其所属契约的目标。
  • FR7 — 豁免保留有界契约。 每项豁免都标识组件、受影响的渲染路径、保留的样式目标、实际 ref 契约或缺失的保证、原因以及所属契约。它只豁免与这一默认行为的所述偏差;并不批准对另一个当前所有者的既有违规。显式列出的拆分或缺失的通用样式目标是遗留的执法豁免,而非有效的替代契约:其当前的保留/组合义务仍然开放。列出的目标范围之外的无关 ref 失败、丢弃的中性 props、命名部件缺陷和样式组合缺陷不在豁免之列。新组件和新的偏差路径 MUST NOT 通过类比继承豁免。移除或扩大豁免需要所有者的明确决定;没有自动过期或强制迁移。
  • FR8 — 兼容性与权威性保持明确。 当 ref API 变更会改变默认目标时,它同时也是一次样式兼容性审查。移动已发布的样式或 ref 目标、合并拆分目标或移除已接受的 prop,均遵循 spec:AST-017,并包含所需的兼容性决定、迁移证据、使用方文档和发布分类。使该记录保持最新,也会一并更新与之冲突的当前 API、系列和组件声明。任何豁免都不能免除另一个当前所有者已经要求的迁移。

平台支持

  • 范围:稳定的 Core Web 组件以及实现这些组件的组合渲染路径。Hook 不独立受管辖;使用 Hook 实现的组件仍然遵循组件契约。
  • 非 DOM 渲染器、没有 DOM 样式表面的 provider,以及 Lab 组件不在本规则范围内。不接受任何通用样式 props 的组件不承担默认样式目标。
  • 浏览器特性支持不变。元素/ref 同一性测试证明了目标定位;未来迁移在可观察的布局、外观或交互方面的声明需要真实浏览器证据,而不是仅凭本记录的文字。

当前状态影响

规范的共享 API 属主是 architecture:public-component-api,其 INV5 和 INV6 在文档化的契约元素与组合上保留样式,其 INV8 保留文档化的 ref 目标。它们不要求样式目标与 ref 目标是同一元素。architecture:public-component-api INV15 和 spec:AST-071 FR1 将部件集描述为根元素以外元素的样式;INV6 和 family:input-fields FR10 将无前缀集合称为根样式输入;FR1 的内部控件目标在提升时修订了这些声明。在本记录处于草案期间,这些当前声明仍然具有权威性。

ref 优先的默认规则仅适用于没有明确豁免的受支持通用样式输入。现有的组件特定表面目标、命名部件和家族排除项仍保持文档化,而不会被静默重新分类。

输入家族的部件目标契约拥有 container* 和 control* 语义。此处的豁免不会免除 family:input-fields FR10 和 DEC-7 下剩余的任何实现债务。

兼容性豁免

这些豁免仅适用于已命名的现有 API 和渲染路径。它们保留下文所述的样式和 ref 目标;提供、省略、分离或清除 ref 不会选择另一个目标。除非存在单独列出的遗留差距,否则所有被接受的通用样式输入继续在保留的元素上组合。当样式集已经到达有效的公共 DOM ref 元素时,仅拓扑差异本身不需要豁免。

目标保留豁免

ID 组件与路径 保留的样式目标 / 公共 ref 目标 原因 / 属主契约
E1 CheckboxInput 和 Switch,所有支持的渲染模式 外层整字段 div / 原生复选框或开关 input 保留整字段样式以及正确暴露的语义控件 ref。二者都不组合 Field,也不属于 FR10 排除的根样式集合;共享 API 及各自控件的属主。
E2 CommandPaletteInput 查询包装器 div / 查询 input 当前的 component:CommandPaletteInput FR3 证实了视觉包装器和原生控件之间的分离接缝。
E3 Horizontal Stepper,展开或紧凑 水平框架 div / 有序列表 ol 保留框架样式以及列表测量/ref 标识;component:Stepper。垂直列表目标的样式无需目标豁免。
E4 Timestamp 和 Timer,受支持的渲染时间状态 外部文本 span / 内部 time 保留现有的时间包装器,而不是将通用样式迁移到 time。component:Timer FR5/ORD2 与时间组件/共享 API 所有者描述了该接缝;Timer 目前更广的计时器系统措辞在 OQ3 中仍是未解决的权威归属张力。
E5 ContextMenu 和 MoreMenu 的指针/sheet 路径 内部菜单/内容 div / 触发器包装器或触发器按钮 现有通用样式描述的是菜单本身,而非其触发器。共享 API 与菜单所有者保留该目标;现有的 sheet ref 转发债务不予豁免。
E6 DropdownMenu 的指针/sheet;Popover 的 automatic/custom/external-anchor 及 sheet;HoverCard 的 text/element/fragment-trigger 路径 DropdownMenu 内部菜单 div、Popover 内部绘制 div(sheet 呈现中的面板,component:Popover DEC-8)或 HoverCard 浮动 div / 不存在未加前缀的组件 ref 在触发器、持久模板、宿主和表面树之间,不存在唯一的最外层回退。命名/payload ref 不是组件 ref。component:Popover 拥有绘制表面样式;相应的菜单/HoverCard 与共享 API 所有者保留其他目标。
E7 嵌套的 Tokenizer Field 框渲染时的 PowerSearch;PowerSearch 的 sheet 呈现 通过 Tokenizer 的 container* 输入实现的嵌套 Field 框 / 外部 PowerSearch 包装器;sheet 呈现:字段容器上的样式集及根节点上的 ref(component:PowerSearch DEC-3) 保留更上层组合当前的样式投射。当 Field 框不存在时,该部件不产生任何效果并发出警告,绝不会改道。component:PowerSearch、component:Tokenizer 及输入族部件契约;不会向 Tokenizer 添加根样式。family:input-fields FR10 绑定 PowerSearch。
E8 InputClearButton 的通用 tooltip 路径 原生清除 button;仅接受 xstyle / 无公共组件 ref tooltip 对等组件会阻止唯一最外层回退。共享 API 所有者;缺失的 class/style 对应物及不完整的图标部件输入仍是 AST-071 的义务。
E9 现有不受限的自定义根 API:Stack、HStack、VStack、StackItem、Item;Avatar、Button、IconButton、Link、Tab、Token、DropdownMenuItem/ContextMenuItem/BreadcrumbMenuItem、NavHeadingMenuItem、TopNavHeading、TopNavItem、TopNavMegaMenuItem、SideNavHeading 和 SideNavItem 的自定义链接/路由分支;自定义 Icon 根交接以及 Table 包装器/变换交接 现有的下放至调用方组件的 class/内联样式与 ref 交接,而非新选中的 DOM 节点;对于 Table,样式和公共 ref 仍保留在接收到的语义化 table 上,包装器/上下文输出可以保留、包装、复制、分离或移除该 table 仅豁免于新的组合样式/ref 同一性证明要求。保留已发布的交接,而不断言任意调用方输出具有 DOM ref 或转发样式。对象句柄不会触发最外层回退。原生/内置分支仍须履行自身的同一性契约;新 API 和分歧路径不在覆盖范围内。family:layout-primitives、共享 API 以及每个根/变换所有者。
E10 BottomSheetSwitcher,每一步 每一步的 sheet 对话框都携带所接受的 className、style 和 xstyle;公共 ref 解析为宿主对话框(当前活动 sheet 的对话框,否则为正在退场或静止的那个) 每个步骤都是各自的 sheet 对话框,因此切换器的对话框表面适用于所有步骤;仅对 ref 指向的对话框设置样式会使其他步骤失去样式。component:BottomSheetSwitcher 负责决定哪个对话框承载 ref。

遗留的默认强制执行豁免

这些是从新的统一目标检查中明确排除的例外情况,并非有效的替代契约。现有的当前所有者义务仍然有效。下表中失败的 ref 绑定并不授权运行时最外层回退。

ID 组件与路径 ref 优先目标保证中的现有缺口 保留的义务
L1 ChatComposer 渲染的 frame/body 路径 style 和 className 作用于 frame/public-ref 元素;xstyle 作用于 body 共享 API INV5/INV6;不会从草案中推断出经批准的拆分目标。
L2 SideNavItem 渲染的路径 xstyle 作用于外层列;className 和 style 作用于内层主要控件/ref 绑定 共享 API INV5/INV6/INV8;拆分和模糊的 root-ref 承诺仍然悬而未决。
L3 TopNav 承载内容的抽屉路径 所有被接受的一般样式输入和公共 ref 都会被丢弃 共享 API INV5/INV6/INV8;真正空的输出本身并不构成豁免。
L4 SideNav 承载内容的 drawer-content 路径 所有被接受的一般样式输入和公共 ref 都会被丢弃 共享 API INV5/INV6/INV8;条件性 footer 根无法修复该丢失。
L5 TypeaheadItem 的非空调用方 item.element 路径 被接受的一般样式和公共 ref 不会应用于返回的调用方节点 共享 API INV5/INV6/INV8;任意的调用方输出不是有保证的转发器。
L6 SegmentedControlItem 被接受的 className 会被覆盖;动态 StyleX 输出可以覆盖整个被接受的内联 style 共享 API INV5/INV6;这是样式丢失,而不是允许的拆分或优先级决定。
L7 VisuallyHidden 所接受的继承 xstyle、固有元素路径和自定义路径 xstyle 被忽略(component:VisuallyHidden FR3),而不是应用到其 ref 元素上;className 和 style 不被接受 共享 API/AST-071 义务与无样式意图需要调和;该豁免不产生样式支持。
L8 Icon 的注册表渲染路径;CheckIndicator 的选中对勾字形路径 Icon:其公共 ref 到达 svg(component:Icon FR8),而带样式的包装器是未承诺的实现(AV2);CheckIndicator:样式到达渲染出的 span,但所接受的公共 ref 未被转发到那里 仅被排除在新的样式/ref 同一性证明之外。Icon 不承诺 span;CheckIndicator 未转发的 ref 并非 INV8 的免除。替换/自定义路径另行界定范围。
L9 Dialog、AlertDialog 和 CommandPalette 的内联打开路径 通用样式到达内联 div;所接受的 dialog ref 未绑定 仅被排除在新的样式/ref 同一性证明之外。现有 INV8/已声明元素欠账仍然存在;内联关闭时的 null 不会选择其他目标。
L10 SideNav 承载目标的顶栏与抽屉路径 现有通用样式到达顶栏 div 或抽屉 dialog,但所接受的公共 ref 未绑定 仅被排除在新的样式/ref 同一性证明之外。现有 INV8 义务仍然存在;不授权最外层回退或改换 ref 目标。

InputGroup 的通用样式和实际公共 ref 都到达其内部 group div,但其当前在 FR10 下的 Field 组合范围尚未解决。匹配这一默认行为并不允许另一个当前所有者所禁止的样式;OQ2 要求由该所有者做出决定。在原本共同指向同一目标的原生分支上,声明 ref 类型不匹配同样仍然是独立义务,而不是移动样式的理由。

Hook 渲染器的样式通道不属于此组件默认规则。它们自身的现有契约继续适用,包括任何已接受的 renderer-prop 缺口。Tooltip、Toast、ToastViewport、Theme、MediaTheme、SyntaxTheme 以及 provider 组件上没有通用样式,这不是祖父条款豁免,也不表示它们没有自有 DOM。

所有者归属

共享目标与豁免边界归属于 architecture:public-component-api 和 contributing:api-conventions。family:layout-primitives 拥有其多态成员契约;family:input-fields 拥有其根元素样式排除与部件目标。每个被豁免组件的所属契约和消费者文档在适用路径上区分样式目标与公共 ref 目标。本草案不会重写现有记录。

验证

契约 验证方式 代表性状态 变更或失败预期
FR1–FR2 将不同的内联样式、类名和 StyleX 标记断言到公共 DOM ref 元素上 内部控件、分离目标、回调/对象/省略/null ref;关闭/打开的表面 传入或省略 ref 会改变样式目标;null ref 会重新路由样式。
FR3–FR4 公共 prop/类型检查与自有根同一性测试 无公开 ref 且只有一个根;无公开 ref 且有同级多根;先完全空渲染再挂载;包含 DOM 值成员的命令式句柄;有歧义或被丢弃的 ref 不可用的 ref 会触发最外层回退,或者没有有效目标的组件会获得通用样式 props。
FR5 元素/ref 同一性夹具与兼容性审查 固有元素 as、保证的组合目标、不受限的 as、添加/移除/重新定向的 ref 仅转发就被当作同一性证明,或 ref API 的编辑会悄然移动样式。
FR6 拥有的契约、公开类型、语义透传测试和命名部分标记 独立字段、分组字段和水平标签字段;公开的命名部分引用 由 Field 组合的组件获得了被禁止的根样式,或命名 ref 将通用/部分样式重定向到了其他目标。
FR7 显式的组件/路径/样式目标/引用目标豁免覆盖和负面案例 所有保留的目标及相关模式;新的同级节点和新的渲染路径 一揽子豁免掩盖了 ref 失败,或覆盖了未列出的分歧。
FR8 当前记录一致性、消费者迁移证据、兼容性审查和发布元数据 豁免保留;ref API 编辑;目标移动;prop 移除 目标被静默更改,或草稿被当作权威依据。

决策日志

DEC-1 — 通用样式遵循公共 DOM 引用

参考: spec:AST-089/DEC-1 决策提议人: imdreamrunner

消费者可以对同一个可公开寻址的 DOM 元素进行检查、测量、聚焦和样式化。即使调用方未传入任何 ref 值,无前缀的 ref 契约也会选择该元素。只有没有无前缀 ref 的 API 才使用唯一的最外层根;显式豁免会保留已确立的目标。

已否决:在运行时从 ref.current 中选择目标,因为挂载或提供 ref 会使样式目标发生移动。 已否决:以最外层为默认目标、且独立于 ref 身份对整个所属根进行样式化的做法,因为那样消费者的 ref 和样式将指向不同的元素。

DEC-2 — 现有分歧是显式的兼容性豁免

参考: spec:AST-089/DEC-2 决策提议人: imdreamrunner

该默认行为不会强制带来破坏性的目标移动、新的 ref API 或 prop 移除。豁免仅保留已命名的现有目标和路径。已命名的组件族排除项及其单独获批的迁移保持其自身的权威性。

已否决:将所有现有分歧都视为立即迁移的先决条件,因为该默认行为会迫使消费者进行无关的更改。

开放问题

  • OQ2 — Field 组合的根样式禁令是否包括 InputGroup? (human-api) InputGroup 的样式和 ref 共同指向其内部组,但其 Field 组合方式和协作者分类使当前 FR10 的范围不一致。组件族和直接 API 的所有者将协调该范围;满足这一默认要求并不豁免 FR10。
  • OQ3 — 当前的哪项 timer 声明拥有保留的 wrapper/ref 拆分? (human-api) component:Timer FR5/ORD2 保留了 Text-wrapper 样式和 time 引用,而 spec:AST-037 对根元素的措辞更为宽泛。共享 API 与 Timer 的所有者将协调当前的声明;E4 不会凭空设定优先级。

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