Building Plugin CLI

Building Admin 插件脚手架工具 - 为智慧楼宇管理系统创建和管理第三方插件

功能特性

• 🚀 快速创建: 一键生成完整的插件项目结构
• 🎨 多种模板: 支持基础模板和自定义模板
• 🔧 完整工具链: 内置开发服务器、构建工具和测试环境
• 🎯 灵活集成: 支持插槽组件和路由页面两种集成方式
• 📦 自动打包: 生产构建自动生成可分发的ZIP包
• 🎭 样式隔离: 自动应用CSS作用域防止样式污染
• 🔥 热重载: 开发模式支持实时预览和热更新

安装

全局安装

npm install -g create-building-plugin
# 或
pnpm add -g create-building-plugin

本地安装（推荐用于项目开发）

npm install create-building-plugin --save-dev
# 或
pnpm add create-building-plugin --save-dev

快速开始

1. 创建新插件

# 使用全局安装
create-building-plugin create my-sensor-plugin

# 或使用本地安装
npx create-building-plugin create my-sensor-plugin

2. 进入项目目录

cd my-sensor-plugin

3. 启动开发服务器

npm run dev

4. 构建生产版本

npm run build

详细使用指南

创建插件项目

基本语法

create-building-plugin create <plugin-name> [options]

选项参数

| 选项 | 描述 | 默认值 | | --------------------------- | -------------- | -------- | | -t, --template <template> | 指定使用的模板 | basic | | -d, --dir <directory> | 指定创建目录 | 当前目录 |

示例

# 在当前目录创建插件
create-building-plugin create dashboard-plugin

# 指定模板创建
create-building-plugin create sensor-monitor --template basic

# 在指定目录创建
create-building-plugin create control-panel --dir ./plugins

# 组合使用
create-building-plugin create advanced-plugin --template basic --dir ./my-plugins

交互式配置

运行创建命令后，CLI 会进行交互式配置：

1. 插件描述: 输入插件的功能描述
2. 作者: 输入插件开发者名称
3. 路由组件: 选择是否包含独立页面
   • 是: 创建路由页面插件
   • 否: 创建插槽组件插件，需要选择插槽类型

开发命令

开发服务器

create-building-plugin dev
# 或在插件项目中
npm run dev

启动开发服务器，提供：

• 热重载
• 实时预览
• 错误提示
• 自动打开浏览器

生产构建

create-building-plugin build
# 或在插件项目中
npm run build

构建过程：

1. TypeScript 编译
2. CSS 处理和优化
3. 代码压缩
4. 自动生成 ZIP 包

测试运行

npm run test

插件架构详解

插槽组件 vs 路由页面

Building Admin 支持两种插件集成方式：

插槽组件 (Slot Components)

适用场景: 需要在宿主应用的特定位置显示UI元素

特点:

• 嵌入到宿主应用的现有布局中
• 共享宿主应用的导航和样式
• 适合菜单项、工具栏按钮、状态指示器等

示例插槽类型:

• sidebar-menu-item: 侧边栏菜单项
• nav-right: 导航栏右侧
• main-top: 主内容区域顶部
• sidebar-footer-bottom: 侧边栏页脚底部

代码示例:

// plugin.tsx
export const myPlugin: PluginModule = {
	meta: {
		id: 'my-plugin',
		name: 'My Plugin',
		slot: 'sidebar-menu-item', // 指定插槽类型
	},
	component: () => (
		<div className="flex items-center space-x-2 p-2">
			<Icon name="sensor" />
			<span>Sensor Status</span>
			<Badge variant="success">Online</Badge>
		</div>
	),
};

路由页面 (Route Pages)

适用场景: 需要完整页面体验的功能模块

特点:

• 拥有独立的URL路径
• 完整的页面布局控制
• 适合复杂的数据展示、表单操作、多步骤流程

代码示例:

// plugin.tsx
export const sensorDashboardPlugin: PluginModule = {
	meta: {
		id: 'sensor-dashboard',
		name: 'Sensor Dashboard',
	},
	route: {
		path: 'sensor-dashboard', // 访问路径: /sensor-dashboard
		component: SensorDashboardPage,
	},
};

选择指南

| 特性 | 插槽组件 | 路由页面 | | -------- | -------------------- | ------------------------ | | UI复杂度 | 简单组件 | 复杂页面 | | 用户交互 | 基础操作 | 多步骤流程 | | 数据展示 | 状态指示 | 图表、表格 | | 导航需求 | 无需导航 | 需要子导航 | | 适用场景 | 工具栏、菜单、状态栏 | 仪表板、设置页、管理界面 |

项目结构

创建的插件项目包含以下结构：

my-plugin/
├── public/                 # 静态资源
├── src/
│   ├── components/         # React 组件
│   ├── types/             # TypeScript 类型定义
│   ├── App.tsx            # 主应用组件
│   ├── main.tsx           # 应用入口
│   ├── plugin.tsx         # 插件定义
│   └── index.ts           # 导出文件
├── plugin.config.json     # 插件配置
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
├── vite.config.ts         # Vite 配置
├── tailwind.config.js     # Tailwind CSS 配置
├── postcss.config.mjs     # PostCSS 配置
└── index.html             # HTML 模板

关键文件说明

plugin.config.json

{
	"id": "my-plugin",
	"name": "My Plugin",
	"version": "1.0.0",
	"author": "Your Name",
	"description": "Plugin description",
	"icon": "plugin",
	"slot": "sidebar-menu-item" // 仅插槽组件需要
}

plugin.tsx

插件的核心定义文件：

import type { PluginModule } from './types';

export const myPlugin: PluginModule = {
	meta: pluginConfig,

	// 插槽组件（可选）
	component: () => <MyComponent />,

	// 路由配置（可选）
	route: {
		path: 'my-plugin',
		component: MyPageComponent,
	},

	// 生命周期方法
	setup() {
		console.log('Plugin loaded');
	},

	destroy() {
		console.log('Plugin unloaded');
	},
};

样式和主题

CSS 作用域

插件样式自动应用作用域类，防止与宿主应用样式冲突：

/* 自动添加作用域前缀 */
.my-button {
	background: blue;
}

/* 编译后 */
.plugin-my-plugin .my-button {
	background: blue;
}

Tailwind CSS 支持

插件项目预配置了 Tailwind CSS：

// 使用 Tailwind 类
<div className="rounded-lg bg-blue-500 p-4 text-white">
	<h2 className="text-xl font-bold">Sensor Data</h2>
	<p className="mt-2">Current temperature: 25°C</p>
</div>

自定义样式

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 自定义组件样式 */
@layer components {
	.sensor-card {
		@apply rounded-lg border bg-white p-4 shadow-md;
	}
}

API 和集成

插件 API

插件可以通过 api 参数访问宿主应用提供的功能：

component: ({ api }) => {
	const currentPath = api.getCurrentPath();
	const isActive = api.isActive('dashboard');

	return (
		<div>
			<p>Current path: {currentPath}</p>
			<button
				className={isActive ? 'active' : ''}
				onClick={() => api.navigate('/dashboard')}
			>
				Go to Dashboard
			</button>
		</div>
	);
};

生命周期

export const myPlugin: PluginModule = {
	setup() {
		// 插件加载时执行
		console.log('Plugin initialized');
		// 初始化数据、事件监听等
	},

	destroy() {
		// 插件卸载时执行
		console.log('Plugin destroyed');
		// 清理资源、移除监听等
	},
};

开发最佳实践

1. 命名规范

• 使用 kebab-case 作为插件 ID: sensor-monitor
• 使用 PascalCase 作为组件名: SensorMonitor
• 使用 camelCase 作为变量名: sensorData

2. 错误处理

component: () => {
	const [data, setData] = useState(null);
	const [error, setError] = useState(null);

	useEffect(() => {
		fetchSensorData().then(setData).catch(setError);
	}, []);

	if (error) {
		return <div className="text-red-500">Error: {error.message}</div>;
	}

	return <div>{/* 正常渲染 */}</div>;
};

3. 性能优化

// 使用 React.memo 避免不必要的重渲染
const SensorCard = React.memo(({ sensor }) => (
	<div className="sensor-card">
		<h3>{sensor.name}</h3>
		<p>Value: {sensor.value}</p>
	</div>
));

// 懒加载组件
const HeavyChart = lazy(() => import('./HeavyChart'));

// 使用 useMemo 缓存计算结果
const processedData = useMemo(
	() => data.map((item) => ({ ...item, processed: expensiveOperation(item) })),
	[data]
);

4. 响应式设计

// 使用 Tailwind 的响应式类
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* 响应式网格布局 */}
</div>

// 移动端友好的交互
<button className="w-full md:w-auto px-4 py-2 bg-blue-500 text-white rounded">
  Action Button
</button>

部署和分发

构建产物

运行 npm run build 后生成：

• dist/plugin-name.umd.js - UMD 格式的插件代码
• dist/plugin-name.css - 插件样式文件（如果有）
• dist/plugin-name.zip - 可分发的压缩包

安装插件

将构建生成的 ZIP 包上传到 Building Admin 系统，或直接使用 JS/CSS 文件通过插件加载器安装。

版本管理

// plugin.config.json
{
	"version": "1.2.3",
	"updateTime": "2024-01-15"
}

故障排除

常见问题

样式不生效

• 检查 CSS 是否正确导入
• 确认作用域类是否正确应用
• 查看浏览器开发者工具中的样式覆盖情况

插件无法加载

• 检查 plugin.config.json 格式
• 确认插件 ID 唯一性
• 查看控制台错误信息

构建失败

• 运行 npm install 确保依赖完整
• 检查 TypeScript 类型错误
• 确认 Vite 配置正确

开发服务器无法启动

• 检查端口 3000 是否被占用
• 确认 Node.js 版本兼容性
• 查看防火墙设置

调试技巧

// 在插件中添加调试信息
setup() {
  console.log('Plugin setup called', this.meta);
},

component: ({ api }) => {
  console.log('Component rendered with API:', api);
  return <div>Debug component</div>;
}

示例插件

基础插槽插件

create-building-plugin create status-indicator

选择插槽类型: sidebar-menu-item

路由页面插件

create-building-plugin create sensor-dashboard

选择包含路由组件: 是

高级功能插件

create-building-plugin create building-control

包含完整的 CRUD 操作、图表展示和实时数据更新。

贡献和支持

报告问题

在 GitHub Issues 中报告 bug 或请求新功能。

开发贡献

1. Fork 项目
2. 创建功能分支: git checkout -b feature/new-template
3. 提交更改: git commit -m 'Add new template'
4. 推送分支: git push origin feature/new-template
5. 创建 Pull Request

许可证

MIT License - 详见 LICENSE 文件

开始构建你的第一个插件吧！ 🚀

create-building-plugin create my-awesome-plugin