跳到主要内容

指南

嵌入

嵌入

将 Clepit 编辑器或渲染器集成到任何应用中非常简单：DOM 容器就是全部的控制点。

挂载编辑器

给容器元素设置一个 id，调用 `Editor.create({ containerId, ... })`，保留返回的 `EditorAPI`，并在清理时调用 `Editor.destroy(containerId)`。

TypeScript
import { Editor } from '@clepit/core';
import type { EditorAPI } from '@clepit/core';

// 1. Give your container a stable id
// <div id="my-editor"></div>

// 2. Create the editor and hold the returned API
const editor: EditorAPI = Editor.create({
  containerId: 'my-editor',
  minHeight: 400,
  placeholder: 'Start writing...',
  theme: 'auto',
  onChange: data => console.log(data),
  onReady: () => console.log('Editor ready'),
});

// 3. Extract content any time
const data = editor.data.extract();

// 4. Destroy on teardown (e.g. component unmount)
Editor.destroy('my-editor');

只读渲染输出

调用 `Renderer.render({ containerId, data })`。下面的示例展示了 `DocsRenderer` 组件中使用的真实 React 模式：`useId` 生成唯一的容器 id，`useEffect` 触发渲染。

TSX
import { Renderer } from '@clepit/core';
import type { EditorData } from '@clepit/core';
import { useEffect, useId } from 'react';

type Props = { content: EditorData };

const ReadOnlyView = ({ content }: Props) => {
  // useId produces a stable, unique id per component instance
  const containerId = useId().replace(/[^a-z0-9]/gi, '');

  useEffect(() => {
    Renderer.render({
      containerId,
      data: content,
      margins: { bottom: 0, top: 0 },
    });
  }, [containerId, content]);

  return <div id={containerId} />;
};

每个 API 在哪里运行

Editor 和 Renderer 挂载真实 DOM，因此只在浏览器中运行：对它们使用 effects 或 use client 指令。服务器输出并不需要它们：renderBlocks 完全不用 DOM 就能绘制成品 HTML，见下文。

不要在服务器组件中调用 Editor.create 或 Renderer.render；它们需要真实的 document。要在服务器上渲染，请改用 renderBlocks。

服务器渲染

renderBlocks 不用 DOM 就能把同一文档绘制成成品 HTML 字符串，因此服务器可以发送真实标记：爬虫能读取，挂载时不会重绘。随之提供 pageStylesheet()，并在挂载后调用 activateBlocks。

TypeScript
import { activateBlocks, pageStylesheet, renderBlocks } from '@clepit/core';

// On the server: finished HTML, no DOM needed
const html = renderBlocks(doc.blocks);
const css = pageStylesheet();

// In the browser, after mount: wire the interactive blocks
const dispose = activateBlocks(container, doc.blocks);
在用 React？@clepit/react 把这条流水线打包成 ClepitContent，一个服务器优先的组件；参见 React 页面。

框架无关

核心 @clepit/core 包是纯 TypeScript，没有 React 依赖。无论你使用 React、Vue、Svelte、Angular 还是原生 TS/JS，都使用相同的 API。