跳到主要内容

指南

嵌入

配置

EditorConfig 和 RendererConfig 是每个自定义的入口。分别传入 Editor.create() 或 Renderer.render()。只有 containerId（以及渲染器的 data）是必填项，其他所有选项都有安全的默认值。

EditorConfig

将 EditorConfig 作为唯一参数传入 Editor.create()。必填的 containerId 必须与 DOM 中已存在的元素 id 匹配。

选项类型必填描述
containerIdstring是将承载编辑器的 DOM 元素的 ID。必须在调用 Editor.create() 之前存在于 DOM 中。
maxHeightnumber否编辑器的最大高度（像素）。设为 0（默认）表示不限高度。
minHeightnumber否编辑器的最小高度（像素）。默认值为 300。
onChange(data: EditorData) => void否文档每次变更时触发的回调函数。接收完整的 EditorData 快照。
onReady() => void否编辑器完全初始化并准备好接受 API 调用时触发的回调。
placeholderstring否编辑器为空时显示的占位符文本。默认为 "Start writing..."。
initialDataEditorData否编辑器挂载时预加载的 EditorData。
initialView'edit' | 'preview' | 'json'否起始视图模式。可选值之一：edit、preview、json。默认为 "edit"。
allowJsonViewEditingboolean否为 true 时，JSON 视图可编辑且更改会传播回文档。默认为 false。
marginsBlockMargins否应用于每个块的全局上下边距（像素）。块级配置优先。
stylesEditorStyles否EditorStyles 对象，用于对编辑器界面（工具栏、对话框、控件）进行精细的 CSS 自定义。
classNamesEditorClassNames否用于为编辑器界面元素附加 CSS 类名的 EditorClassNames 对象。
imageUploaderUploadFunction否上传图片文件并返回公开 URL 字符串的异步函数。
audioUploaderUploadFunction否上传音频文件并返回公开 URL 字符串的异步函数。
videoUploaderUploadFunction否上传视频文件并返回公开 URL 字符串的异步函数。
theme'auto' | 'light' | 'dark'否颜色方案。可选值之一：auto（跟随系统）、light、dark。默认为 auto。
themeOverrides{ light?: ThemeTokens; dark?: ThemeTokens }否每模式令牌覆盖。提供 light 和/或 dark 令牌映射，无需替换完整主题即可自定义颜色。
TypeScript
import { Editor } from '@clepit/core';

const editor = Editor.create({
  containerId: 'editor',
  minHeight: 400,
  placeholder: 'Start writing...',
  theme: 'auto',
  onChange: data => console.log(data),
  onReady: () => console.log('Editor ready'),
  imageUploader: async file => {
    const form = new FormData();
    form.append('file', file);
    const res = await fetch('/api/upload', { body: form, method: 'POST' });
    const { url } = await res.json();
    return url;
  },
});

RendererConfig

将 RendererConfig 作为唯一参数传入 Renderer.render()。containerId 和 data 均为必填项。

选项类型必填描述
containerIdstring是将注入渲染输出的 DOM 元素的 ID。
dataEditorData是要渲染的 EditorData 文档。必填。
marginsBlockMargins否应用于每个渲染块的全局上下边距（像素）。
stylesBlockStyles否用于渲染输出中按块类型进行 CSS 自定义的 BlockStyles 映射。
classNamesBlockClassNames否用于渲染输出中按块类型附加 CSS 类名的 BlockClassNames 映射。
editorClassNamesEditorClassNames否传递给渲染交互组件的块（如段落的 tooltip 类名）的 EditorClassNames。
configsPartial<BlockTypeOutputConfigs>否每块 OutputConfig 对象的部分映射。每个条目可以设置块级边距和 tooltip 类名。
theme'auto' | 'light' | 'dark'否颜色方案。可选值之一：auto、light、dark。
themeOverrides{ light?: ThemeTokens; dark?: ThemeTokens }否渲染输出的每模式令牌覆盖。
TypeScript
import { Renderer } from '@clepit/core';
import type { EditorData } from '@clepit/core';

const data: EditorData = await fetch('/api/content/123').then(r => r.json());

Renderer.render({
  containerId: 'output',
  data,
  theme: 'auto',
  margins: { bottom: 16, top: 16 },
});

块级样式

EditorConfig 和 RendererConfig 都接受以块类型为键的 styles、classNames 和 configs。将它们用于有针对性的覆盖；完整的每令牌参考请参见 Themes 页面。

TypeScript
import { Editor, Renderer } from '@clepit/core';
import type { BlockStyles, BlockClassNames, EditorStyles } from '@clepit/core';

const editorStyles: EditorStyles = {
  blockToolbar: { container: { borderRadius: '8px' } },
};

const blockStyles: BlockStyles = {
  header: { h1: { fontFamily: 'Georgia, serif' } },
  paragraph: { lineHeight: '1.75' },
  table: { cell: { padding: '8px 12px' } },
};

const blockClassNames: BlockClassNames = {
  paragraph: 'prose-paragraph',
  header: { h1: 'prose-h1', h2: 'prose-h2' },
  alert: { info: 'alert-info', error: 'alert-error' },
};

Editor.create({
  containerId: 'editor',
  styles: editorStyles,
});

Renderer.render({
  containerId: 'output',
  data,
  styles: blockStyles,
  classNames: blockClassNames,
});