> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/ar/mlfat-alfeh/04-writing-your-own-class.md). # كتابة فئة خاصة بك أحيانًا يكون أفضل خيار لتخصيص مستند هو كتابة فئة جديدة من الصفر. تشرح هذه المقالة البنية الأساسية والأوامر المطلوبة في فئة جديدة. ## مقدمة أول ما يجب فعله قبل برمجة فئة جديدة هو تحديد ما إذا كنت تحتاج حقًا إلى فئة جديدة أم لا. يُوصى بـ [البحث في CTAN (شبكة أرشيف TeX الشاملة)](http://www.ctan.org/ctan-portal/search/) والتحقق مما إذا كان أحدهم قد أنشأ بالفعل شيئًا مشابهًا لفئة المستند التي تحتاجها. شيء مهم آخر يجب أخذه في الاعتبار هو [الفرق بين الحزم والفئات](/latex/ar/mlfat-alfeh/01-understanding-packages-and-class-files.md). قد يؤثر اتخاذ الخيار الخاطئ في مرونة المنتج النهائي. ## البنية العامة يمكن وصف بنية جميع ملفات الفئات تقريبًا في الأجزاء الأربعة التالية: * ***التعريف***. يعلن الملف عن نفسه كفئة مكتوبة باستخدام صياغة LaTeX2ε. * ***التصريحات التمهيدية***. هنا يتم استيراد الحزم والفئات الخارجية المطلوبة. كما تُكتب في هذا الجزء من الملف الأوامر والتعريفات اللازمة للخيارات المعلنة. * ***الخيارات***. تُعلن الفئة عن الخيارات وتعالجها. * ***تصريحات إضافية***. الجسم الرئيسي للفئة. يُعرَّف هنا تقريبًا كل ما تفعله الفئة. في الأقسام الفرعية التالية سيُعرض وصف أكثر تفصيلًا للبنية ومثال عملي، *exampleclass.cls*، سيتم تقديمهما. ### التعريف هناك أمران بسيطان يجب أن تتضمنهما جميع الفئات: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] ``` الأمر `\NeedsTeXFormat{LaTeX2e}` يحدد إصدار LaTeX الذي ستعمل به الفئة. بالإضافة إلى ذلك، يمكن إضافة تاريخ بين الأقواس لتحديد الحد الأدنى لتاريخ الإصدار المطلوب. الأمر `ProvidesClass{exampleclass}[...]` يعرّف هذه الفئة على أنها *exampleclass* ويُدرج داخل الأقواس تاريخ الإصدار وبعض المعلومات الإضافية. يجب أن يكون التاريخ بالشكل YYYY/MM/DD [افتح مثالًا على كيفية كتابة فئة في Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### التصريحات التمهيدية تقوم معظم الفئات بتوسيع وتخصيص الفئات الموجودة، كما تحتاج أيضًا إلى بعض الحزم الخارجية لتعمل. أدناه، تمت إضافة المزيد من الشيفرة إلى الفئة النموذجية `exampleclass.cls`. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \LoadClass[twocolumn]{article} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} ``` الأوامر في هذا الجزء إما تهيئ بعض المعلمات التي ستُستخدم لاحقًا لإدارة الخيارات، أو تستورد ملفات خارجية. الأمر `\LoadClass[twocolumn]{article}` يحمل الفئة `article` بالوسيط الإضافي `twocolumn`. وبالتالي ستكون جميع الأوامر في `article` الفئة القياسية **مثال** متاحة تلقائيًا في فئة المستند، باستثناء أن المستند سيُطبع بتنسيق عمودين. `\RequirePackage` يشبه كثيرًا الأمر الشهير `\usepackage`، كما أن إضافة معاملات اختيارية بين الأقواس ستعمل أيضًا. والفرق الوحيد هو أن `\usepackage` لا يمكن استخدامه قبل `\documentclass` الأمر. يُنصح بشدة باستخدام `\RequirePackage` عند كتابة فئات أو حزم جديدة. [افتح مثالًا على كيفية كتابة فئة في Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### الخيارات للسماح ببعض المرونة في الفئات، تكون بعض الخيارات الإضافية مفيدة جدًا. الجزء التالي في الملف `exampleclass.cls` يعالج المعلمات الممررة إلى أمر فئة المستند. وقد نقلنا أيضًا `\LoadClass` إلى *بعد* تُعالج الخيارات، بحيث يمكن تمرير الخيارات المحددة في ملف .tex إلى الفئة الأساسية. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} ``` هناك أربعة أوامر رئيسية هنا تتعامل مع الخيارات الممررة إلى الفئة. الأمر `\DeclareOption{}{}` يتعامل مع خيار معيّن. يأخذ معاملين؛ الأول هو اسم الخيار والثاني هو الشفرة التي ستُنفَّذ إذا تم تمرير الخيار. الأمر `\OptionNotUsed` سيعرض رسالة في المترجم وفي السجلات، ولن يُستخدم الخيار. في هذه الحالة يُضبط المستند على عمودين، وإذا حاول المستخدم تغييره إلى عمود واحد فلن ينجح ذلك، وسيُتجاهل الخيار. الأمر `\Declareoption*{}` يتعامل مع كل خيار غير معرّف صراحةً. ويأخذ وسيطًا واحدًا فقط، وهو الشيفرة التي ستُنفّذ عند تمرير خيار غير معروف. في هذه الحالة سيشغّل الأمر التالي: `\PassOptionsToClass{}{}`يمرر الخيار الموجود داخل الزوج الأول من الأقواس إلى فئة المستند المحددة داخل الزوج الثاني من الأقواس. في المثال، ستُمرر جميع الخيارات غير المعروفة إلى **article** فئة المستند. `\CurrentOption` يخزن اسم خيار الفئة الجاري التعامل معه في لحظة معينة. الأمر `\ProcessOptions\relax` ينفذ الشيفرة الخاصة بكل خيار، ويجب إدراجه بعد كتابة جميع أوامر معالجة الخيارات. توجد نسخة مُنجّمة من هذا الأمر ستنفذ الخيارات بالترتيب الدقيق الذي تحدده الأوامر المستدعية. في المثال، إذا كانت الخيارات `أحمر` أو `green` تُمرر إلى المستند، وسيُضبط الخط المستخدم للعنوان الرئيسي والأقسام على اللون المقابل. اللون المسمى `slcolor` تم تعريفه في [التصريحات التمهيدية](#preliminary-declaration) بعد استيراد `xcolor` الحزمة. [افتح مثالًا على كيفية كتابة فئة في Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ### تصريحات إضافية في هذا الجزء ستظهر معظم الأوامر. في "exampleclass.cls" يتم ضبط أبعاد الصفحة، وحجم الخط للعنوان، والنص الرئيسي، والأقسام. أدناه يمكنك رؤية ملف الفئة الكامل. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesClass{exampleclass}[2014/08/16 Example LaTeX class] \newcommand{\headlinecolor}{\normalcolor} \RequirePackage{xcolor} \definecolor{slcolor}{HTML}{882B21} \DeclareOption{onecolumn}{\OptionNotUsed} \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} \DeclareOption{red}{\renewcommand{\headlinecolor}{\color{slcolor}}} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions\relax \LoadClass[twocolumn]{article} \renewcommand{\maketitle}{% \twocolumn[% \fontsize{50}{60}\fontfamily{phv}\fontseries{b}% \fontshape{sl}\selectfont\headlinecolor \@title \medskip ]% } \renewcommand{\section}{% \@startsection {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% } \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont} \setlength{\textwidth}{17.5cm} \setlength{\textheight}{22cm} \setcounter{secnumdepth}{0} ``` لفهم بقية الأوامر، انظر إلى [دليل المراجع](#reference-guide) والروابط في [قسم القراءة الإضافية](#further-reading). الأوامر الأربعة الأخيرة في المثال تُظهر الأشياء الأربعة التي يجب أن تتضمنها جميع الفئات: * تعريف `normalsize`. يضبط الإعداد الافتراضي لـ [حجم الخط](/latex/ar/alkhtwt/01-font-sizes-families-and-styles.md). * قيمة افتراضية لـ [`textwidth`](/latex/ar/altnsyq/07-page-size-and-margins.md) * قيمة افتراضية لـ [`textheight`](/latex/ar/altnsyq/07-page-size-and-margins.md) * المواصفات الخاصة بـ [ترقيم الصفحات](/latex/ar/altnsyq/03-page-numbering.md). أدناه، مستند يستخدم الفئة *exampleclass.cls*. ```latex \documentclass[red]{exampleclass} \usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage{blindtext} \title{Example to show how classes work} \author{Team Learn ShareLaTeX} \date{August 2014} \begin{document} \maketitle \noindent لنبدأ هنا بمثال عملي بسيط. \blindtext \section{Introduction} مشكلة مونتي هول... \section{The same thing} مونتي... ``` ![WrittingClassesEx1.png](/files/40ac0f29d1deeacd8a6ffe563d2eddf1262c5e8e) لاحظ أن الأمر الأول هنا هو ```latex \documentclass[red]{exampleclass} ``` [افتح مثالًا على كيفية كتابة فئة في Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## معالجة الأخطاء عندما يتعلق الأمر بتطوير فئات جديدة، من المهم التعامل مع الأخطاء المحتملة لإعلام المستخدم بأن شيئًا ما قد حدث بشكل خاطئ. توجد أربعة أوامر رئيسية للإبلاغ عن الأخطاء في المترجم. * `\ClassError{*class-name*}{*error-text*}{*help-text*}`. يأخذ ثلاثة معاملات، كل واحد داخل أقواس: اسم الفئة، ونص الخطأ الذي سيُعرض (ستتوقف عملية الترجمة مؤقتًا)، ونص المساعدة الذي سيُطبع إذا ضغط المستخدم على "h" عندما تتوقف عملية الترجمة بسبب الخطأ. * `\ClassWarning{*class-name*}{*warning-text*}`. في هذه الحالة سيُعرض النص، لكن عملية الترجمة لن تتوقف. وسيظهر رقم السطر الذي حدث فيه التحذير. * `\ClassWarningNoLine{*class-name*}{*warning-text*}`. يعمل تمامًا مثل الأمر السابق، لكنه لن يعرض السطر الذي حدث فيه التحذير. * `\ClassInfo{*class name*}{*info-text*}`. في هذه الحالة ستُطبع المعلومات في المعامل الثاني فقط في ملف السجل، بما في ذلك رقم السطر. [افتح مثالًا على كيفية كتابة فئة في Overleaf](https://www.overleaf.com/project/new/template/19419?id=65524436\&templateName=An+example+of+writing+a+LaTeX+class\&latexEngine=\&texImage=texlive-full%3A2020.1\&mainFile=) ## دليل المراجع **قائمة بالأوامر الشائعة الاستخدام في الفئات والحزم** * `\newcommand{*name*}{*definition*}`. يُعرّف [أمرًا جديدًا](/latex/ar/alawamr/01-commands.md#defining-a-new-command)، المعامل الأول هو اسم الأمر الجديد، والمعامل الثاني هو ما سيفعله الأمر. * `\renewcommand{}{}`. بنفس معنى `\newcommand` ولكنه سيستبدل أمرًا موجودًا. * `\providecommand{}{}`. يعمل تمامًا مثل `\newcommand` ولكن إذا كان الأمر معرّفًا بالفعل فسيُتجاهل هذا الأمر بصمت. * `\CheckCommand{}{}`. يكون التركيب نفسه مثل `\newcommand`، بل سيتحقق بدلًا من ذلك مما إذا كان الأمر موجودًا وكان له التعريف المتوقع، وسيعرض LaTeX تحذيرًا إذا لم يكن الأمر هو ما `\CheckCommand` كان متوقعًا. * `\setlength{}{}`. يضبط طول العنصر الممرَّر كمعامل أول إلى القيمة المكتوبة كمعامل ثانٍ. * `\mbox{}`. ينشئ صندوقًا يحتوي العناصر المكتوبة داخل الأقواس. * `\fbox{}`. بنفس معنى `\mbox`، لكن يتم في الواقع طباعة صندوق حول المحتويات. ## قراءة إضافية لمزيد من المعلومات، انظر * [فهم الحزم وملفات الأصناف](/latex/ar/mlfat-alfeh/01-understanding-packages-and-class-files.md) * [كتابة حزمة خاصة بك](/latex/ar/mlfat-alfeh/03-writing-your-own-package.md) * [الأوامر](/latex/ar/alawamr/01-commands.md) و [البيئات](/latex/ar/alawamr/02-environments.md) * [الأطوال في LaTeX](/latex/ar/altnsyq/01-lengths-in-latex.md) * [استخدام الألوان في LaTeX](/latex/ar/altnsyq/13-using-colors-in-latex.md) * [الإدارة في مشروع كبير](/latex/ar/bnyh-almstnd/07-management-in-a-large-project.md) * [LaTeX2ε لمؤلفي الفئات والحزم](http://www.latex-project.org/guides/clsguide.pdf) * [ملاحظات حول البرمجة في tex](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [دقائق بدلًا من ساعات: استخدام موارد LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [رفيق LaTeX. الطبعة الثانية](http://ptgmedia.pearsoncmg.com/images/9780201362992/samplepages/0201362996.pdf) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/ar/mlfat-alfeh/04-writing-your-own-class.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.