\usepackage{listings}
كتل الشيفرة في LaTeX باستخدام listings
حزمة listings هي الطريقة القياسية لتنضيد الشيفرة المصدرية في LaTeX. توفر تمييز الصياغة لأكثر من 80 لغة، وترقيم الأسطر، وإطارات مخصصة، وألوان خلفية، وأنماطًا مسماة، وكل ذلك دون مغادرة مستندك.
الاستخدام الأساسي لـ listings
يعرض المثال أدناه إعدادًا بسيطًا لكنه كامل: حمّل الحزمة، واضبطها عامًا باستخدام \lstset{…}، ثم ضع الشيفرة داخل بيئة lstlisting مع لغة وعنوان توضيحي.
\documentclass{article}
\usepackage{listings}
\usepackage{xcolor}
% Global listings configuration
\lstset{
basicstyle=\ttfamily\small,
keywordstyle=\color{blue}\bfseries,
commentstyle=\color{gray}\itshape,
stringstyle=\color{orange},
breaklines=true,
showstringspaces=false,
frame=single,
rulecolor=\color{black!20},
tabsize=2,
}
\begin{document}
\begin{lstlisting}[language=Python, caption={Hello World in Python}]
def greet(name: str) -> None:
# Print a personalised greeting
message = f"Hello, {name}!"
print(message)
greet("World")
\end{lstlisting}
\end{document}الإعداد الأساسي
Add \usepackage{listings} and optionally \usepackage{xcolor} to your preamble. Wrap code in a \begin{lstlisting}…\end{lstlisting} environment.
دعم اللغات
حدد اللغة بالخيار language=: Python وC++ وJava وBash وSQL وHTML وأكثر من 80 لغة أخرى مضمَّنة وتطبّق تلوين الكلمات المفتاحية تلقائيًا.
العنوان التوضيحي والوسم
Use caption={…} to add a numbered caption below the listing, and label={lst:name} for cross-references with \ref{lst:name} anywhere in your document.
الإعداد العام
\lstset{} applies settings globally to all listings. Place it in your preamble after \usepackage{listings} to avoid repeating options on every environment.
خيارات التنسيق
عرّف نمطًا مسمى باستخدام \lstdefinestyle{name}{…} وفعّله عامًا باستخدام \lstset{style=name}. ينشئ المثال أدناه ألوانًا مخصصة للخلفية والتعليقات والكلمات المفتاحية والسلاسل النصية، ثم يعرضها في تنفيذ للبحث الثنائي بلغة C++.
يرسم الخيار frame=tb خطًا أفقيًا فوق الشيفرة وتحتها، بينما يضيف numbers=left ترقيم الأسطر في الهامش الأيسر.
\documentclass{article}
\usepackage{listings}
\usepackage{xcolor}
% Custom colour definitions
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.58,0,0.82}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
\lstdefinestyle{mystyle}{
backgroundcolor=\color{backcolour},
commentstyle=\color{codegreen},
keywordstyle=\color{magenta}\bfseries,
numberstyle=\tiny\color{codegray},
stringstyle=\color{codepurple},
basicstyle=\ttfamily\footnotesize,
breakatwhitespace=false,
breaklines=true,
captionpos=b,
keepspaces=true,
numbers=left,
numbersep=5pt,
showspaces=false,
showstringspaces=false,
showtabs=false,
tabsize=2,
frame=tb,
}
\lstset{style=mystyle}
\begin{document}
\begin{lstlisting}[language=C++, caption={Binary search}, label={lst:binsearch}]
#include <iostream>
using namespace std;
int binarySearch(int arr[], int n, int target) {
int left = 0, right = n - 1;
while (left <= right) {
int mid = left + (right - left) / 2;
if (arr[mid] == target) return mid;
else if (arr[mid] < target) left = mid + 1;
else right = mid - 1;
}
return -1; // not found
}
\end{lstlisting}
\end{document}لون الخلفية
Use backgroundcolor=\color{name} inside \lstdefinestyle{} to apply a tinted background. Define custom colours first with \definecolor{name}{rgb}{r,g,b}.
ترقيم الأسطر
Enable with numbers=left (or right). Control the font size and colour with numberstyle=\tiny\color{gray} and adjust the gutter width via numbersep=5pt.
الإطارات
يرسم الخيار frame= حدودًا: single (مربع كامل) أو tb (خطان علوي وسفلي فقط) أو lines (خطان علوي وسفلي) أو none. اجمعه مع rulecolor= للحصول على خطوط منسّقة.
اللغات المدعومة
تأتي listings مع مجموعات كلمات مفتاحية مضمَّنة لأكثر من 80 لغة برمجة وترميز. حدد لغة باستخدام language= في البيئة أو عامًا في \lstset{}.
لغتك غير مدرجة؟ عرّفها بنفسك باستخدام \lstdefinelanguage، راجع القسم أدناه.
تعريف لغة مخصصة
عندما لا تكون لغتك مضمَّنة، استخدم \lstdefinelanguage{name}{…} للإعلان عن الكلمات المفتاحية وصياغة التعليقات ومحددات السلاسل النصية. ضعها في المقدمة (preamble) قبل أول استخدام.
\lstdefinelanguage{MyLang}{
keywords={let, const, fn, return, if, else},
keywordstyle=\color{blue}\bfseries,
sensitive=true,
comment=[l]{//},
commentstyle=\color{gray}\itshape,
string=[b]",
stringstyle=\color{orange},
}
\begin{lstlisting}[language=MyLang]
fn add(a: Int, b: Int) -> Int {
return a + b // sum of two integers
}
\end{lstlisting}listings مقابل minted
تنضّد الحزمتان الشيفرة، لكن لكل منهما نهجًا مختلفًا تمامًا. اختر بحسب بيئة البناء ومتطلبات التمييز لديك.
listings
- + LaTeX خالص، دون اعتماديات خارجية
- + تعمل مع pdfLaTeX وXeLaTeX وLuaLaTeX
- + تأتي مع كل توزيعة قياسية
- − دعم Unicode محدود في محتوى الشيفرة
- − يعتمد التمييز على التعابير النمطية لا على محلل لغوي حقيقي
minted
- + مدعومة بـ Pygments: تمييز قائم على محلل لغوي كامل
- + تمييز دقيق للصياغة المعقدة
- + دعم كامل لـ UTF-8 / Unicode في الشيفرة
- − تتطلب تثبيت Python وPygments
- − تحتاج إلى خيار المُجمِّع --shell-escape
جرّبها في الـ playground
افتح مثال listings المنسّق، بألوان مخصصة وترقيم أسطر وبحث ثنائي بلغة C++، مباشرةً في FormaTeX playground. عدّل وجمّع إلى PDF في ثوانٍ، دون الحاجة إلى تثبيت.
الأسئلة الشائعة
هل listings مضمَّنة في LaTeX القياسي؟
Yes. The listings package ships with every major LaTeX distribution (TeX Live, MiKTeX, MacTeX). You do not need to install anything extra — just add \usepackage{listings} to your preamble.
كيف أضيف ترقيم الأسطر؟
Pass numbers=left or numbers=right to \lstset{} or directly on the environment as an option. Control the style with numberstyle=\tiny\color{gray} and the gap width with numbersep=5pt.
هل يمكنني استخدام أحرف UTF-8 في listings؟
Not directly — listings processes its content as plain ASCII by default. For accented characters (é, ü, etc.) add inputencoding=utf8 and define each character with \lstset{literate={é}{{\'{e}}}1 ...}. For full Unicode support, consider the minted package with LuaLaTeX.
ما الفرق بين verbatim وlistings؟
تعيد بيئة verbatim إنتاج النص حرفًا بحرف دون أي تنسيق. أما listings فتبني على هذا الأساس وتضيف تمييز الصياغة وترقيم الأسطر والعناوين التوضيحية والإطارات والإحالات المتقاطعة واكتشاف الكلمات المفتاحية الواعي باللغة، ما يجعلها أنسب بكثير لتنضيد الشيفرة المصدرية الفعلية.
\end{document}
جمّع مستند listings الخاص بك
استخدم FormaTeX API أو الـ playground لتجميع المستندات التي تستخدم حزمة listings. لا حاجة إلى تثبيت TeX محليًا، أرسل مصدرك فقط واحصل على PDF.