Medusa UI 设计系统演进全解析medusajs/ui 从 1.0.0 到 4.2.3 的组件库变更路线图【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusamedusajs/ui是 Medusa 开源商业平台的官方 React 组件库为 Medusa Admin 仪表盘提供全部界面基础。本文以 packages/design-system/ui/CHANGELOG.md 为骨架结合仓库内组件源码完整梳理该设计系统从 1.0.0 首发到 4.2.3 的演进历程你能借此掌握其包结构与依赖栈、历次破坏性变更的迁移要点、Toast 体系的重构逻辑以及 DataTable、OtpInput 等核心组件的真实用法与底层实现为在 Medusa 生态中开发管理界面或自建组件库提供可直接落地的参考。设计系统三件套ui、icons 与 ui-presetv1.0.0 是 Medusa UI 设计系统的正式首发版本见 CHANGELOG.md 686-695 行它一次发布了三个相互配套的 npm 包包名职责medusajs/uiReact 组件、hooks 与工具函数集合medusajs/iconsReact 图标集medusajs/ui-preset包含 Medusa UI 设计令牌design tokens的 Tailwind CSS 预设三者分工明确组件消费图标与设计令牌令牌决定颜色、阴影、间距、字体等视觉变量图标提供统一风格的图形资产。这一组件 图标 样式预设的三层架构沿用至今在 package.json 中可以看到medusajs/ui当前将medusajs/icons列为直接依赖版本 2.20.1并将medusajs/ui-preset用于开发与样式构建。从源码目录看UI 包共分四层components46 个基础组件目录alert、button、checkbox、select、tooltip 等对应 src/componentsblocks复合业务区块目前仅有>import { toast } from medusajs/ui // 成功通知 toast.success(订单已创建, { description: 订单 #1234 已成功提交, }) // 带操作的通知 toast.warning(库存不足, { action: { label: 查看详情, onClick: () console.log(navigate to product), }, })ToastProps支持id、position、duration、dismissable、icon、description、action等选项其中action是一个{ label, onClick }结构对应 src/types.ts 中的ToastAction类型。迁移提示如果你的项目还在用useToast()v3.0.0 之后必须改为import { toast } from medusajs/ui并调用toast.success(...)等方法同时检查Toaster的position是否仍符合预期新默认值为bottom-right。v4.x 时代DataTable 区块与 Medusa 2.0 对齐v4.0.0 伴随 Medusa 2.0 正式发布见 CHANGELOG.md 475-484 行此后 UI 包进入以数据表格与视图配置为核心的功能建设期。v4.0.4DataTable 区块正式加入PR #10024 引入了新的DataTableblock见 CHANGELOG.md 441 行。这是 UI 包中第一个也是目前唯一的区块级组件位于 src/blocks/data-table其定位是在Table组件之上扩展功能创建类似 Medusa Admin 中的表格。从>const DataTable Object.assign(Root, { Table: DataTableTable, Toolbar: DataTableToolbar, Search: DataTableSearch, SortingMenu: DataTableSortingMenu, FilterMenu: DataTableFilterMenu, FilterBar: DataTableFilterBar, ColumnVisibilityMenu: DataTableColumnVisibilityMenu, Pagination: DataTablePagination, CommandBar: DataTableCommandBar, })useDataTable hookDataTable 的驱动核心DataTable必须配合 use-data-table.tsx 返回的instance使用。该 hook 构建在tanstack/react-table之上依赖见 package.json通过useReactTable组装核心行模型并在其上封装了表格自身的状态管理支持的能力包括能力配置项列定义columns: DataTableColumnDefTData, any[]过滤filters与filtering: { state, onFilteringChange }排序sorting: { state, onSortingChange }搜索search: { state, onSearchChange, debounce? }debounce默认 300ms分页pagination: { state, onPaginationChange }行选择rowSelection: { state, onRowSelectionChange, enableRowSelection? }批量命令commands?: DataTableCommand[]针对选中行执行的操作行点击onRowClick(event, row)加载态isLoading典型用法use client import { DataTable, useDataTable } from medusajs/ui import { columns } from ./columns const MyTable ({ data }) { const table useDataTable({ columns, data, search: { state: search, onSearchChange: setSearch, }, pagination: { state: pagination, onPaginationChange: setPagination, }, }) return ( DataTable instance{table} DataTable.Toolbar DataTable.Search placeholder搜索订单... / DataTable.SortingMenu / DataTable.FilterMenu / DataTable.ColumnVisibilityMenu / /DataTable.Toolbar DataTable.Table / DataTable.Pagination / /DataTable ) }v4.0.5 ~ v4.0.20生态迁移与功能补丁v4.0.5SC tables迁移到 DataTable#11106Divider组件移入 UI 包#11357改用统一的radix-ui包#11195补齐缺失的use client指令#11368修复 Command 在可编辑字段聚焦时被误触发#11254升级 vitest 并对齐 Vite 版本。v4.0.6InlineTip移入 UI 包并显式指定 props 类型#11462、#11575更新 Vite 依赖。v4.0.8DataTable 在行不可选中时禁用行选择单元格#11442。v4.0.10修复 filter/sorting 菜单的 tooltip 错误#12309。v4.0.16修复Select.Content的onScroll事件#12855。v4.0.20Toast 改为在右上角显示#13092与toast.tsx中DEFAULT_TOAST_POSITION top-right的实现一致。v4.0.27依赖清理与安全漏洞修复#13910、#13932、#13940。v4.1.x交互细节与 OtpInputv4.1.2修复选择视图时筛选条件残留stale filters的问题#14160与视图配置功能 VIEW_CONFIGURATIONS_FF 相关。v4.1.4修复 DataTable 滚动传播问题#14849。v4.1.13新增OtpInput组件#15424用于分段数字验证码输入典型场景是 MFA 二次验证、邮件/短信验证码。从 otp-input.tsx 看OtpInput支持以下属性属性说明length验证码位数value/onChange受控值onChange收到的是经sanitizeOtp清洗后的纯数字字符串onComplete当清洗后的验证码长度达到length时回调groupSize每隔多少位渲染一个分隔符separator分组之间的分隔节点ReactNodeautoFocus挂载时是否聚焦第一个输入框disabled/readOnly禁用态 / 只读态inputClassName每个输入框的附加 className其内部通过value.replace(/\D/g, ).slice(0, length)对输入做纯数字清洗与长度截断保证传入后端的一定是规范格式。v4.2.x可配置 DataTable 与视图配置Views端到端落地v4.2.0 与 v4.2.2 标志着 DataTable 从展示组件演进为可配置数据表格体系见 CHANGELOG.md 24-35 行v4.2.0实现 configurable data tables 的端到端支持横跨 dashboard、settings、ui、types 等多个包#16025v4.2.2视图配置 UI 增强——动态 filter/sort 解析、自定义 cell renderer 注册、属性标签property labels管理 UI#14661。这一轮更新意味着管理员可以保存并切换不同的视图即一组预设的列组合、筛选条件与排序规则数据表格的行为由配置驱动而不是写死在代码中。这与仓库中integration-tests/http/__tests__/views/下的视图配置接口测试、以及packages/medusa/src/api中视图相关 API 相互印证。v4.0.3 与 React 19 兼容性v4.0.3 将React 19 / 19-rc 加入 peer dependencies#10458同时 v4.0.3 还做了 TSDocs 与类型全面更新#10753。当前 package.json 的 peer 依赖为react ^18.3.1与react-dom ^18.3.1React 19 作为可选兼容范围存在。依赖栈透视UI 包的底层拼图从 package.json 可以看到medusajs/ui的核心依赖栈及其各自负责的领域依赖用途medusajs/icons图标资产版本与 UI 包保持同步发布radix-ui/radix-ui/react-*无头可访问性原语Dialog、DismissableLayer 等react-aria/react-stately表单与日期等复杂组件的状态与无障碍逻辑tanstack/react-tableDataTable 的表头模型与状态管理sonnerToast 渲染引擎v3.0.0 起cva变体驱动的 className 工厂按钮、徽章等 variant 样式tailwind-merge智能合并冲突的 Tailwind 类名clsxclassName 条件拼接clx即其封装prism-react-renderer/prismjsCodeBlock 代码高亮react-currency-input-fieldCurrencyInput 金额输入dnd-kit/*拖拽排序DataTable 列拖拽、可排序列表等copy-to-clipboardCopy 组件复制能力lodash.isequal深度相等比较版本节奏一览版本类型核心内容1.0.0Major设计系统首发ui icons ui-preset 三包齐发2.0.0Major8 个新组件Button/Badgeformat移除CodeBlock API 调整2.1.0Minor样式统一TextleadingRadioGroup.ChoiceBox6 个新图标2.2.0Minor新增 PopoverDatePicker 行为修正2.3.0Minorsize variantsfocus-visible 化ui-code-fg-*更名2.4.0Minor新增 AlertTailwindCSS 升级3.0.0MajorToast 重构useToast→toast函数基于 sonner默认位置 bottom-right4.0.0Major对齐 Medusa 2.04.0.4 ~ 4.0.5Patch新增 DataTable 区块SC 表迁移Divider/InlineTip 入包4.1.13Patch新增 OtpInput 验证码组件4.2.0 / 4.2.2Minor可配置 DataTable 与视图配置体系端到端落地结语从 CHANGELOG.md 的完整记录来看medusajs/ui的演进呈现出清晰的三个阶段1.x 建立设计系统基础、2.x~3.x 完成组件能力扩张与 Toast 范式切换、4.x 聚焦 DataTable 与配置驱动视图。对开发者而言最重要的两个迁移节点是 v2.0.0Button/Badge 的format移除与 v3.0.0useToast移除、改用命令式toast函数。如果你正在为 Medusa Admin 扩展自定义页面建议直接基于 DataTable 区块 与useDataTable构建数据密集型界面并结合 OtpInput、Toast 工具 等组件快速补齐交互能力。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Medusa UI 设计系统演进全解析：@medusajs/ui 从 1.0.0 到 4.2.3 的组件库变更路线图
Medusa UI 设计系统演进全解析medusajs/ui 从 1.0.0 到 4.2.3 的组件库变更路线图【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusamedusajs/ui是 Medusa 开源商业平台的官方 React 组件库为 Medusa Admin 仪表盘提供全部界面基础。本文以 packages/design-system/ui/CHANGELOG.md 为骨架结合仓库内组件源码完整梳理该设计系统从 1.0.0 首发到 4.2.3 的演进历程你能借此掌握其包结构与依赖栈、历次破坏性变更的迁移要点、Toast 体系的重构逻辑以及 DataTable、OtpInput 等核心组件的真实用法与底层实现为在 Medusa 生态中开发管理界面或自建组件库提供可直接落地的参考。设计系统三件套ui、icons 与 ui-presetv1.0.0 是 Medusa UI 设计系统的正式首发版本见 CHANGELOG.md 686-695 行它一次发布了三个相互配套的 npm 包包名职责medusajs/uiReact 组件、hooks 与工具函数集合medusajs/iconsReact 图标集medusajs/ui-preset包含 Medusa UI 设计令牌design tokens的 Tailwind CSS 预设三者分工明确组件消费图标与设计令牌令牌决定颜色、阴影、间距、字体等视觉变量图标提供统一风格的图形资产。这一组件 图标 样式预设的三层架构沿用至今在 package.json 中可以看到medusajs/ui当前将medusajs/icons列为直接依赖版本 2.20.1并将medusajs/ui-preset用于开发与样式构建。从源码目录看UI 包共分四层components46 个基础组件目录alert、button、checkbox、select、tooltip 等对应 src/componentsblocks复合业务区块目前仅有>import { toast } from medusajs/ui // 成功通知 toast.success(订单已创建, { description: 订单 #1234 已成功提交, }) // 带操作的通知 toast.warning(库存不足, { action: { label: 查看详情, onClick: () console.log(navigate to product), }, })ToastProps支持id、position、duration、dismissable、icon、description、action等选项其中action是一个{ label, onClick }结构对应 src/types.ts 中的ToastAction类型。迁移提示如果你的项目还在用useToast()v3.0.0 之后必须改为import { toast } from medusajs/ui并调用toast.success(...)等方法同时检查Toaster的position是否仍符合预期新默认值为bottom-right。v4.x 时代DataTable 区块与 Medusa 2.0 对齐v4.0.0 伴随 Medusa 2.0 正式发布见 CHANGELOG.md 475-484 行此后 UI 包进入以数据表格与视图配置为核心的功能建设期。v4.0.4DataTable 区块正式加入PR #10024 引入了新的DataTableblock见 CHANGELOG.md 441 行。这是 UI 包中第一个也是目前唯一的区块级组件位于 src/blocks/data-table其定位是在Table组件之上扩展功能创建类似 Medusa Admin 中的表格。从>const DataTable Object.assign(Root, { Table: DataTableTable, Toolbar: DataTableToolbar, Search: DataTableSearch, SortingMenu: DataTableSortingMenu, FilterMenu: DataTableFilterMenu, FilterBar: DataTableFilterBar, ColumnVisibilityMenu: DataTableColumnVisibilityMenu, Pagination: DataTablePagination, CommandBar: DataTableCommandBar, })useDataTable hookDataTable 的驱动核心DataTable必须配合 use-data-table.tsx 返回的instance使用。该 hook 构建在tanstack/react-table之上依赖见 package.json通过useReactTable组装核心行模型并在其上封装了表格自身的状态管理支持的能力包括能力配置项列定义columns: DataTableColumnDefTData, any[]过滤filters与filtering: { state, onFilteringChange }排序sorting: { state, onSortingChange }搜索search: { state, onSearchChange, debounce? }debounce默认 300ms分页pagination: { state, onPaginationChange }行选择rowSelection: { state, onRowSelectionChange, enableRowSelection? }批量命令commands?: DataTableCommand[]针对选中行执行的操作行点击onRowClick(event, row)加载态isLoading典型用法use client import { DataTable, useDataTable } from medusajs/ui import { columns } from ./columns const MyTable ({ data }) { const table useDataTable({ columns, data, search: { state: search, onSearchChange: setSearch, }, pagination: { state: pagination, onPaginationChange: setPagination, }, }) return ( DataTable instance{table} DataTable.Toolbar DataTable.Search placeholder搜索订单... / DataTable.SortingMenu / DataTable.FilterMenu / DataTable.ColumnVisibilityMenu / /DataTable.Toolbar DataTable.Table / DataTable.Pagination / /DataTable ) }v4.0.5 ~ v4.0.20生态迁移与功能补丁v4.0.5SC tables迁移到 DataTable#11106Divider组件移入 UI 包#11357改用统一的radix-ui包#11195补齐缺失的use client指令#11368修复 Command 在可编辑字段聚焦时被误触发#11254升级 vitest 并对齐 Vite 版本。v4.0.6InlineTip移入 UI 包并显式指定 props 类型#11462、#11575更新 Vite 依赖。v4.0.8DataTable 在行不可选中时禁用行选择单元格#11442。v4.0.10修复 filter/sorting 菜单的 tooltip 错误#12309。v4.0.16修复Select.Content的onScroll事件#12855。v4.0.20Toast 改为在右上角显示#13092与toast.tsx中DEFAULT_TOAST_POSITION top-right的实现一致。v4.0.27依赖清理与安全漏洞修复#13910、#13932、#13940。v4.1.x交互细节与 OtpInputv4.1.2修复选择视图时筛选条件残留stale filters的问题#14160与视图配置功能 VIEW_CONFIGURATIONS_FF 相关。v4.1.4修复 DataTable 滚动传播问题#14849。v4.1.13新增OtpInput组件#15424用于分段数字验证码输入典型场景是 MFA 二次验证、邮件/短信验证码。从 otp-input.tsx 看OtpInput支持以下属性属性说明length验证码位数value/onChange受控值onChange收到的是经sanitizeOtp清洗后的纯数字字符串onComplete当清洗后的验证码长度达到length时回调groupSize每隔多少位渲染一个分隔符separator分组之间的分隔节点ReactNodeautoFocus挂载时是否聚焦第一个输入框disabled/readOnly禁用态 / 只读态inputClassName每个输入框的附加 className其内部通过value.replace(/\D/g, ).slice(0, length)对输入做纯数字清洗与长度截断保证传入后端的一定是规范格式。v4.2.x可配置 DataTable 与视图配置Views端到端落地v4.2.0 与 v4.2.2 标志着 DataTable 从展示组件演进为可配置数据表格体系见 CHANGELOG.md 24-35 行v4.2.0实现 configurable data tables 的端到端支持横跨 dashboard、settings、ui、types 等多个包#16025v4.2.2视图配置 UI 增强——动态 filter/sort 解析、自定义 cell renderer 注册、属性标签property labels管理 UI#14661。这一轮更新意味着管理员可以保存并切换不同的视图即一组预设的列组合、筛选条件与排序规则数据表格的行为由配置驱动而不是写死在代码中。这与仓库中integration-tests/http/__tests__/views/下的视图配置接口测试、以及packages/medusa/src/api中视图相关 API 相互印证。v4.0.3 与 React 19 兼容性v4.0.3 将React 19 / 19-rc 加入 peer dependencies#10458同时 v4.0.3 还做了 TSDocs 与类型全面更新#10753。当前 package.json 的 peer 依赖为react ^18.3.1与react-dom ^18.3.1React 19 作为可选兼容范围存在。依赖栈透视UI 包的底层拼图从 package.json 可以看到medusajs/ui的核心依赖栈及其各自负责的领域依赖用途medusajs/icons图标资产版本与 UI 包保持同步发布radix-ui/radix-ui/react-*无头可访问性原语Dialog、DismissableLayer 等react-aria/react-stately表单与日期等复杂组件的状态与无障碍逻辑tanstack/react-tableDataTable 的表头模型与状态管理sonnerToast 渲染引擎v3.0.0 起cva变体驱动的 className 工厂按钮、徽章等 variant 样式tailwind-merge智能合并冲突的 Tailwind 类名clsxclassName 条件拼接clx即其封装prism-react-renderer/prismjsCodeBlock 代码高亮react-currency-input-fieldCurrencyInput 金额输入dnd-kit/*拖拽排序DataTable 列拖拽、可排序列表等copy-to-clipboardCopy 组件复制能力lodash.isequal深度相等比较版本节奏一览版本类型核心内容1.0.0Major设计系统首发ui icons ui-preset 三包齐发2.0.0Major8 个新组件Button/Badgeformat移除CodeBlock API 调整2.1.0Minor样式统一TextleadingRadioGroup.ChoiceBox6 个新图标2.2.0Minor新增 PopoverDatePicker 行为修正2.3.0Minorsize variantsfocus-visible 化ui-code-fg-*更名2.4.0Minor新增 AlertTailwindCSS 升级3.0.0MajorToast 重构useToast→toast函数基于 sonner默认位置 bottom-right4.0.0Major对齐 Medusa 2.04.0.4 ~ 4.0.5Patch新增 DataTable 区块SC 表迁移Divider/InlineTip 入包4.1.13Patch新增 OtpInput 验证码组件4.2.0 / 4.2.2Minor可配置 DataTable 与视图配置体系端到端落地结语从 CHANGELOG.md 的完整记录来看medusajs/ui的演进呈现出清晰的三个阶段1.x 建立设计系统基础、2.x~3.x 完成组件能力扩张与 Toast 范式切换、4.x 聚焦 DataTable 与配置驱动视图。对开发者而言最重要的两个迁移节点是 v2.0.0Button/Badge 的format移除与 v3.0.0useToast移除、改用命令式toast函数。如果你正在为 Medusa Admin 扩展自定义页面建议直接基于 DataTable 区块 与useDataTable构建数据密集型界面并结合 OtpInput、Toast 工具 等组件快速补齐交互能力。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考