跳到主要内容

快速开始

create-ydesign 是一个画布编辑器项目脚手架，专门用来快速初始化基于 @ydesign/react-editor 的编辑器项目。

它提供多种垂类场景模板（完整设计编辑器 / 最小编辑器 / 图片编辑器），每个场景都计划提供 React 与 Vue 两种框架版本，并区分 JavaScript 和 TypeScript 语言版本。

🚧 目前仅 React 流程已打通。Vue 版本仍在开发中，选中后会给出提示并退出，敬请期待。

环境要求​

  • Node.js 20.19+ / 22.12+（与 Vite 7 的要求一致）
  • 一个包管理器：npm / pnpm / yarn 任选其一

搭建你的第一个 Ydesign 项目​

在终端执行下面的命令，按提示操作即可：

npm create ydesign@latest

随后脚手架会进入交互式向导，依次询问：

  1. 项目名称（Project name） —— 默认 ydesign-project，将作为创建的目录名
  2. 是否覆盖（仅当目标目录非空时）—— 「清空目录后继续 / 忽略文件直接继续 / 取消」
  3. 包名称（package name） —— 当项目名不是合法的 npm 包名时才会询问，默认自动转换
  4. 选择一个框架（Select a framework） —— React / Vue（开发中）
  5. 选择语言版本（Select a variant） —— TypeScript / JavaScript
  6. 选择一个模板（Select a template） —— 见下方可选模板
  7. 是否立即安装并启动（Install with <pm> and start now?） —— 选 Yes 自动跑 install + dev，选 No 仅生成项目并打印接下来的命令

整体交互如下（以 React + TypeScript + editor 为例）：

✔ 项目名称：       my-editor
✔ 选择一个框架：    React
✔ 选择语言版本：    TypeScript
✔ 选择一个模板：    editor
✔ 使用 npm 安装依赖并立即启动？  Yes

正在 /Users/you/my-editor 中创建项目...
使用 npm 安装依赖...
启动开发服务器...

  VITE  ready in 284 ms
  ➜  Local:   http://localhost:5173/

如果在「选择框架」时选了 Vue，会提示版本正在开发中并直接退出：

🚧 Vue 版本正在开发中，敬请期待！
   目前可用：React（JavaScript / TypeScript）

通过命令行参数直接指定​

如果你已经想好了项目名和模板，可以用命令行参数跳过交互：

# 注意：npm 需要额外的 -- 把参数透传给脚手架
npm create ydesign@latest my-editor -- --template react-editor-ts

⚠️ 关于 npm 那个 --：npm create 会先消费它自己的参数，-- 之后的内容才会原样传给 create-ydesign。所以用 npm 时 --template 前面必须有 --；而 pnpm / yarn 不需要。

--template（简写 -t）的命名规则为 <框架>-<场景>[-ts]，JavaScript 版不带后缀，TypeScript 版带 -ts（与 create-vite 的命名一致）：

  • react-editor-ts / react-editor
  • react-minimal-ts / react-minimal
  • react-photo-ts / react-photo

可选模板​

每个垂类场景模板都同时提供 TypeScript 版 和 JavaScript 版：

场景说明TypeScriptJavaScript
editor完整设计编辑器：顶栏 + 侧边栏 + 工具栏 + 画布 + 多语言 + 主题切换react-editor-tsreact-editor
minimal最小可运行编辑器：仅工具栏 + 画布 + 缩放按钮react-minimal-tsreact-minimal
photo图片编辑器模式：上传 / 图片 / 蒙版 / 滤镜react-photo-tsreact-photo

每个模板都是一个标准的 Vite + React 18 工程，开箱包含：

  • 已配置好的 @ydesign/react-editor 与必要的 peer 依赖（antd、mobx、styled-components 等）
  • 引入编辑器样式的 import '@ydesign/react-editor/style.css'
  • 一个可直接运行的 src/App.tsx（或 src/App.jsx）示例

🚧 Vue 模板（vue-editor-ts / vue-editor 等）正在开发中，预计随 @ydesign/vue-editor 一起发布。

命令行选项​

选项说明
-t, --template <name>指定模板（跳过框架/语言/模板三步交互），如 react-editor-ts
--overwrite目标目录非空时直接清空后继续
--install创建后自动安装依赖并启动开发服务器
--no-install不自动安装，仅生成项目并打印接下来的命令
-h, --help显示帮助信息

ℹ️ 自动安装会沿用当前包管理器：用 npm create ydesign 就跑 npm install + npm run dev，用 yarn create ydesign 就跑 yarn + yarn dev，用 pnpm create ydesign 就跑 pnpm install + pnpm dev。

运行项目​

如果你在向导里选了 Yes，脚手架会自动安装依赖并启动开发服务器，不需要手动操作。

如果选了 No，按照终端打印的命令进入项目即可：

cd my-editor
npm install
npm run dev

打开浏览器即可看到编辑器界面。生成后的项目结构大致如下（以 react-minimal-ts 为例）：

my-editor/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── src/
    ├── main.tsx          # 应用入口
    ├── App.tsx           # 编辑器示例（创建 store + 渲染组件）
    └── vite-env.d.ts

JavaScript 版（react-minimal）则不带 tsconfig.* 与 vite-env.d.ts，源码后缀为 .jsx：

my-editor/
├── index.html
├── package.json
├── vite.config.js
└── src/
    ├── main.jsx
    └── App.jsx

src/App.tsx（或 App.jsx）里通过 createStore 创建编辑器数据源：

import createStore from '@ydesign/react-editor/model/store';
import '@ydesign/react-editor/style.css';

const store = createStore({
  key: 'YOUR_LICENSE_KEY', // 👈 替换成你的 YDesign License Key
});

🔑 模板中的 key 是占位符。本地开发时可以先保留占位符跑通界面，正式使用时请替换为你的 YDesign License Key。

不想用脚手架？​

脚手架只是为了让你少敲几行配置。如果你想把编辑器接入一个已有项目，直接安装包即可，无需脚手架：

npm install @ydesign/react-editor

具体的接入代码（一键启动 / 组合使用 / Headless）见 概览 · 快速上手。

下一步​

遇到问题或有功能建议？欢迎到 GitHub Issues 反馈。