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

Cấu hình

EditorConfig và RendererConfig là các điểm vào cho mọi tùy chỉnh. Truyền một trong hai vào Editor.create() hoặc Renderer.render() tương ứng. Chỉ có containerId (và data cho renderer) là bắt buộc, tất cả các tùy chọn khác đều có giá trị mặc định an toàn.

EditorConfig

Truyền EditorConfig làm đối số duy nhất cho Editor.create(). containerId bắt buộc phải khớp với id của một phần tử DOM hiện có.

Tùy chọnKiểuBắt buộcMô tả
containerIdstringCóID của phần tử DOM sẽ chứa trình soạn thảo. Phải tồn tại trong DOM trước khi Editor.create() được gọi.
maxHeightnumberKhôngChiều cao tối đa của trình soạn thảo theo pixel. Đặt thành 0 (mặc định) để không giới hạn chiều cao.
minHeightnumberKhôngChiều cao tối thiểu của trình soạn thảo theo pixel. Mặc định là 300.
onChange(data: EditorData) => voidKhôngCallback được kích hoạt mỗi khi tài liệu thay đổi. Nhận toàn bộ bản chụp EditorData.
onReady() => voidKhôngCallback được kích hoạt khi trình soạn thảo được khởi tạo hoàn toàn và sẵn sàng nhận các lời gọi API.
placeholderstringKhôngVăn bản giữ chỗ hiển thị khi trình soạn thảo trống. Mặc định là 'Start writing...'.
initialDataEditorDataKhôngEditorData được điền sẵn để tải khi trình soạn thảo gắn kết.
initialView'edit' | 'preview' | 'json'KhôngChế độ xem ban đầu. Một trong: edit, preview, json. Mặc định là 'edit'.
allowJsonViewEditingbooleanKhôngKhi true, chế độ xem JSON có thể chỉnh sửa và các thay đổi được truyền ngược lại vào tài liệu. Mặc định là false.
hasViewSwitcherbooleanKhôngKhi false, các nút chỉnh sửa, xem trước và JSON được bỏ khỏi thanh thao tác. Mặc định là true.
hasDocumentActionsbooleanKhôngKhi false, các nút sao chép, tải xuống và xóa được bỏ khỏi thanh thao tác. Nếu hasViewSwitcher cũng là false, thanh thao tác không được vẽ. Mặc định là true.
onClearRequest() => Promise<boolean>KhôngĐược gọi khi nhấn Xóa trắng. Trang chỉ bị xóa khi kết quả là true; nếu bị từ chối, trang giữ nguyên. Nếu không có, Xóa trắng sẽ xóa ngay.
marginsBlockMarginsKhôngLề trên và dưới toàn cục (theo pixel) áp dụng cho mỗi khối. Cấu hình mỗi khối được ưu tiên.
stylesEditorStylesKhôngĐối tượng EditorStyles để tùy chỉnh CSS chi tiết cho giao diện trình soạn thảo (thanh công cụ, hộp thoại, điều khiển).
classNamesEditorClassNamesKhôngĐối tượng EditorClassNames để gắn tên lớp CSS vào các phần tử giao diện trình soạn thảo.
imageUploaderUploadFunctionKhôngHàm bất đồng bộ tải lên tệp hình ảnh và trả về chuỗi URL công khai.
audioUploaderUploadFunctionKhôngHàm bất đồng bộ tải lên tệp âm thanh và trả về chuỗi URL công khai.
videoUploaderUploadFunctionKhôngHàm bất đồng bộ tải lên tệp video và trả về chuỗi URL công khai.
fileUploaderUploadFunctionKhôngHàm tải lên chuyển tệp đính kèm của khối tệp vào bộ lưu trữ của bạn.
localestringKhôngLocale duy nhất mà trình soạn thảo chỉnh sửa. Các khối đa ngôn ngữ được làm phẳng về locale này.
defaultLocalestringKhôngLocale dự phòng khi một khối không có nội dung cho locale được yêu cầu.
onLocaleFallback(info: { blockId: string; locale: string }) => voidKhôngĐược gọi khi một khối rơi về locale khác, để máy chủ hiển thị chỉ báo.
onInlineRewrite(selection: string, action: InlineRewriteAction) => Promise<string | null>KhôngHàm viết lại văn bản được chọn bằng AI; khi đặt, thanh công cụ hiển thị nút viết lại.
inlineRewriteLabelsPartial<Record<InlineRewriteAction, string>>KhôngGhi đè nhãn các thao tác trong menu viết lại, để bản địa hóa.
inlineRewriteTooltipstringKhôngGhi đè chú giải công cụ của đũa viết lại trên thanh công cụ nội tuyến, để bản địa hóa.
blockToolLabelsPartial<Record<BlockToolType, string>>KhôngGhi đè nhãn công cụ khối trong hộp công cụ và menu gạch chéo, để bản địa hóa.
blockToolbarLabelsPartial<Record<BlockToolbarLabel, string>>KhôngGhi đè văn bản thanh công cụ khối (thêm, di chuyển, xóa, và các mục còn lại) và các gợi ý hiển thị trong ô khối trống, để bản địa hóa.
controlLabelsPartial<Record<ControlLabel, string>>KhôngGhi đè tên các nút của thanh thao tác (chỉnh sửa, xem trước, JSON, sao chép, tải xuống, xóa), được dùng làm tên truy cập và chú giải của chúng, để bản địa hóa.
dialogLabelsPartial<Record<DialogLabel, string>>KhôngCác từ mà hộp thoại liên kết, chú thích và trạng thái hiển thị, theo tên: tiêu đề, nhãn trường, văn bản gợi ý, kiểu trạng thái, Hủy và Áp dụng. Tiếng Anh nếu không có.
resolveLink(url: string) => Promise<Partial<EmbedData>>KhôngĐiền ảnh chụp của phần nhúng đã dán từ máy chủ của bạn: tiêu đề, tệp Drive, các tệp gist, hoặc lý do không thể xem trực tiếp. Truy vấn thất bại vẽ thẻ như công cụ không phản hồi, kèm Thử lại bên cạnh.
onEmbedAction(action: EmbedAction, blockId: string) => voidKhôngCách khắc phục bên cạnh lý do của thẻ mà chỉ máy chủ lưu trữ mới thực hiện được: connectGoogle đưa thành viên đi kết nối tài khoản Google; retry do trình soạn thảo tự xử lý.
disabledEmbedProvidersreadonly string[]KhôngCác công cụ nhúng mà không gian làm việc đã tắt, theo khóa (figma, miro, loom, google_drive, github_gist); liên kết của chúng được vẽ thành thẻ nêu lý do.
pasteEmbeds'live' | 'offer' | 'card'KhôngViệc dán một liên kết được hỗ trợ sẽ làm gì: hiển thị trực tiếp (mặc định), đề xuất, hoặc hiển thị thẻ.
embedLabelsPartial<Record<EmbedLabel, string>>KhôngCác từ đã dịch cho dòng lý do, hành động và nhãn gist của khối nhúng, theo khóa EmbedLabel; nếu không có thì dùng tiếng Anh.
resolveIssues(urls: string[]) => Promise<Record<string, IssueSnapshot>>KhôngTrả lời các liên kết issue của trang bằng ảnh chụp của chúng, theo khóa URL. Nếu thiếu, chip và thẻ giữ những gì tài liệu đã lưu và không có gì được làm mới.
onIssueAction(action: IssueAction, tool: string) => voidKhôngCách khắc phục bên cạnh lý do issue mà chỉ máy chủ thực hiện được: kết nối công cụ, dẫn đến trang Tích hợp của máy chủ.
issueCards'off' | 'on'KhôngLiên kết issue dán trên dòng riêng có trở thành thẻ hay không; off nếu thiếu. Chip trong câu luôn là chip.
issueChip{ assignee: boolean; status: boolean }KhôngHai công tắc chip của thành viên: viên trạng thái và người phụ trách. Cả hai bật nếu thiếu.
issueLabelsPartial<Record<IssueLabel, string>>KhôngCác từ đã dịch cho chip issue, thẻ và bảng issue được liên kết, theo khóa IssueLabel; nếu không có thì dùng tiếng Anh.
jiraSitesreadonly string[]KhôngURL của các site Jira mà kết nối của không gian làm việc tiếp cận, để liên kết trên miền riêng của site được nhận là issue.
allowedBlockToolsreadonly BlockToolType[]KhôngCác loại khối mà trình soạn thảo cung cấp trong menu khối, tìm kiếm của nó, menu chuyển đổi và khi dán. Mọi khối đã đăng ký khi bỏ trống; khối đã lưu ngoài danh sách vẫn được hiển thị.
allowedInlineToolsreadonly InlineToolType[]KhôngCác định dạng mà thanh công cụ nội dòng cung cấp. Mọi định dạng đã đăng ký khi bỏ trống.
theme'auto' | 'light' | 'dark'KhôngBảng màu. Một trong: auto (theo hệ thống), light, dark. Mặc định là auto.
themeOverrides{ light?: ThemeTokens; dark?: ThemeTokens }KhôngGhi đè token theo chế độ. Cung cấp bản đồ token light và/hoặc dark để tùy chỉnh màu sắc mà không cần thay thế toàn bộ chủ đề.
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

Truyền RendererConfig làm đối số duy nhất cho Renderer.render(). Cả containerId và data đều là bắt buộc.

Tùy chọnKiểuBắt buộcMô tả
containerIdstringCóID của phần tử DOM nơi đầu ra được kết xuất sẽ được chèn vào.
dataEditorDataCóTài liệu EditorData cần kết xuất. Bắt buộc.
marginsBlockMarginsKhôngLề trên và dưới toàn cục (theo pixel) áp dụng cho mỗi khối được kết xuất.
stylesBlockStylesKhôngBản đồ BlockStyles để tùy chỉnh CSS theo từng loại khối của đầu ra được kết xuất.
classNamesBlockClassNamesKhôngBản đồ BlockClassNames cho tên lớp CSS theo từng loại khối trên đầu ra được kết xuất.
editorClassNamesEditorClassNamesKhôngEditorClassNames được truyền đến các khối kết xuất các thành phần tương tác (ví dụ: classNames tooltip cho các đoạn văn).
configsPartial<BlockTypeOutputConfigs>KhôngBản đồ một phần của các đối tượng OutputConfig theo từng khối. Mỗi mục có thể đặt lề cấp khối và tên lớp tooltip.
theme'auto' | 'light' | 'dark'KhôngBảng màu. Một trong: auto, light, dark.
themeOverrides{ light?: ThemeTokens; dark?: ThemeTokens }KhôngGhi đè token theo chế độ cho đầu ra được kết xuất.
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 },
});

Tạo kiểu cấp khối

Cả EditorConfig và RendererConfig đều chấp nhận styles, classNames và configs được khóa theo loại khối. Sử dụng chúng cho các ghi đè có mục tiêu; xem trang Themes để biết tham chiếu đầy đủ theo token.

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,
});