عنصر <kaleidr-map>

<kaleidr-map> هو الأسلوب التصريحي لتركيب أحد منتجات Kaleidr. تكتب العنصر مع سماته، فيُركَّب تلقائيًا عند إدراجه في المستند ويُزال عند إخراجه. يعرّفه kaleidr.js، ولذلك يجب تحميل هذا السكربت في الصفحة.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

العنصر غلاف خفيف يحوّل سماته إلى خيارات ويستدعي Kaleidr.mount على نفسه. كل ما يفعله العنصر ممكن عبر Kaleidr.mount، ولكن العكس ليس صحيحًا: فلا يمكن للعنصر تلقي كائن خريطة يعمل بالفعل، ولا يعيد المقبض.

استخدم العنصر عندما	استخدم Kaleidr.mount عندما
يكون التضمين ترميز HTML ثابتًا.	تحتاج إلى المقبض لتشغيل setCamera أو setStyle أو setTheme أو destroy.
ينشئ نظام إدارة المحتوى أو القالب ترميز HTML.	تربط Chat بخريطتك الخاصة، وهو ما يتطلب خيار map.
تريد التنظيف تلقائيًا عند إزالة العنصر من المستند.	يتحكم إطار العمل في توقيت التركيب والإزالة.

السمات

تُكتب أسماء السمات بصيغة kebab-case، وتُكتب خيارات التركيب المقابلة بصيغة camelCase.

السمة	خيار التركيب	المنتجات	مطلوب	الافتراضي	يُراقَب بعد التركيب	الوصف
product	product	الجميع	نعم	لا شيء	لا	chat أو viewer أو editor أو tile.
publishable-key	publishableKey	chat، editor، tile	نعم، باستثناء Chat على خريطة منشورة	لا شيء	لا	مفتاحك kld_pk_…. لا يستخدمه Viewer.
share-id	shareId	viewer، chat	مطلوب في viewer	لا شيء	لا	في Viewer: معرّف الخريطة المنشورة. وفي Chat بلا مفتاح: الخريطة المنشورة التي توفر الدردشة.
map-id	mapId	viewer	لا	لا شيء	لا	اسم بديل لـ share-id.
style-id	styleId	tile، editor	يوصى به في Tile	الخريطة الأساسية الافتراضية للمؤسسة؛ وفي Editor يليها kaleidr-morning	لا	معرّف نمط خريطة أساسية أو عنوان URL للنمط.
map-target	mapTarget	chat	لا	لا شيء	لا	محدِّد CSS لعنصر <kaleidr-map> من نوع Viewer أو Tile ليتحكم فيه المساعد.
contained	contained	chat	لا	معطل	لا	يثبت لوحة الدردشة داخل العنصر، الذي يجب تحديد موضعه وأبعاده.
lang	lang	chat	لا	لغة <html lang> إذا كان الوسم صالحًا، وإلا فالإنجليزية	لا	لغة إجابات اللوحة بصيغة BCP 47 مثل en أو ko أو pt-BR. راجع لغة Chat.
chat-title	title	chat	لا	عنوان اللوحة الافتراضي	لا	عنوان رأس اللوحة. السمة هي chat-title وليست title، لأن title في HTML يعرض تلميحًا عند المرور بالمؤشر.
placeholder	placeholder	chat	لا	النص الإرشادي الافتراضي للوحة	لا	النص الإرشادي في حقل الإدخال.
layout	layout	viewer	لا	map	لا	تركّب القيمة bar شريط الدردشة، الذي يقرأ أيضًا chat-title وplaceholder وtheme وlang بقيم افتراضية خاصة به: راجع خيارات Viewer. تعرض locator وlistings الخريطة بجانب قائمة لمجموعة من مكتبة الأماكن: راجع تخطيطات الأماكن. تفتح guide الدردشة بجانب خريطة للمنشآت: راجع تخطيط الدليل. تعرض live المركبات ومحطات اليوم: راجع التخطيط المباشر.
collection	collection	محدد المواقع وقائمة العقارات والدليل والمباشر في Viewer	لا	أول مجموعة من نوع التخطيط ترسمها الخريطة	لا	معرّف المجموعة المعروضة في القائمة؛ وفي live معرّف مجموعة المركبات.
stops	stops	المباشر في Viewer	لا	أول مجموعة محطات ترسمها الخريطة	لا	معرّف مجموعة المحطات.
filters	filters	محدد المواقع وقائمة العقارات في Viewer	لا	كل عوامل تصفية المجموعة	لا	عوامل تصفية الزوار المعروضة، مفصولة بـ |: search وcategory وprice وbeds وbaths وopen_now.
card	card	viewer	لا	auto	لا	تعرض بطاقات الأماكن compact العنوان الرئيسي والعنوان الفرعي والإجراءات فقط.
prompt	prompt	viewer	لا	لا شيء	لا	سؤال لطرحه على Kaleidr AI الخاص بالخريطة عند فتحها؛ وفي شريط الدردشة، النص المعبأ مسبقًا في الحقل.
prompt-param	promptParam	viewer	لا	لا شيء	لا	يقرأ prompt من معامل الاستعلام هذا في عنوان URL للصفحة، عندما يأتي الزائر من صفحة من الأصل نفسه.
prompts	prompts	شريط دردشة Viewer	لا	لا شيء	لا	أمثلة أسئلة، مفصولة بـ |.
accent	accent	شريط دردشة Viewer	لا	#2da84a	لا	لون CSS.
results-url	resultsUrl	شريط دردشة Viewer	لا	لا شيء	لا	يرسل الزوار إلى تلك الصفحة مع ?q=<question>.
center	center	viewer، tile، editor	لا	القيمة الافتراضية للمنتج	نعم	"longitude,latitude"، مثل "-0.1276,51.5072".
zoom	zoom	viewer، tile، editor	لا	القيمة الافتراضية للمنتج	نعم	رقم. لا يُطبَّق عند تركيب Viewer وTile إلا مع center.
pitch	pitch	viewer، tile، editor	لا	القيمة الافتراضية للمنتج	نعم	زاوية الميل بالدرجات.
bearing	bearing	viewer، tile، editor	لا	القيمة الافتراضية للمنتج	نعم	زاوية الدوران بالدرجات.
theme	theme	chat، editor	لا	لا شيء	نعم (يؤثر في Chat فقط)	سلسلة JSON. في Chat خصائص CSS مخصصة، وفي Editor مفاتيح السمات السبعة عشر.
flag	enabled	الجميع	لا	لا شيء	لا	تحكم على مستوى العنصر في بوابة التفعيل.
base	base	الجميع	لا	https://cdn.kaleidr.com	لا	مصدر حزم المنتج. يُقبل فقط نطاق CDN الخاص بـ Kaleidr (https://cdn.kaleidr.com)، أو المصدر الذي حُمِّل منه kaleidr.js، أو مصدر الصفحة نفسها. تُتجاهل القيم الأخرى مع تحذير. راجع تجاوز العنوان الأساسي.
viewer-base	viewerBase	viewer، tile	لا	https://map-embed.kaleidr.com	لا	مصدر تحميل iframe.
api-base	apiBase	chat، editor، tile	لا	https://api.kaleidr.com/inference-api	لا	وجهة تبادل الجلسة وطلبات المنتج. يجب أن يتضمن /inference-api.
tile-base	tileBase	editor	لا	https://tile.kaleidr.com	لا	المضيف الذي تُحلّ من خلاله معرّفات الأنماط.

api-key اسم بديل مهمل لـ publishable-key. وتُستخدم سمات …-base الأربع للاختبار مع نشر آخر، ولا حاجة إليها في بيئة الإنتاج.

السمات المنطقية

تُقرأ السمتان flag وcontained بوصفهما قيمتين منطقيتين:

طريقة الكتابة	القيمة المقروءة
contained دون قيمة، أو contained=""	صحيح
"true" أو "1" أو "yes" أو "on"	صحيح
"false" أو "0" أو "no" أو "off"	خطأ
غياب السمة	غير محدد
أي قيمة أخرى	تُتجاهل مع تحذير في وحدة التحكم

لا تؤثر حالة الأحرف أو المسافات المحيطة في المطابقة، لذا فإن flag="False" يعطل العنصر. ولأن وجود السمة دون قيمة يعني «صحيح»، فإن القالب الذي ينتج flag="" يفعّل العنصر. اكتب false صراحة.

سمات الأرقام والكاميرا

تُحلّل zoom وpitch وbearing كأرقام. وتحتوي center على رقمين مفصولين بفاصلة، خط الطول أولاً. تُتجاهل القيمة التي يتعذر تحليلها دون رسالة، وتُستخدم القيمة الافتراضية للمنتج.

السمات بعد التركيب

يقرأ العنصر سماته مرة واحدة عند دخوله المستند. وبعد ذلك يراقب خمس سمات فقط:

السمة المتغيرة	viewer	tile	editor	chat
center وzoom وpitch وbearing	تنتقل الخريطة مباشرة إلى وضع الكاميرا الجديد.	تنتقل الكاميرا مباشرة.	تنتقل الكاميرا مباشرة.	تحذير في وحدة التحكم دون تأثير.
theme	تحذير في وحدة التحكم.	تحذير في وحدة التحكم.	تحذير؛ يقرأ Editor السمة عند التركيب فقط.	يتغير مظهر اللوحة.
أي سمة أخرى	لا شيء.	لا شيء.	لا شيء.	لا شيء.

تغيير الكاميرا عبر السمات لا يستخدم الحركة المتدرجة. للحصول على انتقال متحرك، ركّب المنتج باستخدام Kaleidr.mount ثم استدعِ handle.setCamera({ …, duration: 800 }).

عند تغيير سمة كاميرا واحدة، يرسل العنصر كل سمات الكاميرا التي يملكها حينئذ. إذا غيّرت zoom فقط مع وجود center، يُعاد تطبيق ذلك المركز.

لتغيير share-id أو style-id أو publishable-key أو product أو flag أو contained أو lang أو chat-title أو placeholder، استبدل العنصر: أزله وأدرج آخر بسماته الجديدة. وفي Tile يمكنك استعمال handle.setStyle لتغيير النمط دون إعادة التركيب، ولكن فقط إذا رُكّب بواسطة Kaleidr.mount.

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

دورة الحياة

الحدث	ما يفعله العنصر
يدخل المستند	يقرأ السمات ويُركّب. تبدأ عملية تبادل جلسة في Chat وEditor وTile.
يوجد في المستند قبل تحميل kaleidr.js	لا يحدث شيء حتى تحميل السكربت، ثم يتم التركيب.
يغادر المستند	يهدم التركيب، ويزيل ما أضافه، ويوقف تجديد الجلسة.
يدخل المستند مجددًا	يعيد قراءة السمات والتركيب مع تبادل جلسة جديد.
يُنقل إلى أبٍ آخر	يغادر ثم يدخل، فيُهدم ويُركّب مجددًا.
غياب product أو كانت قيمته غير إحدى القيم الأربع	يسجل [kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" ولا يُركّب. تعيين product لاحقًا لا يغير ذلك.

ينتج عن ذلك ما يلي:

• اضبط السمات قبل إدراج العنصر. إذا أنشأته باستخدام JavaScript، اضبط سماته كلها ثم أضفه إلى المستند. إذا أضفته أولًا فسوف يُركّب بالقيم الموجودة حينها.

  const el = document.createElement('kaleidr-map');
  el.setAttribute('product', 'tile');
  el.setAttribute('publishable-key', 'kld_pk_live_…');
  el.setAttribute('style-id', 'kaleidr-night');
  el.style.cssText = 'display:block; height:480px';
  document.getElementById('slot').appendChild(el); // mounts here

• إعادة التركيب ليست مجانية. إعادة تركيب Tile تُحسب تحميل خريطة إضافيًا. يفقد Editor تعديلاته، وتبدأ محادثة جديدة في Chat. قد تتسبب إعادة إنشاء أو ترتيب عقد DOM، كما يحدث في إعادة عرض قائمة بإطار عمل، في ذلك دون قصد. راجع دمج أطر العمل.

• العنصر المخفي يُركّب كذلك. display:none لا يؤخر التركيب، لذا تبدأ جلسة Tile داخل علامة تبويب مغلقة.

• يُعرض محتوى العنصر حتى تستبدله الخريطة. يظهر كل ما تضعه داخل العنصر. يستبدل Viewer وTile المحتوى بـ iframe بعد تحميلهما، لذا يمكن أن يكون العنصر الداخلي مؤشر تحميل أو بديلاً إذا فشل التركيب أو أوقفته بوابة التفعيل. لا يزيل Chat وEditor أبناء العنصر. اتركه فارغًا ما لم تحتج إلى ذلك.

تحديد الأبعاد

يستخدم <kaleidr-map> القيمة الافتراضية display:block، لذا يمكن تطبيق height عليه:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="height:480px"></kaleidr-map>

ثلاث نقاط عن هذه القيمة الافتراضية:

• تحديدك أنت لـ display يتقدم دائمًا. النمط المباشر، أو قواعد ورقة CSS، أو السمة hidden كلها تتجاوز الافتراضي. إذا عيّنت display:inline لا تعود height مؤثرة.
• لا يلزم استثناء في سياسة أمان المحتوى. الافتراضي لا يمر عبر وسم <style> أو سمة style، لذا يعمل دون 'unsafe-inline'.
• لا تحصل إصدارات Safari قبل 16.4 على هذا الافتراضي. يبقى العنصر مضمنًا ويتجاهل width وheight. لهذا تتضمن الأمثلة display:block داخل سمة style؛ لا يضر عند دعم الافتراضي ويتيح تحديد الأبعاد في الإصدارات القديمة.

لذلك تُستخدم الصيغة التالية في هذه الوثائق:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

أو تُستخدم مرة واحدة للموقع كله:

kaleidr-map { display: block; height: 480px; }

المنتج	سلوك الأبعاد
viewer، tile	يشغل iframe عرض العنصر بنسبة 100%. ويكون ارتفاعه 100% إذا كان للعنصر ارتفاع عند التركيب، وإلا فيكون ثابتًا عند 500 بكسل. يُضبط position:relative عند غياب تحديد موضع مباشر، ويُضبط overflow:hidden على العنصر.
editor	يشغل 100% من عرض العنصر وارتفاعه. إذا لم يكن له ارتفاع فلا يظهر شيء.
chat	دون contained، تكون اللوحة نافذة ثابتة في الزاوية العلوية اليسرى بغض النظر عن أبعاد العنصر. ومع contained تستقر داخله ويحتاج إلى position:relative أو تموضع مماثل، وإلى أبعاد محددة.

يُقرر استخدام ارتفاع 500 بكسل البديل مرة واحدة عند التركيب. فإذا لم يكن للعنصر ارتفاع وقتها، يبقى iframe بارتفاع 500 بكسل حتى لو حددت له ارتفاعًا لاحقًا.

إذا كانت سياسة أمان المحتوى لديك تحظر سمات style المباشرة، فحدّد أبعاد العنصر عبر ورقة أنماط. لا تتأثر القيمة الافتراضية لعرضه ككتلة بهذه السياسة.

مصفوفة المقبض

لا يتيح العنصر مقبضًا. لاستدعاء هذه الوظائف، ركّبه باستخدام Kaleidr.mount الذي يعيد مقبضًا.

الوظيفة	chat	viewer	editor	tile
destroy()	نعم	نعم	نعم	نعم
setCamera(camera)	غير مدعومة	نعم	نعم	نعم
setTheme(theme)	نعم	غير مدعومة	غير مدعومة	غير مدعومة
setStyle(style)	غير مدعومة	غير مدعومة	غير مدعومة	نعم
send(text)	غير مدعومة	نعم	غير مدعومة	غير مدعومة
setFilters(filters)	غير مدعومة	نعم	غير مدعومة	غير مدعومة
showVehiclesLayer(layer)	غير مدعومة	نعم	غير مدعومة	غير مدعومة
clearVehiclesLayer()	غير مدعومة	نعم	غير مدعومة	غير مدعومة

يتضمن كل مقبض جميع هذه الوظائف. الوظيفة الموسومة «غير مدعومة» لا تفعل شيئًا عند استدعائها وتُصدر تحذيرًا في وحدة التحكم دون رمي استثناء. وهذا السلوك جزء من عقد /embed/v1.

حسب المنتج:

• chat: تغيّر setTheme مظهر اللوحة. ولا تدعم Chat الوظيفة setCamera لأنها لا تملك خريطة: ينقل المساعد الخريطة المتصلة عند الإجابة، ويمكنك تحريك خريطتك بواجهة مكتبة الخرائط نفسها.
• viewer: تحرك setCamera الخريطة المنشورة. وتضبط setFilters عوامل تصفية الزوار في تخطيط أماكن. وترسم showVehiclesLayer مركباتك الخاصة على الخريطة، وتزيلها clearVehiclesLayer: راجع طبقة المركبات.
• editor: تحرك setCamera خريطة المحرر. ويُثبَّت المظهر والخريطة الأساسية عند التركيب.
• tile: تحرك setCamera الخريطة وتستبدل setStyle الخريطة الأساسية دون إعادة التركيب.

تقبل setCamera الكائن { center, zoom, pitch, bearing, duration }. كل الحقول اختيارية، وتأتي center بصيغة [longitude, latitude]، وتقاس duration بالمللي ثانية. راجع التفاصيل في kaleidr.js.

Chat وmap-target

يمكن لـ Chat التحكم في نوعين من الخرائط:

• خريطتك الخاصة (Mapbox GL JS وMapLibre GL JS وGoogle Maps وLeaflet). لا يمكن كتابة كائن الخريطة داخل سمة، لذا يجب استدعاء Kaleidr.mount بخيار map. راجع مرجع Chat.

• عنصر Viewer أو Tile من Kaleidr في الصفحة نفسها. وجّه map-target إليه باستخدام محدِّد CSS:

  <div style="position:relative">
    <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
                 style-id="kaleidr-morning"
                 style="display:block; height:480px"></kaleidr-map>
  
    <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
                 map-target="#basemap"
                 style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
  </div>

  لا يهم ترتيب العنصرين. يبحث Chat عن العنصر المستهدف عند الحاجة إليه.

دون map أو map-target تكون Chat لوحة بلا خريطة.

يضع الغلاف وأنماط عنصر Chat اللوحة فوق الخريطة. شُرحت كل قاعدة في المظاهر والتخطيط. وتتناول الدردشة على خريطة منشورة Chat المتصلة بخريطة منشورة.

رسائل وحدة التحكم

الرسالة	المعنى
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	سمة product غائبة أو مكتوبة خطأ؛ لن يُركّب العنصر.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).	قيمة flag أو contained غير مقبولة. تحدد الرسالة السمة: flag="…" أو contained="…".
[kaleidr] base "<value>" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.	تشير سمة base إلى مصدر غير مسموح. يستمر تحميل المنتج من CDN الافتراضي.
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	أوقفت flag التركيب. استبدل العنصر دون هذا الإعداد ليُركّب.
[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …	تغيّرت إحدى سمات الكاميرا في Chat.
[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …	تغيّرت سمة theme في Viewer أو Tile أو Editor.

تُسجَّل إخفاقات التركيب بصيغة [kaleidr:<product>] …. وترد قائمتها في kaleidr.js.

ما ليس متاحًا

• الأحداث: لا يصدر العنصر أي أحداث DOM.
• الخصائص أو الوظائف: لا يمتلك العنصر setCamera ولا خاصية handle ولا وعد ready.
• إعادة قراءة السمات: باستثناء السمات الخمس المراقبة، تُتجاهل التغييرات بعد التركيب.

صفحات ذات صلة

• محمّل kaleidr.js
• دمج أطر العمل
• مراجع Viewer وTile، وEditor وChat