跳到主要内容

无框架集成

ydesign 的官方 UI 版本是 @ydesign/react-editor，但如果你的页面没有使用 React、也不想单独搭构建工具，完全可以通过一段 <script> 标签把编辑器直接嵌入到任意 HTML 页面里。

我们为此提供了打包好的 UMD / IIFE 产物，通过 CDN 引入后会在 window 上挂出一个全局方法 createYdesignApp，一行调用即可得到完整编辑器。

使用方式​

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <title>Ydesign Demo</title>

    <!-- 1. 引入编辑器样式 -->
    <link rel="stylesheet" href="https://unpkg.com/@ydesign/react-editor/dist/style.css" />

    <!-- 2. 引入编辑器 bundle（注意：放在 <body> 末尾，不要放 <head>） -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
      #container {
        width: 100vw;
        height: 100vh;
      }
    </style>
  </head>
  <body>
    <!-- 3. 给编辑器一个容器 -->
    <div id="container"></div>

    <!-- 4. 引入 bundle，它会在 window 上挂出 createYdesignApp -->
    <script src="https://unpkg.com/@ydesign/react-editor/dist/ydesign.bundle.js"></script>

    <!-- 5. 初始化 -->
    <script>
      const { store } = window.createYdesignApp({
        container: document.getElementById('container'),
        key: 'YOUR_API_KEY',
        // 可选：只开启你需要的侧边面板
        // sections: ['templates', 'text', 'photos', 'shapes', 'background', 'layers'],
      });

      // store 是完整的 MobX-State-Tree 实例
      // 你可以在这里做任何画布操作，比如：
      // store.setSize(1200, 800);
      // store.editor.zoomHandler.zoomToFit();
    </script>
  </body>
</html>

什么时候适合用这种方式？​

✅ 适合：

  • 静态 HTML 页面、Jekyll / Hugo 博客、老项目
  • 没有 npm / 构建工具 / bundler 的环境
  • 想快速出个 Demo 验证一下编辑器
  • 嵌入到某个现有页面的某块区域，不影响整个页面的技术栈

⚠️ 不适合：

  • 需要对侧边面板、工具栏做深度定制（因为无法 import 子模块）
  • 需要服务端渲染（SSR）
  • 对首屏加载体积敏感（UMD bundle 会打包全部能力，体积约 700KB+ gzipped）

如果上面任何一条命中，更推荐使用 非 React 项目集成 的打包方式，或者直接安装 npm 包。

API 与 createDesignEditorApp 一致​

createYdesignApp 与 npm 包里的 createDesignEditorApp 是同一个函数，仅签名保持一致。所有 定制化 文档里的 API 都可用：

window.createYdesignApp({
  container: document.getElementById('container'),
  key: 'YOUR_API_KEY',
  sections: ['templates', 'text', 'photos', 'shapes', 'background'],
});

// 一些常用的定制方法，bundle 也会同步挂到 window 上
window.Ydesign.setBaseURL('https://api.your-company.com');
window.Ydesign.setTranslations({
  /* 多语言字典 */
});
window.Ydesign.setUploadFunc(async file => {
  // 自定义上传逻辑
});

完整示例​

下面是一个可以直接另存为 index.html 双击打开的最小示例：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="https://unpkg.com/@ydesign/react-editor/dist/style.css" />
    <style>
      body,
      html {
        margin: 0;
        height: 100%;
      }
      #app {
        height: 100vh;
      }
    </style>
  </head>
  <body>
    <div id="app"></div>
    <script src="https://unpkg.com/@ydesign/react-editor/dist/ydesign.bundle.js"></script>
    <script>
      window.createYdesignApp({
        container: document.getElementById('app'),
        key: 'YOUR_API_KEY',
      });
    </script>
  </body>
</html>

常见问题​

Q：为什么必须把 <script> 放在 <body> 末尾？ A：bundle 启动时会查找 container 元素。如果脚本放在 <head> 里执行时容器还没渲染出来，会直接报错。

Q：key 是什么？ A：是你调用后端 API（模板、字体、AI 能力等）时使用的凭据，可以在 ydesign 控制台申请。Demo / 本地调试可以随便填一个字符串。

Q：bundle 是否支持按需加载？ A：暂不支持。需要按需加载请使用 npm 包方式，让你的构建工具（Vite / Webpack / Rspack）自己做 tree-shaking。