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ọn | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| containerId | string | Có | 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. |
| maxHeight | number | Không | Chiề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. |
| minHeight | number | Không | Chiều cao tối thiểu của trình soạn thảo theo pixel. Mặc định là 300. |
| onChange | (data: EditorData) => void | Không | Callback đượ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 | () => void | Không | Callback đượ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. |
| placeholder | string | Không | Văn bản giữ chỗ hiển thị khi trình soạn thảo trống. Mặc định là 'Start writing...'. |
| initialData | EditorData | Không | EditorData được điền sẵn để tải khi trình soạn thảo gắn kết. |
| initialView | 'edit' | 'preview' | 'json' | Không | Chế độ xem ban đầu. Một trong: edit, preview, json. Mặc định là 'edit'. |
| allowJsonViewEditing | boolean | Không | Khi 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. |
| hasViewSwitcher | boolean | Không | Khi 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. |
| hasDocumentActions | boolean | Không | Khi 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. |
| margins | BlockMargins | Không | Lề 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. |
| styles | EditorStyles | Khô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). |
| classNames | EditorClassNames | Khô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. |
| imageUploader | UploadFunction | Không | Hàm bất đồng bộ tải lên tệp hình ảnh và trả về chuỗi URL công khai. |
| audioUploader | UploadFunction | Không | Hàm bất đồng bộ tải lên tệp âm thanh và trả về chuỗi URL công khai. |
| videoUploader | UploadFunction | Không | Hàm bất đồng bộ tải lên tệp video và trả về chuỗi URL công khai. |
| fileUploader | UploadFunction | Không | Hà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. |
| locale | string | Không | Locale 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. |
| defaultLocale | string | Không | Locale 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 }) => void | Khô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ông | Hà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. |
| inlineRewriteLabels | Partial<Record<InlineRewriteAction, string>> | Không | Ghi đè nhãn các thao tác trong menu viết lại, để bản địa hóa. |
| inlineRewriteTooltip | string | Không | Ghi đè 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. |
| blockToolLabels | Partial<Record<BlockToolType, string>> | Không | Ghi đè nhãn công cụ khối trong hộp công cụ và menu gạch chéo, để bản địa hóa. |
| blockToolbarLabels | Partial<Record<BlockToolbarLabel, string>> | Không | Ghi đè 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. |
| controlLabels | Partial<Record<ControlLabel, string>> | Không | Ghi đè 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. |
| dialogLabels | Partial<Record<DialogLabel, string>> | Không | Cá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) => void | Không | Cá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ý. |
| disabledEmbedProviders | readonly string[] | Không | Cá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ông | Việ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ẻ. |
| embedLabels | Partial<Record<EmbedLabel, string>> | Không | Cá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ông | Trả 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) => void | Không | Cá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ông | Liê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ông | Hai 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. |
| issueLabels | Partial<Record<IssueLabel, string>> | Không | Cá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. |
| jiraSites | readonly string[] | Không | URL 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. |
| allowedBlockTools | readonly BlockToolType[] | Không | Cá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ị. |
| allowedInlineTools | readonly InlineToolType[] | Không | Cá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ông | Bảng màu. Một trong: auto (theo hệ thống), light, dark. Mặc định là auto. |
| themeOverrides | { light?: ThemeTokens; dark?: ThemeTokens } | Không | Ghi đè 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ọn | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
| containerId | string | Có | ID của phần tử DOM nơi đầu ra được kết xuất sẽ được chèn vào. |
| data | EditorData | Có | Tài liệu EditorData cần kết xuất. Bắt buộc. |
| margins | BlockMargins | Không | Lề trên và dưới toàn cục (theo pixel) áp dụng cho mỗi khối được kết xuất. |
| styles | BlockStyles | Không | Bản đồ BlockStyles để tùy chỉnh CSS theo từng loại khối của đầu ra được kết xuất. |
| classNames | BlockClassNames | Không | Bản đồ BlockClassNames cho tên lớp CSS theo từng loại khối trên đầu ra được kết xuất. |
| editorClassNames | EditorClassNames | Không | EditorClassNames đượ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). |
| configs | Partial<BlockTypeOutputConfigs> | Không | Bả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ông | Bảng màu. Một trong: auto, light, dark. |
| themeOverrides | { light?: ThemeTokens; dark?: ThemeTokens } | Không | Ghi đè 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,
});