> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# بلوكات الكود المخصص

> بلوك Custom code في Aftersell Cart: أضف HTML أو React خاصًا بك في أي مكان في الدرج، بما في ذلك داخل Cart items.

> يضيف بلوك **Custom code** كود HTML أو React خاصًا بك إلى السلة. ضعه في أي قسم من الدرج، أو أدرجه داخل [**Cart items**](/ar/aftersell/cart/cart-items-block) كبلوك فرعي ليتكرر لكل سطر. بخلاف البلوكات الأخرى، لا توجد له إعدادات Content ولا قسم Design: البلوك *هو* الكود، لذا تعمل بالكامل في علامة تبويب **Code** الخاصة به.

<Frame>
  <img src="https://mintcdn.com/aftersell/1Y3gBpUfxv16VGSW/images/aftersell/cart-custom-code-block-add-and-enable.gif?s=6717cc64a8765b0c06b65990f99e12ff" alt="معاينة متحركة لإضافة بلوك Custom code وتفعيله في محرر Aftersell Cart" title="معاينة متحركة لإضافة بلوك Custom code وتفعيله في محرر Aftersell Cart" width="1200" height="558" data-path="images/aftersell/cart-custom-code-block-add-and-enable.gif" />
</Frame>

<div id="add-and-turn-on-a-custom-code-block">
  ## إضافة بلوك Custom code وتفعيله
</div>

1. أضف بلوك **Custom code** إلى أي قسم، أو كبلوك فرعي تحت **Cart items**.
2. حدده وافتح علامة تبويب **Code**.
3. اختر **HTML** أو **React component**. تبدأ البلوكات الجديدة بـ HTML افتراضيًا.
4. اكتب الكود الخاص بك.
5. إذا اخترت React، انقر <span style={{display:'inline-flex',alignItems:'center',gap:'4px',background:'#1C1C1C',color:'#fff',border:'1px solid #0A0A0A',borderRadius:'4px',padding:'0 6px',fontSize:'0.85em',fontWeight:500,lineHeight:'1.4em',verticalAlign:'middle'}}><svg width="8" height="9" viewBox="0 0 10 12" fill="none" aria-hidden="true" style={{display:'block'}}><path d="M1.5 1.2v9.6L8.8 6 1.5 1.2Z" stroke="#fff" strokeWidth="1.5" strokeLinejoin="round" /></svg>Compile</span>.
6. فعّل **"Use custom template"**. بالنسبة لهذا البلوك، يعني هذا المفتاح "اعرض الكود المخصص الخاص بي"، وهو معطّل افتراضيًا، فلا يُعرض شيء حتى تفعّله.
7. أبقِ مفتاح العين في الشريط الجانبي مفعّلًا ليظل البلوك مرئيًا للمتسوقين.

يجب أن يكون كل من مفتاح العين و\*\*"Use custom template"\*\* مفعّلَين ليظهر البلوك.

<div id="behavior">
  ## السلوك
</div>

* لا يعرض البلوك شيئًا حتى يكتمل تحميل السلة.
* كما لا يعرض شيئًا عندما تكون عين الشريط الجانبي معطلة، أو **"Use custom template"** معطلًا، أو الكود فارغًا، أو عندما يفشل React في التجميع أو العرض. ولأن الفشل صامت، افحص بلوكك في [المعاينة](/ar/aftersell/cart/previewing-carts) قبل النشر.

<div id="html-mode">
  ## وضع HTML
</div>

يستبدل وضع HTML مجموعة صغيرة من الرموز في ترميزك. وهو مخصص للمحتوى الثابت أو المعتمد على الرموز، وليس لتشغيل منطق.

* **وسوم `<script>` المضمّنة لا تعمل**، وليس لوضع HTML **أي وصول إلى SDK أو `window`.**
* للمنطق، استخدم [**وضع React**](#react-mode) أو [السكربتات المخصصة](/ar/aftersell/cart/custom-scripts) مع [Cart SDK](/ar/aftersell/cart/sdk-overview).

<div id="tokens">
  ### الرموز
</div>

قيم الرموز **سلاسل نصية منسّقة** (تنسيق عملة المتجر، أو نسبة مئوية مع `%`، أو كمية)، جاهزة للإدراج في الترميز:

| الرمز                    | ما الذي يعرضه                                                 |
| ------------------------ | ------------------------------------------------------------- |
| `{{pre_cart_total}}`     | إجمالي السلة قبل الخصومات.                                    |
| `{{post_cart_total}}`    | إجمالي السلة بعد الخصومات.                                    |
| `{{savings_amount}}`     | المبلغ الموفَّر (الإجمالي قبل الخصم ناقص الإجمالي بعد الخصم). |
| `{{savings_percentage}}` | التوفير كنسبة مئوية، مع علامة `%` (مثل `15%`).                |
| `{{cart_quantity}}`      | عدد العناصر المرئية في السلة.                                 |

<div id="example">
  ### مثال
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<div class="cart-external-custom-code_html">
  You saved {{savings_amount}} ({{savings_percentage}})
</div>
```

<div id="react-mode">
  ## وضع React
</div>

يجمّع وضع React مكوّنًا ويمرّر إليه بيانات السلة إضافة إلى إجراء `add-to-cart`.

* يقفل المحرر الغلاف على `function CustomCode(props: CustomCodeProps) { … }`، وتحرر أنت فقط الجسم بين هذين السطرين.
* يجب أن تنقر <span style={{display:'inline-flex',alignItems:'center',gap:'4px',background:'#1C1C1C',color:'#fff',border:'1px solid #0A0A0A',borderRadius:'4px',padding:'0 6px',fontSize:'0.85em',fontWeight:500,lineHeight:'1.4em',verticalAlign:'middle'}}><svg width="8" height="9" viewBox="0 0 10 12" fill="none" aria-hidden="true" style={{display:'block'}}><path d="M1.5 1.2v9.6L8.8 6 1.5 1.2Z" stroke="#fff" strokeWidth="1.5" strokeLinejoin="round" /></svg>Compile</span> ثم تفعّل **"Use custom template"**، قبل أن يظهر البلوك.
* يمكن لمكوّنك استخدام `useState` و`useEffect` و`useMemo` و`useRef` و`useCallback`.
* بخلاف وضع HTML، يعمل React في سياق الصفحة، لذا يمكنه استدعاء `window` و[Cart SDK](/ar/aftersell/cart/sdk-overview) عند توفرهما.
* إذا رمى مكوّنك أخطاء وقت التشغيل، لا يعرض البلوك شيئًا ويستمر باقي السلة في العمل.

<div id="props">
  ### الخصائص (Props)
</div>

الإجماليات ومبالغ التوفير أعداد صحيحة بـ[الوحدة الصغرى](/ar/aftersell/cart/sdk-actions#formatmoneycents) للعملة (السنتات للدولار الأمريكي)، لذا فإن `$12.50` هي `1250` وليس `12.50`. وهي ليست سلاسل نقدية منسّقة مثل رموز HTML.

| الخاصية                                         | النوع                       | الوصف                                                                                                           |
| ----------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `cart`                                          | `AftersellCart`             | السلة الحالية. راجع [مرجع كائن السلة](/ar/aftersell/cart/sdk-cart-object).                                      |
| `line`                                          | `AftersellCartLine \| null` | تُعيَّن فقط عندما يكون البلوك بلوكًا فرعيًا لـ Cart items (عرض واحد لكل سطر)؛ وتكون `null` في قسم.              |
| `preCartTotal`                                  | `number`                    | إجمالي السلة **قبل الخصومات** (`original_total_price` في Shopify)، بالوحدة الصغرى للعملة (مثل السنتات).         |
| `postCartTotal`                                 | `number`                    | إجمالي السلة **بعد الخصومات**، بالوحدة الصغرى للعملة.                                                           |
| `savings`                                       | `{ amount, percentage }`    | مبلغ التوفير ونسبته المئوية.                                                                                    |
| `addProduct(variantId, quantity?, properties?)` | `function`                  | يضيف منتجًا إلى السلة، موسومًا بإسناد هذا البلوك لتتمكن [التحليلات](/ar/aftersell/cart/analytics) من نسبه إليه. |

<div id="the-cart-and-line-shapes">
  ### بنيتا cart وline
</div>

`cart` و`line` هما نفس الكائنين اللذين يعرضهما SDK في كل مكان آخر، لذا وُثّقا مرة واحدة في **[مرجع كائن السلة](/ar/aftersell/cart/sdk-cart-object)**: كل حقل في السلة وفي السطر وفي الحزمة.

أكثر ما ستستخدمه: `cart.items` و`cart.itemCount` و`cart.totalPrice` و`line.title` و`line.quantity` و`line.finalLinePrice`.

ثلاثة أمور خاصة بهذا البلوك:

* **لا تُعيَّن `line` إلا في بلوك فرعي لـ Cart items**، حيث يُعرض مكوّنك مرة لكل سطر. عند وضعه كقسم، تكون `line` قيمتها `null` وتقرأ `cart.items` بدلًا منها.
* **العناصر التابعة للحزم ليست في `cart.items`.** عندما تُجمَّع الأسطر [في حزمة](/ar/aftersell/cart/sdk-use-case-bundles)، يظهر السطر المرجعي فقط؛ وتوجد عناصره التابعة في `line.bundle.children`.
* **الأسطر المخفية عبر [تحويل الأسطر](/ar/aftersell/cart/sdk-hooks#registerlinetransform) ليست موجودة أيضًا**، رغم أنها لا تزال تُحتسب ضمن `cart.totalPrice`.

<div id="examples">
  ### أمثلة
</div>

عرض عدد العناصر:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  return (
    <div className="cart-external-custom-code_jsx">
      {props.cart.itemCount} items
    </div>
  );
}
```

كبلوك فرعي لـ Cart items، استخدم `props.line` لمحتوى خاص بكل منتج. يُعرض البلوك مرة لكل سطر، موسومًا بمنتج ذلك السطر ونسخته:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  if (!props.line) return null;
  return (
    <div className="cart-external-custom-code_jsx">
      {props.line.productTitle}
      {props.line.variantTitle ? ` · ${props.line.variantTitle}` : ''}
    </div>
  );
}
```

<div id="reading-enrichment-metadata">
  ### قراءة بيانات الإثراء الوصفية
</div>

يحمل كل عنصر في `cart.items` حقل `metadata`: كائن فارغ `{}` حتى يملأه [مثري السلة](/ar/aftersell/cart/sdk-hooks#registercartenricher). بمجرد ملئه، يُفهرَس بمعرّف المثري `id` ويحتوي على بيانات Storefront لمنتج ذلك السطر أو نسخته:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  return (
    <ul>
      {(props.cart.items ?? []).map((item) => {
        const note = item.metadata?.shipping?.shippingNote;
        return (
          <li key={item.key}>
            {item.title}
            {note ? ` · ${note.value}` : ''}
          </li>
        );
      })}
    </ul>
  );
}
```

`metadata` موجودة دائمًا وتكون افتراضيًا كائنًا فارغًا `{}` حتى يكتمل الجلب غير المتزامن للمثري (اختبار "لم يُثرَ بعد" هو `Object.keys(item.metadata).length === 0`). استخدم السلسلة الاختيارية (`item.metadata?.enricherId`) عند قراءة مفتاح مثرٍ محدد، لأن ذلك المفتاح غائب حتى يكتمل الإثراء.

<div id="reading-discount-codes-and-line-discounts">
  ### قراءة رموز الخصم وخصومات الأسطر
</div>

يسرد `cart.discountCodes` رموز الخصم المطبقة على السلة، ويسرد `discountAllocations` لكل سطر الخصومات المطبقة على ذلك السطر تحديدًا:

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomCode(props) {
  const codes = props.cart.discountCodes;
  return (
    <div>
      {codes.length > 0 && (
        <p>Active discounts: {codes.join(', ')}</p>
      )}
      <ul>
        {(props.cart.items ?? []).map((item) => {
          return (
            <li key={item.key}>
              {item.title}
              {item.discountAllocations.map(
                (discount) => ` · ${discount.title} (-${(discount.amount / 100).toFixed(2)})`
              )}
            </li>
          );
        })}
      </ul>
    </div>
  );
}
```

<div id="placement-and-limits">
  ## الموضع والحدود
</div>

* **المنطقة:** أي منطقة (الأعلى أو الوسط أو الأسفل). متاح أيضًا كبلوك فرعي لـ Cart items.
* **الحد الأقصى:** غير محدود.
* **الحالة:** السلة الممتلئة والفارغة (كبلوك قسم). كبلوك فرعي لـ Cart items، لا يُعرض إلا عندما تحتوي السلة على أسطر، بنسخة واحدة لكل سطر.
* غير مقفل، لذا يمكنك إزالته أو إخفاؤه.
* لا يوجد قسم Design خاص بالبلوك. نسّق من خلال ترميزك الخاص و[**CSS المخصص**](/ar/aftersell/cart/custom-css) و[**إعدادات التصميم**](/ar/aftersell/cart/design-settings) العامة.

<div id="when-to-use-custom-code-block-vs-custom-template-vs-custom-script">
  ## متى تستخدم بلوك الكود المخصص مقابل القالب المخصص مقابل السكربت المخصص
</div>

|                                                          | ما الذي يفعله                                                               | متى تستخدمه                                              | مثال                                                                                                                                               |
| -------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **بلوك الكود المخصص**                                    | يضيف بلوكًا *جديدًا* من HTML أو React الخاص بك.                             | شيء لا تغطيه البلوكات المدمجة.                           | سطر إجمالي تقديري يضيف رسوم شحنك الثابتة إلى إجمالي السلة، أو عد تنازلي لموعد التسليم النهائي فوق زر إتمام الشراء.                                 |
| **[القالب المخصص](/ar/aftersell/cart/custom-templates)** | يستبدل عرض بلوك *موجود* بكود JSX الخاص بك، مستخدمًا بيانات ذلك البلوك.      | البلوك المدمج قريب مما تريد، لكنك تحتاج ترميزًا مختلفًا. | أعد بناء [صف Product](/ar/aftersell/cart/cart-items-block#custom-template) بحيث يقع اسم النسخة والتوفير ومنتقي الكمية في سطر واحد.                 |
| **[السكربت المخصص](/ar/aftersell/cart/custom-scripts)**  | يشغّل JavaScript على السلة عبر [Cart SDK](/ar/aftersell/cart/sdk-overview). | منطق على مستوى السلة وأحداث وتكوين بدلًا من ترميز الدرج. | أنفق 75\$ واحصل على حقيبة مجانية: [أضف الهدية](/ar/aftersell/cart/sdk-use-case-free-gift) عندما تتجاوز السلة العتبة، وأزلها إذا هبط المتسوق دونها. |