sw-migrate-to-material
将主包(apps/app)中已有的物料渲染组件及其编辑器配置面板,迁移到物料包(packages/material),使其可被独立构建、复用并通过 @screenwright/material 导出。当用户说"把 xxx 组件搬到物料包"、"迁移 xxx 到 material"、"提取物料组件"、"xxx 组件物料化"时使用。已完成的迁移参考案例:图表(ScreenwrightEcharts)、文本(ScreenwrightText)、交互(ScreenwrightInteractive)。
Onweekendd · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Onweekendd/ScreenWright --skill sw-migrate-to-material技能说明
name: sw-migrate-to-material description: 将主包(apps/app)中已有的物料渲染组件及其编辑器配置面板,迁移到物料包(packages/material),使其可被独立构建、复用并通过 @screenwright/material 导出。当用户说"把 xxx 组件搬到物料包"、"迁移 xxx 到 material"、"提取物料组件"、"xxx 组件物料化"时使用。已完成的迁移参考案例:图表(ScreenwrightEcharts)、文本(ScreenwrightText)、交互(ScreenwrightInteractive)。
物料组件迁移到 @screenwright/material
适用前提
仅迁移渲染组件 + 编辑器配置面板,不迁移业务流程代码(如 buildConfig 的目录结构、componentEntry 类型注册仍留在主包)。迁移单位通常是一整个"组件分类"(如全部图表、全部文本),不要只搬其中一两个枚举值——会导致同一分类的组件 Map 一部分来自 material、一部分来自本地,增加维护成本。
迁移分四块,必须全部完成才算闭环:渲染组件 → 编辑器配置面板 → 类型/枚举 → 主包接线。详细文件清单与代码模板见 references/migration-checklist.md。
整体架构(已验证的事实)
packages/material/src/
├── components/<Category>/index.ts 导出 XxxMap: Record<Enum, Component>
├── editor-ui/<category>Component/ 导出 XxxConfigComponent: Record<Enum, ConfigTab[]>
└── index.ts 统一对外导出上述两者
apps/app/src/
├── components/MaterialRegistry.ts 合并所有 XxxMap
└── views/build/components/buildConfig/attrsRender/componentOption/ 合并所有 XxxConfigComponent
主包侧不要删除 componentOption/<category>Component.ts 这个聚合文件本身,而是把它改成纯转发:
// apps/app/.../componentOption/baseComponent.ts(图表已迁移后的真实写法)
import { ScreenwrightEchartsConfigComponent } from "@screenwright/material";
export { chartOptionType as optionType } from "@screenwright/material";
export const baseComponentOptions = ScreenwrightEchartsConfigComponent;
这样 componentOption/index.ts 里 ...baseComponentOptions 的聚合逻辑完全不用动,降低改动面。MaterialRegistry.ts 同理:把本地 import 换成 @screenwright/material import,getAllComponentMaps() 里的 spread 逻辑不变。
迁移步骤
-
物料组件迁移(
packages/material/src/components/<Category>/) 把渲染用的.vue/.ts原样搬入,导出Record<Enum, Component>。组件内部对@/的导入必须逐类替换为新源(vite.config.ts 中已配置@material→src、@editor→src/editor-ui),具体映射见下方「依赖处理速查」,先查表再批量替换(用 perl/正则一次性改,几十个文件手工改不现实)。 -
编辑器配置面板迁移(
packages/material/src/editor-ui/<category>Component/) 按 Tab 类型分子目录(Global/Series/xAxis/Tooltip 等),导出optionTypeenum、ConfigTabtype、XxxConfigComponent: Record<Enum, ConfigTab[]>。不要沿用主包旧的ComponentOptions基类(defineAsyncComponent+ 路径拼接动态 import),迁移后统一用静态 import + 普通对象,更简洁也避免相对路径拼接出错。面板里@/components/FtXxx这类 UI 组件(FtInputNumber/FtCollapseItem 等)真实实现都在ft-component包,改成from "@screenwright/ui/xxx"具名导入、不要迁移(详见速查表)。跨分类引用其他分类的面板子组件(如交互引用 text 的 ItemTextShadow)用@editor/textComponent/...alias,不要用../../(面板分布在不同深度目录,相对路径会错)。 -
物料包导出(
packages/material/src/index.ts) 新增两行export { XxxMap } from "./components/XxxCategory"和export { XxxConfigComponent, optionType as xxxOptionType } from "./editor-ui/xxxComponent"。 -
主包接线(两处,零结构改动)
apps/app/src/components/MaterialRegistry.ts:把对应的本地 import 换成import { XxxMap } from "@screenwright/material"。componentOption/<category>Component.ts:改成上面展示的纯转发写法。
-
依赖注入检查(仅当组件依赖主包能力时)
initMaterial()已废弃删除,不存在这一层了。物料包不能反向 import 主包任何模块(包括@/hooks、ft-component之外的主包内部代码),但绝大多数主包 hook(useBaseData/useEvent/useDataFilter/useEditStore等)本身已经整体下沉到@screenwright/composables,物料包直接import { useXxx } from "@screenwright/composables"即可共享同一份运行时状态,不需要注入。只有真正的 IO/业务边界(后端接口、UE4/终端通信、动作策略执行、状态动画触发等)才通过@screenwright/composables自己的端口(packages/composables/src/ports/*.ts的initXxx(fn))注入,由主包main.ts直接调用initXxx(...)。检查组件用到的能力是否已有对应端口;没有则参照下方「重依赖主包能力:端口注入模式」新增。 -
类型枚举确认
AllComponentType(packages/types/src/types/componentProp/index.ts)通常已经包含目标枚举(因为渲染功能早就存在),迁移本身一般不需要新增枚举值——只是改变了实现的物理位置。 -
清理残留(迁移类问题最容易翻车的环节) 迁移完成后,必须删除主包
apps/app/src/components/<Category>/下的旧实现代码,不要只留一个转发index.ts。已发生过的真实问题:图表迁移后apps/app/src/components/ScreenwrightEcharts/index.ts仍保留着完整的旧ScreenwrightEchartsMap构建逻辑(只是没人 import 它),文本迁移后apps/app/src/components/ScreenwrightText/components/整个子组件目录原样留着。这些死代码会让人误以为还在维护两份实现。清理前用 Grep 确认全局没有@/components/<Category>的残留引用,再删除整个目录。 -
CSS 与构建验证
- dev 模式直连 material 源码,scoped 样式由 Vue SFC 自动注入,无需额外处理。
- prod 需要确认
apps/app/src/main.ts中await import("@screenwright/material/dist/style.css")仍在,且packages/material执行vite build能正常产出dist/style.css(rollup 配置里assetFileNames: "[name][extname]")。 - 跑一次物料包构建(
pnpm --filter @screenwright/material build)和主包类型检查,确认无报错。
依赖处理速查(真实迁移经验)
物料组件的 .vue/.ts 从主包搬进物料包后,内部对 @/ 的引用必须逐类替换。下表是经 chart/text/交互三轮迁移验证的映射,先查此表再动手:
原 @/ 来源 | 替换为 | 说明 |
|---|---|---|
@/views/.../constants 的 EventTypeEnum | @screenwright/types | 枚举已下沉 |
@/views/.../buildRender/type 的 ComponentType | @screenwright/types | 类型已下沉 |
@/components/componentEntry/type 的 interactiveEnum/各分类 xxxEnum | @screenwright/types 取 XxxEnum(必要时 as xxxEnum 保留别名) | 主包 componentEntry/type 只是从 @screenwright/types 重导出的别名 |
@/utils/utils 的 sleep/lineargradientHandle/uuid/setPx/getPartialGradientCSS/extractComponentId 等纯函数 | @screenwright/core | 纯函数优先下沉 core(见下) |
@/utils/websocket 的 Websocketconfig | @screenwright/composables | |
@/hooks/useBaseData、@/utils/config 的 setMinioUrl | @screenwright/composables 的 useBaseData、minioUrl 工具 | 已整体下沉,直接 import,不再需要注入 |
@/components/FtInputNumber/FtCollapseItem/FtInput/FtRadio/FtSingleColorPicker/FtColorPicker/FtSlider/FtCoordinateTabs 等 UI 组件 | from "@screenwright/ui/xxx" 具名导入 | 真实实现都在 workspace 包 ft-component(packages/ui),主包 @/components/FtXxx 只是转发壳,不要迁移;原默认导入 → 具名 { FtXxx },模板内组件名不变 |
@/components/ScreenwrightColorPicker/ScreenwrightSeriesTabs | from "@screenwright/ui" 主入口具名 | 同上,ft-component main.ts 导出 |
@/components/Icon、@/components/FtUpload | @editor/base/Icon、@editor/base/FtUpload | 物料包 base 自有实现(ft-component 无) |
@/views/.../textComponent/...、@/views/.../chartComponent/... 等跨分类子组件 | @editor/textComponent/...、@editor/chartComponent/...(用 @editor alias,不要用 ../../) | 相对路径在面板的不同目录深度会错;@editor 任何深度都对 |
| `@/<c |