内容
# dashcraft
[](https://github.com/Nishant-Chaudhary5338/dashcraft/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/dashcraft-core)
[](LICENSE)
[](CONTRIBUTING.md)
**无头 React 仪表盘库。四个布尔属性。您的样式。**
dashcraft 为您提供拖拽网格、可调整大小的小部件、KPI 卡片、recharts 图表（条形图、折线图、面积图、饼图、散点图、雷达图）+ 层次结构图表（热力图、树形图、日晕图）、持久化布局和 MCP 代码生成服务器 — 无需接触您的设计系统。
→ **[实时网站和游乐场](https://dashcraft.digitribe.world)** · [文档](https://dashcraft.digitribe.world/docs) · [npm](https://www.npmjs.com/package/dashcraft-core)
---
## 为什么选择 dashcraft？
| 痛点 | dashcraft |
| ------------------------------------------------ | -------------------------------------------------------- |
| 每个仪表盘库都强制使用其设计系统 | 完全无头 — 引入 Tailwind、CSS Modules 或不引入 |
| 将 recharts 连接到拖拽需要数天 | `drag resize settings delete` — 四个属性，搞定 |
| AI 工具不知道您的组件 API | `llms.txt` + MCP 代码生成服务器内置 |
| 每次保存布局都是自定义构建 | `persistenceKey="key"` — 一个属性，自动 localStorage |
---
## 安装
```sh
npm install dashcraft-core
# 图表对等依赖（条形图、折线图、面积图、饼图、散点图、雷达图 + 层次结构图表）
npm install recharts
```
---
## 快速开始
小部件会渲染自己的卡片，因此可以直接将它们放入 `<Dashboard>` 并使用 `defaultPosition` / `defaultSize` 定位：
```tsx
import { Dashboard } from "dashcraft-core";
import { KPIWidget } from "dashcraft-core/widgets/kpi";
import { RechartsWidget } from "dashcraft-core/widgets/recharts";
import "dashcraft-core/styles.css";
const data = [
{ month: "Jan", revenue: 12400 },
{ month: "Feb", revenue: 15600 },
{ month: "Mar", revenue: 18200 },
];
export function SalesDashboard() {
return (
<Dashboard persistenceKey="sales" defaultEditMode>
<KPIWidget
id="revenue"
label="收入"
value={46200}
previousValue={38000}
format="currency"
drag
resize
defaultPosition={{ x: 0, y: 0 }}
defaultSize={{ width: 280, height: 130 }}
/>
<RechartsWidget
id="chart"
title="每月收入"
chartType="bar"
data={data}
series={[{ dataKey: "revenue", name: "收入", color: "#C2FF3D" }]}
xAxisKey="month"
drag
resize
settings
defaultPosition={{ x: 296, y: 0 }}
defaultSize={{ width: 560, height: 320 }}
/>
</Dashboard>
);
}
```
---
## 布尔 API
每个交互行为都是 `DashboardCard` 上的一个布尔属性：
| 属性 | 功能 |
| ------------ | ---------------------------------- |
| `drag` | 通过 @dnd-kit 启用拖拽 |
| `resize` | 显示调整大小的句柄 |
| `settings` | 显示设置齿轮图标 |
| `delete` | 显示删除按钮 |
| `viewSizes` | 双击循环预设尺寸 |
没有配置对象。没有冗长的属性名称。只有布尔值。
---
## 组件
| 组件 | 目的 |
| ------------------- | ------------------------------------------------ |
| `<Dashboard>` | 根网格容器，管理状态 + 持久化 |
| `<DashboardCard>` | 小部件包装器，带有所有行为属性 |
| `<KPIWidget>` | 带有趋势指标的指标卡 |
| `<RechartsWidget>` | recharts（条形图、折线图、面积图、饼图、散点图、雷达图） |
| `<HierarchyWidget>` | 热力图、树形图、日晕图（内置） |
---
## 钩子
| 钩子 | 目的 |
| --------------------- | ----------------------------------------------- |
| `useDashboard(id)` | 访问状态，切换编辑模式 |
| `usePersistedState(k)` | 本地状态自动持久化到存储 |
| `useWidgetEvents(id)` | 订阅设置/删除/调整大小/拖拽事件 |
| `usePersistence(key)` | 使用自定义存储手动保存/恢复 |
| `useDraggable(id)` | 原始 @dnd-kit 拖拽状态 |
| `useResize(id)` | 原始调整大小状态 |
---
## AI 原生
dashcraft 构建为开箱即用地与 AI 工具配合使用：
- **`llms.txt`** at [`/llms.txt`](https://dashcraft.digitribe.world/llms.txt) — 机器可读的 API 参考，任何 LLM 都可以获取
- **`AGENTS.md`** at [`/AGENTS.md`](https://dashcraft.digitribe.world/AGENTS.md) — 用于代码生成的完整代理指南
- **MCP 服务器** — `dashcraft-mcp-codegen` 用于 Claude Desktop、Cursor 和任何 MCP 客户端
### MCP 设置
```sh
npm install -g dashcraft-mcp-codegen
```
添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"dashcraft": {
"command": "dashcraft-codegen"
}
}
}
```
工具：`analyze_dashboard` · `generate_code` · `generate_project`
---
## 源码结构
```
packages/
core/ dashcraft-core — React 库
apps/
site/ 产品站点（Next.js 15）
tools/
codegen/ dashcraft-mcp-codegen — MCP 服务器
```
---
## 开发
```sh
# 安装依赖
pnpm install
# 启动所有应用
pnpm dev
# 仅启动站点
pnpm --filter site dev
# 构建库
pnpm --filter dashcraft-core build
# 运行库测试
pnpm --filter dashcraft-core test
```
需要 Node.js 20+，pnpm 9+。
---
## 贡献
非常欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取完整指南。
简要版本：
1. Fork → 分支 → 编写代码
2. `pnpm --filter dashcraft-core build` 必须通过
3. `pnpm --filter dashcraft-core test` 必须通过
4. 打开一个带有已填写的检查清单的 PR
---
## 许可证
MIT © [Nishant Chaudhary](https://github.com/Nishant-Chaudhary5338)
