تخطَّ إلى المحتوى الرئيسي

الأدلة

التضمين

مرجع API

الصادرات العامة من @clepit/core. يوفر كل رمز أدناه توقيعًا مكتوبًا ومثال استخدام بسيط.

Editor

الفئة الأساسية للمحرر. تحتوي Editor على طريقتَين ثابتَتَين عامتَتَين: create (المصنع الرئيسي) وdestroy. تُعيد الطريقة create() كائن EditorAPI، يمكن من خلاله استدعاء جميع الطرق بعد تهيئة المحرر.

الطريقةالتوقيعالوصف
Editor.createEditor.create(config: EditorConfig): EditorAPIأنشئ نسخة محرر جديدة وركّبها داخل عنصر DOM ذي المعرّف containerId المُقدَّم.
Editor.destroyEditor.destroy(containerId: string): voidطريقة destroy() على كائن EditorAPI تستدعي Editor.destroy() لهذه النسخة.
الطريقةالتوقيعالوصف
data.extractdata.extract(): EditorDataاستخرج بيانات الكتل الحالية من نسخة محرر كـ EditorData آمن لـ JSON.
data.setdata.set(data: EditorData): voidاستبدل قائمة الكتل بأكملها بحمولة بيانات جديدة. يؤدي ذلك إلى إعادة تصيير كاملة.
data.cleardata.clear(): voidيمسح كلاً من محتوى الكتل وبيانات الحالة المحفوظة.
data.clearContentdata.clearContent(): voidيزيل الكتل فقط، تاركًا بيانات المخزن سليمة.
data.clearStoragedata.clearStorage(): voidيمسح بيانات المخزن فحسب، تاركًا الكتل الحالية سليمة.
blocks.insertblocks.insert<T extends BlockToolType>(type: T, data: Block<T>['data'], index: number): HTMLElement | nullأدرِج كتلة عند الفهرس المعطى index. يقبل شكل البيانات نفسه الخاص بنوع الكتلة المستهدف.
blocks.convertblocks.convert(blockId: string, newType: BlockToolType): voidحوّل كتلة إلى نوع جديد في مكانها.
blocks.removeblocks.remove(index: number): voidأزل الكتلة عند الفهرس المعطى index.
blocks.moveblocks.move(fromIndex: number, toIndex: number): voidينقل كتلة من فهرس fromIndex إلى فهرس toIndex.
blocks.updateblocks.update<T extends BlockToolType>(blockId: string, data: Block<T>['data']): voidيُحدِّث بيانات كتلة موجودة في مكانها. لا يتغير النوع.
blocks.getblocks.get(blockId: string): EditorData['blocks'][number] | nullيجلب كتلة بمعرّفها ID. يُعيد null إذا لم يُعثر عليها.
blocks.getAllblocks.getAll(): EditorData['blocks']يُعيد مصفوفة تحتوي على بيانات جميع الكتل.
blocks.countblocks.count(): numberيُعيد عدد الكتل في المحرر.
focusfocus(): voidينقل التركيز إلى المحرر، ويُركِّز على الكتلة الأولى.
blurblur(): voidيُزيل التركيز النشط من أي عنصر داخل المحرر.
destroydestroy(): voidطريقة destroy() على كائن EditorAPI تستدعي Editor.destroy() لهذه النسخة.
selection.getselection.get(): Selection | nullيُعيد كائن تحديد النافذة أو null.
selection.setselection.set(selection: Selection): voidيضبط تحديد النافذة على كائن Selection المُقدَّم.
selection.clearselection.clear(): voidيُزيل جميع نطاقات تحديد النافذة.
ui.showBlockMenuui.showBlockMenu(block: HTMLElement): voidيعرض قائمة نوع الكتلة لعنصر DOM للكتلة المُعطى.
ui.hideBlockMenuui.hideBlockMenu(): voidيخفي قائمة نوع الكتلة إذا كانت مفتوحة.
ui.showToolbarui.showToolbar(x: number, y: number): voidيعرض شريط الأدوات المضمّن في إحداثيات x وy المُقدَّمة.
ui.hideToolbarui.hideToolbar(): voidيخفي شريط الأدوات المضمّن إذا كان ظاهرًا.
view.getCurrentViewview.getCurrentView(containerId: string): EditorView | nullيُعيد العرض الحالي (edit أو preview أو json) لمعرف الحاوية containerId المُعطى.
view.switchViewview.switchView(containerId: string, view: EditorView): voidيُبدِّل المحرر إلى view محدد: edit أو preview أو json.

مثال استخدام نموذجي

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

const editor = Editor.create({
  containerId: 'editor',
  theme: 'auto',
  placeholder: 'Start writing...',
  minHeight: 300,
});

// Insert a block
editor.blocks.insert('paragraph', { html: 'Hello world' }, 0);

// Extract data
const data = editor.data.extract();

// Switch view
editor.view.switchView('editor', 'preview');

// Tear down
editor.destroy();

Renderer

فئة تُحوِّل بيانات الكتل المحفوظة إلى HTML للقراءة فقط داخل عنصر DOM. تحتوي هذه الفئة على طريقة ثابتة عامة واحدة: render().

الطريقةالتوقيعالوصف
Renderer.renderRenderer.render(config: RendererConfig): HTMLElementصيِّر JSON الكتل المحفوظ داخل حاوية كـ HTML للقراءة فقط. استخدم هذا في أي مكان تريد فيه عرض المحتوى دون إمكانيات التحرير.

مثال استخدام نموذجي

TypeScript
import { Renderer } from '@clepit/core';

Renderer.render({
  containerId: 'output',
  data,
  theme: 'auto',
  margins: { bottom: 12, top: 0 },
});

StyleManager

فئة مركزية تدير نظام السمات. توفر ثلاث طرق ثابتة عامة مفيدة للمستهلكين: subscribe (للتغييرات في السمة على مستوى نظام التشغيل)، وgetResolvedTheme (لمعرفة السمة الحالية لنظام التشغيل)، وinjectStyles (لحقن CSS مخصص).

الطريقةالتوقيعالوصف
StyleManager.subscribeStyleManager.subscribe(cb: (theme: 'light' | 'dark') => void): () => voidاشترك في تغييرات رموز السمة أثناء التشغيل. يُطلَق المستمع كلما تغيّر theme أو themeOverrides.
StyleManager.getResolvedThemeStyleManager.getResolvedTheme(): 'light' | 'dark'يقرأ سمة نظام التشغيل الحالية ("light" أو "dark"). يُعيد "light" إذا كانت matchMedia غير متاحة.
StyleManager.injectStylesStyleManager.injectStyles(styleId: string, styles: string): booleanيُدرج سلسلة CSS في document.head (استخدم styleId فريدًا). يُعيد false إذا كان موجودًا بالفعل، وإلا true.

مثال استخدام نموذجي

TypeScript
import { StyleManager } from '@clepit/core';

// React to OS theme changes
const unsubscribe = StyleManager.subscribe(theme => {
  console.log('OS theme:', theme); // 'light' | 'dark'
});

// Read current OS theme
const current = StyleManager.getResolvedTheme();

// Inject custom CSS once
StyleManager.injectStyles('my-overrides', `
  .clepit-editor { font-family: 'Inter', sans-serif; }
`);

// Unsubscribe when done
unsubscribe();