跳转至

结构化百分比 useResizable 配置系统规格

意图

调整面板大小的人应当获得与手柄所呈现以及辅助技术所宣告的面板大小一致的结果。构建者可以将初始大小或边界配置为百分比,并可选地通过 percent(value, {min: pixel(value)}) 或 percent(value, {max: pixel(value)}) 指定一个显式的像素下限或上限。每个用户选择的大小都保持为像素,以便指针、键盘、持久化和程序化行为保持可预测。

本规格保留了在未提供 containerRef 时 defaultSize: 'N%' 的已发布语义:在 window.innerWidth(或 1200px 服务端回退值)上解析一次,然后继续作为像素使用。提供 containerRef 仅改变百分比配置所使用的基础:容器的 content-box 活动轴替代视口。它不会创建持久化的相对尺寸模式。

数值输入为像素。已解析的公共输出仍为像素。在下面的实现和验证落地之前,随版本发布的源代码、测试和使用方文档仍然是当前行为的证据;草稿 component:Resizable 记录将随该实现一并更新。

非目标

  • 在本规格的拉取请求中实现运行时行为。
  • 在指针、键盘或程序化调整大小后保留百分比比例。
  • 自动分配剩余空间,或要求独立调整大小的区域总计达到 100%。
  • 支持任意 CSS 单位、函数、表达式或递归组合,包括 rem、vw、calc()、CSS min() 和 CSS max()。
  • 添加百分比吸附点或百分比折叠阈值。
  • 添加受控大小状态;当前的受控折叠行为不变。
  • 将 resize() 扩展到其已发布的数值像素输入之外。
  • 更改持久化状态形状或添加相对尺寸字段。
  • 扩展 SideNav 简化的 defaultWidth、minWidth 和 maxWidth 配置。该集成需要单独的组件决策,因为 SideNav 拥有其根节点和手柄。
  • 更改 LayoutPanel 对结构、滚动、内嵌或分隔线呈现的所有权。

需求

FR1 — 百分比配置使用明确的基础。

未提供 containerRef 时,defaultSize 中的百分比叶子节点 MUST 在 window.innerWidth 上解析一次;当 window 不可用时,使用 1200px,从而保留已发布的回退行为。提供 containerRef 时,它 MUST 针对该容器的第一个正值测量到的 content-box 活动轴解析一次。随后,结构化百分比 MUST 应用其单一的像素下限或上限。解析之后,所选大小即为像素,并且当视口或容器变化时 MUST NOT 缩放。

FR2 — 方向选择容器基础。

提供 containerRef 时,水平调整 MUST 使用容器的 content-box 内联尺寸,垂直调整 MUST 使用其 content-box 块尺寸。RTL 可以反转指针增量,但 MUST NOT 更改百分比基础。未提供 containerRef 时,无论方向如何,兼容性基础仍为 window.innerWidth。

FR3 — 交互保持基于像素。

数值默认值以及原子或结构化百分比默认值的每个结果都会解析为像素。指针、键盘、吸附、折叠、展开、持久化、回调和程序化调整路径 MUST 继续像已发布 API 一样精确地读写像素选择。任何交互都不得创建或保留百分比选择模式。

FR4 — 混合边界仍然有效。

构建者可以组合 defaultSize、minSize 和 maxSize 中的像素、原子百分比和结构化百分比值。数值边界保持为像素。百分比值与 FR1 一样针对相同的视口或容器基础解析;随后结构化值应用其一个像素下限或上限。当该基础变化时,百分比边界 MUST 重新解析。重新解析后的边界会钳制现有的像素选择;它们 MUST NOT 按比例缩放该选择。如果解析后的最小值超过解析后的最大值,开发环境 MUST 发出警告,并且最大值 MUST 生效,保留已发布的 Math.min(max, Math.max(min, size)) 顺序,同时保证有限且非 NaN 的几何值。

FR5 — 有效几何保持同步。

有效选中的像素大小、LayoutPanel 或调用方渲染的大小、持久化的展开值,以及 ResizeHandle 的 aria-valuenow、aria-valuemin 和 aria-valuemax MUST 描述相同的已解析几何。禁止仅通过 CSS 钳制,使 hook 状态留在绘制边界之外。现有的受控折叠回调仍是一个明确例外:它们报告被拒绝的折叠或展开意图,但不声称受控所有者更改了渲染大小。

FR6 — 基础变化仅更新百分比约束。

一旦原子或结构化百分比默认值初始化了选中的像素大小,视口或容器大小调整 MUST NOT 重新解析该默认值。百分比边界 MUST 重新解析,应用其可选的像素下限或上限,并钳制选中的像素大小。仅基础变化的布局更改 MUST NOT 触发交互回调,也不得以其他方式声称用户选择了新大小。

FR7 — 指针手势保留已发布行为。

指针增量继续从选中的像素大小计算。百分比边界在手势期间 MUST 使用一个稳定的基础;手势期间发生的基础变化在手势结束后才生效,以便手柄不会偏离指针。

FR8 — 键盘、吸附和折叠语义继续有效。

方向键步进、Shift+方向键步进、Home、End、折叠阈值和吸附点仍基于像素。折叠会保留展开时的像素大小,展开会根据当前已解析的边界恢复该像素大小。

FR9 — 持久化仅限像素。

现有的正普通数字和 {size, isCollapsed} 条目 MUST 继续作为像素选择恢复。旧版普通 0 MUST 保留其当前含义:在启用折叠时折叠且不保存展开大小,否则没有可用的已保存大小。新的百分比配置 MUST 使用当前持久化的像素形状;不会添加百分比或相对模式字段。

FR10 — 回调报告已解析的像素。

onSizeChange MUST 继续为用户交互和已发布的程序化转换接收已解析的像素数字。初始化、hydration 校正、视口大小调整、容器大小调整以及仅边界的重新钳制 MUST NOT 作为用户交互报告。

FR11 — 单区域和多区域配置共享该契约。

多区域调用 MUST 为所有区域使用一个可选的容器和轴。各区域仍独立地以像素为单位选择;此更改 MUST NOT 添加平衡、比例保持或总和 100% 的不变式。

FR12 — 无效配置具有安全的确定性回退。

可接受的配置是非负有限数字、精确的非负有限 Npx 字符串、从 0% 到 100% 的精确 N% 字符串,或结构化 percent() 值,其百分比是有限的且在 0–100 范围内,并且其一个 min 或 max 值是有限的非负 PixelWidth。一个结构化值如果没有任一边界、同时包含两个边界、包含其他判别字段或任何无效数字,则该值无效。无效的 defaultSize MUST 在正常边界钳制之前使用 250px;无效的 minSize MUST 使用 50px;无效的 maxSize MUST 使用无界 Infinity。显式的 maxSize: Infinity 仍然有效。开发环境 MUST 对每次回退发出警告;生产环境 MUST 使用相同回退但不发出警告。初始化之后,无效的原始值 MUST NOT 直接替换已持久化或以其他方式合法的已选像素大小;回退归一化后的边界只能通过正常钳制影响该大小。

公共 API 要求

  • API1 — containerRef 选择容器基准,而非相对模式。 单区域和多区域配置可以接受 containerRef?: React.RefObject<HTMLElement | null>。省略时,百分比配置使用已发布的视口(viewport)基准。提供时,每个百分比默认值或边界都使用该容器的 content-box 活动轴。该 ref 由调用方持有,因为只有调用方才能识别预期的布局容器;该 hook MUST NOT 推断 panel 或 ResizeHandle 的祖先。
  • API2 — 方向是显式的。 单区域配置可以接受 direction?: 'horizontal' | 'vertical',默认值为 horizontal。 多区域配置现有的顶层 direction 为每个区域提供其轴向。ResizeHandle 方向与 hook 方向 MUST 一致;实现 MUST 让开发环境中的不匹配可被检测到。只有当存在 containerRef 时,方向才会影响容器基准。
  • API3 — 一套显式的 Resizable 词汇涵盖像素和有界百分比。 添加服务端安全的辅助函数和类型:
type ResizablePercentSize = {
  type: 'percent';
  value: number;
} & ({min: PixelWidth; max?: never} | {min?: never; max: PixelWidth});

type ResizableSize =
  number | `${number}px` | `${number}%` | PixelWidth | ResizablePercentSize;

function percent(
  value: number,
  options: {min: PixelWidth; max?: never} | {min?: never; max: PixelWidth},
): ResizablePercentSize;

minSize 和 maxSize 使用 ResizableSize。defaultSize 保留已发布的宽泛 SizeValue,并新增 PixelWidth | ResizablePercentSize,从而在运行时验证依然具有权威性的同时,兼容所有现有的 number | string 调用方。复用 Table 中完全相同的 pixel() 绑定和 PixelWidth;不要创建第二个固定尺寸辅助函数。percent() 的 options 参数是必需的,并且必须恰好携带一个 min 或 max,其值必须是有效的 PixelWidth。无界百分比保留现有的规范 N% 拼写;percent(40) 刻意不作为 '40%' 的另一种拼写。数字、精确的 Npx 和 pixel(value) 仍为像素。精确的 N% 和 percent() 百分比是有限值,范围为 0–100。不要接受 proportional()(这是一种同类权重,不是字面百分比)、CSS 函数、算术表达式、变量、其他单位、同时出现 min 和 max,或完全没有边界。不要添加并行的百分比 props。

配置映射:

- `333` 或 `'333px'` → 保持不变;`pixel(333)` 是新组合式配置的规范结构化静态形式;
- `'40%'` → 保持不变,是规范的无界百分比;
- `max(40%, 333px)` 的意图 → `percent(40, {min: pixel(333)})`;
- `min(10%, 400px)` 的意图 → `percent(10, {max: pixel(400)})`。
  • API4 — 统一的边界是 0.6 中唯一的公共拼写形式。 minSize 和 maxSize 是完整的边界词汇表。已弃用的 minSizePx 和 maxSizePx 别名在 0.5 中受支持,在 0.6 中移除。数值型 minSize 和 maxSize 保留相同的像素语义,包括显式的 maxSize: Infinity。0.6 升级 codemod 会重写静态内联配置;动态组装的配置必须重命名这些键。
  • API5 — 解析后的输出和状态保持像素。 ResizableRegion.size、onSizeChange、内部 ResizableProps 几何信息以及持久化状态仍保持像素数值。现有的 width={region.size}、算术运算、持久化和 ARIA 调用点 MUST 继续通过类型检查并按原有行为运行。受控折叠(controlled-collapse)回调保留已发布的意图上报行为:当调用方拒绝所请求的状态变更时,即使回调报告了所请求的转换,渲染尺寸仍由调用方控制。
  • API6 — 编程式调整大小仍使用像素。 resize(size: number) 保留其已发布的签名,并选择一个经过钳制的像素尺寸。百分比字符串不受支持,MUST 仍然作为类型错误;运行时无效、负数或非有限值在开发环境中会发出警告,并且不会替换最后一个合法的像素选择。

无效配置行为

输入 可接受值 无效时的回退值 开发环境行为 生产环境行为
defaultSize 已发布的 SizeValue,加上 PixelWidth 或 ResizablePercentSize;结构化默认值只解析一次 250px,然后按正常边界钳制 发出警告并使用回退值 使用相同回退值但不警告
minSize ResizableSize;完全匹配的原子字符串;有效的 pixel(value) 或 percent(value, {min XOR max: PixelWidth}) 50px 发出警告并使用回退值 使用相同回退值但不警告
maxSize ResizableSize;完全匹配的原子字符串;有效的结构化值;显式的 Infinity 仍为无界 无界的 Infinity 发出警告并使用回退值 使用相同回退值但不警告
解析后的最小值大于解析后的最大值 两个值各自都有效 最大值生效 发出警告并使用已发布的钳制顺序 使用相同顺序但不警告

回退值修复配置;它不是新的用户选择。初始化之后,无效的原始值绝不会直接替换已持久化或以其他方式合法的已选像素状态。有效的回退边界只能通过正常钳制来影响该状态。

平台支持

  • 受支持的功能/引擎下限:Astryx Core 支持的每个浏览器都具备 ResizeObserver;对于所提供的容器,共享观察器仍是其唯一的运行时所有者。
  • 在所提供的容器获得正向测量值之前,依赖基线的配置 MAY 使用已发布的确定性 1200px 基线作为临时回退。首次有效测量会将依赖基线的默认值解析为其最终的初始像素尺寸,并解析百分比边界,而不会持久化或通告该临时回退。该初始选择完成后,仅用于默认值的观察器 MUST 被移除;已持久化的像素状态 MUST 跳过原本不会使用的默认测量。
  • 浏览器证据:真实 Chromium MUST 验证三种规范的结构化调用、宽/窄初始容器、后续基线变化、存储与 ARIA,以及未改变的视口兼容性与像素路径。仅靠 jsdom 几何测试桩并不足够。
  • SSR:在未提供 containerRef 时,原子型和结构化百分比默认值会保留已发布的 1200px 服务端基线与客户端初始化行为。在提供 containerRef 时,服务端使用相同的临时 1200px 基线,直到客户端完成首次测量。水合 MAY 做一次文档化的修正,但 MUST NOT 将该临时回退写入存储,也不得为该修正触发 onSizeChange。

当前状态影响

当前 main 分支交付完整的 AST-010 模型:defaultSize、minSize 和 maxSize 接受像素与百分比两种形式;containerRef 提供可选的 content-box 基线;百分比默认值只解析一次;在选中状态、绘制、持久化、回调和分隔条 ARIA 均保持为已解析像素的同时,百分比边界保持实时生效。无 ref 路径保留已发布的 window.innerWidth 基线和确定性 1200px 服务端回退。

在统一边界发布之前,仅支持像素的 API 无法表达百分比约束。单独应用 CSS 约束可能会使绘制与 hook 状态及 ResizeHandle ARIA 不一致。统一边界现在涵盖这两种形式。Astryx 0.6 移除了已废弃的纯像素键别名,同时保留 minSize 和 maxSize 下数值型像素行为。

已发布的契约仍分散在其当前的各个所有者之间:

  • architecture:public-component-api 拥有稳定的导出和组件契约形态;
  • spec:AST-017 — 发布兼容性与版本化系统规范 拥有分类、弃用/清理状态、Changesets 和迁移证据;本规范保留了确切的 Resizable 映射及其直接过渡要求;
  • family:layout-regions 将调整大小状态与交互委托给 useResizable 和 ResizeHandle,而 LayoutPanel 消费已解析的尺寸;
  • spec:AST-002 管理调用方拥有的容器基线和可预测状态;
  • 已发布的 Resizable 源码、测试、浏览器证据和消费者文档验证指针、键盘、折叠、吸附、持久化、手柄、SSR 和 ARIA 行为;以及
  • component:Resizable 记录组件特定的实现契约。

持久化表示

持久化表示不会改变:

interface PersistedResizableState {
  size: number | null;
  isCollapsed: boolean | null;
}

原子型或结构化百分比默认值在持久化之前会先被转换为像素选择。恢复时,已持久化的像素选择优先于 defaultSize,并被当前已解析的边界钳制。遗留的纯 0 仍然是折叠标记,且不包含展开尺寸,因此展开会回退到已配置的默认值;当折叠被禁用时,它不会提供任何可用的已保存尺寸。指针、键盘、折叠、展开和数值型编程式调整大小操作会继续持久化像素。基线变化永远不会写入百分比描述符或相对意图。

实现要求

  1. 对每个百分比默认值保留当前的无 ref 解析器:客户端使用 window.innerWidth,window 不可用时使用 1200px。
  2. 解析完整的原子型字符串,并验证完整的 percent() 描述符,包括其 XOR 边界形态。在钳制之前应用 FR12 的 250px/50px/Infinity 回退,且仅在开发环境中发出警告。保留显式的 maxSize: Infinity 作为有效的无界输入。
  3. 从 Resizable 导出 percent、ResizablePercentSize 和 ResizableSize;从服务端安全的 Resizable/utils 子路径暴露 percent、与 Table 相同的 pixel 绑定、PixelWidth 以及 Resizable 类型。
  4. 仅暴露 minSize 和 maxSize 作为边界。不要为已移除的像素别名保留运行时解析、冲突警告或源码类型。
  5. 当提供了 containerRef 时,在配置的轴上测量其 content box,并通过 Astryx 的共享 ResizeObserver 观察它。
  6. 将百分比默认值一次性解析为选中的像素状态。一旦该选择最终确定,就移除仅用于默认值的观察。仅当百分比边界的视口或容器基线发生变化时重新解析它们,应用其单一像素下限或上限,然后钳制选中的像素状态,使绘制、持久化和 ARIA 保持同步。
  7. 在新激活的百分比边界能够钳制之前,刷新过期的缓存基线;即使 resize() 在首次正向测量之前已选择了像素,也要移除仅用于默认值的观察。
  8. 当解析后的最小值超过其最大值时,保留已发布的“最大值优先”钳制顺序,在开发环境中发出警告,并且绝不产生 NaN 或无效几何。
  9. 保持指针、键盘、吸附、折叠、展开、回调、持久化和 resize(number) 行为基于像素。不要添加相对模式,也不要将 resize() 扩展为接受字符串。后续的无效配置不得替换已持久化或原本合法的选中状态。
  10. 保留本规范未显式更改的所有当前受控折叠和遗留持久化行为。
  11. 在单独的集成规范或兼容性决策授权扩展之前,保持 SideNav 的简化调整大小配置为纯像素。

验证

Contract 验证 代表性状态 变异或失败预期
FR1, API1 聚焦的 hook 测试加上 Chromium 几何测试 原子/结构化默认值;1200px 时无 ref;宽/窄初始容器;首次正值测量;后续 resize 默认值使用了错误基准,初始化后重新缩放,或提供的 ref 测量了错误的元素
FR2, API2 轴向测试和 Chromium 交互测试 水平/垂直;LTR/RTL;反向手柄;无 ref 垂直兼容性 垂直容器尺寸读取了宽度,或兼容性不再使用 innerWidth
FR3, FR6-FR8 交互和基准变化测试 交互前后的结构化默认值;视口/容器 resize;Arrow、Shift+Arrow、Home、End;折叠/展开 选中状态保持比例,基准变化重新缩放它,或现有像素交互发生变化
FR4 结构化下限/上限、混合边界和无效顺序测试 规范 percent(40, {min: pixel(333)}) / percent(10, {max: pixel(400)});混合单位;min 大于 max 描述符边界应用方向错误,边界使用不同基准,选择被缩放而非被钳制,或最大值不生效
FR5 Hook、LayoutPanel、持久化和 ResizeHandle 断言 低于/等于/高于最大值;基准收缩;受控折叠意图 实际绘制、状态、存储和 ARIA 不一致,或受控拒绝改变了自有状态
FR9 持久化兼容性测试 正数;旧版零值;旧版对象;结构化默认值;损坏条目 存储结构改变,描述符被持久化,未使用的默认值测量了基准,或旧状态语义改变
FR10, API5 回调测试 初始化;水合修正;仅基准重新钳制;指针/键盘/编程式更改 回调收到描述符,或报告非交互性布局修正
FR11 多区域和共享观察者测试 一个容器上的两个区域;另一个 hook 观察同一节点 区域使用不同基准,引入了选中比例,或一个订阅移除了另一个
FR12 生产/开发验证和状态保持测试 格式错误的字符串;缺失/同时存在描述符边界;无效百分比/像素;无效重新渲染;持久化选择;Infinity 回退因构建而异,生产环境出现警告,无效输入替换合法状态,或任何路径产生 NaN
API3, API4, API6 类型、导出、运行时验证和 codemod 测试 必需的 helper 选项;XOR 边界;服务端安全子路径;被移除的别名类型错误;resize('50%') percent(40) 或同时提供两个边界都能通过类型检查,被移除的别名仍通过类型检查,服务端导入获得客户端指令,或 resize 接受非像素输入
Platform/SSR 服务端渲染、水合测试和 Chromium 证据 无 ref;ref 未被测量;隐藏/零尺寸容器;首次正值测量;布局前 resize;后续边界激活 临时基准持久化,修正触发 onSizeChange,仅默认观察泄漏,或新激活的边界用过期缓存测量进行钳制
Compatibility 现有 Resizable、LayoutPanel、SideNav 和模板套件 当前纯像素调用点;无 ref 原子百分比默认值;已发布的宽泛 defaultSize 字符串 现有数字/原子百分比行为、宽泛默认类型、输出、交互或持久化发生变化

完成标准

交付的契约在以下情况下仍然得到满足:

  • 无 ref 的原子和结构化百分比默认值保留一次性 window.innerWidth 解析和 1200px SSR 回退,且不跟踪视口 resize;
  • 提供的容器结构化默认值针对第一个正值的 content-box 活动轴解析一次,在该选择后移除仅默认观察,并在基准变化和每条交互路径中保持为像素选择;
  • 原子和结构化百分比边界在两种基准模式下重新解析,应用其可选的像素下限或上限,并钳制现有像素状态而不按比例缩放;
  • percent() 在类型系统和运行时验证中都需要 options 参数,且恰好需要 min / max 之一,并携带有效的 PixelWidth;percent(40) 不是 '40%' 的别名;
  • Resizable/utils 保持服务端安全,重新导出 Table 的精确 pixel 绑定和 PixelWidth,并导出 percent 以及 Resizable 类型;根包解析一个 pixel 符号和一个 percent 符号,无冲突;
  • 指针、键盘、吸附、折叠、展开、持久化、回调和 resize(number) 保持已发布的像素语义;
  • minSizePx 和 maxSizePx 不再通过类型检查或接收运行时处理,且 0.6 升级 codemod 将静态内联配置重写为 minSize 和 maxSize;
  • 精确解析仅接受非负有限数字、完整的 Npx 字符串和 0–100 的 N% 字符串;描述符验证拒绝缺失/同时存在像素边界或无效数字字段。无效值使用文档记录的 250px、50px 或 Infinity 回退,而不替换已持久化/合法的选中状态,同时显式 maxSize: Infinity 仍然有效;
  • 反转的解析边界在开发环境中发出警告,确定性地选择最大值,并且绝不产生 NaN 或无效几何;
  • 混合边界保持有效状态、绘制、存储和分隔符 ARIA 一致,同时受控折叠回调保留已发布的意图报告;
  • 仅默认订阅即使在测量前的 resize() 之后也会终止,新激活的百分比边界在钳制前测量当前基准;
  • 单区域和多区域订阅与同一元素的所有其他观察者共存;
  • 聚焦的测试在旧实现上失败,在新实现上通过;
  • 真实 Chromium 在宽/窄基准、后续 resize、存储和 ARIA 中验证三个典型的结构化调用,以及未改变的兼容路径;并且
  • component:Resizable 和消费者文档在与实现相同的拉取请求中描述交付的契约。

决策日志

DEC-1 — 百分比配置像素状态;它们不会创建相对状态

参考: spec:AST-010/DEC-1 决策者: cixzhang,2026-08-31

保留已发布的 no-ref 百分比默认值:针对 window.innerWidth 解析一次,当 window 不可用时使用 1200px,然后按像素行为处理。可选的、由调用方拥有的 containerRef 会将百分比默认值和边界的基准改为容器的 content-box 活动轴。它不会使已选尺寸变成响应式。

所有用户交互、编程式 resize()、折叠/展开、回调和持久化仍然只使用像素。百分比边界可随其基准重新解析,并钳制该像素状态。这使 API 保持可预测,并使每个表示的状态在 spec:AST-002 下有效,同时避免引入第二种持久化尺寸模式。

已拒绝:在拖拽后保留百分比比例,或扩展 resize() 以接受百分比字符串。这两种做法都会改变已发布的基于像素的交互,并增加调用方并未要求的单位感知状态、持久化、回调和恢复语义。

DEC-2 — 初始尺寸与边界共用同一套配置词汇

参考: spec:AST-010/DEC-2 决策者: cixzhang,2026-08-31

新增 minSize 和 maxSize,其原子值与 defaultSize 及结构化 ResizablePercentSize 描述符相同。数字和精确 Npx 仍为像素;字符串也接受有限的 0–100 N%;Table 现有的 pixel(value) 是权威的结构化静态值;percent(value, {min: pixel(value)}) 添加一个像素下限,percent(value, {max: pixel(value)}) 添加一个像素上限。在初始尺寸和边界之间混合单位是有效的。这为构建者提供了一套可预测的词汇,无需并行的百分比 props 或重复的辅助函数。

minSizePx 和 maxSizePx 在 0.5 中仍是弃用的兼容别名。Astryx 0.6 在两个稳定版本之后移除它们;数字形式的 minSize 和 maxSize 保留其像素含义,astryx upgrade 会重写静态内联配置。动态组装的配置必须重命名这些键。

无效输入在每次构建中都使用确定性的、按角色区分的回退值:defaultSize 为 250px,minSize 为 50px,maxSize 为无界的 Infinity。开发模式还会额外发出警告。显式 maxSize: Infinity 仍然有效。如果解析后的最小值超过最大值,开发模式会发出警告,并且在已发布的钳制顺序中最大值优先。这些规则可防止格式错误的输入和颠倒的边界产生 NaN,也可防止它们替换已持久化/合法的所选状态。

DEC-3 — 有界百分比使用一个显式的结构化辅助函数

参考: spec:AST-010/DEC-3 决策者: cixzhang,2026-09-03

使用由 percent() 创建的 Table 风格可判别值(discriminated value),而不是用于 CSS 函数的 JavaScript 解析器。该描述符携带一个百分比,并恰好包含一个 min 或 max,其值为 Table 现有的 PixelWidth。它的 options 参数是必需的:现有的精确 N% 字符串仍是无界百分比的唯一写法。

pixel(333);
percent(40, {min: pixel(333)});
percent(10, {max: pixel(400)});

复用 Table 现有的 pixel() 绑定;不要创建另一个固定值辅助函数。不要复用 proportional():它表示同级列之间的相对权重,而不是针对某个被测量基准的字面百分比。这种固定形态将所有受支持的组合暴露给 TypeScript,在验证和解析时保持常数时间,并且不意味着任意的 CSS 组合。

已拒绝:递归 CSS min() / max() 字符串、可选的辅助选项、同时具有两个边界的描述符,以及单独的百分比 props。

DEC-4 — Astryx 0.6 移除已弃用的像素绑定别名

参考: spec:AST-010/DEC-4 决策者: cixzhang,2026-09-07

在 0.6 破坏性变更窗口(breaking window)中移除 minSizePx 和 maxSizePx。它们的替代项已经随两个稳定版本发布,数字形式的 minSize 和 maxSize 保留相同的像素行为,第一方调用方在移除变更中完成迁移,astryx upgrade 会重写内联配置。同时保留这两套词汇会继续保留类型联合、运行时解析、冲突警告、测试和文档,却不会新增任何能力。

已拒绝:无限期保留这些别名。它们明确只是临时的,并且统一的边界覆盖了所有受支持的像素场景以及百分比约束。

未决问题

无。更改已发布的 1200px 服务端回退值,或增加持久化的相对尺寸模式,都需要单独做出决策。

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