<kaleidr-map> — العنصر
الواجهة التعريفية. ضع العنصر وحدد السمات؛ ويتم تركيبه عند الاتصال وإزالته عند الحذف.
<kaleidr-map product="viewer" share-id="abcd1234" style="height:480px"></kaleidr-map>
جدول السمات
تم التحقق مقابل kaleidr-sdk/packages/embed/src/element.ts. أسماء السمات
بصيغة kebab-case؛ وأسماء خيارات Kaleidr.mount(...) المطابقة في
kaleidr.js بصيغة camelCase.
| السمة | المنتجات | مطلوبة | الافتراضي | المعنى |
|---|---|---|---|---|
product | الكل | نعم | — | chat | viewer | editor | tile |
publishable-key | chat, editor, tile | نعم* | — | kld_pk_live_…؛ يتم تبادله برمز جلسة وقت التشغيل |
api-key | chat, editor, tile | — | — | اسم بديل مهمل؛ يقبل أيضًا kld_live_… القديم |
share-id | viewer | نعم | — | معرّف الخريطة المنشورة / المشاركة؛ حذفه يؤدي إلى خطأ عند تحميل الحزمة |
map-id | viewer | — | — | اسم بديل لـ share-id |
style-id | tile, editor | اختياري | tile: افتراضي viewer؛ editor: افتراضي المؤسسة → kaleidr-morning | معرّف نمط خريطة الأساس، أو (في editor) URL كامل للنمط |
map-target | chat | اختياري | — | محدد CSS لعنصر الخريطة المضيف |
contained | chat | اختياري | false | يثبت اللوحة داخل عنصر التركيب بدلًا من جعلها عائمة على document.body |
center | viewer, tile, editor | اختياري | — | lon,lat |
zoom | viewer, tile, editor | اختياري | editor: 2 | التكبير الأولي |
pitch | viewer, tile, editor | اختياري | 0 | الميل الأولي |
bearing | viewer, tile, editor | اختياري | 0 | الاتجاه الأولي |
theme | chat, editor | اختياري | — | سلسلة كائن JSON لرموز CSS |
doorway | الكل | اختياري | افتراضي المنتج | تجاوز iframe | attach |
base | الكل | اختياري | https://cdn.kaleidr.com | أصل CDN للحزم المحملة بشكل كسول (/embed/v1/*.js) |
viewer-base | viewer, tile | اختياري | https://map-embed.kaleidr.com | الأصل الذي يحمّل منه iframe — مختلف عن CDN الخاص بالحزمة |
api-base | chat, editor, tile | اختياري | https://api.kaleidr.com/inference-api | يجب أن يتضمن /inference-api. أصل مجرد مثل https://api.kaleidr.com يُرجع 404 عند تبادل الجلسة. ينطبق على أي منتج ينفذ تبادل جلسة (chat, editor, tile). |
tile-base | editor | اختياري | https://tile.kaleidr.com | CDN البلاطات المستخدم لحل قيم style-id في الكتالوج |
flag | الكل | اختياري | — | تجاوز dormancy لكل عنصر |
* مطلوب للاستخدام المصرح به/المفوّر. لا يحتاج Viewer إلى مفتاح؛ وتمرير مفتاح إلى
Viewer embed يُرفض بـ product_not_allowed.
امنح العنصر ارتفاعًا (عبر style مضمن أو CSS). كل منتج يملأ
الحاوية؛ ومنتج iframe داخل حاوية بدون أبعاد يعود إلى
ارتفاع ثابت 500px حتى يظل مرئيًا.
Handle matrix
السلوك كما هو منشور على /embed/v1/. التركيبات غير المدعومة لا ترمي أخطاء —
يسجل SDK تحذير [kaleidr] ويعيد. هذا جزء من العقد في الاسم المستعار الرئيسي v1؛
وإزالة الأساليب القابلة للاستدعاء ستكون تغييرًا يكسر السلوك.
| الأسلوب | chat | viewer | editor | tile |
|---|---|---|---|---|
destroy() | نعم | نعم | نعم | نعم |
setCamera(camera) | no-op | نعم | نعم | نعم |
setTheme(theme) | نعم (مباشر) | n/a | وقت التركيب فقط | n/a |
setStyle(styleId) | n/a | n/a | n/a | متاح في tile فقط |
لا يتحكم Chat في كاميرا الخريطة — استخدم API الكاميرا الخاص بمثيل خريطتك
بعد Kaleidr.mount(...). تحديث setTheme المباشر في Editor سيأتي في إصدار SDK
لاحق؛ أما theme وقت التركيب فيعمل بالفعل.
التحديثات المباشرة
تتم مراقبة center وzoom وpitch وbearing وإعادة تأطير viewer و
editor وtile دون إعادة التركيب. تغييرات theme تحدّث chat مباشرة؛
أما theme الخاص بـ editor فيبقى وقت التركيب فقط.
Chat + map-target
يقوم Chat بالإرفاق بخريطتك الحية، وهو ما لا يمكن لسمة نصية حمله. هناك طريقتان لتوفيره:
- Imperative (موصى به):
Kaleidr.mount(el, { product: 'chat', publishableKey, map, contained: true }). - Declarative: خزّن مثيل الخريطة على العنصر المضيف كالتالي
hostEl.__kaleidrMap__ = map، ثم استخدمmap-target="#host".
بدون خريطة، يعمل chat في وضع headless (دون تفاعلات مع الخريطة).