الصفحات

الصفحات هي ملفات موجودة في المجلد الفرعي src/pages/ لمشروع أسترو الخاص بك. وهي مسؤولة عن معالجة التوجيه (Routing)، وتحميل البيانات، والتخطيط العام للصفحة لكل صفحة في موقعك.

أنواع الملفات المدعومة للصفحات

يدعم أسترو أنواع الملفات التالية في دليل src/pages/:

.astro
.md
.mdx (بشرط تثبيت MDX Integration (EN))
.html
.js/.ts (كـ نقاط نهاية (Endpoints) (EN))

التوجيه القائم على الملفات (File-based Routing)

يستخدم أسترو استراتيجية توجيه تسمى التوجيه القائم على الملفات. كل ملف في دليل src/pages/ الخاص بك يصبح نقطة نهاية (endpoint) في موقعك بناءً على مسار الملف.

يمكن لملف واحد أيضًا أن يولد صفحات متعددة باستخدام التوجيه الديناميكي (Dynamic Routing) (EN). هذا يسمح لك بإنشاء صفحات حتى لو كان محتواك موجودًا خارج الدليل الخاص /pages/، مثل مجموعات المحتوى (EN) أو نظام إدارة المحتوى (CMS) (EN).

اقرأ المزيد حول التوجيه في أسترو (EN).

الربط بين الصفحات

اكتب عناصر <a> HTML القياسية في صفحات أسترو الخاصة بك للربط بصفحات أخرى على موقعك. استخدم مسار URL نسبي لنطاقك الأساسي كرابط، وليس مسار ملف نسبي.

على سبيل المثال، للربط بـ https://example.com/authors/sonali/ من أي صفحة أخرى على example.com:

اقرأ المزيد <a href="/authors/sonali/">عن سونالي</a>.

صفحات أسترو

تستخدم صفحات أسترو امتداد الملف .astro وتدعم نفس الميزات مثل مكونات أسترو.

---
---
<html lang="ar" dir="rtl">
  <head>
    <title>الصفحة الرئيسية</title>
  </head>
  <body>
    <h1>مرحبًا بكم في موقعي!</h1>
  </body>
</html>

يجب أن تنتج الصفحة مستند HTML كامل. إذا لم يتم تضمينها صراحةً، ستقوم أسترو تلقائيًا بإضافة تعريف <!DOCTYPE html> الضروري ومحتوى <head> إلى أي مكون .astro موجود داخل src/pages/ افتراضيًا. يمكنك إلغاء هذا السلوك لكل مكون على حدة بوضعه كصفحة جزئية (Partial).

لتجنب تكرار عناصر HTML نفسها في كل صفحة، يمكنك نقل عناصر <head> و <body> الشائعة إلى مكونات التخطيط (Layout Components) الخاصة بك. يمكنك استخدام العديد من مكونات التخطيط أو القليل منها كما تريد.

---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
  <p>محتوى صفحتي، مغلف داخل تخطيط!</p>
</MySiteLayout>

اقرأ المزيد حول مكونات التخطيط في أسترو.

صفحات ماركداون/MDX

أسترو أيضًا يعتبر أي ملفات Markdown (.md) داخل src/pages/ كصفحات في موقعك النهائي. إذا كان لديك MDX Integration مثبتًا (EN)، فستعامل ملفات MDX (.mdx) بنفس الطريقة.

يمكن لملفات Markdown استخدام خاصية frontmatter الخاصة layout لتحديد مكون تخطيط (Layout Component) الذي سيلف محتوى Markdown الخاص بها داخل مستند صفحة <html>...</html>.

---
layout: ../layouts/MySiteLayout.astro
title: صفحتي المكتوبة بماركداون
---
# العنوان

هذه هي صفحتي، مكتوبة بـ **Markdown.**

اقرأ المزيد حول Markdown (EN) في أسترو.

صفحات HTML

يمكن وضع الملفات ذات امتداد الملف .html في دليل src/pages/ واستخدامها مباشرة كصفحات على موقعك. لاحظ أن بعض ميزات أسترو الرئيسية غير مدعومة في مكونات HTML.

صفحة خطأ 404 مخصصة

لصفحة خطأ 404 مخصصة، يمكنك إنشاء ملف 404.astro أو 404.md في src/pages.

سيؤدي هذا إلى بناء صفحة 404.html. سيجدها معظم موفري النشر (Deploy Services) (EN) وسيستخدمها.

صفحة خطأ 500 مخصصة

لصفحة خطأ 500 مخصصة لعرضها للصفحات التي يتم تقديمها عند الطلب (On-demand Rendering) (EN)، أنشئ الملف src/pages/500.astro. هذه الصفحة المخصصة غير متاحة للصفحات التي يتم تقديمها مسبقًا (Prerendered).

إذا حدث خطأ أثناء تقديم هذه الصفحة، فسيتم عرض صفحة الخطأ الافتراضية 500 الخاصة بمضيفك لزائرك.

أُضيفت في: astro@4.10.3

أثناء التطوير، إذا كان لديك ملف 500.astro، فسيتم تسجيل الخطأ الذي تم طرحه أثناء وقت التشغيل في الطرفية (Terminal) الخاصة بك، بدلاً من عرضه في نافذة الأخطاء (Error Overlay).

`error`

أُضيفت في: astro@4.11.0

src/pages/500.astro هي صفحة خاصة يتم تمرير خاصية error تلقائيًا لها لأي خطأ يتم طرحه أثناء التقديم. هذا يسمح لك باستخدام تفاصيل الخطأ (مثل خطأ من صفحة، من middleware، إلخ) لعرض المعلومات لزائرك.

يمكن أن يكون نوع بيانات خاصية error أي شيء، مما قد يؤثر على كيفية كتابة النوع (Typing) أو استخدام القيمة في الكود الخاص بك:

---
interface Props {
  error: unknown;
}

const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "خطأ غير معروف"}</div>

لتجنب تسريب معلومات حساسة عند عرض محتوى من خاصية error، فكر في تقييم الخطأ أولاً، وإرجاع محتوى مناسب بناءً على الخطأ الذي تم طرحه. على سبيل المثال، يجب عليك تجنب عرض الـ (Stack Trace) للخطأ لأنه يحتوي على معلومات حول كيفية هيكلة الكود الخاص بك على الخادم.

الصفحات الجزئية

أُضيفت في: astro@3.4.0

الصفحات الجزئية مخصصة للاستخدام جنبًا إلى جنب مع مكتبة واجهة أمامية (Front-end)، مثل htmx أو Unpoly. يمكنك أيضًا استخدامها إذا كنت مرتاحًا لكتابة JavaScript منخفض المستوى للواجهة الأمامية. لهذا السبب، فهي ميزة متقدمة.

بالإضافة إلى ذلك، لا ينبغي استخدام الجزئيات إذا كان المكون يحتوي على أنماط (Styles) أو نصوص برمجية (Scripts) محددة النطاق (Scoped)، حيث سيتم إزالة هذه العناصر من ناتج HTML. إذا كنت بحاجة إلى أنماط محددة النطاق، فمن الأفضل استخدام صفحات عادية غير جزئية مع مكتبة واجهة أمامية تعرف كيفية دمج المحتويات في head.

الجزئيات (Partials) هي مكونات صفحات موجودة داخل src/pages/ لا يُقصد بها أن تُعرض كصفحات كاملة.

مثل المكونات الموجودة خارج هذا المجلد، لا تتضمن هذه الملفات تلقائيًا تعريف <!DOCTYPE html>، ولا أي محتوى <head> مثل الأنماط أو النصوص البرمجية محددة النطاق.

ومع ذلك، نظرًا لأنها موجودة في الدليل الخاص src/pages/، فإن HTML الذي تم إنشاؤه يكون متاحًا عند عنوان URL يتوافق مع مسار ملفه. هذا يسمح لمكتبة تقديم (Rendering Library) (مثل htmx، Stimulus، jQuery) بالوصول إليها على العميل (Client) وتحميل أقسام HTML ديناميكيًا على صفحة دون تحديث المتصفح أو التنقل بين الصفحات.

توفر الجزئيات، عند دمجها مع مكتبة تقديم، بديلاً لجزر أسترو (Astro Islands) (EN) و علامات <script> (EN) لبناء محتوى ديناميكي في أسترو.

ملفات الصفحات التي يمكنها تصدير قيمة لـ partial (EN) (مثل .astro و .mdx، ولكن ليس .md) يمكن وضعها كجزئيات.

---
export const partial = true;
---
<li>أنا جزء جزئي!</li>

الاستخدام مع مكتبة

تُستخدم الجزئيات لتحديث قسم من الصفحة ديناميكيًا باستخدام مكتبة مثل htmx.

يظهر المثال التالي سمة hx-post مضبوطة على عنوان URL الجزئي. سيتم استخدام المحتوى من صفحة الجزئي لتحديث عنصر HTML المستهدف على هذه الصفحة.

<html lang="ar" dir="rtl">
  <head>
    <title>صفحتي</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
  <body>
    <section>
      <div id="parent-div">الهدف هنا</div>

      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        انقر هنا!
      </button>
    </section>
  </body>
</html>

يجب أن يوجد الجزئي .astro في مسار الملف المقابل، ويشمل تصديرًا يحدد الصفحة كجزئي:

---
export const partial = true;
---
<div>تم النقر علي!</div>

راجع وثائق htmx لمزيد من التفاصيل حول استخدام htmx.

ساهم المجتمع Sponsor