# designable

**Repository Path**: bill_law6/designable

## Basic Information

- **Project Name**: designable
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-05-14
- **Last Updated**: 2025-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Designable 项目 - 通用可视化拖拽设计器

<p align="center">
<img width="600" src="https://img.alicdn.com/imgextra/i1/O1CN01bg1tTN1p5ZOPmhKV0_!!6000000005309-55-tps-2200-981.svg">
</p>

---

## 项目简介

Designable 是一个通用的可视化拖拽设计器引擎，专为构建表单设计器、图表设计器、应用构建器等低代码/无代码场景而设计。基于现代化的 React/Vue 生态系统，提供了完整的设计器解决方案。

### 核心特性

- 🚀 **高性能**：流畅美观的拖拽体验，采用虚拟滚动和优化渲染
- 💡 **全场景覆盖**：支持表单、图表、页面等多种设计场景
- 🎨 **低代码/无代码**：可视化操作，无需编写代码
- 🏅 **强扩展性**：插件化架构，易于定制和扩展
- 🔧 **现代化架构**：基于 Vite、TypeScript、Vitest 构建
- 🌍 **多框架支持**：同时支持 React 和 Vue 框架

## 在线预览

- [基础示例](https://designable.netlify.app)
- [Antd 组件库示例](https://localhost:5173)
- [Shadcn 组件库示例](https://localhost:3100)

## 项目结构

```
designable/
├── packages/                    # 核心包
│   ├── core/                   # 设计器核心引擎
│   ├── shared/                 # 共享工具库  
│   ├── react/                  # React 适配层
│   ├── vue/                    # Vue 适配层
│   ├── react-sandbox/          # React 沙箱组件
│   └── react-settings-form/    # 属性设置表单
├── formily/                     # Formily 集成
│   ├── antd/                   # Ant Design 组件库
│   ├── shadcn/                 # Shadcn/UI 组件库
│   ├── setters/                # 属性设置器
│   └── transformer/            # 数据转换器
├── examples/                    # 示例项目
│   ├── basic/                  # 基础示例
│   ├── sandbox/                # 沙箱示例
│   └── multi-workspace/        # 多工作区示例
├── docs/                       # 文档
└── scripts/                    # 构建脚本
```

## 快速开始

### 环境要求

- Node.js >= 16.0.0
- pnpm >= 8.0.0

### 安装依赖

```bash
# 安装项目依赖
pnpm install

# 构建所有包
pnpm run build
```

### 本地开发

```bash
# 启动开发模式（监听文件变化自动重新构建）
pnpm run dev

# 启动不同示例项目
pnpm run start:basic        # 基础示例 (http://localhost:5174)
pnpm run start:shadcn       # Shadcn 示例 (http://localhost:3100)  
pnpm run start:sandbox      # 沙箱示例 (http://localhost:5174)
pnpm run start:designable   # Antd 示例 (http://localhost:3000)
```

### 运行测试

```bash
# 运行所有测试
pnpm run test

# 监听模式运行测试
pnpm run test:watch

# 生成测试覆盖率报告
pnpm run test:coverage

# 运行测试 UI 界面
pnpm run test:ui
```

### 代码质量检查

```bash
# 代码格式检查和修复
pnpm run lint

# 仅检查不修复
pnpm run lint:check

# TypeScript 类型检查
pnpm run type-check
```

## 核心概念

### 设计器引擎 (Engine)

设计器引擎是整个系统的核心，负责管理设计器的状态、事件和生命周期。

```typescript
import { Engine } from '@bill_law6/designable-core'

const engine = new Engine({
  drivers: [], // 驱动器配置
  effects: [], // 副作用配置  
  shortcuts: [], // 快捷键配置
})
```

### 树节点系统 (TreeNode)

TreeNode 是设计器中所有组件的抽象表示，支持树形结构的增删改查操作。

```typescript
import { TreeNode } from '@bill_law6/designable-core'

const node = new TreeNode({
  componentName: 'Form',
  props: { title: '表单标题' },
  children: []
})
```

### 组件资源 (Resources)

组件资源定义了可以拖拽到设计器中的组件列表。

```typescript
import { ComponentResource } from '@bill_law6/designable-react'

const resources = [
  {
    componentName: 'Form',
    title: '表单',
    icon: 'FormOutlined',
    elements: [
      {
        componentName: 'Form',
        props: {}
      }
    ]
  }
]
```

## 开发指南

### 创建自定义组件

1. **定义组件资源**：

```typescript
// 定义组件行为
export const FormBehavior = createBehavior({
  name: 'Form',
  extends: ['Field'],
  selector: (node) => node.componentName === 'Form',
  designerProps: {
    droppable: true,
    cloneable: true,
    deletable: true,
  },
  designerLocales: {
    'zh-CN': {
      title: '表单',
      addFormItem: '添加表单项',
    }
  }
})

// 定义组件资源
export const FormResource = createResource({
  icon: 'FormOutlined',
  elements: [
    {
      componentName: 'Form',
      props: {
        labelCol: 6,
        wrapperCol: 12,
      },
    },
  ],
})
```

2. **注册组件**：

```typescript
import { GlobalRegistry } from '@bill_law6/designable-core'

GlobalRegistry.registerDesignerBehaviors(FormBehavior)
GlobalRegistry.registerDesignerIcons({ FormOutlined })
```

### 构建打包

```bash
# 构建所有包
pnpm run build

# 构建特定包
pnpm --filter @bill_law6/designable-core run build

# 清理构建产物
pnpm run clean
```

### 版本发布

```bash
# 版本升级
pnpm run version:patch    # 补丁版本 x.x.1
pnpm run version:minor    # 次版本 x.1.x  
pnpm run version:major    # 主版本 1.x.x

# 发布到 npm
pnpm run release
```

## 可用包列表

| 包名 | 版本 | 描述 |
|------|------|------|
| @bill_law6/designable-core | 1.0.8 | 设计器核心引擎 |
| @bill_law6/designable-shared | 1.0.8 | 共享工具库 |
| @bill_law6/designable-react | 1.0.8 | React 适配层 |
| @bill_law6/designable-vue | 1.0.8 | Vue 适配层 |
| @bill_law6/designable-react-sandbox | 1.0.8 | React 沙箱组件 |
| @bill_law6/designable-react-settings-form | 1.0.8 | 属性设置表单 |
| @bill_law6/designable-formily-antd | 1.0.8 | Antd 组件库 |
| @bill_law6/designable-formily-shadcn | 1.0.8 | Shadcn 组件库 |
| @bill_law6/designable-formily-setters | 1.0.8 | 属性设置器 |
| @bill_law6/designable-formily-transformer | 1.0.8 | 数据转换器 |

## 技术栈

- **构建工具**: Vite 5.x
- **包管理**: pnpm 8.x + Lerna 8.x  
- **开发语言**: TypeScript 5.x
- **测试框架**: Vitest 1.x
- **UI 框架**: React 18.x / Vue 3.x
- **组件库**: Ant Design 5.x / Shadcn/UI
- **状态管理**: @formily/reactive
- **样式处理**: Less / CSS Modules

## 设计理念

### 1. 响应式架构

基于 @formily/reactive 的响应式状态管理，确保数据变化时 UI 的自动更新。

### 2. 可插拔设计

采用插件化架构，核心功能通过插件扩展，支持自定义驱动器、副作用和快捷键。

### 3. 多框架支持

通过适配层模式，同时支持 React 和 Vue 框架，共享核心逻辑。

### 4. 类型安全

全面使用 TypeScript，提供完整的类型定义和类型推导。

### 5. 性能优化

- 虚拟滚动优化大量节点渲染
- 异步组件加载减少初始包体积
- 精确的重新渲染控制

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

### 代码规范

- 使用 ESLint + Prettier 进行代码格式化
- 提交信息遵循 Conventional Commits 规范
- 添加必要的测试用例
- 更新相关文档

## 常见问题

### Q: 如何添加自定义组件？

A: 参考 `formily/shadcn/src/components` 目录下的组件实现，创建组件行为定义、资源定义和属性设置器。

### Q: 如何自定义主题？

A: 通过修改 CSS 变量或 Less 变量来自定义主题，参考 `packages/react/src/styles` 目录。

### Q: 如何调试设计器？

A: 使用浏览器开发者工具，结合 React/Vue DevTools 进行调试。

### Q: 性能优化建议？

A: 
- 避免在渲染组件中进行复杂计算
- 使用 memo/computed 缓存计算结果  
- 合理使用组件懒加载

## 版本历史

### v1.0.8 (2025-07-05)

- ✅ 完成 Vite 生态系统迁移
- ✅ 升级所有依赖到最新版本
- ✅ 优化构建配置和测试环境
- ✅ 添加 Shadcn/UI 组件库支持
- ✅ 完善 TypeScript 类型定义
- ✅ 重构文档和示例项目

### v1.0.7 及之前版本

参考 [CHANGELOG.md](./CHANGELOG.md) 了解详细版本历史。

## 许可证

MIT License - 详见 [LICENSE](./LICENSE) 文件。

## 鸣谢

本项目基于以下优秀的开源项目：

- [Formily](https://formilyjs.org/) - 阿里巴巴统一前端表单解决方案
- [Ant Design](https://ant.design/) - 企业级 UI 设计语言
- [Shadcn/UI](https://ui.shadcn.com/) - 现代化组件库
- [Vite](https://vitejs.dev/) - 下一代前端构建工具

感谢所有贡献者的辛勤付出！

---

**注意**: 本项目持续开发中，欢迎反馈问题和建议。更多技术细节请参考 [开发文档](./docs/README.md)。