Chuyển đến nội dung chính

Hướng dẫn

Nhúng

Tích hợp trình soạn thảo hoặc bộ hiển thị Clepit vào bất kỳ ứng dụng nào đều đơn giản: một DOM container là điểm kiểm soát duy nhất.

Gắn kết trình soạn thảo

Đặt id cho phần tử container, gọi `Editor.create({ containerId, ... })`, giữ lại `EditorAPI` được trả về và gọi `Editor.destroy(containerId)` khi dọn dẹp.

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');

Hiển thị đầu ra ở chế độ chỉ đọc

Gọi `Renderer.render({ containerId, data })`. Ví dụ bên dưới cho thấy mẫu React thực tế từ component `DocsRenderer`: `useId` tạo ra id container duy nhất và `useEffect` kích hoạt quá trình hiển thị.

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} />;
};

Mỗi API chạy ở đâu

Editor và Renderer gắn DOM thật, nên chúng chỉ chạy trong trình duyệt: dùng effects hoặc chỉ thị use client cho chúng. Đầu ra máy chủ không cần đến chúng: renderBlocks vẽ HTML hoàn chỉnh mà không cần DOM, trình bày bên dưới.

Đừng gọi Editor.create hay Renderer.render bên trong thành phần máy chủ; chúng cần document thật. Để hiển thị trên máy chủ, hãy dùng renderBlocks.

Hiển thị phía máy chủ

renderBlocks vẽ cùng tài liệu đó thành chuỗi HTML hoàn chỉnh không cần DOM, nên máy chủ gửi được mã đánh dấu thật: trình thu thập đọc được và không có gì vẽ lại khi gắn kết. Phục vụ pageStylesheet() kèm theo, và gọi activateBlocks sau khi gắn kết.

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);
Dùng React? @clepit/react đóng gói chính pipeline này thành ClepitContent, một thành phần ưu tiên máy chủ; xem trang React.

Không phụ thuộc framework

Gói lõi @clepit/core là TypeScript thuần túy, không có phụ thuộc React. Dù bạn dùng React, Vue, Svelte, Angular hay vanilla TS/JS, tất cả đều dùng chung một API.