---
order: 7
section: features
title: الأصول
description: >-
  صرح عن حقول الأصول التي تم التحقق من صحتها باستخدام field.asset()، وقم بتقييد
  المسارات والتنسيقات، وتحويلها إلى عناوين URL عامة عند القراءة.
noindex: false
canonicalPath: /ar/docs/assets
---
يعامل Scribe الأصول الثابتة (مثل الصور حاليًا) كمراجع من الدرجة الأولى يتم التصريح عنها في المخطط، بدلاً من مجرد سلاسل نصية عادية. المبدأ الأساسي: **لا تقوم المكونات أبدًا ببناء عناوين URL للأصول عن طريق دمج السلاسل النصية.** تخزن بيانات Frontmatter *مرجع المصدر* الأساسي؛ وتقوم بيئة التشغيل بتحويله إلى *عنوان URL المعروض* وقت التحميل. هذا التوجيه غير المباشر هو ما يسمح بإضافة `publicPath` وشبكات توصيل المحتوى (CDNs) وتجزئة المحتوى كإعدادات بسيطة بدلاً من إجراء تعديلات معقدة على الكود.

## الإعدادات

تحدد مجموعة إعدادات `assets` أماكن تواجد الملفات المصدرية وكيفية تقديمها. لا يزال الخيار `assetsDir` المجرد يعمل كاسم مستعار مهمل لـ `{ dir: assetsDir }`.

```ts
export default defineConfig({
  // ...
  assets: {
    dir: "public",            // where source files live on disk, relative to rootDir. Default "public".
    publicPath: "/",          // URL prefix they are served under. A path ("/static/") or a CDN origin. Default "/".
    managedDirs: ["/blog-images"], // extra Scribe-owned web-path roots not covered by any field.asset()
  },
});
```

يتبع `publicPath` نفس المبدأ المتعارف عليه في webpack وVite. أما مدخلات `managedDirs` فهي تمثل **جذور المصدر** (source roots) وهي المجلدات المشار إليها في محتوى MDX والتي لا ترتبط بحقل أصول محدد.

## `field.asset()`

```ts
import { field } from "scribe-cms";

const garmentSchema = z.object({
  title: field.translatable(z.string()),
  productImage: field.asset({
    dir: "/try-on/garments",   // value must live under this web path
    formats: ["webp"],          // extension allowlist
    maxKB: 150,                 // size budget (warning)
    optional: false,            // default
  }),
});
```

كما هو الحال في `field.relation()`، **تُكتب القيود داخل كائن الخيارات وليس في دوال Zod المتسلسلة**؛ فالتسلسل ينسخ المخطط ويتجاهل البيانات الوصفية. حقول الأصول دائمًا ما تكون هيكلية، حيث لا تُرسل مسارات الأصول أبدًا إلى المترجم.

| الخيار | النوع | المعنى |
| --- | --- | --- |
| `dir` | `string` | بادئة مسار الويب التي يجب أن يتواجد ضمنها الملف. وتصرح أيضًا عن جذر مُدار. |
| `template` | `string` | قالب مسار مشتق، مثل `"/try-on/garments/{slug}/product.webp"`. يمثل `{slug}` الاسم اللطيف الإنجليزي للمدخل. عند تعيينه، يمكن تجاهل حقل frontmatter بالكامل وسيقوم المُحمّل بملئه؛ بينما تلغي القيمة الصريحة عمل القالب (بهدف المشاركة المقصودة بين المدخلات). |
| `formats` | `string[]` | الامتدادات المسموح بها (بحروف صغيرة وبدون نقطة). وتؤدي مخالفتها إلى ظهور تحذير. |
| `maxKB` | `number` | الحد الأقصى لحجم الملف. وتؤدي مخالفتها إلى ظهور تحذير. |
| `optional` | `boolean` | قد يكون الحقل غائبًا (وهو أمر منطقي فقط في حالة عدم استخدام `template`). ومع ذلك، إذا كانت القيمة موجودة ولكن الملف مفقود فسيظل ذلك خطأً. |

قيمة frontmatter هي **مسار ويب نسبي للجذر** يوجه إلى `assets.dir`، مثل `/try-on/garments/denim-flare/product.webp`، وهو نفس العرف المستخدم في السلاسل النصية العادية للصور بدون أي مخطط URI جديد. على مستوى القرص، تخزن بيانات frontmatter مرجع المصدر (أو لا شيء في حال استخدام القوالب). ولا تتواجد عناوين URL المحولة إلا في مخرجات بيئة التشغيل؛ حيث ترى عمليات التصدير الثابتة أو الخام، وكذلك المترجم، القيم المصدرية دائمًا.

## معالجة المُحمّل

عندما تقوم بيئة التشغيل بتحميل مستند ما، فإنها تتنقل عبر المخطط بحثًا عن حقول الأصول، وتقوم بالآتي لكل منها:

1. إذا كانت القيمة مفقودة في frontmatter وكان الحقل يحتوي على `template`، يتم إنشاء المسار بناءً على القالب (حيث يتحول `{slug}` إلى الاسم اللطيف الإنجليزي).
2. إضافة بادئة `assets.publicPath` (يتم دمجها بدون خطوط مائلة مزدوجة، ويدعم النظام `publicPath` ذو الأصل المطلق).

وبالتالي يحصل المستخدمون على عناوين URL النهائية دون أي استدعاءات إضافية:

```ts
const garment = scribe.garment.get("denim-flare");
garment.frontmatter.productImage;
// "/try-on/garments/denim-flare/product.webp"                       (publicPath "/")
// "https://cdn.example.com/try-on/garments/denim-flare/product.webp" (CDN publicPath)
```

تتم عملية التحويل بعد دمج الحقول الهيكلية في مستندات اللغات المحلية، لذا تحصل كل لغة على القيم المحولة من المصدر الإنجليزي.

### `scribe.assets.url(ref)`

يمثل هذا الخيار مخرجًا لصور محتوى MDX والحالات الاستثنائية، حيث يُطبّق `publicPath` على المرجع الخام:

```ts
scribe.assets.url("/blog-images/hero.webp"); // publicPath applied
```

يمكنك أيضًا الإشارة إلى الأصول مباشرةً في محتوى MDX باستخدام [الرمز المضمن `asset`](/docs/inline-tokens)، والذي تتم معالجته بنفس الطريقة وقت القراءة.

## التحقق من الصحة

يتحقق أمر `scribe validate` من حقول الأصول المُصرح عنها:

- **ملف مفقود لحقل أصول مطلوب**: خطأ (يوقف عملية البناء، تمامًا كعلاقة مطلوبة غير مرتبطة).
- **ملف مفقود لحقل `optional` مع وجود قيمة له**: خطأ أيضًا. فكلمة `optional` تعني أن *الحقل* قد يكون غائبًا، ولا تعني السماح بكتابة مسار غير حقيقي.
- **قيمة خارج نطاق `dir` الخاص بالحقل**: خطأ.
- **امتداد غير موجود في `formats`**: تحذير.
- **ملف يتجاوز حجمه `maxKB`**: تحذير.
- تتحقق الحقول المبنية على قوالب من المسار *المنشأ* الفعلي، فيجب أن يكون الملف موجودًا حتى وإن غابت قيمته من بيانات frontmatter.

تتضمن رسائل الخطأ تفاصيل الحقل المعني، مثل `garment/denim-flare: productImage → /try-on/garments/denim-flare/product.webp not found`. وبشكل منفصل، فإن السلاسل النصية التي تشبه الصور والتي تُجمع من خلال الاستدلال في بيانات frontmatter ومحتوى MDX سيتم الإبلاغ عنها كتحذيرات في حال فقدانها، لتشمل صور المحتوى دون الحاجة لأي تعديلات.

## الاستوديو

يعرض [الاستوديو](/docs/studio) الأصول بصيغة القراءة فقط:

- **مُفتش المدخلات** يعرض حقول الأصول كمعاينات للصور تتضمن عنوان URL المُعالج وحجم الملف وأبعاده، وتظهر شارة حمراء في حالة فقدان الملف.
- **متصفح الأصول** (`/assets`) يعرض شبكة صور مصغرة لكل جذر مُدار، بحيث يترافق كل أصل مع مساره وحجمه وأبعاده بالإضافة إلى قائمة "مُشار إليه بواسطة" التي تضم كل مدخل وحقل يشير إليه. وتوضح الشارات الأصول غير المُشار إليها (المرشحة لتكون أصولاً يتيمة)، وتلك المفقودة رغم الإشارة إليها، والأصول كبيرة الحجم، وتلك التي لا تتوافق صيغها.
- **عرض المعرض** يتيح لأي نوع يحتوي على حقل أصول عرض قائمة مدخلاته كشبكة من البطاقات، ليكون بمثابة لوحة تحكم لضمان جودة الصور المولدة.