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

# كتلة ترقية الاشتراك

> الكتلة الفرعية Subscription upgrade في سلة Aftersell: حوّل الأسطر المؤهلة ذات الشراء لمرة واحدة إلى اشتراك من داخل السلة.

> كتلة **Subscription upgrade** هي كتلة فرعية تتداخل داخل [**Cart items**](/ar/aftersell/cart/cart-items-block). وهي تحث المتسوقين على تحويل عنصر سطر مؤهل ذي شراء لمرة واحدة إلى اشتراك مباشرة من السلة، محوّلة الشراء لمرة واحدة إلى إيرادات متكررة عند نقطة القرار، وتتيح للمتسوقين المشتركين بالفعل تغيير خطتهم أو إلغاءها على ذلك السطر.

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

* **تظهر على الأسطر المؤهلة فقط.** تقرأ الكتلة خطط بيع المنتج ولا تعرض شيئًا على سطر ليس لمنتجه خطط اشتراك.
* **لا تُعرض أبدًا على هدايا المكافآت.** الاشتراك في هدية مجانية ممنوحة تلقائيًا سيجرّدها من حالة المكافأة، لذا يُكبح الحث على تلك الأسطر.
* على **سطر شراء لمرة واحدة**، تعرض دعوة الترقية.
* على **سطر مشترك بالفعل**، تعرض محدد خطط بالإضافة إلى خيار "الرجوع إلى الشراء لمرة واحدة".

<div id="settings">
  ## الإعدادات
</div>

| الإعداد              | ما الذي يتحكم فيه                                                                      | الافتراضي                       |
| -------------------- | -------------------------------------------------------------------------------------- | ------------------------------- |
| **Button text**      | دعوة الترقية على سطر الشراء لمرة واحدة. يدعم الرمزين `{{discount}}` و `{{plan name}}`. | `Subscribe & Save`              |
| **Unsubscribe text** | الخيار الذي يعيد السطر المشترك إلى شراء لمرة واحدة.                                    | `Downgrade - One time purchase` |

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

* **الأصل:** تتداخل داخل Cart items فقط.
* **الحد الأقصى:** 1 لكل سلة.
* لا تُضاف افتراضيًا. غير مقفلة، لذا يمكنك إزالتها أو إخفاؤها.

ولأنها كتلة فرعية، تُعرض لكل سطر، موضوعة فوق محتوى المنتج أو أسفله بحسب مكان وضعها بالنسبة لصف المنتج. راجع [كيف تتموضع الكتل الفرعية](/ar/aftersell/cart/cart-items-block#sub-blocks-and-how-they-position).

<div id="custom-template">
  ## القالب المخصص
</div>

تدعم [قالبًا مخصصًا](/ar/aftersell/cart/custom-templates) من تبويب Code الخاص بها، والذي يستبدل ترميز هذه الكتلة المدمج بـ JSX الخاص بك. هذه هي الخصائص التي تستقبلها.

تعرض هذه الكتلة إحدى حالتين، ويخبرك `view.state` أيهما. لا يكون `view` أبدًا `null` داخل قالب مخصص: عندما لا يكون للسطر خطط، لا تعرض الكتلة شيئًا ولا يُستدعى قالبك.

| الخاصية           | النوع                              | ما هي لأجله                                                                                                   |
| ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `view`            | `object`                           | حالة السطر. إما `{ state: 'upgrade', buttonText, planId }` أو `{ state: 'subscribed', plans, activePlanId }`. |
| `title`           | `string`                           | عنوان **المنتج**، وليس عنوانًا للكتلة. لا يستخدمه القالب المدمج إلا لبناء التسمية الميسّرة لمحدد الخطط.       |
| `unsubscribeText` | `string`                           | تسمية خيار الرجوع إلى الشراء لمرة واحدة.                                                                      |
| `busy`            | `boolean`                          | `true` أثناء تنفيذ تغيير الخطة.                                                                               |
| `selectPlan`      | `(planId: number \| null) => void` | يشترك أو يبدّل الخطة. مرّر `null` لإلغاء الاشتراك.                                                            |
| `onChange`        | `(event: Event) => void`           | معالج `onChange` جاهز لعنصر `<select>`، حتى لا تضطر إلى تحليل القيمة بنفسك.                                   |
| `oneTimeValue`    | `string`                           | قيمة `<option>` الدلالية التي تمثّل "الشراء لمرة واحدة".                                                      |
| `line`            | `AftersellCartLine`                | [سطر السلة](/ar/aftersell/cart/sdk-cart-object#cart-lines) الذي تنتمي إليه هذه الكتلة.                        |
| `productId`       | `number`                           | معرّف منتج Shopify.                                                                                           |
| `variantId`       | `number`                           | معرّف متغير Shopify.                                                                                          |

كل إدخال في `view.plans` هو `{ id: number, name: string, discountPercent: number }`.

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function CustomTemplate(props) {
  const { view } = props;

  if (view.state === 'upgrade') {
    return (
      <button type="button" onClick={() => props.selectPlan(view.planId)} disabled={props.busy}>
        {view.buttonText}
      </button>
    );
  }

  return (
    <div>
      <select
        aria-label={`Subscription plan — ${props.title}`}
        value={String(view.activePlanId)}
        onChange={props.onChange}
        disabled={props.busy}
      >
        {view.plans.map((plan) => (
          <option key={plan.id} value={String(plan.id)}>
            {plan.name}{plan.discountPercent > 0 ? ` (${plan.discountPercent}% off)` : ''}
          </option>
        ))}
        <option value={props.oneTimeValue}>{props.unsubscribeText}</option>
      </select>
    </div>
  );
}
```

<Note>
  استخدم `onChange` لعنصر `<select>` و `selectPlan` للأزرار. يعالج `onChange` بالفعل القيمة الدلالية `oneTimeValue`؛ إذا وصلت معالجك الخاص بعنصر `<select>`، فعليك المقارنة مع `oneTimeValue` واستدعاء `selectPlan(null)` بنفسك.
</Note>

<div id="design">
  ## التصميم
</div>

صمّم هذه الكتلة عبر قسم **Design** الخاص بها في لوحة الإعدادات. هذه تجاوزات لكل كتلة تُطبَّق فوق تصميمك العام وتعود إليه عندما تكون فارغة.

ما هي إعدادات التصميم؟ اعرف المزيد هنا: [إعدادات التصميم](/ar/aftersell/cart/design-settings).