Astryx 主题 target 废弃迁移指南规范命名优先、运行时别名兼容与astryx upgrade --apply前向迁移【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx本文围绕 Astryx 设计系统主题系统中的「组件 theming target」命名治理展开当维护的主题与新示例全面改用规范 target 名称如popover、code-block时系统如何通过组件文档中的deprecatedFor标注、astryx theme targets发现标记、astryx theme build精确替换警告以及astryx upgrade --apply的 bare selector 迁移在保留已发布主题的运行时兼容性的同时为 0.7.0 的移除窗口铺平道路。读完本文你将理解 Astryx 主题 target 的规范命名约定、废弃别名的生命周期管理机制以及如何安全地把旧主题迁移到新的规范名称。一、背景什么是组件 theming target在 Astryx 中主题作者通过defineTheme()的components字段为组件定制样式。每个可被主题定制的组件表面称为一个theming target其键key是组件实际渲染的稳定类名去掉astryx-前缀后的名称。例如组件渲染astryx-button主题里就写button这个 target 键。这套 target 的唯一枚举源位于 packages/cli/foundation/discovery/theming-targets.mjs。该文件明确说明所有 theming target 均由 core 组件目录下的.doc.mjs组件文档中的theming.targets条目声明再扁平化为主题作者在defineTheme中使用的组件键。它不是一个独立的第二注册表因此主题作者能枚举的列表与编译器接受的集合不会彼此漂移——这是本机制可信的前提。collectThemingTargets(coreSrc, options)扫描 core 的src目录跳过node_modules与__tests__逐个读取.doc.mjs并为每个 target 记录keydefineTheme的组件键类名去掉astryx-前缀className组件渲染的稳定类名component声明该 target 的组件propstarget 反映的视觉属性variant:value形式statestarget 反映的运行时状态裸名称形式deprecatedFor可选废弃 target 的规范替换键。二、规范命名约定与废弃别名本次变更的核心是命名规范化维护的主题与新示例全面改用规范组件 target 名称。仓库源码中可以看到两类典型的历史命名问题及其规范形式废弃 target 键规范替换键出处checkboxcheckbox-indicatorCheckboxInput.doc.mjscodeblockcode-blockCodeBlock.doc.mjshovercardhover-cardHoverCard.doc.mjsnaviconnav-iconNavIcon.doc.mjspopover-surfacepopoverPopover.doc.mjsdate-input-clear-iconinput-clear-iconDateInput.doc.mjs可见历史命名问题主要有两类无连字符粘连词codeblock、hovercard、navicon与冗余后缀别名popover-surface之于popover。规范命名统一采用连字符分词kebab-case并消除无独立所有权语义的别名 target。以 Popover 为例Popover.spec.md 对废弃兼容 target 的语义给出了权威解释popover-surface是popover在同一个绘制表面上的废弃别名它不属于组件解剖结构anatomy也没有独立的概念所有权。组件文档保留deprecatedFor: popover发现机制用该精确替换标记别名而运行时继续同时输出两个名称以支持既有主题。文档同时明确废弃不意味着或要求移除——已有popover-surface主题继续受支持只是维护的主题、模板和可复制的示例应使用popover。三、deprecatedFor的发现与标记废弃标注从组件文档出发经过三层处理1. 组件文档声明。组件doc.mjs的theming.targets条目中以deprecatedFor字段声明规范替换例如theming: { targets: [ {className: astryx-checkbox, visualProps: [size], states: [checked, disabled], deprecatedFor: checkbox-indicator}, ], },2. 发现机制收集。collectThemingTargets在 theming-targets.mjs 中将deprecatedFor并入 target 行当调用方传入{includeDeprecated: false}时如所有权检查场景带deprecatedFor的 target 会被跳过。发现结果默认保留全部条目以维持 CLI 完整列表。3. 验证注册表。targetValidationRegistry(targets)从同一批 target 行构建组件验证注册表返回{propsByKey, deprecatedByKey}两个映射propsByKey同时容纳 props 与 states 键两者都是合法 override 键deprecatedByKey记录废弃键 → 规范替换键。该函数还内置冲突保护若同一废弃键被两个不同组件声明了不同的替换目标会直接抛出Deprecated theme target X has conflicting replacements: ...错误杜绝模糊迁移。四、astryx theme targets发现列表中的废弃标记主题作者可通过astryx theme targets命令枚举全部 theming target相关命令文档见 theme-targets.doc.mjs。该命令与theme build共享同一发现模块——两者都读取组件文档这一唯一事实来源因此主题作者能枚举的集合与编译器接受的集合不会漂移。典型用法# 查看整个可主题化表面 astryx theme targets # 查看单个组件的 target astryx theme targets Switch # 搜索包含某关键词的 target astryx theme targets thumb # 供 lint 或审计脚本使用结构化输出 astryx --json theme targets由于发现机制默认includeDeprecated: true列表会完整保留废弃 target 及其deprecatedFor替换信息帮助主题作者在编写新代码时避开旧名称。五、astryx theme build精确替换警告theme build是废弃 target 的第二道防线。在 build.mjs 中loadKnownComponents()从 core 组件文档构建验证注册表文档不可用时返回null验证静默跳过绝不猜测第二注册表validateComponentOverridesAgainstRegistry随后遍历主题的所有组件层——base、onDark/onLight表面层以及每条 adaptation rule——对每个组件键做三重检查未知组件给出最多 3 个编辑距离 ≤ 2 的相似键建议Did you mean: ...?废弃 target命中deprecatedByKey时输出精确警告Deprecated component target popover-surface in onDark. Use popover instead.未知 prop/state列出该 target 已知的 props/states或提示该组件没有变体属性。每条警告按层定位in onDark、in adaptation rule 2等使作者能精确定位需要修改的代码位置。这套验证对 rootcomponents与 adaptation rules 一视同仁见themedComponentEntries对规则层components的展开保证条件主题同样被覆盖。六、运行时保留与 0.7.0 移除窗口兼容策略的关键在「发现与构建推进新名运行时保留旧名」已发布的 bare prop/state selector 类在 0.7.0 移除窗口之前继续存在已发布主题不会被破坏运行时继续同时输出废弃类名与规范类名如 Popover 同时保留popover与popover-surface两个名称确保既有主题的样式选择器仍然命中维护的主题与模板theme-neutral、theme-butter、theme-stone等随本次变更同步 patch全面改用规范名称成为新代码的参照。这形成了双轨制旧主题零改动即可继续运行新主题从一开始就用规范命名废弃名称只在窗口期结束后按计划移除。七、astryx upgrade --apply前向兼容迁移对存量主题astryx upgrade提供了从旧命名到新命名的前向迁移能力。命令入口在 upgrade.mjs其标准用法为# 先升级/安装 Astryx 相关包再执行 astryx upgrade --from old-version --path source-dir --apply--from指定迁移的旧版本基线--path指向待迁移源码目录--apply实际写入迁移结果不带--apply时仅预览。命令支持--json结构化输出含migration类型的结果集便于 CI 脚本与 Agent 集成。针对本次核心主题——Core bare selector-class 移除——upgrade --apply内置了保守的迁移 transform。依据 CHANGELOG.md 的记载该 transform解析.css选择器语法将精确的旧版本 target/value 组合改写为行为保持的「旧类 data 属性」并集old-class/data-attribute unions覆盖旧版本可能发射的无界unbounded值对无法确认归属的消费者自定义类保持原样、不做改写。这种保守策略保证了迁移的「行为保持」特性只改写能精确识别为框架发射内容的组合未知类一律不动避免迁移工具本身引入回归。八、主题作者实操清单综合上述机制主题作者面对本次变更有三条明确的实践路径新主题 / 新示例一律使用规范 target 名称code-block、hover-card、nav-icon、popover、checkbox-indicator、input-clear-icon等可借助astryx theme targets核对当前规范列表存量主题无需立即改动theme build会输出精确替换警告按警告逐条将废弃键替换为规范键即可消除告警同时保持运行时行为不变大规模存量代码升级 Astryx 包后运行astryx upgrade --from old-version --path source-dir --apply借助 bare selector 迁移 transform 批量完成前向兼容改写再以theme build的警告输出与--check模式验证结果。九、设计要点总结从源码结构可以提炼出这套废弃治理机制的四个设计原则单一事实来源target 的合法集合、props/states、废弃替换关系全部来自组件文档.doc.mjs发现机制与构建验证共享同一数据源theming-targets.mjs不存在第二注册表导致的两处漂移精确而非猜测无论是构建警告逐条给出规范替换名、未知键的相似建议还是迁移 transform 的精确匹配改写都避免模糊处理如冲突替换直接抛错兼容与推进并存运行时保留旧类名与数据属性已发布主题在整个移除窗口期不受影响维护的主题与新示例则率先示范规范命名工具链闭环发现标记theme targets→ 构建告警theme build→ 自动迁移upgrade --apply→ CI 校验theme build --check形成完整的升级闭环让主题生态可以有序收敛到规范命名最终安全抵达 0.7.0 移除节点。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考