Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Data & analytics

sw-migrate-to-material

将主包(apps/app)中已有的物料渲染组件及其编辑器配置面板,迁移到物料包(packages/material),使其可被独立构建、复用并通过 @screenwright/material 导出。当用户说"把 xxx 组件搬到物料包"、"迁移 xxx 到 material"、"提取物料组件"、"xxx 组件物料化"时使用。已完成的迁移参考案例:图表(ScreenwrightEcharts)、文本(ScreenwrightText)、交互(ScreenwrightInteractive)。

Onweekendd · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add Onweekendd/ScreenWright --skill sw-migrate-to-material

About this skill


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 逻辑不变。

迁移步骤

  1. 物料组件迁移(packages/material/src/components/<Category>/) 把渲染用的 .vue/.ts 原样搬入,导出 Record<Enum, Component>。组件内部对 @/ 的导入必须逐类替换为新源(vite.config.ts 中已配置 @material → src、@editor → src/editor-ui),具体映射见下方「依赖处理速查」,先查表再批量替换(用 perl/正则一次性改,几十个文件手工改不现实)。

  2. 编辑器配置面板迁移(packages/material/src/editor-ui/<category>Component/) 按 Tab 类型分子目录(Global/Series/xAxis/Tooltip 等),导出 optionType enum、ConfigTab type、XxxConfigComponent: Record<Enum, ConfigTab[]>。不要沿用主包旧的 ComponentOptions 基类(defineAsyncComponent + 路径拼接动态 import),迁移后统一用静态 import + 普通对象,更简洁也避免相对路径拼接出错。面板里 @/components/FtXxx 这类 UI 组件(FtInputNumber/FtCollapseItem 等)真实实现都在 ft-component 包,改成 from "@screenwright/ui/xxx" 具名导入、不要迁移(详见速查表)。跨分类引用其他分类的面板子组件(如交互引用 text 的 ItemTextShadow)用 @editor/textComponent/... alias,不要用 ../../(面板分布在不同深度目录,相对路径会错)。

  3. 物料包导出(packages/material/src/index.ts) 新增两行 export { XxxMap } from "./components/XxxCategory" 和 export { XxxConfigComponent, optionType as xxxOptionType } from "./editor-ui/xxxComponent"。

  4. 主包接线(两处,零结构改动)

    • apps/app/src/components/MaterialRegistry.ts:把对应的本地 import 换成 import { XxxMap } from "@screenwright/material"。
    • componentOption/<category>Component.ts:改成上面展示的纯转发写法。
  5. 依赖注入检查(仅当组件依赖主包能力时) 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(...)。检查组件用到的能力是否已有对应端口;没有则参照下方「重依赖主包能力:端口注入模式」新增。

  6. 类型枚举确认 AllComponentType(packages/types/src/types/componentProp/index.ts)通常已经包含目标枚举(因为渲染功能早就存在),迁移本身一般不需要新增枚举值——只是改变了实现的物理位置。

  7. 清理残留(迁移类问题最容易翻车的环节) 迁移完成后,必须删除主包 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> 的残留引用,再删除整个目录。

  8. 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/ScreenwrightSeriesTabsfrom "@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
Read the complete source ↗