编辑器配置

@ydesign/react-editor 提供了一组全局配置类的 API，用来调整编辑器的运行时行为：上传策略、后端域名、多语言、字体、颜色预设、超时等。它们和定制化章节的关注点不同 —— 定制化偏 UI 替换/裁剪，而本页这些 API 是「一次设置、全局生效」的开关。

💡 本页所有 API 都来自真实仓库实现。所有方法都应该在 createDesignEditorApp(...) 之前调用，确保编辑器初始化时就读到正确配置。

---

自定义图片上传

默认的 SidePanel 组件里有一个 Upload 标签，让用户把本地图片导入到画布。开箱即用的实现会把本地文件转成 base64 字符串塞进 image 元素里。

base64 写法虽然能即时使用，但会让你的设计稿 JSON 体积膨胀得非常快 —— 一张 2MB 的图就足以让 JSON 超过 3MB。因此，强烈建议你接入自己的对象存储（OSS / S3 / COS / 自建图床都可以）：上传到服务器后只把短链塞回 JSON，体积小、加载快、还能复用 CDN。

import { setUploadFunc } from '@ydesign/react-editor/side-panel/upload-panel';

// 自定义上传逻辑，签名是 (file: File) => Promise<string>
async function upload(localFile: File) {
  const formData = new FormData();
  formData.append('files[]', localFile);

  const res = await fetch('https://your-api.com/upload', {
    method: 'POST',
    body: formData,
  });
  const { url } = await res.json();

  // 必须返回一个最终可用的 URL 字符串
  return url;
}

setUploadFunc(upload);

设置完成后，从「上传」面板选取的本地图片会自动走你的逻辑，编辑器内部接到 URL 后会直接当成普通图片元素使用。

---

切换后端域名 / 替换接口实现

@ydesign/react-editor 内置了若干后端接口（字体列表、模板列表、图片上传、消除笔等）。如果你的后端域名不同，只需要一行：

import { setBaseURL } from '@ydesign/react-editor';

setBaseURL('https://api.your-company.com');

如果某个接口的路径或参数和默认实现不一致，可以单独覆盖：

import { setAPI } from '@ydesign/react-editor';

// 把模板列表接口指向自家系统
setAPI('templateList', () => ({
  url: 'https://your-api.com/v2/design-templates',
}));

// 上传接口 —— 支持指定 method / url / data
setAPI('uploadImage', () => ({
  method: 'POST',
  url: 'https://your-api.com/assets/upload',
}));

可被覆盖的接口名：fontList、templateList、templateDetail、uploadImage、psdParse、createRecord、updateRecord、recordDetail、resourcesDetail、teamFontList、inpaint。

---

多语言（i18n）

如果想把 UI 翻译成另一种语言，或者只是改某些标签的文案：

import { setTranslations } from '@ydesign/react-editor';

setTranslations({
  sidePanel: {
    text: '文字',
    myFonts: '我的字体',
  },
});

如果你需要查看完整的 key 结构（用于翻译为其他语言）：

import { getTranslations } from '@ydesign/react-editor';

console.log(getTranslations());

📮 如果你已经为某种语言完成了完整翻译，欢迎通过 GitHub Issue 或 PR 把成果反馈给我们 —— 这能让 @ydesign 官方默认翻译变得更全面，也让其他人能直接复用你的工作。

同一套翻译机制也可以用在你的自定义组件里：

import { observer } from 'mobx-react-lite';
import { t } from '@ydesign/react-editor/utils/l10n';

const App = observer(() => {
  return <div>{t('sidePanel.yourLabel')}</div>;
  // sidePanel.yourLabel 是翻译字典中的 key
});

t 是 translate 的别名，二者完全等价。

---

字体管理

@ydesign 中的字体来源分为三类：

1. Google Fonts
2. 用户字体 —— 通过 store.fonts 添加，会随设计稿一起序列化
3. 全局字体 —— 通过全局 API 添加，对所有用户都生效，但不会进入设计稿 JSON

(1) Google Fonts

默认情况下 @ydesign 会从 Google Fonts 加载字体。每个字体默认会加载 4 种变体：常规 / 斜体 / 粗体 / 粗斜体。如果你只需要部分变体（节省请求量）：

import { setGoogleFontsVariants } from '@ydesign/react-editor';

// 默认值就是这个
setGoogleFontsVariants('400,400italic,700,700italic');

// 仅加载常规与细体两种
setGoogleFontsVariants('400,100');

获取当前的变体配置：

import { getGoogleFontsVariants } from '@ydesign/react-editor';

console.log(getGoogleFontsVariants()); // '400,400italic,700,700italic'

如果需要直接拼出某个 Google Fonts 的 CSS 链接（例如在自定义 UI 中预览）：

import { getGoogleFontsUrl, injectGoogleFont } from '@ydesign/react-editor';

const url = getGoogleFontsUrl('Roboto');
// → https://fonts.googleapis.com/css?family=Roboto:400,400italic,700,700italic

// 直接把 Google 字体注入到页面
injectGoogleFont('Roboto');

(2) 用户字体

如果想给当前用户单独添加 / 移除字体，使用 Store Fonts API。

通过 store.fonts 添加的字体会随 store.toJSON() 一起导出。这意味着设计稿在另一个用户那边打开时，会自动加载相同的字体；用户也可以从默认「文字」侧边面板里的「字体」标签自行管理。

(3) 全局字体

如果有一批字体你希望对所有用户都开启（例如公司品牌字体），用全局 API：

import { addGlobalFont } from '@ydesign/react-editor';

// 通过 URL 添加
addGlobalFont({
  fontFamily: 'MyCustomFont',
  url: 'https://your-cdn.com/fonts/MyCustomFont.woff2',
});

// 更精细地控制不同字重 / 字形
addGlobalFont({
  fontFamily: 'MyCustomFont',
  styles: [
    {
      src: 'url(https://your-cdn.com/fonts/MyCustomFont-Regular.ttf)',
      fontStyle: 'normal',
      fontWeight: 'normal',
    },
    {
      src: 'url(https://your-cdn.com/fonts/MyCustomFont-Bold.ttf)',
      fontStyle: 'normal',
      fontWeight: 'bold',
    },
  ],
});

// 如果某字体已经通过 CSS 在外部加载好，仅注册即可
// 之后该字体名就会出现在工具栏的字体下拉里
addGlobalFont({
  fontFamily: 'MyCustomFont',
});

对应的删除与替换：

import { removeGlobalFont, replaceGlobalFonts } from '@ydesign/react-editor';

// 删除单个
removeGlobalFont('MyCustomFont');

// 一次性替换全部全局字体
replaceGlobalFonts([
  { fontFamily: 'Inter', url: 'https://your-cdn.com/Inter.woff2' },
  { fontFamily: 'Roboto Mono', url: 'https://your-cdn.com/RobotoMono.woff2' },
]);

⚠️ 全局字体不会进入 store.toJSON() 导出的 JSON。如果设计稿要在没有调用过 addGlobalFont 的环境下重新打开，对应字体会丢失。需要持久化的字体请放到 store.fonts 里。

字体加载超时回调

字体来自外网，偶尔会有加载失败的情况。给一个 toast 提示是合理的做法：

import { setFontLoadTimeoutCallback, setFontLoadTimeout } from '@ydesign/react-editor';
import { message } from 'antd';

// 加载超时阈值（毫秒）
setFontLoadTimeout(15_000);

// 超时时的回调，msg 是带字体名的提示文案
setFontLoadTimeoutCallback(msg => {
  message.warning(msg);
});

---

资源加载超时

字体之外还有图片 / SVG / 模板 JSON 等其他远程资源。它们共用一个全局超时设置：

import { setAssetLoadTimeout, getAssetLoadTimeout } from '@ydesign/react-editor';

setAssetLoadTimeout(30_000); // 30 秒
console.log(getAssetLoadTimeout()); // 30000

---

修改背景色预设

「背景」面板默认会展示一组预设颜色。如果你的产品有品牌色 / 主题规范，可以一次性替换：

import { setBackgroundColorsPreset } from '@ydesign/react-editor/side-panel/background-panel';

setBackgroundColorsPreset(['#ffffff', '#000000', '#f5f5f5', '#ff4d4f', '#1677ff', '#52c41a']);

---

注册自定义工具栏组件

工具栏会根据当前选中元素的类型（textbox、image、path 等）自动渲染。如果你新加了一种自定义元素，或者想替换某种元素的工具栏：

import { registerToolbarComponent } from '@ydesign/react-editor/toolbar';
import { MyQRCodeToolbar } from './my-qrcode-toolbar';

// 选中 type 为 'qrcode' 的元素时显示 MyQRCodeToolbar
registerToolbarComponent('qrcode', MyQRCodeToolbar);

工具栏组件接收 { store } 作为 props，里面就可以基于 store.selectedElements 做你需要的操作。

---

何时调用这些 API？

所有这些配置都是进程级单例，建议在应用入口、createDesignEditorApp(...) 之前调用一次：

// app.tsx
import { setBaseURL, setTranslations, addGlobalFont, setUploadFunc, createDesignEditorApp } from '@ydesign/react-editor';
import zhCN from './i18n/zh-CN.json';

// 1) 配置全局
setBaseURL(import.meta.env.VITE_API_BASE);
setTranslations(zhCN);
addGlobalFont({ fontFamily: 'Brand-Sans', url: '/fonts/brand.woff2' });
setUploadFunc(myUpload);

// 2) 启动编辑器
createDesignEditorApp({
  container: document.getElementById('root')!,
  key: 'YOUR_API_KEY',
});

---

延伸阅读

• 定制化 —— 替换 / 扩展 UI 的方式
• 概览 —— Core / UI 两层架构
• Store API —— 画布状态读写