> ## 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.

# كائن السلة

> شكل كائن السلة وبنودها في Aftersell Cart SDK: كل حقل في السلة وبنود السلة والحزم وخطط البيع.

شكل كائن واحد يسري عبر SDK بأكمله. فهو ما يعيده [`getCart()`](/ar/aftersell/cart/sdk-actions#getcart)، وما يمرره [`cart_loaded` و`cart_updated`](/ar/aftersell/cart/sdk-events) إلى معالجك، وما يستقبله [بلوك Custom code](/ar/aftersell/cart/custom-code-blocks).

<Note>
  **كل المبالغ بالوحدة الصغرى للعملة** (السنتات للدولار الأمريكي)، وليست أبدًا سلسلة منسّقة. `5779` تعني \$57.79. استخدم [`formatMoney`](/ar/aftersell/cart/sdk-actions#formatmoneycents) لعرضها.
</Note>

<div id="the-cart">
  ## السلة
</div>

| الحقل                  | النوع                    | الوصف                                                                                                                                             |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                | `string`                 | رمز سلة Shopify.                                                                                                                                  |
| `items`                | `AftersellCartLine[]`    | بنود السلة. انظر [بنود السلة](#cart-lines).                                                                                                       |
| `itemCount`            | `number`                 | إجمالي كمية العناصر، كما يراها المتسوق.                                                                                                           |
| `hasSubscriptionItems` | `boolean`                | تكون `true` عندما يحمل بند واحد على الأقل في `items` خطة بيع، بما في ذلك بنود الإضافات التي يستبعدها `itemCount`. وتكون `false` في السلة الفارغة. |
| `totalPrice`           | `number`                 | الإجمالي الحالي، بالسنتات.                                                                                                                        |
| `originalTotalPrice`   | `number`                 | الإجمالي قبل الخصومات، بالسنتات.                                                                                                                  |
| `totalDiscount`        | `number`                 | إجمالي الخصم، بالسنتات.                                                                                                                           |
| `compareAtTotalPrice`  | `number \| null`         | مجموع سعر المقارنة (MSRP) لكل بند × الكمية، بالسنتات. تكون `null` عند عدم توفرها، فارجع حينها إلى `originalTotalPrice`.                           |
| `currency`             | `string`                 | رمز العملة.                                                                                                                                       |
| `discountCodes`        | `string[]`               | أكواد الخصم المقبولة على السلة، مرتَّبة. تكون `[]` عند عدم وجودها.                                                                                |
| `attributes`           | `Record<string, string>` | سمات السلة. للقراءة فقط من SDK.                                                                                                                   |

<Warning>
  **`itemCount` ليس دائمًا مجموع `items`.** يعكس `items` سلة Shopify الحقيقية، بما في ذلك بنود الإضافات التي يخفيها الدرج، مثل حماية الشحن. أما `itemCount` فهو الرقم الموجَّه للمتسوق الذي يطابق شارة السلة. لمعرفة "كم عنصرًا اختار المتسوق"، استخدم `itemCount`؛ وللمرور على البنود التي تعرضها السلة، استخدم `items`.

  هناك أمران غائبان تمامًا عن `items`: البنود المخفية عبر [`setHidden`](/ar/aftersell/cart/sdk-hooks#registerlinetransform)، و[أبناء الحزم](#bundles) الذين ينتقلون إلى بندهم الرئيسي. كلاهما يظل محسوبًا في إجماليات السلة، التي تأتي مباشرةً من Shopify.
</Warning>

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log(state.itemCount, 'items');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
  console.log('Saved:', window.aftersell.cart.actions.formatMoney(state.totalDiscount));
  console.log('Codes:', state.discountCodes.join(', ') || 'none');
});
```

<div id="cart-lines">
  ## بنود السلة
</div>

كل عنصر في `items`، وكذلك `item` في [`item_added`](/ar/aftersell/cart/sdk-events#item_added) و[`item_removed`](/ar/aftersell/cart/sdk-events#item_removed):

| الحقل                 | النوع                            | الوصف                                                                                                                                               |
| --------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                 | `string`                         | مفتاح البند في Shopify. مرره إلى [إجراءات](/ar/aftersell/cart/sdk-actions) البنود.                                                                  |
| `productId`           | `number`                         | معرّف المنتج في Shopify.                                                                                                                            |
| `variantId`           | `number`                         | معرّف المتغير في Shopify.                                                                                                                           |
| `handle`              | `string`                         | معرّف المنتج النصي (handle).                                                                                                                        |
| `title`               | `string`                         | عنوان العرض.                                                                                                                                        |
| `productTitle`        | `string`                         | عنوان المنتج بدون المتغير.                                                                                                                          |
| `variantTitle`        | `string \| null`                 | تسمية المتغير، أو `null`.                                                                                                                           |
| `variantOptions`      | `Array<{ name, value }>`         | الخيارات المحددة، مثل `[{ name: 'Size', value: 'Medium' }]`. يُصدر Shopify القيمة `Title: Default Title` للمنتج ذي المتغير الواحد.                  |
| `quantity`            | `number`                         | كمية هذا البند.                                                                                                                                     |
| `linePrice`           | `number`                         | سعر البند، بالسنتات.                                                                                                                                |
| `finalLinePrice`      | `number`                         | سعر البند بعد الخصومات، بالسنتات.                                                                                                                   |
| `originalLinePrice`   | `number`                         | سعر البند قبل الخصومات، بالسنتات.                                                                                                                   |
| `compareAtPrice`      | `number \| null`                 | سعر المقارنة (MSRP) للمتغير **لكل وحدة**، بالسنتات. يكون `null` عند عدم وجوده.                                                                      |
| `properties`          | `Record<string, string> \| null` | خصائص بند السلة.                                                                                                                                    |
| `internalProperties`  | `Record<string, string>`         | طبقة عرض فقط من [`registerLineTransform`](/ar/aftersell/cart/sdk-hooks#registerlinetransform). لا تُحفظ أبدًا في Shopify. تكون `{}` عند عدم وجودها. |
| `discountAllocations` | `Array<{ title, amount }>`       | الخصومات المطبَّقة على هذا البند. تكون `amount` بالسنتات. وتكون `[]` عند عدم وجودها.                                                                |
| `isGiftCard`          | `boolean`                        | ما إذا كان البند بطاقة هدية.                                                                                                                        |
| `sellingPlan`         | `{ id, name } \| null`           | خطة الاشتراك النشطة، أو `null` للشراء لمرة واحدة.                                                                                                   |
| `bundle`              | `AftersellCartBundle \| null`    | نموذج عرض [الحزمة](#bundles) على البند الرئيسي؛ ويكون `null` على البنود غير المرتبطة بحزمة وعلى الأبناء.                                            |
| `metadata`            | `Record<string, unknown>`        | بيانات [الإثراء](/ar/aftersell/cart/sdk-hooks#registercartenricher) مفهرسة بمعرّف المُثري `id`. تكون `{}` حتى يملأها مُثرٍ.                         |

<Warning>
  يمكن أن تحمل `properties` مدخلات من المتسوق، مثل حقل نص مخصص في نموذج المنتج. اعرضها كنص، وليس أبدًا كـ HTML خام.
</Warning>

<div id="identifying-a-line">
  ### تحديد بند
</div>

استخدم `key` لأي شيء يتصرف على بند، و`variantId` أو `productId` لأي شيء يحدد *منتجًا*:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// ✅ Acting on a line: use key.
window.aftersell.cart.actions.removeItem(line.key);

// ✅ Recognising a product: use variantId.
const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);
```

يمكن أن يظهر المتغير نفسه في عدة بنود عندما تختلف الخصائص. كوبان منقوشان بنصين مختلفين هما بندان يتشاركان `variantId` واحدًا. لهذا تأخذ الإجراءات `key`.

<div id="prices-on-a-line">
  ### أسعار البند
</div>

ثلاثة أسعار يسهل الخلط بينها:

| ما تريده                         | ما تستخدمه                    |
| -------------------------------- | ----------------------------- |
| ما يدفعه المتسوق مقابل هذا البند | `finalLinePrice`              |
| ما كان يكلفه قبل خصومات السلة    | `originalLinePrice`           |
| السعر المشطوب (MSRP)، لكل وحدة   | `compareAtPrice` × `quantity` |

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Is this line discounted?
const isDiscounted = line.finalLinePrice < line.originalLinePrice;

// Is it free? (A common way to detect a gift line.)
const isFree = line.finalLinePrice === 0;
```

<div id="bundles">
  ## الحزم
</div>

عندما تُجمَّع البنود في حزمة، يحمل البند **الرئيسي** كائن `bundle`. تُطوى البنود الأبناء داخله ولا تظهر في `items` بمفردها بعد ذلك. راجع [جمع بنود حزمة من تطبيق آخر](/ar/aftersell/cart/sdk-use-case-bundles) لمعرفة كيفية إعداد التجميع.

| الحقل          | النوع                    | الوصف                                         |
| -------------- | ------------------------ | --------------------------------------------- |
| `id`           | `string`                 | معرّف الحزمة.                                 |
| `source`       | `'native' \| 'grouped'`  | حزمة Shopify أصلية، أو بنود جمّعها Aftersell. |
| `memberKeys`   | `string[]`               | مفتاح `key` لكل بند في الحزمة.                |
| `children`     | `AftersellBundleChild[]` | محتويات الحزمة.                               |
| `displayPrice` | `number`                 | السعر المعروض للحزمة، بالسنتات.               |

يحمل كل ابن `key` (يكون `null` للمكوّن الأصلي)، و`title`، و`variantTitle`، و`quantity`، و`perAnchorQty`، و`imageUrl`، و`finalLinePrice`، و`originalLinePrice`، و`compareAtPrice`.

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
// Skip bundle children when totalling your own line list.
const topLevel = state.items.filter((line) => !isBundleChild(line, state));
```

<div id="subscription-plans">
  ## خطط الاشتراك
</div>

الخطة النشطة للبند هي `sellingPlan`، أو `null` للشراء لمرة واحدة. للحصول على إجابة على مستوى السلة كلها، اقرأ `hasSubscriptionItems` بدلًا من فحص البنود بنفسك، لأنه يحسب أيضًا بنود الإضافات التي يعرضها `items` لكن يتخطاها `itemCount`:

```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
if (state.hasSubscriptionItems) {
  // The cart contains at least one subscription line.
}

const subscriptions = state.items.filter((line) => line.sellingPlan);
console.log(subscriptions.length, 'subscription lines');
```

الخطط *المتاحة* على البند، أي الموجودة في المنتقي، ليست على كائن السلة. شكّلها باستخدام [`registerSubscriptionOptionsTransform`](/ar/aftersell/cart/sdk-hooks#registersubscriptionoptionstransform) و[`registerDefaultSubscriptionOptionSelector`](/ar/aftersell/cart/sdk-hooks#registerdefaultsubscriptionoptionselector).

<div id="where-to-go-next">
  ## إلى أين تذهب بعد ذلك
</div>

* **[الإجراءات](/ar/aftersell/cart/sdk-actions)**: اقرأ السلة وغيّرها.
* **[الأحداث](/ar/aftersell/cart/sdk-events)**: من أين يأتي هذا الكائن.
* **[الخطافات](/ar/aftersell/cart/sdk-hooks)**: أضِف بياناتك الخاصة إلى بند عبر مُثرٍ.
* **[حالات الاستخدام](/ar/aftersell/cart/sdk-use-cases)**: حلول كاملة تقرأ هذه الحقول.