前端UI组件【免费下载链接】zagBuild your design system in React, Solid, Vue, Svelte or Vanilla. Powered by finite state machines项目地址https://gitcode.com/gh_mirrors/za/zag点击查看免费下载导读本文以zag-js/cascade-select的 CHANGELOG.md 为骨架系统梳理这一基于有限状态机实现的分级联级下拉组件cascading dropdown从 1.34.0 首次发布到 1.46.0 的演进脉络。通过将变更日志与 状态机实现、连接层 API、类型定义 及 e2e 测试 相互印证你将掌握该组件 API 修复、交互细节与各依赖包升级背后的具体原理并了解如何在 React、Solid、Vue、Svelte 或 Vanilla 项目中安全升级与规避回归。一、组件定位用状态机驱动的级联选择器zag-js/cascade-select是 zag 仓库中专门实现 cascade select级联下拉 / 级联选择器的独立包其 README 明确将它描述为 a comprehensive state machine for building cascade select (cascading dropdowns) components with hierarchical data navigation。它通过 cascade-select.machine.ts 中的createMachineCascadeSelectSchema()定义了一套有限状态机核心状态只有三个idle闲置、focused触发按钮获得焦点、open下拉展开并在 cascade-select.types.ts 中通过CascadeSelectSchema声明了状态、props、context、computed、action、effect、guard 与 event 的完整结构。从源码结构看该包还包含一套完整的部件解剖anatomy体系。在 cascade-select.anatomy.ts 中createAnatomy(cascade-select).parts(...)声明了 root、label、control、trigger、indicator、valueText、clearTrigger、positioner、content、list、item、itemText、itemIndicator 共 13 个部件对应 shared/src/css/cascade-select.css 中形如[data-scopecascade-select][data-partitem]的样式选择器体系。CHANGELOG 表明该包与zag-js/anatomy、zag-js/core、zag-js/types、zag-js/collection、zag-js/utils、zag-js/dom-query、zag-js/popper、zag-js/rect-utils、zag-js/dismissable、zag-js/focus-visible十个依赖包同步版本迭代本文以其中的非依赖升级类实质性变更为主线。二、初始发布1.34.0Cascade Select 状态机的诞生在 1.34.0 之前zag 中并无级联选择器。CHANGELOG 记录该版本对应 PR #2945是Cascade Select 状态机的初始发布由 anubra266 贡献。这也是 1.34.0 中唯一标注为Minor Changes的条目而同期其他变更均为 Patch。从当前源码回看初始设计可以发现该状态机的几个核心机制从首版就已确立三态模型idle → focused → open的迁移在 cascade-select.machine.ts 中完整保留idle与focused都带closed标签open状态则带open标签并挂载trackDismissableElement、trackFocusVisible、computePlacement、scrollToHighlightedItems四个 effect。树形数据集合cascade-select.collection.ts 提供collectionT(options)工厂底层直接复用zag-js/collection的TreeCollection当未传入数据时使用 collection.empty 的空集合兜底。路径即值模型value的类型是string[][]一组完整路径如[[africa,algeria,adrar]]highlightedValue是string[]当前高亮路径这在 cascade-select.types.ts 的ValueChangeDetails/HighlightChangeDetails中体现回调同时上报value/items与highlightedValue/highlightedItems。同一 PR 还顺带修复了一批 API 不一致问题Patch 部分为后续迭代奠定了 API 形态。三、API 一致性修复1.34.0 PatchElementIds 与回调命名对齐初始发布的同一版本中另一条 Patch 变更专门修复 API 不一致commitf64e81f共三处逐条对照源码解读如下ElementIds中list参数类型修正number → string在 cascade-select.types.ts 中list与item的签名现在都是((valuePath: string) string) | undefined即根据值路径如asia,india生成对应列表/条目的 DOM id。底层 cascade-select.dom.ts 的getListId/getItemId也接受字符串值路径默认生成cascade-select:${id}:list:${value}与cascade-select:${id}:item:${value}。highlightedItem更名为highlightedItemsAPI 与 context 中统一使用复数形式与HighlightChangeDetails回调的highlightedItems: T[]字段保持一致。当前 connect.ts 与 types.ts 均导出highlightedItems高亮路径上各级节点数组。shouldCloseOnSelectHighlightedguard 修复原先在判断是否关闭时把整个路径数组传给了isBranchNode现改为取路径最后一个节点再判断即只对叶节点才允许closeOnSelect生效。对应实现见 cascade-select.machine.tsconst node last(items); return prop(closeOnSelect) node ! null !collection.isBranchNode(node)。这三处修复说明首版级联选择器在值路径value path与索引路径index path两类路径概念上做了明确区分——前者以节点 value 组成用于 id 生成与回调后者以数组下标组成用于树内定位见IndexPath理解这一点是正确使用 API 的前提。四、交互与行为修复1.41.0 1.44.01.42.0 之前多为依赖升级从 1.41.0 起陆续出现与本组件交互行为直接相关的修复。4.1 新增>赞分享前端UI组件【免费下载链接】zagBuild your design system in React, Solid, Vue, Svelte or Vanilla. Powered by finite state machines项目地址https://gitcode.com/gh_mirrors/za/zag点击查看免费下载相关推荐zag 中 zag-js/select 的版本演进全解状态机 Select 组件从 0.1.0 到 1.46.0 的 API 变迁与实现要点zag 中 zag js/select 的版本演进全解状态机 Select 组件从 0.1.0 到 1.46.0 的 API 变迁与实现要点 本文基于 pa前端UI组件zag-js/menu 状态机深度解读从 CHANGELOG 看 Zag 菜单组件的演进与实现原理zag js/menu 状态机深度解读从 CHANGELOG 看 Zag 菜单组件的演进与实现原理 zag js/menu 是 Zag 生态中基于有限状态前端UI组件Zag.js Cascade Select 状态机全解析构建支持无限层级数据的级联下拉组件Zag.js Cascade Select 状态机全解析构建支持无限层级数据的级联下拉组件 导读 zag js/cascade select 是 Zag 项前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
