---
title: "مكوّن React"
description: "تضمين ودجت ThunderPhone الصوتي في تطبيق React"
---

يعرض المكوّن `ThunderPhoneWidget` شريط مكالمات بتصميم زجاجي مع عناصر تحكم مدمجة لكتم الصوت وإنهاء المكالمة وعرض حالة الاتصال. وهو أسرع طريقة لإضافة الذكاء الاصطناعي الصوتي إلى تطبيق React.

## التثبيت

```bash
npm install @thunderphone/widget
```

## الاستخدام الأساسي

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  **يجب** استيراد ملف CSS لكي يُعرض الودجت بصورة صحيحة. بدونه، سيظهر الودجت دون تنسيق.
</Warning>

---

## الخصائص

يقبل المكوّن الخصائص التالية عبر `ThunderPhoneWidgetProps`:

| الخاصية | النوع | مطلوب | الافتراضي | الوصف |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | نعم | -- | مفتاح واجهة برمجة التطبيقات القابل للنشر (`pk_live_...`) من **أدوات الويب** في لوحة التحكم. يُحدَّد الوكيل تلقائيًا من إعدادات الأداة المرتبطة بالمفتاح. |
| `theme` | `'light' \| 'dark'` | لا | `'light'` | نظام الألوان. يطبّق الفئة `tp--light` أو `tp--dark` على جذر الأداة. |
| `primaryColor` | `string` | لا | `'#000000'` (فاتح) / `'#ffffff'` (داكن) | سلسلة ألوان CSS تُستخدم كلون تمييز (زر الاتصال، شكل الموجة، المؤشرات النشطة). |
| `title` | `string` | لا | `'Voice assistant'` | النص المعروض في شريط الأداة. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | لا | `'bottom-right'` | موضع ثابت للأداة ضمن إطار العرض. |
| `apiBase` | `string` | لا | `'https://api.thunderphone.com/v1'` | تجاوز عنوان URL الأساسي لواجهة برمجة التطبيقات. |
| `language` | `string` | لا | -- | تجاوز اللغة لكل جلسة -- رمز لغة أو إعدادات محلية مثل `en` أو `es` أو `fr-FR`. عند عدم تعيينه، تُطبَّق اللغة المُعدّة للوكيل. يتطلب `language` ضمن [تجاوزات المتصفح](/ar/guides/embed-web-widget) الخاصة بالمفتاح. |
| `voice` | `string` | لا | -- | تجاوز الصوت لكل جلسة -- اسم صوت مثل `maria`. عند عدم تعيينه، يُطبَّق الصوت المُعدّ للوكيل. يتطلب `voice` ضمن [تجاوزات المتصفح](/ar/guides/embed-web-widget) الخاصة بالمفتاح. |
| `context` | `string` | لا | -- | سياق واقعي للصفحة أو الموقع لكل جلسة يُمرَّر إلى الوكيل (مثل تفاصيل الصفحة التي يعرضها الزائر). يُقتطع من جانب الخادم إلى 12,000 حرف. يتطلب `context` ضمن [تجاوزات المتصفح](/ar/guides/embed-web-widget) الخاصة بالمفتاح. |
| `onConnect` | `() => void` | لا | -- | يُستدعى عند اتصال الجلسة الصوتية بنجاح. |
| `onDisconnect` | `() => void` | لا | -- | يُستدعى عند انتهاء الجلسة. |
| `onError` | `(error) => void` | لا | -- | يُستدعى عند حدوث أخطاء. يحتوي الكائن `error` على الحقلين `error` (الرمز) و`message`. |
| `className` | `string` | لا | -- | اسم فئة CSS إضافي يُطبَّق على حاوية الأداة. |
| `ringtone` | `boolean \| string` | لا | `false` | شغّل نغمة رنين أثناء الاتصال. استخدم `true` لنغمة الرنين الافتراضية، أو سلسلة URL لصوت مخصص. |

---

## أمثلة

### سمة داكنة بلون مخصص

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}
```

### موضع مخصص

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### اللغة والصوت والسياق لكل جلسة

تُمرَّر الخصائص `language` و`voice` و`context` إلى طلب الجلسة (`POST /widget/session`) عند بدء مكالمة، متجاوزةً الإعدادات الافتراضية التي ضُبطت للوكيل لتلك الجلسة. فعّل كل خاصية تستخدمها ضمن **تجاوزات المتصفح** للأداة في لوحة التحكم (أو في `allowed_overrides` للمفتاح). لا تقبل الأدوات الجديدة أيًّا منها، ويفشل طلب جلسة يتضمن خاصية غير مفعّلة بالخطأ `400 override_not_allowed`؛ راجع [تجاوزات المتصفح](/ar/guides/embed-web-widget).

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

استخدم `context` لمنح الوكيل معرفة واقعية حول الصفحة التي يتصفحها الزائر، مثل تفاصيل المنتج أو الأسعار أو الأسئلة الشائعة الخاصة بالصفحة. يتعامل الوكيل معها كمحتوى للصفحة، لا كتعليمات. ويُقتطع من جانب الخادم إلى 12,000 حرف.

### مع معاودات الأحداث

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### مع تنسيق مخصص

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

راجع [دليل التنسيق](/ar/widget/styling) للاطلاع على جميع فئات CSS والخصائص المخصصة المتاحة.

### مع نغمة رنين

شغّل صوت رنين هاتف أثناء إنشاء الاتصال:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

استخدم نغمة رنين مخصصة بتمرير عنوان URL لملف صوتي:

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

تتكرر نغمة الرنين بينما تكون الأداة في حالة `connecting`، وتتلاشى بسلاسة عند اتصال الوكيل.

### مع أساس API مخصص

<Tip>
  لا تحتاج إلى ضبط `apiBase` إلا إذا كنت تستخدم نقطة نهاية API مستضافة ذاتيًا أو عبر وكيل. يشير الإعداد الافتراضي إلى `https://api.thunderphone.com/v1`.
</Tip>

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

---

## معالجة الأخطاء

عند تشغيل معاودة `onError`، تتلقى كائن خطأ يحتوي على حقلين:

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `error` | `string` | رمز خطأ قابل للقراءة آليًا |
| `message` | `string` | وصف خطأ قابل للقراءة البشرية |

تشمل رموز الأخطاء الشائعة: النطاق غير مسموح به، أو لم يُعثر على الوكيل، أو مفتاح API غير صالح.

---

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="خطاف بلا واجهة" icon="code" href="/ar/widget/headless-hook">
    هل تحتاج إلى تحكم كامل في واجهة المستخدم؟ استخدم الخطاف `useThunderPhone` بدلًا من ذلك.
  </Card>
  <Card title="التنسيق" icon="palette" href="/ar/widget/styling">
    خصّص الألوان والأحجام والتخطيط باستخدام خصائص CSS المخصصة.
  </Card>
</CardGroup>