Ydesign

Ydesign 是一套用于构建「Canva / 创客贴一类在线设计编辑器」的 JavaScript SDK。它不是一个成品应用，而是一组开箱即用的 JS 模块、组件库与画布渲染引擎，帮助开发者在几天之内搭起一款功能完整、可深度定制的设计编辑器。

🎯 典型场景：电商商品自定义、社交媒体设计工具、印刷物料生产、证件照编辑器、海报 / 横幅生成器、企业内部 VI 模板…… 具体可以看案例展示。

为什么要再造一个编辑器？

市面上已有一些优秀的画布底层库（如 fabric.js、Konva），以及闭源的商业 SaaS 方案（如 Polotno）。但自研过程中遇到的问题仍然明显：

底层库只解决"渲染"：选中、吸附、标尺、辅助线、撤销重做、图层、组合、滤镜、裁剪、消除笔……这些业务能力仍需要你一行行去写。
商业 SaaS 不够自由：定制界面、替换组件、接私有化的素材 / AI 能力时束手束脚。
React / Vue 落地需要胶水：fabric 是命令式的，React / Vue 是声明式的，如何把画布状态同步到 UI、如何做响应式，每个团队都要踩一遍坑。

Ydesign 的目标：

✅ 提供成熟的画布业务封装（20+ Handler：滤镜、裁剪、辅助线、标尺、历史、锁、组、快捷键、AI 消除笔等），开箱即用
✅ 保持架构清晰、分层明确，上层 UI 完全可替换、可裁剪
✅ 用 MobX + MST 做数据层，让 React / Vue 写起来像"声明式"的 fabric
✅ 以 Monorepo + 多包 形式分发，React / Vue / Headless 各取所需

三个包组成一个生态

Ydesign 仓库是一个 pnpm + turborepo 的 Monorepo，按职责拆为三个独立发布的 npm 包：

                    ┌─────────────────────────────┐
                    │   @ydesign/core             │
                    │   画布渲染核心               │
                    │   （纯 TS + fabric.js v6）   │
                    └──────────────┬──────────────┘
                                   │
                 ┌─────────────────┴─────────────────┐
                 │                                   │
     ┌───────────▼───────────┐           ┌───────────▼───────────┐
     │  @ydesign/react-editor │           │   @ydesign/vue-editor  │
     │  React 版 UI 层        │           │   Vue 版 UI 层（规划）  │
     │  React 18 + Antd v6    │           │   Vue 3 + Ant Design V │
     └───────────────────────┘           └───────────────────────┘

每一层都可以独立使用，互相之间通过公共的 @ydesign/core 桥接。

`@ydesign/core`

画布渲染核心

纯 TypeScript 实现的画布业务引擎，零 UI 依赖、不写一行 CSS。它接受一份 Fabric canvas，在其之上抽象出 20+ 个独立 Handler（每个 Handler 负责一块业务），由顶层 Editor 类统一管理。

能力域	代表性 Handler
画布基础	`WorkareaHandler` / `ZoomHandler` / `RendererHandler` / `RulerHandler` / `ResizeHandler`
对象与图层	`ObjectsHandler` / `LayerHandler` / `AlignmentHandler` / `LockHandler` / `GuidelinesHandler`
交互	`EventHandler` / `HotkeyHandler` / `CustomHandler`
历史	`HistoryHandler` / `SceneHandler`
图片与 AI	`ImageCropHandler` / `ImageFiltersHandler` / `ImageStrokeHandler` / `InpaintHandler`

适合只要画布不要 UI 的场景（你自己做 UI）、或者想扩展新元素类型（比如二维码、条形码）。

`@ydesign/react-editor`

React 版 UI 层（已发布）

基于 React 18 + Ant Design v6 + MobX + mobx-state-tree 构建，是 Ydesign 目前最成熟、推荐首选的 UI 层。内部遵循「MST store 单一数据源 + observer 响应式渲染」模式，让开发者写组件几乎不用关心 fabric 的命令式事件流。

提供：

<Workspace /> 画布工作区
<Toolbar /> 顶部工具栏（按选中元素类型自动切换）
<SidePanel /> 左侧业务面板（10 个内置面板：模板 / 文字 / 图片 / 形状 / 上传 / 背景 / 图层 / 尺寸 / 证件照 / AI 消除笔）
<ZoomButtons /> 缩放控件
createStore / createDesignEditorApp 等入口工厂

`@ydesign/vue-editor`

Vue 版 UI 层（规划中）

基于 Vue 3 + Composition API + Pinia，与 React 版在能力、API 命名、JSON schema 上完全对齐。当前仍在设计阶段，优先级在 v1.0 稳定发布后。

两个 UI 层共享同一个 @ydesign/core，这意味着：

在 React 版导出的设计稿 JSON，可以直接被 Vue 版打开（反之亦然）
画布能力只需要维护一份，两套 UI 并行演进
团队可以按前端栈选型，不被锁死

详情见 Vue 集成页面的路线图。

分层原则

用一句话说清 Ydesign 的分层哲学：画布业务在 core，UI 在上层；UI 只读 store，state 单向流动。

┌──────────────────────────────────────────────────────────────┐
│              React 组件 / Vue 组件（你的应用）                  │
└──────────────────────────┬───────────────────────────────────┘
                           │  observer 订阅 / actions 修改
                           ▼
┌──────────────────────────────────────────────────────────────┐
│              MST store（单一数据源）                           │
│              width / height / fonts / selectedElementsIds…   │
└──────────────────────────┬───────────────────────────────────┘
                           │  store.editor.xxxHandler.xxx()
                           ▼
┌──────────────────────────────────────────────────────────────┐
│              @ydesign/core · Editor + 20+ Handler            │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
                    fabric.Canvas（fabric.js v6）

这种分层意味着：

🎨 想要把 UI 换成 Solid / 原生 Web Components？重写 UI 层即可，core 完整复用
🧩 想嵌入自家 UI 组件体系（Chakra / MUI）？替换 react-editor 里的局部面板
🎯 只需要 headless 画布？直接用 @ydesign/core，UI 完全自研

快速上手

🚀 想用一条命令直接生成可运行的项目？请看快速开始 · 使用脚手架。下面介绍的是把 Ydesign 接入已有项目的方式。

安装

# React 项目：安装完整 UI 版（推荐）
npm install @ydesign/react-editor

# 只要画布能力（Headless / Vue / Angular 项目）
npm install @ydesign/core

# Vue 项目（规划中，敬请期待）
# npm install @ydesign/vue-editor

一键启动一个完整编辑器

import { createDesignEditorApp } from '@ydesign/react-editor';
import '@ydesign/react-editor/style.css';

const { store, root } = createDesignEditorApp({
  container: document.getElementById('root')!,
  key: 'YOUR_API_KEY',
  // 按需裁剪面板
  sections: ['templates', 'text', 'photos', 'shapes', 'background', 'layers'],
});

// store 是 MST 实例，可用来读写状态
store.setSize({ width: 1200, height: 800 });

组合使用（保留最大自由度）

当你想把工具栏、侧边栏、画布自由布局：

import { DesignEditorContainer, SidePanelWrap, WorkspaceWrap, createStore, SidePanel } from '@ydesign/react-editor';
import Workspace from '@ydesign/react-editor/canvas/workspace';
import Toolbar from '@ydesign/react-editor/toolbar';
import ZoomButtons from '@ydesign/react-editor/toolbar/zoom-buttons';
import '@ydesign/react-editor/style.css';

export const App = () => {
  const store = createStore({ key: 'YOUR_API_KEY' });

  return (
    <DesignEditorContainer>
      <SidePanelWrap>
        <SidePanel store={store} />
      </SidePanelWrap>
      <WorkspaceWrap>
        <Toolbar store={store} />
        <Workspace store={store} />
        <ZoomButtons store={store} />
      </WorkspaceWrap>
    </DesignEditorContainer>
  );
};

直接使用 Core（Headless）

如果你只需要画布能力、UI 完全自研：

import { Editor } from '@ydesign/core';

const editor = new Editor({
  id: 'my-canvas',
  container: document.getElementById('stage')!,
  config: {
    size: { width: 1920, height: 1080 },
  },
});

// 添加一个文字
editor.objectsHandler.add({
  type: 'text',
  text: 'Hello Ydesign',
  left: 100,
  top: 100,
  fill: '#111',
});

// 绑定快捷键
editor.hotkeyHandler.bind({
  'ctrl+z,command+z': () => editor.historyHandler.undo(),
  'ctrl+shift+z,command+shift+z': () => editor.historyHandler.redo(),
});

技术栈

	`@ydesign/core`	`@ydesign/react-editor`	`@ydesign/vue-editor`
画布底层	fabric.js v6	共用 core	共用 core
框架	纯 TS，零依赖	React 18	Vue 3
组件库	—	Ant Design v6	Ant Design Vue（规划）
状态管理	内部 `State`	MobX + mobx-state-tree	Pinia（规划）
样式	—	styled-components + Tailwind v4	规划中
图标	—	lucide-react + Antd Icons	规划中
语言	TypeScript 5	TypeScript 5	TypeScript 5
状态	公开预览（0.1.x）	公开预览（0.2.x）	🚧 规划中

工具链：pnpm workspace + turborepo + tsup + tsc。

与同类方案对比

维度	Ydesign	纯 fabric.js	Konva	Polotno
渲染层	fabric.js v6	✓	自研	自研（闭源）
上层业务封装	✅ 20+ Handler	✗	✗	✅
开箱即用 UI	✅ Antd 组件	✗	✗	✅ Blueprint
支持框架	React ✅ + Vue 🚧 + Headless ✅	纯 JS	纯 JS + `react-konva` / `vue-konva`	仅 React
响应式数据流	✅ MobX + MST	✗	✗	✅ MST
Core / UI 分包	✅ 3 包分发	—	—	❌（单包）
开源可定制	✅	✅	✅	❌（商业授权）
TypeScript	✅ 全链路	⚠️ 类型不全	✅	✅

下一步

👉 快速开始 —— 用脚手架 create-ydesign 一键创建项目
👉 定制化 —— 如何替换 / 扩展 UI
👉 集成方式总览 —— React / Vue / 无框架 / Iframe 四种方式对比
👉 侧边面板总览 —— 10 个内置面板的用法
👉 云渲染 API —— 服务端批量生成 / 高清导出
👉 案例展示 —— 典型应用场景

遇到问题或有功能建议？欢迎到 GitHub Issues 提。想投票决定路线图？路线图页面见。

为什么要再造一个编辑器？​

三个包组成一个生态​

@ydesign/core​

@ydesign/react-editor​

@ydesign/vue-editor​

分层原则​

快速上手​

安装​

一键启动一个完整编辑器​

组合使用（保留最大自由度）​

直接使用 Core（Headless）​

技术栈​

与同类方案对比​

下一步​