توسيع الودجت

المساعد يجيب ويستدعي واجهة API لديك من دون أي إعداد. وعند التسجيل عبر window.syncanix يذهب أبعد: يعرض مكوّناتك داخل الدردشة، وينفّذ إجراءات على الصفحة الحالية، ويعرض بيانات حيّة تبقى محدّثة.

اعرض مكوّناتك داخل الدردشة

يمنح registerComponent المساعدَ مكوّنًا يجوز له عرضه ضمن الإجابة: بطاقة طلب، رسم بياني، نموذج. تعطيه معرّفًا والمكوّن ومخطط Zod لخصائصه؛ ويخبر الوصفُ الاختياري النموذجَ متى يستخدمه.

import { z } from 'zod';
import { OrderCard } from './OrderCard';

const OrderCardProps = z.object({ orderId: z.string() });

window.syncanix?.registerComponent('OrderCard', OrderCard, OrderCardProps, {
  description: 'Shows an order summary',
  propDescriptions: { orderId: 'Which order to show' },
});

تُتحقق الخصائص التي يقدّمها النموذج مقابل مخططك قبل أي عرض: يُرفض عدم التطابق بوضوح بدل عرض شيء نصف صحيح.

امنح المكوّنات سياق تطبيقك

تُعرض المكوّنات المسجّلة داخل الودجت، لذا تفتقر افتراضيًا إلى موفّري تطبيقك. يلفّ registerProviders كل مكوّن معروض بغلافك الخاص — عميل البيانات، الموجّه، السمة — فتتصرف تمامًا كما في بقية تطبيقك.

window.syncanix?.registerProviders(({ children }) => (
  <ApolloProvider client={apolloClient}>
    <ThemeProvider theme={theme}>{children}</ThemeProvider>
  </ApolloProvider>
));

دع المساعد يتصرف على الصفحة

يكشف registerAction دالة يستطيع المساعد استدعاءها على الصفحة الحالية: الانتقال إلى مكان ما، إعادة تحميل جدول، فتح لوحة. أضِف مخطط معاملات Zod عندما يأخذ الإجراء وسائط.

window.syncanix?.registerAction('refetch_orders', () => ordersQuery.refetch(), {
  description: 'Reload the orders table with the latest data',
});

window.syncanix?.registerAction('go_to_invoice', ({ id }) => navigate(`/invoices/${id}`), {
  parameters: z.object({ id: z.string() }),
  parameterDescriptions: { id: 'The invoice id to open' },
  description: 'Navigate to a specific invoice',
});

اجعل الإجراءات بنطاق الصفحة: سجّلها عند تركيب الواجهة وألغِ تسجيلها عند التفكيك، فلا يرى المساعد إلا المتاح الآن. وللإجراءات ذات الأثر الفعلي مرّر confirm: true ليوافق المستخدم قبل التنفيذ.

اربط بيانات حيّة

يتيح registerDataSource للمساعد عرض بيانات تبقى حديثة: بدل تثبيت لقطة في إجابته يشير إلى مصدرك، ويستدعي الودجت دالة الجلب لديك وقت العرض. عيّن pollMs (بحد أدنى 1000) لتفعيل التحديث التلقائي.

window.syncanix?.registerDataSource(
  'open_orders',
  async (params) => ({ rows: await api.orders({ status: 'open', ...params }) }),
  { description: 'Current open orders', pollMs: 30000 },
);

أخبر المساعد أين المستخدم

يغذّي setContext الدورَ التالي بالصفحة الحالية أو الخطة أو السلة أو أي حالة أخرى من تطبيقك، فتعكس الإجابات ما يراه المستخدم. استدعِه مجددًا مع التنقل: القيمة الأخيرة هي المعتمدة.

window.syncanix?.setContext({
  user: { id: 'u_1', plan: 'pro' },
  page: { path: '/checkout' },
});

بلا React؟ استخدم Web Components

إذا لم يكن تطبيقك مبنيًا على React، فإن جسر @syncanix/web-components يلفّ أي عنصر مخصص أصلي ليندمج في مسار registerComponent نفسه:

npm install @syncanix/web-components

import { defineSyncanixComponent } from '@syncanix/web-components';
import { z } from 'zod';

const StatusBadge = defineSyncanixComponent(
  'status-badge',
  StatusBadgeElement, // your HTMLElement subclass
  z.object({ label: z.string(), tone: z.string() }),
);

window.syncanix?.registerComponent('status-badge', StatusBadge, StatusBadge.propsSchema);

اكتشاف إجراءات الصفحة تلقائيًا

يستطيع exposePageActions اكتشاف الإجراءات ضمن نطاق صريح تحدده أنت — خريطة مسارات للتنقل وعناصر تعلّمها بـ data-syncanix-action — بدل تسجيل كل واحد يدويًا. الميزة خلف مفتاح Labs المسمى auto-detect-actions، ويُبلَّغ عن كل إجراء مكتشف إلى لوحتك للمراجعة قبل أن يصبح قابلًا للاستدعاء: التنقل بلا تأكيد، والعناصر المعلَّمة تؤكد دائمًا.

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