Vite plugin for Design Mode - enables visual editing of React components with source mapping
npm install @xagi/vite-plugin-design-mode一个为AppDev启用设计模式功能的Vite插件,为React组件提供源码映射和可视化编辑功能。
- 源码映射: 在编译时自动向DOM元素注入源码位置信息
- 可视化编辑: 提供直观的设计模式UI,支持实时样式编辑
- 实时修改: 支持实时编辑样式和内容,并自动持久化到源码文件
- Tailwind CSS集成: 内置Tailwind CSS预设,提供快速样式编辑
- 桥接通信: 提供消息桥接机制,支持与外部工具和设计系统集成
- 开发服务器集成: 无缝集成Vite开发服务器,支持热重载
- 零配置: 开箱即用,无需复杂配置即可开始使用
使用 CLI 工具一键配置插件:
``bash`
npx @xagi/vite-plugin-design-mode install或
pnpm dlx @xagi/vite-plugin-design-mode install
这个命令会:
- 在 package.json 的 devDependencies 中添加插件依赖vite.config.ts/js/mjs
- 自动在 中添加插件配置
- 使用默认配置,无需手动传参
注意: CLI 只会在配置文件中添加配置,不会执行包管理器安装命令。配置完成后,请手动运行包管理器安装命令来安装依赖:
`bash`
pnpm install或
npm install或
yarn install
使用 CLI 工具一键卸载插件并清理配置:
`bash`
npx @xagi/vite-plugin-design-mode uninstall或
pnpm dlx @xagi/vite-plugin-design-mode uninstall
这个命令会:
- 从 package.json 中移除插件依赖vite.config.ts/js/mjs
- 从 中移除 import 和插件配置
- 自动清理所有相关配置
注意: CLI 只会在配置文件中移除配置,不会执行包管理器卸载命令。配置清理完成后,请手动运行包管理器卸载命令来移除依赖:
`bash`
pnpm remove @xagi/vite-plugin-design-mode或
npm uninstall @xagi/vite-plugin-design-mode或
yarn remove @xagi/vite-plugin-design-mode
如果需要手动安装:
`bash`
npm install @xagi/vite-plugin-design-mode --save-devor
yarn add @xagi/vite-plugin-design-mode --devor
pnpm add @xagi/vite-plugin-design-mode -D
使用一键安装后,插件已自动配置,vite.config.ts 中会包含:
`typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import appdevDesignMode from '@xagi/vite-plugin-design-mode';
export default defineConfig({
plugins: [
react(),
appdevDesignMode() // 使用默认配置,无需传参
]
});
`
默认配置说明:
- enabled: true - 启用插件enableInProduction: false
- - 仅在开发环境生效,生产构建时自动禁用verbose: true
- - 启用详细日志include: ['src/*/.{ts,tsx}']
- - 处理 src 目录下的 TypeScript/TSX 文件exclude: ['node_modules', 'dist', 'src/components/ui']
- - 排除指定目录
`typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import appdevDesignMode from '@xagi/vite-plugin-design-mode';
export default defineConfig({
plugins: [
react(),
appdevDesignMode({
enabled: true,
enableInProduction: false,
attributePrefix: 'data-appdev',
verbose: true,
exclude: ['node_modules', '.git'],
include: ['*/.{js,jsx,ts,tsx}']
})
]
});
`
1. 编译时转换: 插件在编译时使用Babel AST转换JSX/TSX文件
2. 抽象语法树分析: 分析AST识别React组件和DOM元素
3. 源码映射数据注入: 将源码位置信息作为data-*属性注入到DOM元素
4. 运行时通信: 设计模式UI通过桥接系统与外部工具通信,支持实时编辑
5. 源码持久化: 修改的样式和内容通过API端点实时写入源码文件
插件提供以下API端点:
- GET /__appdev_design_mode/get-source?elementId=xxx - 获取指定元素的源码信息和文件内容POST /__appdev_design_mode/modify-source
- - 修改源码文件中的样式或内容GET /__appdev_design_mode/health
- - 健康检查,返回插件运行状态POST /__appdev_design_mode/update
- - 更新源码,支持样式类和内容修改
插件处理的元素将具有以下属性(默认前缀为 data-source,可通过 attributePrefix 配置项自定义):
- {prefix}-file: 源码文件路径{prefix}-line
- : 源码行号{prefix}-column
- : 源码列号{prefix}-info
- : 包含完整源码映射信息的JSON字符串{prefix}-element-id
- : 唯一元素标识符,格式为文件路径:行号:列号_标签名_类名或ID{prefix}-component
- : 组件名称(如果适用){prefix}-function
- : 函数名称(如果适用){prefix}-position
- : 位置信息,格式为行号:列号{prefix}-static-content
- : 标记元素是否包含纯静态内容(值为 'true'),用于判断元素是否可以直接编辑
注意:这些属性使用可配置的前缀,默认值为 data-source。通过设置 attributePrefix 选项,可以避免与用户自定义的 data-* 属性冲突。例如,设置 attributePrefix: 'data-appdev' 后,属性名将变为 data-appdev-file、data-appdev-line、data-appdev-static-content 等。
在浏览器开发者工具或外部应用中:
`javascript
// 获取元素源码信息
const element = document.querySelector('.my-element');
const sourceInfo = element.getAttribute('data-source-info');
const sourceData = JSON.parse(sourceInfo);
console.log(sourceData);
// {
// fileName: 'src/App.tsx',
// lineNumber: 10,
// columnNumber: 5,
// elementType: 'div',
// componentName: 'App',
// elementId: 'src/App.tsx:10:5_div_my-class'
// }
`
使用内置桥接系统与设计模式UI交互:
`javascript
// 监听元素选择变化
window.addEventListener('message', (event) => {
const { type, payload } = event.data;
if (type === 'SELECTION_CHANGED') {
console.log('选中的元素:', payload);
// payload 包含: tagName, id, className, innerText, source
}
});
// 发送样式更新命令
window.parent.postMessage({
type: 'UPDATE_STYLE',
payload: {
newClass: 'bg-blue-500 text-white p-4 rounded-lg'
}
}, '*');
// 发送内容更新命令
window.parent.postMessage({
type: 'UPDATE_CONTENT',
payload: {
newContent: '更新后的文本内容'
}
}, '*');
`
| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| enabled | boolean | true | 是否启用设计模式插件 |enableInProduction
| | boolean | false | 是否在生产环境启用,通常保持false |attributePrefix
| | string | 'data-source' | 自定义源码映射属性的前缀 |verbose
| | boolean | true | 是否启用详细日志输出,便于调试 |exclude
| | string[] | ['node_modules', 'dist', 'src/components/ui'] | 排除处理的文件模式和目录 |include
| | string[] | ['src/*/.{ts,tsx}'] | 包含处理的文件模式,支持glob语法 |
`typescript`
// vite.config.ts
export default defineConfig({
plugins: [
react(),
appdevDesignMode({
enabled: true,
enableInProduction: false,
attributePrefix: 'data-appdev',
verbose: true,
exclude: ['node_modules', '.git', 'dist'],
include: ['src//.{ts,tsx}', 'pages//.{ts,tsx}']
})
]
});
插件内置了常用的Tailwind CSS类预设:
- 白色背景
- bg-slate-50 - 浅灰色背景
- bg-blue-50 - 浅蓝色背景
- bg-blue-100 - 中浅蓝色背景
- bg-blue-600 - 深蓝色背景
- bg-red-50 - 浅红色背景
- bg-green-50 - 浅绿色背景$3
- text-slate-900 - 深灰色文字
- text-slate-600 - 中灰色文字
- text-blue-600 - 蓝色文字
- text-white - 白色文字
- text-red-600 - 红色文字$3
- p-0 - 无内边距
- p-2 - 小内边距
- p-4 - 中等内边距
- p-6 - 大内边距
- p-8 - 特大内边距
- p-12 - 超大内边距$3
- rounded-none - 无圆角
- rounded-sm - 小圆角
- rounded-md - 中等圆角
- rounded-lg - 大圆角
- rounded-full - 完全圆角设计模式UI使用指南
$3
1. 在页面右下角找到设计模式开关
2. 点击开关启用设计模式
3. 开始选择和编辑页面元素$3
1. 点击页面中的任意元素
2. 在右侧编辑面板中选择预设样式
3. 实时预览样式效果
4. 修改会自动保存到源码文件$3
- 点击“重置所有修改”按钮撤销所有更改
- 页面将重新加载并恢复原始状态故障排除
$3
Q: 设计模式UI没有显示
A: 检查插件是否正确配置,确保在开发模式下运行
Q: 点击元素没有反应
A: 确认已经启用设计模式,检查浏览器控制台是否有错误信息
Q: 样式修改没有保存
A: 检查文件权限,确保有写入权限,或者检查开发服务器状态
Q: 源码映射不准确
A: 检查是否正确配置了include模式,确保源文件被正确处理
$3
1. 启用verbose模式查看详细日志
2. 检查浏览器开发者工具的网络面板,确认API请求状态
3. 查看元素是否正确生成了源码映射属性
4. 使用健康检查端点验证插件运行状态
`bash
检查插件状态
curl http://localhost:3000/__appdev_design_mode/health
`开发指南
$3
`bash
克隆项目
git clone
cd vite-plugin-design-mode安装依赖
npm install运行示例
cd examples/advanced
npm install
npm run dev
`$3
如需自定义样式预设,可以修改客户端配置:
`typescript
// 在 DesignModeUI.tsx 中自定义预设
const CUSTOM_PRESETS = {
bgColors: [
{ label: 'Primary', value: 'bg-blue-600' },
{ label: 'Secondary', value: 'bg-gray-600' },
// 添加更多自定义颜色
]
};
``欢迎提交Issue和Pull Request来改进这个插件!
MIT