كل ما تصدّره النواة

صفحة واحدة للخيارات والدوال والسمات. وتعيد حزم أطر العمل تصدير كل ذلك.

في هذه الصفحة

createEditor(options)

كل الخيارات مع قيمها الافتراضية. وجميعها اختيارية.

خيارات createEditor
الخيار	النوع	الافتراضي	الوصف
`element`	`HTMLElement \| string \| <textarea>`		الحاوية أو محدّد CSS أو textarea (يُخفى ويبقى متزامنًا). احذفه لإنشاء المحرّر منفصلًا وأضِف `editor.root` بنفسك.
`content`	`string \| JSON`		المحتوى الابتدائي: HTML (يُعقَّم دائمًا) أو JSON بصيغة ProseMirror.
`extensions`	`AnyExtension[]`	`[StarterKit]`	مجموعة الميزات.
`editable`	`boolean`	`true`	السماح بالتحرير.
`autofocus`	`boolean \| "start" \| "end"`	`false`	التركيز على المحرّر عند إنشائه.
`placeholder`	`string`		نص يظهر حين يكون المحرّر فارغًا.
`ariaLabel, ariaLabelledBy, ariaDescribedBy`	`string`		الاسم والوصف المتاحان لقارئات الشاشة لمنطقة التحرير.
`language`	`string`	`<html lang>`	لغة الواجهة. المدمجة: `en` و`ar`.
`languages`	`EditorLanguage[]`		إضافة لغات للواجهة أو استبدال الموجودة.
`labels`	`Partial<Labels>`		استبدال نصوص مفردة في الواجهة.
`dir`	`"ltr" \| "rtl" \| "auto"`		الاتجاه الأساسي للمحتوى.
`contentLang`	`string`		قيمة `lang` للمحتوى، تُستخدم في التدقيق الإملائي وقارئات الشاشة.
`urlPolicy`	`UrlPolicy`		`{ protocols, allowDataImages, allowRelative }`. عناوين الروابط والصور المسموح بها.
`inputRules`	`boolean`	`true`	اختصارات الكتابة بأسلوب Markdown: `#` و`` و`1.` و`>` والكود المحاط بعلامات، و`bold*`…
`ui`	`UIOptions \| false`	`built-in UI`	شريط الأدوات والأزرار المخصّصة وشريط الحالة والسمة والاختصارات. `false` = بدون واجهة.

خيارات ui

شريط الأدوات وشريط الحالة والسمة المدمجة. مرّر false بدلًا منها للحصول على محرّر بلا واجهة.

خيارات ui
الخيار	النوع	الافتراضي	الوصف
`toolbar`	`string[] \| false`	`DEFAULT_TOOLBAR`	أسماء العناصر والفواصل `"\|"`. يُخفي `false` شريط الأدوات.
`items`	`Record<string, ItemSpec>`		أزرار مخصّصة أو بديلة لشريط الأدوات، يُشار إليها بالاسم في `toolbar`.
`statusbar`	`{ elementPath, wordCount, characterCount } \| false`		محتوى شريط الحالة. يمكن أن تأخذ `characterCount` القيمة `{ limit }`.
`theme`	`"auto" \| "light" \| "dark"`	`"auto"`	سمة ألوان المحرّر.
`stickyToolbar`	`boolean`	`true`	إبقاء شريط الأدوات ظاهرًا أثناء تمرير المستندات الطويلة.
`shortcuts`	`{ toolbar, help, find, link }`	`Alt-F10, Alt-0, Mod-f, Mod-k`	اختصارات لوحة المفاتيح للواجهة المدمجة.

دوال الاستدعاء

مرّرها ضمن الخيارات. وتستدعي حزم أطر العمل أحدث دالة دائمًا.

دوال استدعاء المحرّر
الاسم	النوع	الوصف
`onCreate`	`(editor) => void`	أُنشئ المحرّر.
`onUpdate`	`(editor) => void`	تغيّر المحتوى.
`onSelectionUpdate`	`(editor) => void`	تغيّر التحديد.
`onFocus, onBlur`	`(editor, event) => void`	اكتسبت منطقة التحرير التركيز أو فقدته.
`onDestroy`	`() => void`	دُمِّر المحرّر.
`onContentError`	`(error: Error) => void`	تعذّر تحميل المحتوى.

دوال المحرّر

ما تعيده createEditor().

دوال المحرّر
الدالة	تعيد	الوصف
`getHTML()`	`string`	HTML نظيف ومعقَّم. احفظ هذا.
`getJSON()`	`JSONContent`	JSON بصيغة ProseMirror.
`getText({ blockSeparator })`	`string`	نص عادي. تُفصل الكتل افتراضيًا بـ `\n\n`.
`setContent(content, { emitUpdate, addToHistory })`	`void`	تحميل HTML أو JSON. الخياران `emitUpdate` و`addToHistory` متوقفان افتراضيًا.
`clearContent()`	`void`	إفراغ المستند.
`isEmpty, isFocused, isEditable`	`boolean`	مؤشرات حالة للقراءة فقط.
`setEditable(editable)`	`void`	تفعيل التحرير أو إيقافه.
`setOptions(options)`	`void`	تغيير الخيارات الديناميكية: `editable` و`placeholder` و`aria*` و`dir` و`contentLang`.
`commands.name()`	`boolean`	تنفيذ أمر واحد، مثل `editor.commands.toggleBold()`.
`can().name()`	`boolean`	هل ينجح الأمر عند التحديد الحالي؟
`chain().…run()`	`boolean`	عدة أوامر في معاملة واحدة وخطوة تراجع واحدة.
`isActive(name, attrs?)`	`boolean`	هل العلامة أو العقدة مفعّلة، مثل `isActive("heading", { level: 2 })`.
`getAttributes(name)`	`object`	سمات العنصر عند التحديد، مثل `href` للرابط.
`on(event, fn)`	`() => void`	الاستماع إلى حدث في المحرّر. تعيد دالة لإلغاء الاشتراك.
`subscribe(fn)`	`() => void`	اشتراك على نمط المخازن يُستدعى عند كل تغيير.
`announce(message)`	`void`	إرسال رسالة إلى قارئات الشاشة.
`focus(), blur()`	`void`	نقل التركيز إلى المحرّر أو منه.
`destroy()`	`void`	إزالة المحرّر ومستمعي الأحداث.

الأوامر

نفّذها بـ editor.commands.name() واختبرها بـ editor.can().name() واجمعها بـ editor.chain()…run().

الأوامر حسب المجال
المجال	الأوامر
علامات التنسيق	`toggleBold toggleItalic toggleUnderline toggleStrike toggleCode toggleSubscript toggleSuperscript unsetAllMarks`
الألوان	`setTextColor(color) unsetTextColor setHighlight(color?) unsetHighlight toggleHighlight(color?)`
الكتل	`setParagraph setHeading(level) toggleHeading(level) clearNodes toggleBlockquote toggleCodeBlock setHorizontalRule setHardBreak`
القوائم	`toggleBulletList toggleOrderedList toggleTaskList sinkListItem liftListItem`
الروابط والصور	`setLink({ href, text?, title?, newTab? }) unsetLink setImage({ src, alt, caption? }) updateImage`
الجداول	`insertTable({ rows, cols, withHeaderRow, caption }) addRowBefore addRowAfter addColumnBefore addColumnAfter deleteRow deleteColumn deleteTable mergeCells splitCell toggleHeaderRow toggleHeaderColumn setTableCaption`
التخطيط	`setTextAlign("start" \| "center" \| "end" \| "justify") setTextDirection("ltr" \| "rtl" \| "auto") unsetTextAlign unsetTextDirection`
البحث	`setSearch({ query, caseSensitive, wholeWord }) findNext findPrevious replaceCurrent(text) replaceAll(text) clearSearch`
عام	`undo redo focus blur selectAll`

السمات

تتبع placeholder وreadonly وdisabled وdir وcontent-lang وlabel التغييرات اللاحقة. أما value وlanguage وtoolbar فتُقرأ عند بدء المحرّر.

سمات owe-editor
الاسم	النوع	الوصف
`name`	`string`	اسم حقل النموذج. يرسل النموذج HTML المحرّر تحته.
`placeholder`	`string`	نص الإرشاد حين يكون المحرّر فارغًا.
`readonly`	`boolean`	يجعل المحتوى للقراءة فقط.
`disabled`	`boolean`	يعطّل المحرّر ويستبعده من النموذج.
`dir`	`ltr \| rtl \| auto`	الاتجاه الأساسي للمحتوى.
`content-lang`	`string`	قيمة `lang` للمحتوى (التدقيق الإملائي وقارئات الشاشة).
`label`	`string`	الاسم المتاح لقارئات الشاشة. أو اجعل `<label for>` يشير إلى `id` العنصر.
`value`	`HTML string`	المحتوى الابتدائي بصيغة HTML. يُقرأ مرة واحدة عند إنشاء المحرّر.
`language`	`string`	لغة الواجهة، مثل `ar`. تُقرأ مرة واحدة. الافتراضي `<html lang>`.
`toolbar`	`string`	عناصر شريط الأدوات مفصولة بمسافات (`"bold italic \| link"`)، أو `none`. تُقرأ مرة واحدة.

الخصائص

عيّن options قبل إضافة العنصر إلى الصفحة.

خصائص owe-editor
الاسم	النوع	الوصف
`editor`	`Editor \| null`	المحرّر الحي، أو `null` ما دام العنصر خارج المستند.
`value`	`string`	المحتوى بصيغة HTML. تعيينه يحمّل محتوى جديدًا.
`options`	`EditorOptions`	خيارات إضافية لـ `createEditor()`. عيّنها قبل إضافة العنصر إلى الصفحة. وتتغلّب عليها السمات.
`form`	`HTMLFormElement \| null`	عنصر `<form>` المحيط، أو `null`.

الأحداث

كلاهما يصعد في الشجرة (bubbles)، فيمكنك الاستماع على النموذج.

أحداث owe-editor
الاسم	النوع	الوصف
`input`	`Event`	عند كل تغيير. تحمل `event.target.value` الـ HTML.
`change`	`Event`	حين يفقد المحرّر التركيز بعد تغيير.

نقاط الدخول

ما يوفّره كل مسار استيراد.

نقاط دخول الحزمة
الاستيراد	النوع	الوصف
`open-wysiwyg-editor`	`ESM + CJS + .d.ts`	المحرّك وكل الإضافات والواجهة المتاحة.
`open-wysiwyg-editor/headless`	`ESM + CJS + .d.ts`	المحرّك والإضافات دون كود الواجهة.
`open-wysiwyg-editor/element`	`ESM + CJS + .d.ts`	يعرّف العنصر `<owe-editor>`.
`open-wysiwyg-editor/style.css`	`CSS`	تنسيقات المحرّر والواجهة والمحتوى (ومنه `style.min.css`).
`open-wysiwyg-editor/content.css`	`CSS`	تنسيقات المحتوى فقط، للصفحات التي تعرض HTML محفوظًا (ومنه `content.min.css`).
`dist/open-wysiwyg-editor.global.js`	`IIFE`	نسخة لوسم السكربت. تكشف `window.OpenWysiwygEditor` وتعرّف `<owe-editor>`.

عدّل هذه الصفحة على GitHub