用途:在规划、调研或实现 Medusa Admin 后台界面时加载本技能,用于构建自定义 UI 扩展,包括商品/订单/客户页面的小部件、自定义管理页面、表单与弹窗、表格与列表展示以及页面间导航。注意 UI Routes 指自定义后台页面,与后端 API 路由不同。
主要能力与规则:所有 API 请求必须使用 Medusa JS SDK,禁止使用原生 fetch(),否则缺少认证头会报错;内置端点用既有 SDK 方法(如 sdk.admin.product.list()),自定义路由用 sdk.client.fetch()。展示类查询必须在挂载时加载,不可基于 UI 状态设置 enabled,且需与弹窗/表单查询分离;变更后要失效(invalidate)展示查询。始终显示加载状态;使用语义化颜色类与 Medusa UI 组件,小部件按钮使用 size="small",区块内边距用 px-6 py-4。价格按原值显示,不要除以 100。文本统一用 Text 组件并配合 text-ui-fg-subtle 等类。创建实体用 FocusModal,编辑用 Drawer,变更期间禁用按钮并显示加载。选项 2-10 个用 Select,大数据集用 DataTable 配合 FocusModal 并传入搜索配置。
使用方式:先加载与任务相关的参考文件(data-loading.md、forms.md、display-patterns.md、table-selection.md、navigation.md、typography.md),至少 1-2 个。pnpm 用户须先安装 @tanstack/react-query,使用导航时安装 react-router-dom,版本需与 dashboard 一致;npm/yarn 用户不要安装这些包。小部件用 defineWidgetConfig 定义 zone,UI 路由用 defineRouteConfig 定义 label。
限制与注意事项:v2.17.2+ 起 .before/.after 不再控制位置,.side 仍有效,新小部件优先使用无后缀 zone;组件具体属性签名、可用 zone 列表与 JS SDK 方法细节应查询 MedusaDocs MCP 服务器。资料未提供具体版本号、完整代码与错误排查以外的收费信息。