# ذكاء الكود

تنقّل بجودة بيئات التطوير المتكاملة لملفات LaTeX وTypst: الانتقال إلى التعريف، وإيجاد المراجع، وإعادة التسمية على مستوى المشروع، وبطاقات التحويم، ومعاينة الرياضيات، ومخطط المستند، ومساعدة التواقيع والتنسيق في Typst.

يفهرس Oleafly المشروع بأكمله، بما في ذلك كل `\label` ومفتاح اقتباس وماكرو مخصص ونظرية وإدخال في المسرد، والرسم البياني لعلاقات `\input` الذي يربط ملفاتك. هذا الفهرس هو ما يشغّل التنقل بين الملفات. وتستخدم ملفات Typst الاختصارات نفسها، لكن يجيب عنها خادم لغة Typst؛ انظر [ملفات Typst](#typst-files) أدناه.

تُعرض الاختصارات بمفاتيح macOS. على Windows وLinux، اقرأ ⌘ بوصفها Ctrl.

## الانتقال إلى التعريف: F12 أو النقر مع ⌘

ضع المؤشر على `\ref` أو مفتاح `\cite` أو ماكرو مخصص أو `\begin{env}` لبيئة عرّفتها، أو مصطلح من المسرد، ثم اضغط F12 (أو اضغط ⌘ باستمرار وانقر عليه). ينتقل المحرر إلى موضع التعريف، ويفتح ملف التعريف إن كان في مكان آخر من المشروع.

إذا ضغطت F12 وأنت أصلًا على تعريف، انقلب الأمر إلى إيجاد مراجعه، وهو العرف نفسه الذي تتبعه بيئات التطوير المتكاملة.

## إيجاد المراجع: ⇧F12

يعرض Shift+F12 كل استخدامات الرمز في لوحة **References** في الشريط الأيسر: صف واحد لكل ورود، مع الملف والسطر ومعاينة، وشارة «def» على التعريف نفسه. انقر صفًّا للانتقال إليه. إنها أسرع طريقة للإجابة عن «هل يمكنني حذف هذا الوسم؟» أو «أين اقتبست هذه الورقة؟».

![إعادة تسمية وسم معادلة في ملفين دفعة واحدة، ثم سرد مراجعه.](https://cdn.oleafly.com/images/gifs/desktop/rename-symbol.gif?v=2)

## إعادة تسمية الرمز: F2

تعيد F2 تسمية وسم أو مفتاح اقتباس أو ماكرو أو نظرية أو إدخال مسرد أو بيئة في المشروع كله في خطوة واحدة: يتحدّث الملف المفتوح مباشرة، وتُعاد كتابة الملفات الأخرى على القرص، ويُعاد بناء الفهرس. وإذا كان الاسم الجديد موجودًا فعلًا، تُحجب إعادة التسمية قبل أن تنشئ تعارضًا، وتعرض رسالة منبثقة عدد التعديلات التي أُجريت وعدد الملفات التي تمت فيها.

إعادة تسمية `fig:overview` إلى `fig:architecture` مع تحديث مراجع `\ref` الستة كلها عملية لا تستغرق ثانيتين.

وإذا كان المؤشر على مسار ملف بدلًا من ذلك، مثل وسيط `\input` أو `\includegraphics`، فإن F2 تعيد تسمية ذلك الملف وتحدّث المسارات التي تشير إليه. ويعمل الأمر نفسه على `#include` و`image()` في Typst وعلى الروابط والصور في Markdown. انظر [المسارات تتبع الملف المنقول](/docs/files/#paths-follow-a-moved-file).

## بطاقات التحويم

حوّم فوق أي رمز فتظهر بطاقة تشرحه:

- عند **مرجع**: نوع الرمز ومعاينة المصدر والموضع. بعد بناء ناجح لـ LaTeX، تعرض المراجع المدعومة أيضًا الرقم والصفحة في الملف المُجمَّع.
- عند **تعريف**: عدد المراجع التي تشير إليه عبر المشروع.
- عند أي شيء **غير محلول**: وسم «Unresolved» واضح، وهو أول إنذار مبكر لك من `\ref` فيه خطأ مطبعي أو إدخال `.bib` مفقود.

اضغط ⌘ (أو Ctrl) باستمرار أثناء التحويم، فتظهر الرموز القابلة للنقر بخط تحتها مثل الروابط؛ انقر للانتقال.

## معاينة الرياضيات عند التحويم

حوّم فوق رياضيات سطرية بين `$…$` أو `\(…\)`، أو رياضيات عرض بين `\[…\]`، لتصييرها باستخدام KaTeX دون بناء. تستخدم رياضيات العرض نمط العرض. وإذا كان التعبير مكسورًا عُرض خطؤه.

## لوحة المخطط Outline

تحت شجرة الملفات، تعرض لوحة **Outline** بنية مستندك: أقسام مزاحة بحسب مستواها، إضافة إلى تضمينات `\input`، عبر جميع الملفات. تحمل العناصر الواردة من ملفات أخرى شارة باسم الملف. انقر أي عنصر للانتقال إليه مباشرة. وبالنسبة لأطروحة موزعة على نحو عشرة ملفات فصول، فهذه قائمة المحتويات التي تتنقل من خلالها.

تُعرض عناوين الأقسام نصًّا عاديًّا، لذلك لا يظهر أمر الألوان أو تبديل الخط أو `\nameref` في عنوان بصيغة LaTeX خام. تُدرَج العناوين التي تنشئها ماكروهاتك الخاصة المغلِّفة لـ `\section`، ولا تُدرَج العناوين الواقعة داخل تعريف ماكرو.

يمكن سحب الفاصل بين الشجرة والمخطط لتغيير الحجم.

## أين يقع شريط الأدوات والقائمة

أوامر التنقل الثلاثة موجودة أيضًا في قائمة **Code intelligence** على شريط أدوات المحرر (أيقونة الحاصرة المتعرجة) وفي قائمة النقر بالزر الأيمن، بحيث يمكن العثور عليها قبل أن تصبح الاختصارات عادة راسخة.

## ملفات Typst

في ملفات `.typ`، يجيب Tinymist، خادم لغة Typst، عن معظم هذه الأوامر. يشغّل Oleafly إصدار Tinymist المطابق لإصدار Typst في المشروع (انظر [مشاريع Typst](/docs/typst/#the-language-server-follows-the-version)).

- ينتقل F12 أو النقر مع ⌘ إلى تعريف وسم أو متغير أو دالة، بما في ذلك تعريف في ملف آخر.
- يعرض ⇧F12 كل الاستخدامات في لوحة **References**.
- تعيد F2 تسمية وسم أو متغير أو دالة عبر المشروع.
- حوّم فوق دالة لقراءة توثيقها. وحوّم فوق استيراد `@preview` للحصول على رابط الحزمة على Typst Universe.

الأوامر الثلاثة نفسها موجودة في قائمة **Code intelligence** على شريط أدوات Typst، وفي قائمة النقر بالزر الأيمن، وفي لوحة الأوامر ⌘K. تبقى الوسوم في ملفات Typst وملفات LaTeX منفصلة، فلا يُبلَّغ عن وسم مستخدم في كليهما مرتين، وإعادة تسمية أحدهما تترك الآخر دون تغيير.

### مساعدة التواقيع وتلميحات الوسائط

اكتب `(` بعد اسم دالة فتظهر بطاقة بوسائطها، والوسيط الذي تكتبه الآن مُبرَز. يغلقها Esc. ولرؤية أسماء الوسائط مكتوبة قبل كل وسيط في استدعاءات الدوال، فعِّل **Parameter name hints** في **Settings → Appearance → Editor** ضمن **Typst**.

تحصل قيم الألوان مثل `rgb("#1f77b4")` على عيّنة لون صغيرة بجانبها. وانقر مع ⌘ على رابط أو مسار ملف في المصدر لفتحه.

### تنسيق ملف Typst

يرتّب **Format document** الملف كله باستخدام typstyle. اضغط ⇧⌥F (Shift+Alt+F)، أو انقر بالزر الأيمن في المحرر، أو ابحث عنه في لوحة الأوامر ⌘K. أما **Format selection** فينسّق الأسطر المحددة فقط.

تتحكم مجموعة **Typst** في **Settings → Appearance → Editor** في المُنسِّق:

- **Format on save** ينسّق ملف Typst في كل مرة تضغط فيها ⌘S (Ctrl+S). الحفظ التلقائي لا يمسّ الملف. وهو متوقف افتراضيًا.
- **Formatter line width** هو العرض الذي يلتف عنده typstyle بالأسطر الطويلة. القيمة الافتراضية 120 حرفًا.
- **Formatter indent** هو عدد المسافات لكل مستوى. القيمة الافتراضية 2.
- **Typst lint checks** يبحث عن الأخطاء المحتملة في كل مرة تحفظ. وتشغيله أو إيقافه يعيد تشغيل خادم اللغة.

## عدة مستندات في مجلد واحد

قد يضم المجلد أكثر من ورقة بحثية، مثل `manuscript.tex` بجانب `manuscript_v1.tex` أو مخرجات `latexdiff`. يُعدّ كل ملف LaTeX له `\documentclass` خاص به مستندًا مستقلًا، مع الملفات التي يستدعيها عبر `\input` أو `\include` أو `\subfile`. تنتمي الوسوم والنظريات وإدخالات المسرد والماكروهات إلى مستندها وحده، فلا يظهر وسم موجود في ثلاث نسخ من الورقة على أنه معرَّف ثلاث مرات.

يبقى الانتقال إلى التعريف وإيجاد المراجع وإعادة التسمية والإكمال و[Preflight](/docs/preflight/) و`oleafly check` داخل المستند الذي تعمل فيه. ويظهر `\ref` إلى وسم لا يعرّفه سوى مستند آخر على أنه غير محلول، وهذا ما يقوله التجميع أيضًا. أما الملفات التي لا يضمها أي مستند بعد فما زالت ترى كل الوسوم، ولا يتأثر مشروع فيه مستند واحد.

## الذكاء الاصطناعي يرى الفهرس نفسه

يمتلك [المساعد الذكي](/docs/ai-chat/) أداة `project_map` مبنية على هذا الفهرس نفسه: المخطط، والوسوم، والاقتباسات، والماكروهات، ورسم علاقات الملفات، وأي مراجع غير محلولة. وعندما تسأله عن «قسم المنهجية»، يستطيع فعلًا العثور عليه.
