الإعداد

EditorConfig وRendererConfig هما نقطتا الدخول لكل تخصيص. مرر أيًا منهما إلى Editor.create() أو Renderer.render() على التوالي. containerId فقط (وdata للـ Renderer) مطلوبان، وباقي الخيارات لها قيم افتراضية آمنة.

EditorConfig

مرر EditorConfig كوسيط وحيد إلى Editor.create(). يجب أن يتطابق containerId المطلوب مع معرف عنصر DOM موجود مسبقًا.

الخيار	النوع	مطلوب	الوصف
containerId	string	نعم	معرف عنصر DOM الذي سيستضيف المحرر. يجب أن يكون موجودًا في DOM قبل استدعاء Editor.create().
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	لا	كائن EditorClassNames لإرفاق أسماء فئات CSS بعناصر واجهة المحرر.
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>	لا	دالة تعيد كتابة النص المحدد بالذكاء الاصطناعي؛ عند ضبطها يعرض شريط الأدوات زر إعادة الكتابة.
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>>	لا	يجيب عن روابط مشكلات الصفحة بلقطاتها مفهرسة بالرابط. إن غاب، تبقى الشارات والكروت على ما خزّنه المستند ولا يُحدَّث شيء.
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 التي تصلها اتصالات مساحة العمل، حتى يُعرَف رابط على نطاق الموقع الخاص كمشكلة.
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 حيث سيتم حقن الناتج المُصيَّر.
data	EditorData	نعم	مستند EditorData المراد تصييره. مطلوب.
margins	BlockMargins	لا	الهامش العلوي والسفلي العام (بالبكسل) المطبق على كل كتلة مُصيَّرة.
styles	BlockStyles	لا	خريطة BlockStyles لتخصيص CSS لكل نوع كتلة في الناتج المُصيَّر.
classNames	BlockClassNames	لا	خريطة BlockClassNames لأسماء فئات CSS لكل نوع كتلة في الناتج المُصيَّر.
editorClassNames	EditorClassNames	لا	EditorClassNames تُمرَّر إلى الكتل التي تُصيِّر مكونات تفاعلية (مثل أسماء فئات tooltip للفقرات).
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,
});

المرجع

الحزم

الإعداد

EditorConfig

RendererConfig

التنسيق على مستوى الكتلة