Astryx v0.5.0 版本详解：共享层关闭栈、Banner 新 API 与 30 个语言包

Astryx v0.5.0 版本详解共享层关闭栈、Banner 新 API 与 30 个语言包【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx v0.5.0 是自 0.4.0 以来八个版本更新的一次集大成发布它带来了两项破坏性变更Banner 折叠 API 重构、全局唯一的 Escape 层关闭机制、三组组件晋级Bottom Sheet、Stepper 进入astryxdesign/coreRichTextEditor 独立为astryxdesign/richtext以及国际化、主题继承、无障碍与 CLI 层面的大批能力升级。读完本文你将掌握 0.5.0 的迁移路径、共享层关闭栈的底层原理、主题extends继承机制以及所有新组件的实际用法。安装与版本策略所有稳定版astryxdesign/*包保持同一版本号因此升级时统一安装 0.5.0 即可npm i astryxdesign/core0.5.0需要注意canary-only 的包 ——lab、charts、richtext、vega—— 拥有自己独立的版本线不会与 core 同步发布。其中astryxdesign/richtext虽然拥有了独立包名但依然仅以canary标签发布并非稳定版本。升级前建议先预览迁移影响面。astryxCLI 提供了升级命令npx astryx upgrade --from your-version默认这是一次 dry run只读预览不会改动文件确认无误后加上--apply才会把改动写入磁盘。它同时负责执行 Banner 新 API 的 codemod 重写。破坏性变更一Banner 的折叠轴收敛为单个collapsibleprop旧版通过defaultIsExpanded控制 Banner 内容区默认展开状态。0.5.0 移除了该 prop并将整个折叠行为统一收敛到collapsible这一个 prop 上——这一约定与SideNav.collapsible保持一致对应 Banner 源码 中collapsible?: boolean | CollapsibleConfig的类型定义。// status 和 title 在每个 Banner 上都是必填的 Banner statuserror titleCheck 3 fields…/Banner // 不变默认收起 Banner statuserror titleCheck 3 fields collapsible{false}…/Banner // 永远展开无切换按钮 Banner statuserror titleCheck 3 fields collapsible{{defaultIsOpen: true}}…/Banner // 取代 defaultIsExpanded Banner statuserror titleCheck 3 fields collapsible{{isOpen, onOpenChange}}…/Banner // 完全受控四种形态覆盖了全部折叠场景省略或传true可折叠默认收起与旧行为一致false内容完全退出折叠体系始终可见、没有切换按钮也没有aria-expanded内容区域保持挂载——这正是大多数 Banner 最需要的形态{defaultIsOpen: true}可折叠且默认展开用于替换旧的defaultIsExpanded{isOpen, onOpenChange}由消费方完全受控。从源码看Banner 的折叠不再由本地useState驱动而是复用共享的useCollapsiblehook见 useCollapsible.ts因此它的 disclosure 行为与Collapsible组件完全一致。唯一的默认差异是 Banner 默认收起而非 hook 默认展开因为 Banner 的信息主体在头部内容只是补充源码注释。迁移提醒codemod 会重写每一个具名使用该 prop 的调用点但它看不到展开运算符...props——TypeScript 也不会对 spread 做多余属性检查。因此 codemod 跑完后请手动 grepdefaultIsExpanded并把Banner {...props} /这类调用点手工迁移。破坏性变更二一次 Escape 只关闭一个层这是 0.5.0 最重要的架构变更。旧实现中每个浮层各自挂载自己的 Escape 监听器导致一次按键可能同时关掉 Popover 和承载它的 Dialog。0.5.0 之后所有浮层共享一个统一的关闭栈每次 Escape 按键只会路由到最顶层的那个层对应 layerStack.ts。Dialog 内部的 Tooltip 现在按 Escape 只关闭 Tooltip。“最顶层”来自 React 树嵌套关系而非 DOM所以即使层通过 portal 渲染判定依然正确。层的登记与行为声明层通过useLayerDismissalhook 接入共享栈见 useLayerDismissal.ts。hook 的核心参数isActive层当前是否参与通常就是层的 open 状态DOM 状态比 open 状态滞后一帧的层应全程传true并用isPresent在按键发生时回答是否真的在屏上onDismiss栈判定该层应该响应 Escape 时调用escapeBehavior: block时不会调用escapeBehaviorclose默认关闭该层并消费按键或block吞掉按键但不关闭——用于必须显式选择的Dialog purposerequiredEscape 既不能关掉它也不能漏到它后面的层getContainer可选层无法用LayerDepthProvider包裹内容如裸useFocusTrap不渲染任何东西时从 DOM 恢复嵌套关系isPresent可选按键时层是否真的在屏上isEnabled默认true传false表示层对关闭完全不可见按键会像它不存在一样流向下面的层Dialog的内联渲染模式就是这种情形。它与block刻意区分block是“在场但吞掉按键”isEnabled: false是“根本不在场”。单一监听器如何裁决layerStack在整个document上只挂一个keydown监听器bubble 阶段按键由栈本身路由给最顶层已登记的层。排序有三把键各司其职compareEntries嵌套深度从 React 树LayerDepthContext取得而非 DOM——context 会穿透 portal且在渲染期就可知能正确处理“同一提交内内外层同时挂载”这一 React 子 effect 先于父 effect 执行的坑DOM 包含关系裸 focus trap 无法提供深度 provider 时用 DOM 包含关系恢复嵌套信号登记顺序无关层之间后登记的在上与浏览器原生 top layer 的堆叠一致。值得注意的是模态性刻意不作为排序键——模态内显示的 hover 提示渲染在其上若模态优先会把按键交给对话框而困住提示嵌套关系已经覆盖了模态想表达的场景。你必须知道的按键语义变化栈处理按键时调用preventDefault()抑制浏览器自身的 close-watcher 行为包括dialog的cancel与popoverauto轻关闭但保留事件传播。因此如果你自己在window上监听keydown现在会看到原本会被焦点陷阱层拦截的 Escape——且其defaultPrevented已经是trueIME 合成期间的 Escape 不是关闭合成中文、日文、韩文输入时按 Escape 是取消候选词不是关层。栈会照样“认领”这次按键防止浏览器据此触发 close request 反而把层关掉但不执行任何关闭动作layerStack.ts浏览器主动发起的关闭请求——Android 返回手势、平台 close watcher——由宿主层通过useLayerDismissal返回的shouldDismissOnCloseRequest()裁决同样遵循最顶层规则并在 IME 合成期间拒绝关闭因为这类事件不带组合状态任何cancelhandler 都无法自行判断。当前已接入共享栈的层包括Dialog及其构建物、Popover 与其菜单体系、Tooltip、HoverCard、Lightbox、MobileNav、BottomSheetSwitcher。从源码注释可见BottomSheet、CommandPalette、ContextMenu、DropdownMenuSubMenu、PowerSearchEditPopover和 lab 的Drawer仍运行自己的 Escape 监听器它们靠“元素级认领按键”与栈共存栈会在已defaultPrevented的按键前退让——但在这类宿主内部打开的已登记层收不到按键会被宿主抢先关掉后续版本会陆续迁移。这次没有 codemod因为没有任何 prop 移动。一并移除的内容UMD bundle 被移除dist/astryx.umd.js以及unpkg、jsdelivr两个 package 字段都不再存在。原因很直接——UMD 绑定window.React而 React 19 没有提供定义它的构建产物因此根本不存在可迁移的可用配置。替代方案是astryx template --cdn它会生成基于 import-map 的无构建步骤页面三个废弃页面模板被删除table-page-chart、table-page-heatmap-status、table-page-shoe-store-heatmap。三组组件晋级晋级promotion意味着组件脱离实验性的lab包进入可以正式依赖的包中。它必然改变导入路径因此是每次发布中最需要关注的环节。Bottom Sheet → corev0.4.4BottomSheet与BottomSheetSwitcher现在从astryxdesign/core导入。核心新能力是snapPoints——让“拖拽停靠点”完全由宿主决定支持三种写法视口比例0.5停靠在视口一半处百分比50%绝对长度320px。同时修复了一组移动端体验问题内容滚到底后继续上拉会持续拉动并顺势展开面板而不是戛然停止停靠在某个 detent 上的面板在窗口缩放或设备旋转时会重新解析自身几何移动端软键盘弹出不再顶动页面、也不会把 detent 从面板下方挤走。Stepper → core本次发布Stepper与Step现在从astryxdesign/core导入带来完整的能力矩阵横向/纵向两种布局、separated分离式与 on-track轨道内嵌两种指示器形态、语义化的状态完成/当前/待办、密度调节以及非线性导航允许直接跳步。动效细节值得一提前进一步会动画化连接线——强调色填充从该段的前缘生长出来于是前进在视觉上读作“进度正在沿轨道行进”。回退、跨多步跳转、中途挂载进入流程、以及prefers-reduced-motion系统减弱动态效果这四种情形都做了正确处理可同时叠加生效。RichTextEditor →astryxdesign/richtextv0.4.1基于 Lexical 的编辑器从lab迁出成为独立包从而可以单独进行 canary 测试。请注意这不是一次稳定化——astryxdesign/richtext与lab一样仅以canary标签发布。对你而言实际的变化是导入路径RichTextEditor、RichTextView、RichTextEditorToolbar现在都从astryxdesign/richtext导入。亮点一30 个语言包日期跟随你的 ProviderCore 最初只带en与fr-FR两个语言包0.5.0 已扩充至30 个 locale 目录仓库中的实际目录见 packages/core/locales包含af-ZA、ar-SA、ca-ES、cs-CZ、da-DK、de-DE、el-GR、es-ES、fi-FI等。关键变化DateInput、DateTimeInput、DateRangeInput、Calendar的格式化与解析改走环境中的InternationalizationProviderlocale不再依赖浏览器 localeCalendar 的星期表头改用 CLDR 的 stand-alone-short独立短形式名称Selector、MultiSelector、Typeahead、FileInput、Tokenizer、Lightbox 的live-region 无障碍播报改从语言包取值并使用ICU plurals处理复数取代了过去在英文后机械追加 s 的做法新增useLocale与useCollator两个导出让业务代码用同一个 locale 做格式化与字符串比较。CJK 输入安全中文、日文、韩文CJK输入得到了专门保障Selector、MultiSelector、Typeahead、DateInput、DateTimeInput、TimeInput、NumberInput都会等待 IME 合成结束后才把 keydown 当作命令处理。于是提交候选词的 Enter不会再连带提交整个字段取消合成的 Escape不会关闭任何浮层与共享关闭栈的 IME 逻辑同源。亮点二主题现在通过extends真正继承过去用extends构建的主题只会输出自己的声明导致继承链上的每个消费方拿到的都是“默认几何 新调色板”的错配样式。0.5.0 中基础主题会解析进子主题的输出子主题的最终结果是一个扁平结构携带完整的继承内容——astryx theme build因此能产出一份自包含的样式表无需再额外加载基础主题的 CSS见 defineTheme.ts 对extends的文档注释defineTheme对非法的extends直接抛错而不是默默继承到空值过去命名导入解析到错误模块时extends值为undefined主题会构建出一份看似合理、实则丢失全部继承内容的样式表。现在defineTheme会拒绝非主题对象并给出可读的错误信息defineTheme.ts图标icons与指示器indicators按名合并子主题替换一个不会丢掉基础主题替换过的其他项。焦点环也成为一等 token--focus-outline-width、--focus-outline-style、--focus-outline-color、--focus-outline-offset四个 token 驱动 core 与 lab 中每一个焦点环一处覆盖即可全系统重设焦点样式。color.accent支持[light, dark]元组亮色方案从第一个种子、暗色方案从第二个种子各派生一套完整色板底层经 HCT 感知色彩模型生成元组在主题创建时转换为 CSSlight-dark()。当元组生效时--color-on-accent也会按各自方案分别烘焙对比度计算是 CSS 无法表达的因此显式覆盖tokens[--color-accent]时反而需要连--color-on-accent一起覆盖而元组方案可以整体重定位。亮点三键盘、指针与触控这一批改动全部围绕无障碍与输入体验TabList在显式声明roletablist时遵循 WAI-ARIA tabs 模式比标签更窄的 strip 会滚动而不是溢出容器——每个 tab 始终是 tab不会藏进菜单里ButtonGroup收敛为单一 Tab 停靠点成员间用方向键移动Breadcrumbs用半粗字重标记当前面包屑而非仅靠颜色——这是 WCAG 1.4.1颜色不作唯一信息载体的要求旧版仅靠色调的写法不满足core 与 lab 中被禁用的元素不再绘制 hover 状态、不再显示交互光标粗指针设备上Slider 轨道、sm尺寸的复选框/单选/开关、共享清除按钮的可点击区域全部达到WCAG 2.5.8 AA 的 24×24px 最小点击目标——只扩大可点区域可见外观没有移动。亮点四更多可构建的部件FormLayout新增defaultOptionality表单只需标注例外项默认可选只标记必填DateRangeInput新增minRangeSpan与maxRangeSpan约束可选的日期区间跨度DateTimeInput新增timeOptionInterval提供预设时间下拉MultiSelector整个触发器行的格式现在通过formatValue统一完成Table插件现在可以抑制某个 body 单元格的内容AspectRatio把ratio作为类级声明输出因此可以按断点覆盖PowerSearch 可浏览的字段数从 10 提升到1,000按每个字段的group分组menuWidth同时作用于字段菜单与搜索菜单值类型 typeahead 也遵循maxOperatorMenuItemsMarkdown 解析器安全性升级拒绝javascript:、vbscript:与data:text/html形式的 URL增量解析在开着的代码围栏上保持已稳定的块——在流式渲染 500 段的响应时需要重建的块从126,756 降到 1,869。CLI 更新CLI 新增了一组主题与模板能力astryx theme targets列出每个组件的全部主题化目标——它的defineTheme键、它着色的类、它接受的 props 与状态--json输出可直接喂给 lint 与审计脚本astryx theme template写出一个带注释的空白主题作为自定义主题的起点astryx theme build单次进程可接受任意数量的主题文件astryx template --cdn写出一个无构建步骤的页面并固定在你安装的版本上同时是 UMD bundle 移除后的替代方案模板集新增五个仪表盘页面模板集成方可贡献参考文档主题astryx docs会提供、astryx search会索引这些主题。总结Astryx v0.5.0 的迁移核心是三件事把 Banner 折叠调用点改写为collapsible并留意 spread 调用、理解共享层关闭栈带来的 Escape 语义变化尤其自建window监听与 IME 场景、以及跟随三组组件的导入路径变化。之后30 个语言包、真正的extends主题继承、焦点环 token 与大批键盘/触控无障碍修复都是可以直接落地的能力。完整的组件文档与主题文档可分别通过astryx docs与astryx search查阅。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考