مرجع الواجهة — 0.2.0¶

LectureDeck¶

LectureDeck(
    course="مختبر التعلم", *, series="LECTURE STUDIO", lesson="",
    language="python", theme="gold", brand=None, **theme_options
)

brand يقبل Brand أو قاموسًا، ويحل محل معاملات الهوية المباشرة. theme يقبل اسم ثيم أو Theme. عند تمرير Theme ضع خياراته داخله، ولا تمرر خيارات متعارضة إلى المنشئ.

الدالة	المعاملات	السلوك
`cover`	`title, description='', *, kicker='', tags=(), sections=(), hero_code='', hero_result='', hero_label=None, footer_label=None, show=True`	غلاف؛ البطاقة المتحركة اختيارية.
`slide`	`title, description='', *, cards=(), subtitle='', diagram=None, activity=None, show=True`	شريحة مرقمة؛ المكونات الفرعية اختيارية.
`note`	`title, body='', *, show=True`	فقرة على خلفية فاتحة.
`table`	`title, headers, rows, *, show=True`	جدول قابل للتمرير.
`render`	`content, *, show=True`	قاموس مكون أو قائمة مكونات؛ `type` افتراضيًا slide.
`from_file`	`path, *, show=True`	دالة صنف تحمل JSON وتعيد deck جاهزًا.
`export`	`path, *, title=None`	تكتب HTML مستقلًا وتعيد `Path` مطلقًا.
`clear`	بلا معاملات	تصفر المجموعة والترقيم.

cover/slide/note/table تعرض داخل Jupyter وتعيد None افتراضيًا لتجنب تكرار المخرجات. في السكربتات استخدم show=False لإرجاع HTML كسلسلة. render(show=False) يعيد سلسلة للمكون الواحد وقائمة سلاسل للقائمة. يتم تضمين CSS مع كل خرج لكي يبقى منسقًا عندما يدير Jupyter عرض الخلايا.

نماذج المحتوى¶

يمكن استخدام النماذج أو قواميس بنفس أسماء الحقول:

Card(title, explanation='', code='', reason='', language=None)
Node(value, note='', selected=False)
Diagram(title, nodes, caption='', direction='ltr', arrows=True, kind='flow')
Activity(question, answer, code='', language=None,
         label='توقّع قبل التنفيذ', reveal='اكشف الإجابة وفسّرها')
CoverSection(title, description='')
RichText(html)

Diagram.nodes تحتوي Node عند إنشاء النموذج مباشرة. عند تمرير قاموس إلى slide، تتحول قواميس العقد تلقائيًا. Card.explanation/reason وdescription/body تقبل RichText صريحًا. بقية الحقول نصوص عادية. kind اسم CSS من حروف صغيرة وأرقام وشرطات؛ استخدم flow للرسم العام.

Brand(course='مختبر التعلم', series='LECTURE STUDIO', lesson='',
      footer='افهم ← توقّع ← جرّب ← فسّر', language='python')
Theme(preset='gold', accent=None, background=None, motion=True,
      direction='rtl', max_width=1280, notebook_style=False, external_fonts=False)

الألوان المخصصة #RRGGBB. العرض بين 320 و2400. الاتجاه rtl أو ltr. الثيم gold/emerald/ocean. أسماء المعاملات غير المعروفة تفشل برسالة Python بدل تجاهلها. البيانات غير الصحيحة ترفع ValueError أو TypeError.

رسومات جاهزة¶

diagram_names() يعيد أسماء الرسومات، وpreset_diagram(name) يعيد Diagram يمكن استخدامه مباشرة. هذه الرسومات أمثلة بايثون، ولا تدخل تلقائيًا في أي مادة.

واجهة التوافق¶

from jupyter_lecture_studio.compat import LuxurySlideDeck

deck = LuxurySlideDeck()
deck.show({
    'title': 'المفهوم',
    'description': '<p>شرح قديم موثوق</p>',
    'steps_data': [{'title': 'مثال', 'explanation': 'شرح', 'code_snippet': 'print(1)'}],
    'visual': 'names',
    'checkpoint': {'question': 'ماذا يحدث؟', 'answer': 'التفسير'},
})

تحافظ على show, steps_data, code_snippet, visual, checkpoint. تنسيق HTML القديم موثوق صراحة داخل الجسر. الواجهة الجديدة هي الخيار المفضل للمحاضرات القادمة.

cover(..., footer_label=None) يحدد نص تذييل الغلاف؛ عدم تمريره يستخدم اسم المحاضرة. الخطان Cairo وJetBrains Mono مضمنان افتراضيًا. RichText('') وRichText(' ') محتوى فارغ ولا ينشئان مربع سبب فارغًا.