مرجع Editor

يؤدي product="editor" إلى تثبيت أدوات Kaleidr لتحرير الخرائط داخل صفحتك. ينشئ المحرر خريطته الخاصة داخل هدف التثبيت ويضع لوحاته فوقها. ويعمل في مستند صفحتك لا في iframe.

يحتفظ المحرر المضمّن بالعمل في ذاكرة الصفحة فقط. ولا يمكن حفظ ما يُنشأ فيه أو تصديره أو نشره، ولا توجد دالة رد نداء للتغييرات. تؤدي إعادة تحميل الصفحة أو استدعاء handle.destroy() إلى فقد جميع التعديلات.

البند	التفاصيل
المفتاح	مفتاح قابل للنشر (`kld_pk_live_…`). مطلوب.
النطاق	`design`، تحمله المفاتيح الجديدة افتراضيًا.
الخطة	جميع الخطط، بما فيها Free.
مكان العرض	داخل صفحتك.
الحفظ الدائم	غير متاح.
النسخ	نسخة واحدة لكل صفحة.
CSP	راجع قسم Editor في Content Security Policy.

لخطوات عملية، راجع إرفاق المحرر.

نطاق الوظائف

متاح	غير متاح
النص الموضوع على الخريطة	تبويب البيانات وتحميل مجموعات البيانات
الصورة: وضع الصور على الخريطة	كتالوج Studio لخرائط الأمثلة وأنواع الأنماط
العلامة	لوحة الذكاء الاصطناعي
النافذة المنبثقة	مكتبة النماذج ثلاثية الأبعاد
الخلفية: المساحة الواقعة خلف الخريطة	المشاركة والنشر
الطبقة: تسميات الخريطة الأساسية والمباني ثلاثية الأبعاد والإضاءة والتضاريس	المشاريع: حفظ الخرائط وفتحها وإظهار قائمتها
التصميم: اختيار معلم من الخريطة الأساسية أو فئة أو منطقة وإعادة تنسيقه	تسجيل الدخول
وسيلة الإيضاح: إعدادات التسميات والوسيلة

يمثل العمود الأيسر شريط أدوات المحرر بترتيبه. أداة التصميم في النسخة المضمّنة مخصصة لإعادة التنسيق؛ ولا تشمل كتالوج تصميمات Studio.

التثبيت

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072],
  zoom: 12,
});

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night" center="-0.1276,51.5072" zoom="12"
             style="display:block; height:640px"></kaleidr-map>

يجب أن يكون لهدف التثبيت ارتفاع محدد. يشغل المحرر كامل عرض الهدف وارتفاعه. يضيف عناصره إلى الهدف من دون إزالة العناصر الموجودة مسبقًا؛ لذا استخدم حاوية فارغة.

الخيارات

خيار التثبيت	السمة	النوع	القيمة الافتراضية	مطلوب	الوصف
`product`	`product`	`'editor'`	لا شيء	نعم	يحدد Editor.
`publishableKey`	`publishable-key`	سلسلة نصية	لا شيء	نعم	مفتاح `kld_pk_…` بنطاق `design`. يُرفض مفتاح الخادم `kld_sk_…` في المتصفح قبل أي طلب.
`styleId`	`style-id`	سلسلة نصية	الخريطة الأساسية الافتراضية للمؤسسة، وإلا `kaleidr-morning`	لا	معرّف نمط مثل `kaleidr-night` أو URL كامل للنمط. راجع معرّفات الأنماط. يثبت عند التثبيت.
`center`	`center`	`[longitude, latitude]`؛ السمة بصيغة `"longitude,latitude"`	`[0, 0]`	لا	المركز الابتدائي.
`zoom`	`zoom`	رقم	`2`	لا	مستوى التكبير الابتدائي. يعمل دون `center`.
`pitch`	`pitch`	رقم بالدرجات	`0`	لا	الميل الابتدائي.
`bearing`	`bearing`	رقم بالدرجات	`0`	لا	الدوران الابتدائي.
`theme`	`theme`	كائن أو سلسلة JSON لكائن	لا شيء	لا	حتى 17 مفتاحًا مسمى. راجع مفاتيح السمة. تُقرأ مرة عند التثبيت.
`apiBase`	`api-base`	URL	`https://api.kaleidr.com/inference-api`	لا	مكان إرسال تبادل الجلسة. يجب تضمين `/inference-api`. لا حاجة لضبطه في الإنتاج.
`tileBase`	`tile-base`	URL	`https://tile.kaleidr.com`	لا	مضيف حل معرّفات الأنماط. غير مطلوب في الإنتاج.
`base`	`base`	URL	`https://cdn.kaleidr.com`	لا	المصدر الذي يحمّل منه SDK ملف `editor.js`. يُستخدم المصدر فقط وتُقبل المصادر الواردة في تجاوز العنوان الأساسي حصريًا.
`enabled`	`flag`	قيمة منطقية	لا شيء	لا	التحكم الخاص بالتثبيت ضمن بوابة التفعيل.

لا تؤثر shareId وmap وmapTarget وcontained وviewerBase في تثبيت Editor. لا يوجد خيار styleUrl؛ مرر عنوان URL بواسطة styleId.

الخريطة الأساسية

يختار المحرر خريطته الأساسية وفق الترتيب التالي:

styleId إذا مررته.
الخريطة الأساسية الافتراضية لمؤسستك إذا حُددت.
kaleidr-morning.

لا يمكن تغيير الخريطة الأساسية بعد التثبيت، ولا يدعم المحرر handle.setStyle. لتغييرها، دمّر المحرر وثبّته مجددًا. ستفقد التعديلات.

الكاميرا

يُذكر خط الطول أولًا في center.
يمكن أن تكون كل قيمة رقمًا أو سلسلة رقمية.
يُتجاهل خيار التثبيت غير الممثل لعدد منتهٍ، وتُستخدم القيمة الافتراضية، وتعرض وحدة التحكم مثلًا [kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.
تُسقط سمة الكاميرا غير الرقمية من العنصر دون رسالة وتُستخدم القيمة الافتراضية.

مفاتيح السمة المرئية

theme كائن مفاتيحه من القائمة أدناه. ويجب أن تكون كل قيمة سلسلة تتضمن قيمة CSS. تُتجاهل المفاتيح غير المدرجة والقيم التي ليست سلاسل غير فارغة من دون رسالة؛ فـ fontSizeBase: 14 لا يعمل بينما fontSizeBase: '14px' يعمل.

المفتاح	العنصر المنسق	المثال
`brandColor`	الأزرار الأساسية وحلقات التركيز والأداة النشطة.	`'#0b5fff'`
`brandColorHover`	حالة مرور المؤشر على `brandColor`.	`'#0847c2'`
`brandColorOn`	النصوص والأيقونات فوق `brandColor`.	`'#ffffff'`
`textColor`	نصوص الجسم والعناوين.	`'#111827'`
`textColorMuted`	النصوص الثانوية مثل الشروح.	`'#6b7280'`
`surfaceColor`	لون تعبئة البطاقات ومربعات الحوار.	`'#ffffff'`
`borderColor`	الحدود والفواصل.	`'#e5e7eb'`
`glassBg`	خلفية اللوحات الشفافة جزئيًا: الشريط الجانبي والقوائم المنبثقة. مرر لونًا صلبًا لمظهر مسطح.	`'rgba(255,255,255,0.8)'`
`glassBlur`	قيمة `backdrop-filter` لتلك اللوحات.	`'blur(12px)'`
`cardRadius`	استدارة زوايا البطاقات ومربعات الحوار.	`'12px'`
`buttonRadius`	استدارة زوايا الأزرار والشارات.	`'8px'`
`listRadius`	استدارة صفوف القوائم.	`'6px'`
`fontPrimary`	قيمة `font-family` الأساسية.	`'"Inter", system-ui, sans-serif'`
`fontMono`	`font-family` أحادية العرض.	`'ui-monospace, monospace'`
`fontSizeBase`	حجم الخط الأساسي.	`'14px'`
`sidebarRailWidth`	عرض شريط الأدوات الجانبي.	`'64px'`
`quickActionsWidth`	عرض شريط الإجراءات السريعة العائم.	`'320px'`

Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    buttonRadius: '8px',
  },
});

السلوك:

السمة المرئية لا تقبل أي خصائص CSS مخصصة عشوائية. يُتجاهل مفتاح مثل '--my-color'.
تُطبّق القيم على عنصر جذر المستند أثناء تثبيت المحرر، بحيث تعتمدها مربعات الحوار أينما تظهر. عند تدمير المحرر تُستعاد القيم السابقة.
تُقرأ السمة مرة واحدة عند التثبيت. لا يدعم Editor طريقة handle.setTheme، وتغيير سمة theme بعد التثبيت يسجل تحذيرًا فقط من دون تأثير.
إذا كانت theme سلسلة نصية، فيجب أن تكون JSON يبدأ بـ {. غير ذلك يُتجاهل مع تحذير في وحدة التحكم.

مقبض التحكم

تُرجع Kaleidr.mount المقبض فورًا. راجع مصفوفة المقابض لكل المنتجات.

العضو	في Editor
`handle.product`	`'editor'`
`handle.setCamera(camera)`	يحرك خريطة المحرر.
`handle.setTheme(theme)`	غير مدعوم. يسجل تحذيرًا ولا يفعل شيئًا.
`handle.setStyle(style)`	غير مدعوم. يسجل تحذيرًا ولا يفعل شيئًا.
`handle.destroy()`	يزيل المحرر وخريطته ويستعيد قيم السمة المرئية ويوقف تجديد الجلسة، ويفقد التعديلات.

ليس للمقبض عضو map، ولا يمكن لصفحتك الوصول إلى كائن الخريطة الداخلي للمحرر.

`setCamera(camera)`

handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });

الحقل	النوع	الوصف
`center`	`[number, number]`	خط الطول ثم خط العرض.
`zoom`	رقم	مستوى التكبير.
`pitch`	رقم	الميل بالدرجات.
`bearing`	رقم	الدوران بالدرجات.
`duration`	رقم	مدة الحركة بالميلي ثانية. عدم ذكرها أو ضبطها على `0` يجعل الانتقال فوريًا.

تُوضع الاستدعاءات أثناء تحميل المحرر في قائمة انتظار وتُنفذ عند بدء عمله.

سمات العنصر بعد التثبيت

على عنصر <kaleidr-map product="editor"> مثبت، يؤدي تغيير center أو zoom أو pitch أو bearing إلى تحريك الخريطة دون حركة انتقالية. ولا يؤثر تغيير style-id أو theme أو أي سمة أخرى.

دورة الحياة

الحدث	النتيجة
`Kaleidr.mount(...)` أو اتصال العنصر	يجري تبادل الجلسة وتحميل `editor.js` معًا. يبدأ المحرر بعد اكتمالهما.
`handle.destroy()` أو إزالة العنصر	يُزال المحرر وتُفقد التعديلات.
نقل العنصر إلى أب آخر	يُدمّر ثم يُثبّت من جديد، وتُفقد التعديلات.
تثبيت محرر ثانٍ مع وجود محرر	غير مدعوم. دمّر الأول قبل تثبيت الآخر.
إعادة تحميل الصفحة	تُفقد التعديلات.

ما يعمل داخل صفحتك

على خلاف المنتجات القائمة على iframe، يؤثر المحرر في الصفحة التي تضمه:

يحمّل editor.js، وهي حزمة بحجم عدة ميغابايت، من https://cdn.kaleidr.com.
يضيف أوراق الأنماط إلى المستند بواسطة JavaScript.
يطلب نمط الخريطة الأساسية وبلاطاتها ورسوماتها وخطوطها من https://tile.kaleidr.com. تحمل طلبات النمط والرسومات والخطوط مفتاحك القابل للنشر في معامل الاستعلام key لكي يتعرف المضيف إلى صفحتك؛ أما طلبات بيانات البلاطات فلا تحمل مفتاحًا. ولا يوضع رمز الجلسة في URL مطلقًا.
يبدأ عمال الويب للخريطة من عناوين blob:.
يضبط قيم السمة المرئية على عنصر جذر المستند أثناء التثبيت.

توجد توجيهات CSP المناظرة في Content Security Policy.

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

الرسالة	المعنى
`[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	لم يُمرر مفتاح. لا يظهر شيء.
`[kaleidr:editor] kaleidr session exchange failed (<status>)`	رُفض تبادل الجلسة. السبب في الاستجابة المرئية بتبويب Network. يحمل 403 رمزه في `detail`، مثل `insufficient_scope` عندما يغيب `design`؛ ويحمله 429 في `error`.
خطأ CORS لطلب `…/sdk/sessions` يتبعه خطأ fetch مع `[kaleidr:editor]`	المفتاح مجهول أو ملغى أو مصدر الصفحة غير مسموح.
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. …`	مُرر مفتاح خادم. لا يُرسل أي طلب.
`[kaleidr:editor] ignored <field>: <value> is not a finite value — using <default> instead.`	خيار كاميرا مُرسل إلى `Kaleidr.mount` ليس رقمًا. سمات العنصر لا تنتج هذه الرسالة.
`[kaleidr:editor] <message>`	أبلغت خريطة المحرر عن خطأ، مثل فشل تحميل نمط أو بلاطة.
`[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.`	كانت `theme` سلسلة لا تحتوي كائن JSON.
`[kaleidr] theme JSON parse failed (…); ignored.`	تضمنت `theme` صيغة JSON غير صحيحة.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op. …`	استدعيت `setTheme` أو غيّرت سمة `theme` بعد التثبيت.
`[kaleidr] setStyle() is not supported on product "editor" — the call is a no-op. …`	استدعيت `setStyle`.

غير متاح

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

صفحات ذات صلة

إرفاق المحرر
المحمّل kaleidr.js
عنصر <kaleidr-map>
تضمين خريطة منشورة، للخرائط التي تُحفظ بشكل دائم

نطاق الوظائف​

التثبيت​

الخيارات​

الخريطة الأساسية​

الكاميرا​

مفاتيح السمة المرئية​

مقبض التحكم​

setCamera(camera)​

سمات العنصر بعد التثبيت​

دورة الحياة​

ما يعمل داخل صفحتك​

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

غير متاح​

صفحات ذات صلة​