配置

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

EditorConfig

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

选项	类型	必填	描述
containerId	string	是	将承载编辑器的 DOM 元素的 ID。必须在调用 Editor.create() 之前存在于 DOM 中。
maxHeight	number	否	编辑器的最大高度（像素）。设为 0（默认）表示不限高度。
minHeight	number	否	编辑器的最小高度（像素）。默认值为 300。
onChange	(data: EditorData) => void	否	文档每次变更时触发的回调函数。接收完整的 EditorData 快照。
onReady	() => void	否	编辑器完全初始化并准备好接受 API 调用时触发的回调。
placeholder	string	否	编辑器为空时显示的占位符文本。默认为 "Start writing..."。
initialData	EditorData	否	编辑器挂载时预加载的 EditorData。
initialView	'edit' \| 'preview' \| 'json'	否	起始视图模式。可选值之一：edit、preview、json。默认为 "edit"。
allowJsonViewEditing	boolean	否	为 true 时，JSON 视图可编辑且更改会传播回文档。默认为 false。
hasViewSwitcher	boolean	否	为 false 时，操作栏中不显示编辑、预览和 JSON 按钮。默认为 true。
hasDocumentActions	boolean	否	为 false 时，操作栏中不显示复制、下载和清空按钮。若 hasViewSwitcher 也为 false，则不绘制操作栏。默认为 true。
onClearRequest	() => Promise<boolean>	否	按下清空按钮时调用。仅当它解析为 true 时才清空页面；被拒绝时页面保持不变。未提供时，立即清空。
margins	BlockMargins	否	应用于每个块的全局上下边距（像素）。块级配置优先。
styles	EditorStyles	否	EditorStyles 对象，用于对编辑器界面（工具栏、对话框、控件）进行精细的 CSS 自定义。
classNames	EditorClassNames	否	用于为编辑器界面元素附加 CSS 类名的 EditorClassNames 对象。
imageUploader	UploadFunction	否	上传图片文件并返回公开 URL 字符串的异步函数。
audioUploader	UploadFunction	否	上传音频文件并返回公开 URL 字符串的异步函数。
videoUploader	UploadFunction	否	上传视频文件并返回公开 URL 字符串的异步函数。
fileUploader	UploadFunction	否	把文件块附件上传到你的存储的上传函数。
locale	string	否	编辑器编辑的单一区域设置。多语言块会被展平到该区域设置。
defaultLocale	string	否	当块没有请求的区域设置内容时使用的后备区域设置。
onLocaleFallback	(info: { blockId: string; locale: string }) => void	否	当某个块落到后备区域设置时调用，便于宿主显示指示。
onInlineRewrite	(selection: string, action: InlineRewriteAction) => Promise<string \| null>	否	用 AI 重写选中文本的函数；设置后工具栏会显示重写按钮。
inlineRewriteLabels	Partial<Record<InlineRewriteAction, string>>	否	覆盖重写菜单操作的标签，用于本地化。
inlineRewriteTooltip	string	否	覆盖行内工具栏中重写魔杖的提示文字，用于本地化。
blockToolLabels	Partial<Record<BlockToolType, string>>	否	覆盖工具箱和斜杠菜单中的块工具标签，用于本地化。
blockToolbarLabels	Partial<Record<BlockToolbarLabel, string>>	否	覆盖块工具栏文本（添加、移动、删除等）以及空块字段中显示的提示，用于本地化。
controlLabels	Partial<Record<ControlLabel, string>>	否	覆盖操作栏按钮（编辑、预览、JSON、复制、下载、清空）的名称，用作其无障碍名称和工具提示，用于本地化。
dialogLabels	Partial<Record<DialogLabel, string>>	否	链接、提示和状态对话框显示的文字，按名称索引：标题、字段标签、占位文字、状态样式，以及取消和应用。未提供时使用英文。
resolveLink	(url: string) => Promise<Partial<EmbedData>>	否	从你的服务器填充粘贴嵌入的快照：标题、Drive 文件、gist 文件或无法实时显示的原因。抛出异常的查询会把卡片绘制为工具未响应，并在旁边提供重试。
onEmbedAction	(action: EmbedAction, blockId: string) => void	否	卡片原因旁只有宿主才能执行的修复：connectGoogle 把成员送去连接 Google 账号；retry 由编辑器自行处理。
disabledEmbedProviders	readonly string[]	否	工作区按线上键关闭的嵌入工具（figma、miro、loom、google_drive、github_gist）；其链接绘制为说明原因的卡片。
pasteEmbeds	'live' \| 'offer' \| 'card'	否	粘贴受支持的链接时的行为：实时显示（默认）、询问是否显示，或显示卡片。
embedLabels	Partial<Record<EmbedLabel, string>>	否	嵌入块的原因行、操作和 gist 标签的翻译文本，按 EmbedLabel 键控；否则回退为英文。
resolveIssues	(urls: string[]) => Promise<Record<string, IssueSnapshot>>	否	以 URL 为键回答页面中事项链接的快照。缺省时，标签和卡片保留文档存储的状态，且不会刷新。
onIssueAction	(action: IssueAction, tool: string) => void	否	事项原因旁只有宿主能执行的修复：连接该工具，落到宿主的集成页面。
issueCards	'off' \| 'on'	否	粘贴在独立一行的事项链接是否成为卡片；缺省为 off。句中的标签始终是标签。
issueChip	{ assignee: boolean; status: boolean }	否	成员的两个标签开关：状态胶囊与负责人。缺省时两者均开启。
issueLabels	Partial<Record<IssueLabel, string>>	否	事项标签、卡片与关联事项表的翻译文本，按 IssueLabel 键控；否则回退为英文。
jiraSites	readonly string[]	否	工作区连接可访问的 Jira 站点 URL，使自有域名站点上的链接被识别为事项。
allowedBlockTools	readonly BlockToolType[]	否	编辑器在块菜单、其搜索、转换菜单和粘贴时提供的块类型。缺省时为每个已注册的块；列表之外已存储的块仍会渲染。
allowedInlineTools	readonly InlineToolType[]	否	行内工具栏提供的标记。缺省时为每个已注册的标记。
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 均为必填项。

选项	类型	必填	描述
containerId	string	是	将注入渲染输出的 DOM 元素的 ID。
data	EditorData	是	要渲染的 EditorData 文档。必填。
margins	BlockMargins	否	应用于每个渲染块的全局上下边距（像素）。
styles	BlockStyles	否	用于渲染输出中按块类型进行 CSS 自定义的 BlockStyles 映射。
classNames	BlockClassNames	否	用于渲染输出中按块类型附加 CSS 类名的 BlockClassNames 映射。
editorClassNames	EditorClassNames	否	传递给渲染交互组件的块（如段落的 tooltip 类名）的 EditorClassNames。
configs	Partial<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,
});