הרחבת הווידג׳ט

כברירת מחדל העוזר עונה וקורא ל-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' },
});

מאפיינים שהמודל מספק מאומתים מול הסכימה שלכם לפני כל הצגה: אי-התאמה נדחית בקול רם במקום להציג משהו חצי נכון.

תנו לרכיבים את ההקשר של האפליקציה

רכיבים רשומים מוצגים בתוך הווידג׳ט, ולכן כברירת מחדל חסרים להם ה-providers של האפליקציה. 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 מאפשר לעוזר להציג נתונים שנשארים עדכניים: במקום לקבע תמונת מצב בתשובה, הוא מפנה למקור שלכם, והווידג׳ט קורא ל-fetcher שלכם בזמן ההצגה. קבעו 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 עוטף כל custom element מקורי כך שישתלב באותו צינור 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, וכל פעולה שהתגלתה מדווחת ללוח הבקרה לבדיקה לפני שתהפוך לזמינה לקריאה: ניווט בלי אישור, אלמנטים מסומנים תמיד מאשרים.

השלבים הבאים