واجهة استيراد Overleaf البرمجية

​

ميزة “Overleaf Import API”

بدءًا من Ayakaleaf Pro v6.3، يمكنك إنشاء روابط تستورد ملف LaTeX أو مشروعًا مضغوطًا من رابط URL وتفتحه في نسخة Ayakaleaf الخاصة بك، على غرار واجهة “Open in Overleaf” البرمجية الخاصة بـ Overleaf.

هذه الميزة مفعّلة افتراضيًا، وكل ما عليك هو زيارة your.overleaf.com/devs لرؤية الصفحة المفصّلة والتعليمات.

تتطلب صفحة /devs تسجيل الدخول ما لم تكن OVERLEAF_ALLOW_PUBLIC_ACCESS=true، راجع الزوار غير المسجّلين.

على سبيل المثال، إذا كنت تستضيف ملف LaTeX على https://example.com/main.tex أو مشروعًا كاملًا على https://example.com/project.zip، فيمكنك إنشاء رابط يستورده إلى نسخة Ayakaleaf Pro الخاصة بك ويفتح المشروع الجديد:

ملف LaTeX

https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fmain.tex

مشروع ZIP

https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fproject.zip

استبدل ayakaleaf.example.com بنطاق نسختك.

​

فتح مشروع LaTeX في Ayakaleaf Pro

بدءًا من Ayakaleaf Pro v6.3، يمكنك إنشاء رابط يستورد ملف LaTeX أو مشروعًا مضغوطًا إلى نسخة Ayakaleaf Pro الخاصة بك. عندما يفتح أحدهم الرابط، ينشئ Ayakaleaf Pro مشروعًا جديدًا من الملف المقدَّم ويفتحه في المحرر.

وجّه الرابط إلى نقطة النهاية /docs في نسختك:

المعامل	الوصف	مثال
snip_uri	رابط URL لملف LaTeX المراد استيراده. يُقبل أيضًا ملف ZIP واحد، لكن استخدم zip_uri للمشاريع.	https://example.com/main.tex
zip_uri	رابط URL لمشروع LaTeX مضغوط المراد استيراده.	https://example.com/project.zip
snip_uri[]	استيراد عدة ملفات بتكرار هذا المعامل.	snip_uri[]=.../main.tex&snip_uri[]=.../refs.bib
snip_name[]	تعيين اسم الملف لكل snip_uri[]، بالترتيب نفسه.	snip_name[]=main.tex
engine	تعيين المترجم: latex_dvipdf أو pdflatex أو xelatex أو lualatex.	engine=xelatex
main_document	تعيين ملف .tex الرئيسي في المشروع المستورد.	main_document=main.tex
name	تعيين اسم المشروع الجديد. يُقبل أيضًا project_name.	name=My%20Project

على سبيل المثال، إذا كانت ملفاتك مستضافة على example.com، فإن هذه الروابط تستوردها إلى نسخة Ayakaleaf Pro المستضافة على ayakaleaf.example.com .

​

استيراد مشروع باستخدام Base64

يمكنك تضمين ملف LaTeX أو مشروع مضغوط مباشرةً في رابط “Open in Ayakaleaf” على شكل رابط بيانات (data URL) بترميز Base64. يتيح لك ذلك إنشاء رابط استيراد دون استضافة الملف على رابط URL منفصل.

المحتوى	المعامل	صيغة رابط البيانات
ملف LaTeX	snip_uri	data:application/x-tex;base64,<base64-encoded-tex>
مشروع مضغوط	zip_uri	data:application/zip;base64,<base64-encoded-zip>

لاستيراد مشروع ZIP، رمّز ملف ZIP بترميز Base64 ومرّره عبر zip_uri بدلًا من ذلك. استخدم encodeURIComponent على رابط البيانات الكامل عند إنشاء أي من الرابطين. بالنسبة للمشاريع الكبيرة، استخدم رابط ZIP مستضافًا، لأن حدود طول عناوين URL في المتصفح والخادم قد تجعل روابط Base64 غير عملية.

​

إضافة زر “Open in Ayakaleaf”

يمكنك استخدام نموذج HTML لاستيراد ملف عندما ينقر الزائر على زر. أرسل النموذج إلى نقطة النهاية /docs في نسختك باستخدام method="post".

لملف LaTeX مستضاف:

<form action="https://ayakaleaf.example.com/docs" method="post" target="_blank">
  <input type="hidden" name="snip_uri" value="https://example.com/main.tex">
  <input type="hidden" name="engine" value="xelatex">
  <button type="submit">Open in Ayakaleaf</button>
</form>

لاستيراد مشروع مضغوط، استبدل snip_uri بـ zip_uri ووجّهه إلى ملف ZIP. يمكنك أيضًا إرسال مصدر LaTeX مباشرةً باستخدام snip للنص الخام أو encoded_snip للنص المرمّز بترميز URL.

استبدل ayakaleaf.example.com بنطاق نسختك. إذا كانت نسختك تفعّل حظر الطلبات عبر المصادر (cross-origin)، فأضف الموقع الذي يستضيف النموذج إلى ALLOWED_ORIGINS.

​

الزوار غير المسجّلين

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

• الروابط (GET /docs?...) تعمل في كل نسخة: يُرسَل الزائر إلى صفحة تسجيل الدخول ويستمر الاستيراد بعد تسجيل الدخول.
• النماذج (POST /docs) تتطلب OVERLEAF_ALLOW_PUBLIC_ACCESS=true للزوار غير المسجّلين. عندها يُحتفظ بالنموذج المُرسَل لمدة 10 دقائق إلى أن يسجّل الزائر دخوله، ويُستخدم مرة واحدة.

افتراضيًا (عندما لا يكون OVERLEAF_ALLOW_PUBLIC_ACCESS معيّنًا)، يُرسَل النموذج الذي يقدّمه زائر غير مسجّل إلى صفحة تسجيل الدخول قبل أن يقرأه Ayakaleaf Pro، فيضيع النموذج المُرسَل: بعد تسجيل الدخول، يرى الزائر الرسالة no snippet, snip_uri or zip_uri provided. استخدم الروابط، أو اطلب من الزوار تسجيل الدخول أولًا، أو فعّل الوصول العام، راجع الوصول إلى الصفحات.

ما موارد ZIP أو TeX التي يمكنني استيرادها؟

يستخدم Ayakaleaf Pro الخدمة المصغّرة linked-url-proxy (المستخدمة أساسًا لـ external-url.md) لجلب الموارد الخارجية. بشكل عام، يمكن استيراد أي مورد ZIP أو TeX متاح للعامة عبر الإنترنت. أما الموارد المستضافة على شبكات خاصة أو داخلية فتُحظر لأسباب أمنية.

بدءًا من الإصدار المُعاد إصداره Ayakaleaf Pro 6.3.0 (3 أكتوبر 2026)، يمكنك تهيئة وكيل HTTP(S) لجلب موارد ZIP وTeX الخارجية باستخدام OVERLEAF_LINKED_URL_OUTBOUND_PROXY. راجع الوكيل الصادر للاطلاع على الإعداد وقيود الوصول إلى الشبكة.