Chakra UI/Zag 项目迁移指南：从 v0 到 v1 的全面升级

前言

Chakra UI/Zag 作为一个跨框架的组件库，经过多年的迭代和优化，终于迎来了 v1 版本的重大更新。本次升级聚焦于性能优化和包体积缩减两大核心目标，通过采用各框架原生的响应式机制，实现了显著的性能提升。

升级概览

性能提升亮点

• 渲染性能：组件渲染速度提升 1.5-4 倍
• 包体积：核心包体积缩减 98%，从 13.78KB 降至 1.52KB
• API 简化：统一了组件控制逻辑，降低了使用复杂度

主要变更点

1. useMachine API 重构

旧版用法：

const [state, send] = useMachine(avatar.machine({ id: useId() }))

新版用法：

const service = useMachine(avatar.machine, { id: useId() })

关键变化：

• 不再返回 [state, send] 元组，而是返回 service 对象
• machine 现在是直接传递的对象而非函数

类型提示： 对于泛型组件（如 Combobox），需进行类型断言：

useMachine(combobox.machine as combobox.Machine<Item>)

2. 受控/非受控模式统一

值控制

旧版：

useMachine(numberInput.machine({ value: "10" }), {
  context: { value: "10" }
})

新版：

useMachine(numberInput.machine, {
  defaultValue: "10",  // 默认值
  value: "10"         // 受控值
})

展开状态控制

旧版：

useMachine(dialog.machine({ open: true }), {
  context: { open: true, "open.controlled": true }
})

新版：

useMachine(dialog.machine, {
  defaultOpen: true,  // 默认状态
  open: true         // 受控状态
})

3. 类型定义变更

<component>.Context 重命名为 <component>.Props

4. Toast 组件重构

新版采用 store 模式管理 toast 状态：

const toaster = toast.createStore({ /* 配置 */ })
const service = useMachine(toast.group.machine, { store: toaster })

// 使用 store 管理 toast
toaster.create({ title: "Hello", description: "World" })

性能对比数据

我们通过 10,000 个组件实例的压测，得到了以下性能提升数据：

组件	挂载时间提升	更新时间提升
Avatar	27%	99%
Accordion	61%	-
Dialog	80%	-
Tooltip	82%	-
Tabs	6%	-

重大修复

1. Menu：修复右键菜单二次点击位置不更新问题
2. Avatar：修复 api.setSrc 失效问题
3. File Upload：修复目录模式下拖拽失效问题
4. Carousel：
   • 修复初始页不生效问题
   • 修复分页指示器同步问题

移除的 API

1. 通用移除：

   • 移除 useActor，统一使用 useMachine
   • 移除 open.controlled 属性

2. 分页组件：

   • 移除 api.setCount，改用 count 属性

3. 选择类组件：

   • 移除 api.setCollection，改用 collection 属性

开发者注意事项

1. 内部变更：

   • activities 重命名为 effects
   • prop、context 和 refs 现在需要显式传递给机器
   • watch 语法有重大变更，类似 React 的 useEffect

2. 核心机制：

   • createMachine 现在只是标识函数，实际逻辑转移到框架的 useMachine 钩子中

升级建议

1. 对于大型项目，建议分组件逐步迁移
2. 使用全局搜索替换工具批量修改 useMachine 调用方式
3. 特别注意 Toast 组件的 store 模式变更
4. 对于性能敏感场景，建议重新测试关键路径

本次升级虽然带来了破坏性变更，但通过统一的 API 设计和显著的性能提升，将为开发者带来更好的开发体验和更优的运行时性能。