إنتقل إلى المحتوى الرئيسي

Editor — تركيب محرر الخرائط

يقوم product="editor" بتركيب محرر خرائط Kaleidr داخل صفحتك. وينشئ ويتحكم في خريطة MapLibre الخاصة به داخل العنصر — عبر طريقة attach، وليس iframe.

  • طريقة الدمج: attach — يعمل MapLibre في المستند الأصل.
  • النطاق المطلوب: design.
  • الحد الأدنى للخطة: Pro — مفاتيح Free لا تسمح بنطاق design.

قبل البدء​

  • يجب أن يكون أصل صفحتك ضمن قائمة الأصول المسموح بها للمفتاح. وإلا يفشل تبادل الجلسة بخطأ 403 session_origin_mismatch. لا يرسل file:// أي Origin ويفشل دائمًا — استخدم HTTP(S). راجع الحصول على مفتاح API.
  • يجب أن يسمح CSP الخاص بك بمحمّل SDK و'wasm-unsafe-eval' (MapLibre داخل الصفحة)، ومضيفي البلاطات/المزود — راجع Content Security Policy.

التركيب​

const handle = Kaleidr.mount('#editor', {
  publishableKey: 'kld_pk_live_…',
  product: 'editor',
  styleId: 'kaleidr-night',  // catalog basemap id or a full style URL
  // Omit it and the organization's stored default applies, falling back to
  // kaleidr-morning when it has none.
});

يشغّل التضمين المستقل أدوات المحرر من جهة العميل — ويتم تركيب واجهات التحرير على الخريطة فوق خريطة الأساس وتبقى التعديلات في مواصفات التضمين الموجودة في الذاكرة (لا يتم حفظ أي شيء). واجهات AI (تصميم الخرائط وControl Tower) ومكتبة النماذج ثلاثية الأبعاد ليست جزءًا من التضمين المستقل؛ فهي تحتاج إلى backend من Kaleidr وأصول يقدّمها المضيف.

لخريطة أساس للتطوير، مرر tileBase: 'https://tile-dev.kaleidr.com' — عندها يتم حل معرفات الأنماط في الكتالوج من خلاله بدلًا من tile.kaleidr.com الخاص بالإنتاج. راجع إرفاق المحرر.

خيارات الكاميرا​

يتم احترام center وzoom وpitch وbearing عند التركيب. كما يقوم SDK الموحّد بتمرير تغييرات سمات الكاميرا التعريفية اللاحقة عبر handle الخاص بالمحرر.

Handle​

handle.destroy();
handle.setCamera({ center: [-0.12, 51.5], zoom: 11 });  // supported
  • يقبل handle.setTheme(...) كائن JSON لرموز CSS وقت التركيب؛ وسيأتي التحديث المباشر عبر handle في إصدار SDK لاحق (أما وقت التركيب فهو يعمل بالفعل).
  • handle.setStyle(...) غير متاح في editor. استخدم styleId عند التركيب، أو API الأنماط الخاص بخريطة MapLibre الأساسية لإجراء التبديلات بعد التركيب.

طلبات خريطة الأساس تحمل مفتاحك تلقائيًا​

خرائط أساس Kaleidr مصرح بها بالمفتاح — يرفض tile.kaleidr.com أصول المتصفح التي لا يعرفها. لذلك يضيف التضمين مفتاح publishable الخاص بك إلى طلبات خريطة الأساس تلقائيًا عبر transformRequest الخاص بـ MapLibre:

// what the embed does internally — you don't write this
transformRequest: (url) =>
  url.startsWith('https://tile.kaleidr.com/')
    ? { url: `${url}?key=kld_pk_live_…` }
    : { url };

هناك نتيجتان مهمتان يجب معرفتهما:

  • يجب أن تتضمن الأصول المسموح بها لمفتاحك أصل الصفحة. المفتاح الذي تم إنشاؤه دون أصل موقعك يُرجع 429 tile_access_restricted لكل بلاطة. حدّثه عبر kaleidr.com/api-keys.
  • تتم إعادة كتابة عناوين URL الخاصة ببلاطات Kaleidr فقط. إذا مررت styleUrl على مضيف مختلف، يترك التضمين تلك الطلبات دون تغيير — ولا يتم أبدًا إرفاق مفتاحك بأصل تابع لجهة خارجية.