مرجع الكتل

توثّق هذه الصفحة كل نوع كتلة يتضمّنه المحرر. لكل كتلة شكل JSON ومُصيّر (renderer) ومسار إدراج برمجي عبر editor.blocks.insert.

تشترك جميع الكتل في الغلاف نفسه عند التسلسل: id وtype وdata وسجل tunes اختياري.

شكل الكتلة

يتسلسل كل كتلة إلى غلاف JSON متطابق. يُعيَّن id بواسطة المحرر ويمكن حذفه عند بناء البيانات برمجيًا.

JSON

{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Hello <b>world</b>" },
  "tunes": {}
}

alert

صندوق تنبيه مميَّز بأربعة أنماط.

الحقل	النوع	مطلوب	الوصف
html	string	نعم	محتوى HTML لرسالة التنبيه. يُدعم ترميز الأدوات المضمّنة.
variant	'error' \| 'info' \| 'success' \| 'warning'	نعم	النمط المرئي للتنبيه. أحد القيم: error وinfo وsuccess وwarning.

JSON

{
  "type": "alert",
  "data": { "html": "Your session will expire in 5 minutes.", "variant": "warning" }
}

audio

كتلة صوت. تُستهلك عبر دالة الاستدعاء audioUploader في Editor.create.

الحقل	النوع	مطلوب	الوصف
url	string	نعم	رابط ملف الصوت المراد تضمينه.
caption	string	لا	تعليق نصي عادي يظهر أسفل مشغّل الصوت.
alt	string	لا	تسمية يمكن الوصول إليها لعنصر الصوت.
alignment	'center' \| 'left' \| 'right'	لا	المحاذاة الأفقية للمشغّل. أحد القيم: center وleft وright.

JSON

{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

قائمة مربعات اختيار تفاعلية مع حالة محدّدة لكل عنصر.

الحقل	النوع	مطلوب	الوصف
items	ChecklistItem[]	نعم	مصفوفة من عناصر القائمة المرجعية، كل منها يحتوي على نص وحالة تحديد.
items[].text	string	نعم	محتوى HTML لتسمية العنصر.
items[].checked	boolean	نعم	ما إذا كان مربع الاختيار مُحدَّدًا.

JSON

{
  "type": "checklist",
  "data": {
    "items": [
      { "text": "Install the package", "checked": true },
      { "text": "Mount the editor", "checked": false }
    ]
  }
}

code

كتلة كود بتمييز لوني للصياغة. تدعم 50 لغة، منها typescript وpython وrust وgo وruby وswift وkotlin.

الحقل	النوع	مطلوب	الوصف
code	string	نعم	سلسلة الكود الخام المراد عرضها.
language	CodeLanguage	لا	لغة تمييز بناء الجملة. القيمة الافتراضية: typescript.
theme	CodeTheme	لا	ثيم ألوان المحرر. القيمة الافتراضية: github-dark.
showCopy	boolean	لا	عرض زر نسخ في الناتج المُصيَّر.
syncKey	string	لا	الكتل التي تتشارك مفتاحًا تبدّل اللغة معًا.
variants	CodeVariant[]	لا	عند امتلائها تعرض شريط تبويبات وتكون هي المرجع.

JSON

{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

collapsible

قسم قابل للطي بعنوان وكتل فرعية متداخلة. تُحفظ أنواع الكتل الفرعية غير المعروفة كما هي، لذا تنجو المستندات الأحدث في العارضات الأقدم.

الحقل	النوع	مطلوب	الوصف
html	string	نعم	عنوان القسم بصيغة HTML مضمّن.
open	boolean	لا	ما إذا كان القسم يُعرض موسّعًا.
children	Block[]	لا	كتل فرعية متداخلة.

JSON

{
  "type": "collapsible",
  "data": {
    "html": "Details",
    "open": true,
    "children": [{ "type": "paragraph", "data": { "html": "Hidden until opened." } }]
  }
}

collection

يضمّن عرض مجموعة حيًّا عبر المعرّف. لا تخزّن الكتلة سوى هوية المجموعة؛ فالخادم يملك الشكل والبيانات.

الحقل	النوع	مطلوب	الوصف
collectionId	string	نعم	معرّف المجموعة المضمّنة. الشيء الوحيد المخزّن.

JSON

{
  "type": "collection",
  "data": { "collectionId": "c-42" }
}

columns

تخطيط متعدد الأعمدة من عمودين إلى أربعة، يحمل كل عمود قائمته الخاصة من الكتل الفرعية.

الحقل	النوع	مطلوب	الوصف
columns	Block[][]	نعم	الأعمدة، كل منها قائمة كتل فرعية. من عمودين إلى أربعة.

JSON

{
  "type": "columns",
  "data": {
    "columns": [
      [{ "type": "paragraph", "data": { "html": "Left" } }],
      [{ "type": "paragraph", "data": { "html": "Right" } }]
    ]
  }
}

date

تاريخ تقويمي، يُخزَّن دون منطقة زمنية حتى يتفق عليه كل المتعاونين.

الحقل	النوع	مطلوب	الوصف
date	string	نعم	تاريخ ISO بصيغة yyyy-MM-dd، دون منطقة زمنية.

JSON

{
  "type": "date",
  "data": { "date": "2026-08-31" }
}

delimiter

فاصل بصري بين الأقسام.

الحقل	النوع	مطلوب	الوصف
variant	'line' \| 'stars'	نعم	النمط المرئي للفاصل. أحد القيم: line وstars.

JSON

{
  "type": "delimiter",
  "data": { "variant": "line" }
}

doc_card

بطاقة رابط غنية لمستند آخر. تخزّن معرّف الصفحة المُشار إليها ولقطة عرض يحدّثها المضيف عند إعادة التسمية.

الحقل	النوع	مطلوب	الوصف
pageId	string	نعم	معرّف الصفحة المُشار إليها؛ هوية البطاقة.
title	string	نعم	لقطة عرض لعنوان الصفحة.
icon	string	لا	أيقونة اختيارية تظهر على البطاقة.
description	string	لا	وصف اختياري يظهر أسفل العنوان.

JSON

{
  "type": "doc_card",
  "data": { "pageId": "p-7", "title": "Release notes", "icon": "📄" }
}

embed

رابط مضمّن. تخزّن الكتلة الرابط فقط؛ ويُشتق المزوّد وترميز التضمين عند العرض، مع حقول المعاينة كبطاقة احتياطية.

الحقل	النوع	مطلوب	الوصف
url	string	نعم	الرابط المضمّن. يُشتق منه المزوّد وترميز التضمين عند العرض.
title	string	لا	لقطة معاينة لبطاقة الرابط.
description	string	لا	وصف المعاينة لبطاقة الرابط.
imageUrl	string	لا	صورة المعاينة لبطاقة الرابط.
display	'card'	لا	"card" لعرض بطاقة رابط حتى حيث يتوفر عرض مباشر.
file	object	لا	اسم ملف Drive ونوعه وأيقونته، من حساب Google الخاص بمن لصق الرابط.
gist	object	لا	ملفات gist كما لُصقت، تُرسم كشيفرة حيث لا يمكن تحميل عرض GitHub.
reason	string	لا	سبب عدم عرض العرض المباشر: connect_google أو no_access أو provider_unreachable أو switched_off.
issue	object	لا	رابط مشكلة يُعرض ككرت: آخر لقطة قُرئت (tool وkey وtitle وstateName وcategory وassigneeName وupdatedAt وreason).

JSON

{
  "type": "embed",
  "data": { "url": "https://www.youtube.com/watch?v=abc123" }
}

file

مرفق ملف مع رابط تنزيل واسم، وحجم ونوع محتوى اختياريين.

الحقل	النوع	مطلوب	الوصف
url	string	نعم	المكان الذي يُقدَّم منه الملف.
name	string	نعم	اسم الملف الظاهر على المرفق.
size	number	لا	حجم الملف بالبايت.
contentType	string	لا	نوع MIME للملف.

JSON

{
  "type": "file",
  "data": { "url": "/files/notes.pdf", "name": "notes.pdf", "size": 2048, "contentType": "application/pdf" }
}

glance

لوحة ملخّص من تسميات وقيم: صفوف حقائق تُقرأ بلمحة، مع تعليق وخلفية اختياريين.

الحقل	النوع	مطلوب	الوصف
rows	GlanceRow[]	نعم	الحقائق المعروضة: كل صف تسمية وقيمة HTML مضمّنة.
caption	string	لا	تعليق اختياري فوق الصفوف.
variant	'plain' \| 'error' \| 'info' \| 'success' \| 'warning'	لا	خلفية العرض؛ plain بلا تنسيق، والبقية تطابق لوحة ألوان التنبيه.

JSON

{
  "type": "glance",
  "data": {
    "caption": "Facts",
    "rows": [{ "label": "Version", "html": "<b>1.0</b>" }],
    "variant": "plain"
  }
}

header

عناوين المستوى الأعلى وعناوين الأقسام (من h1 إلى h6). تعمل الأدوات المضمّنة داخل حمولة html.

الحقل	النوع	مطلوب	الوصف
html	string	نعم	محتوى HTML للعنوان. يُدعم ترميز الأدوات المضمّنة.
level	'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'	لا	مستوى العنوان. أحد القيم: h1 وh2 وh3 وh4 وh5 وh6. القيمة الافتراضية: h1.

JSON

{
  "type": "header",
  "data": { "html": "Getting started", "level": "h2" }
}

image

كتلة صورة مع تعليق ونص بديل alt. تُستهلك عبر دالة الاستدعاء imageUploader في Editor.create.

الحقل	النوع	مطلوب	الوصف
url	string	نعم	رابط الصورة المراد تضمينها.
caption	string	لا	تعليق نصي عادي يظهر أسفل الصورة.
alt	string	لا	النص البديل لعنصر الصورة.
alignment	'center' \| 'left' \| 'right'	لا	المحاذاة الأفقية للصورة. أحد القيم: center وleft وright.

JSON

{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

issues

جدول بالمشكلات المرتبطة يُشتق عند العرض من شارات وكروت المشكلات في الصفحة (المشكلة، العنوان، الحالة، المسؤول). لا يخزّن بيانات خاصة به.

لا تخزّن هذه الكتلة أي حقول؛ تُشتق الصفوف من شارات وكروت المشكلات في الصفحة عند العرض.

JSON

{
  "type": "issues",
  "data": {}
}

latex

رياضيات LaTeX، تُخزَّن كمصدر وتُنضَّد عند العرض. أي منضّد أفضل لاحقًا يحسّن كل مستند موجود بالفعل.

الحقل	النوع	مطلوب	الوصف
source	string	نعم	مصدر LaTeX. يُخزَّن كمصدر، وليس أبدًا كناتج منضَّد.

JSON

{
  "type": "latex",
  "data": { "source": "\\frac{a}{b}" }
}

list

قائمة مرتّبة أو غير مرتّبة. كل عنصر هو html.

الحقل	النوع	مطلوب	الوصف
type	'ordered' \| 'unordered'	نعم	نوع القائمة. أحد القيم: ordered وunordered.
items	string[]	نعم	مصفوفة من سلاسل HTML، واحدة لكل عنصر من عناصر القائمة.

JSON

{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

mermaid

مخطط Mermaid، يُخزَّن كمصدر ويُرسم عند العرض، وليس أبدًا كصورة نقطية.

الحقل	النوع	مطلوب	الوصف
source	string	نعم	مصدر Mermaid. يُخزَّن كمصدر، وليس أبدًا كناتج مرسوم.

JSON

{
  "type": "mermaid",
  "data": { "source": "flowchart TD\n  A --> B" }
}

openapi

يعرض مرجع API تفاعليًا من مستند OpenAPI 3.x، مضمّنًا أو مجلوبًا من رابط، مع منتقي خوادم ومقاطع شيفرة.

الحقل	النوع	مطلوب	الوصف
spec	object	لا	مستند OpenAPI 3.x مضمّن. يتقدّم على url عند ضبط الاثنين.
url	string	لا	من أين يُجلب مستند OpenAPI عند العرض.
include	OpenApiFilter	لا	مرشّح للعمليات التي تُعرض.
exclude	OpenApiFilter	لا	مرشّح للعمليات التي تُخفى.
defaultServer	string	لا	الخادم الذي يختاره المرجع افتراضيًا.
snippetLanguages	CodeLanguage[]	لا	اللغات المتاحة لمقاطع الطلبات.

JSON

{
  "type": "openapi",
  "data": { "url": "/api/openapi.json", "defaultServer": "https://api.example.com" }
}

paragraph

فقرة نص منسّق. تقبل ترميز الأدوات المضمّنة مثل bold وitalic وcode وlink وmarker وtooltip.

الحقل	النوع	مطلوب	الوصف
html	string	نعم	محتوى HTML للفقرة. يُدعم ترميز الأدوات المضمّنة.

JSON

{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

اقتباس مع إسناد اختياري للمؤلف.

الحقل	النوع	مطلوب	الوصف
html	string	نعم	محتوى HTML لجسم الاقتباس. يُدعم ترميز الأدوات المضمّنة.
author	string	لا	إسناد نصي عادي أو HTML يظهر أسفل الاقتباس.

JSON

{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

sketch

رسم حر يُخزَّن كضربات، وليس أبدًا كصورة نقطية، فيبقى قابلًا للتحرير ويتدرّج بنقاء.

الحقل	النوع	مطلوب	الوصف
strokes	SketchStroke[]	نعم	الرسم كضربات: كل ضربة قائمة نقاط مع لون وعرض اختياريين.

JSON

{
  "type": "sketch",
  "data": { "strokes": [{ "points": [0, 0, 10, 10], "color": "#ff0000", "width": 3 }] }
}

table

شبكة بيانات. يمكن استخدام الصف الأول كرأس؛ كل خلية هي html.

الحقل	النوع	مطلوب	الوصف
data	string[][]	نعم	مصفوفة ثنائية الأبعاد من سلاسل خلايا HTML. الصف الأول هو صف الرأس.
caption	string	لا	تعليق نصي عادي أو HTML يظهر أسفل الجدول.
showDownload	boolean	لا	عرض زر تنزيل في الناتج المُصيَّر.

JSON

{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

updates

موجز نشاط حي لمستند. يخزّن الهوية لا لقطة، فيواصل عرض النشاط الجاري.

الحقل	النوع	مطلوب	الوصف
pageId	string	لا	نشاط أي مستند يُعرض. غيابه يعني المستند الذي تقع فيه الكتلة.

JSON

{
  "type": "updates",
  "data": { "pageId": "p-7" }
}

video

كتلة فيديو. تُستهلك عبر دالة الاستدعاء videoUploader في Editor.create.

الحقل	النوع	مطلوب	الوصف
url	string	نعم	رابط ملف الفيديو أو رابط تضمين YouTube/Vimeo.
caption	string	لا	تعليق نصي عادي يظهر أسفل المشغّل.
alt	string	لا	تسمية يمكن الوصول إليها لعنصر الفيديو.
alignment	'center' \| 'left' \| 'right'	لا	المحاذاة الأفقية للمشغّل. أحد القيم: center وleft وright.

JSON

{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}

المرجع

الحزم

مرجع الكتل

شكل الكتلة

alert

audio

checklist

code

collapsible

collection

columns

date

delimiter

doc_card

embed

file

glance

header

image

issues

latex

list

mermaid

openapi

paragraph

quote

sketch

table

toc

updates

video