إرفاق محرّر الخرائط

بعد إكمال هذا الدليل، ستعرض صفحتك أدوات التحرير على الخرائط من Kaleidr فوق خريطة Kaleidr الأساسية، مع تنسيق يلائم علامتك التجارية. تتوفر الميزة في جميع الخطط، بما فيها Free. ستحتاج إلى مفتاح قابل للنشر يحمل النطاق design، وهو متاح افتراضياً في المفاتيح الجديدة.

لا تُحفظ التعديلات

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

قبل البدء

مفتاح Kaleidr قابل للنشر (kld_pk_live_…) من kaleidr.com/api-keys. راجع الحصول على مفتاح API.
إضافة أصل الصفحة التي ستختبرها، مثل http://localhost:3000، إلى قائمة الأصول المسموح بها للمفتاح. يعمل المفتاح غير المقيّد بالأصول على أي موقع.
وسيلة لتقديم الصفحة عبر HTTP، مثل npx serve ..
إذا كان موقعك يطبّق سياسة أمان المحتوى، فاسمح بتوجيهات المحرّر المذكورة في Content Security Policy. يعمل المحرّر داخل صفحتك، ولذلك يحتاج إلى إعدادات connect-src وimg-src وworker-src وfont-src وstyle-src الإضافية التي لا تتطلبها منتجات iframe.
التأكد من عدم وجود محرّر Kaleidr آخر في الصفحة نفسها.

الخطوة 1: إضافة حاوية بأبعاد محددة وتثبيت المحرّر

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

النتيجة المتوقعة: تملأ خريطة Kaleidr الأساسية الحاوية بمنظور العالم (بأسلوب kaleidr-morning ما لم تحدد مؤسستك إعداداً افتراضياً آخر)، ويظهر زر Create على الخريطة. اضغط Create لفتح الشريط الجانبي الذي يضم أدوات النص والصور والعلامات والنوافذ المنبثقة.

يجب تحديد ارتفاع الحاوية. يشغل المحرّر 100% من عرضها وارتفاعها، وتبقى لوحاته داخلها.

يمكنك أيضاً استخدام العنصر المخصص. يستخدم display:block افتراضياً، لذا يعمل تحديد الارتفاع؛ ويضيف المثال display:block صراحة للتوافق مع Safari قبل الإصدار 16.4:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

الخطوة 2: اختيار الخريطة الأساسية والكاميرا الأولية

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

النتيجة المتوقعة: خريطة أساسية داكنة فوق وسط لندن مع إمالة وتدوير.

تُختار الخريطة الأساسية وفق الترتيب التالي:

استخدم styleId عند تمريره، مثل kaleidr-morning أو kaleidr-afternoon أو kaleidr-evening أو kaleidr-night أو kaleidr-plain أو kaleidr-editorial. تجد الأوصاف في مرجع Tile.
وإلا تُستخدم الخريطة الأساسية الافتراضية لمؤسستك، إن كانت محددة.
وإلا يُستخدم kaleidr-morning.

إعدادات الكاميرا الافتراضية هي المركز [0, 0] والتكبير 2 والإمالة 0 والاتجاه 0. خلافاً لمنتجي Viewer وTile، يقبل المحرّر zoom دون center.

يتجاهل Kaleidr.mount أي خيار كاميرا لا يمثل رقماً محدوداً مع إظهار رسالة في وحدة التحكم. وفي العنصر المخصص، تُهمل سمات الكاميرا غير الرقمية بلا رسالة.

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

الخطوة 3: تخصيص مظهر اللوحات (اختياري)

مرّر theme لمطابقة لوحات المحرّر مع تصميم منتجك. يقبل الكائن حتى 17 مفتاحاً مسمى، ويُتجاهل أي مفتاح خارج القائمة.

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

النتيجة المتوقعة: تظهر الأداة النشطة وحلقات التركيز والأزرار الأساسية بلون علامتك التجارية، وتستخدم اللوحات خطك.

جميع المفاتيح السبعة عشر مدرجة في مرجع المحرّر.

ثلاث نقاط ينبغي معرفتها:

القيم هي قيم CSS. يقبل brandColor أي لون CSS، وcardRadius أي طول CSS، وfontPrimary أي قيمة font-family. يجب تحميل الخط بنفسك.
يُطبّق المظهر على المستند كله ما دام المحرّر مثبتاً، وتُستعاد القيم الأصلية عند إزالته. لا تتأثر تنسيقاتك إلا إذا استخدمت الخصائص المخصصة نفسها.
يُقرأ المظهر عند التثبيت فقط. لا يدعم المحرّر handle.setTheme. لتغييره، أزل المحرّر وأعد تثبيته، ما يؤدي إلى فقدان التعديلات.

في العنصر المخصص، تكون theme سلسلة JSON:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

الخطوة 4: تحريك الكاميرا من صفحتك (اختياري)

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

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

setCamera هي الطريقة الوحيدة لتحكم صفحتك في خريطة المحرّر. لا يكشف مقبض التحكم عن كائن الخريطة.

الخطوة 5: إزالة المحرّر

handle.destroy();

تزيل destroy() المحرّر والخريطة واللوحات من الحاوية وتستعيد قيم المظهر. وتُتلف التعديلات.

في تطبيق أحادي الصفحة، استدعِ destroy() عند إزالة المسار أو المكوّن الذي يمتلك المحرّر. وإذا استخدمت العنصر المخصص، فإزالته من المستند لها النتيجة نفسها. راجع تكامل أطر العمل.

لا يمكن أن يوجد سوى محرّر واحد في كل صفحة في الوقت نفسه، لذلك أزل المحرّر الحالي قبل تثبيت محرّر آخر.

صفحة كاملة

احفظها باسم index.html، وأدخل مفتاحك، وقدّم المجلد عبر HTTP من أصل يسمح به المفتاح.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

طريقة العمل

الموضوع	السلوك
مكان التشغيل	داخل المستند. لوحة رسم الخريطة ولوحات المحرّر عناصر داخل حاوية التثبيت.
الجلسة	يستبدل SDK المفتاح بجلسة قصيرة العمر قبل تشغيل المحرّر ويجددها طوال فترة تثبيته.
التعديلات	تبقى في الذاكرة فقط، ولا تُحفظ أو تُصدّر أو تُنشر أو تُرسل إلى الصفحة.
الخريطة الأساسية	تُحمّلها الصفحة من `https://tile.kaleidr.com` وتُثبّت عند بدء المحرّر.
المظهر	يطبّق على المستند كله عند التثبيت ويُستعاد عند الإزالة.
الكاميرا	تُحدد عند التثبيت ويمكن تحريكها باستخدام `handle.setCamera`.
الاستهلاك	طلب جلسة المحرّر لا يُحسب تحميلاً للخريطة؛ وليس في المحرّر المضمّن ميزات ذكاء اصطناعي تستهلك الرصيد. تضيف طلبات خريطة الأساس التي تتضمن مفتاحك عمليات تحميل خرائط على دفعات: تحميل واحد لكل 20 طلبًا خلال ساعة. راجع عمليات تحميل الخرائط.
الإشعارات	لا توجد أحداث جاهزية أو تغيير أو استدعاءات أخطاء.

إبلاغ المستخدمين

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

التحقق من نجاح الإعداد

في الصفحة: تملأ الخريطة الأساسية الحاوية، ويفتح زر Create الشريط الجانبي، ويمكن وضع نص أو علامة على الخريطة.
في وحدة التحكم: لا توجد أسطر تحتوي على [kaleidr.
في تبويب الشبكة: تحميل kaleidr.js وeditor.js من https://cdn.kaleidr.com، وطلب POST …/sdk/sessions بحالة 200، وطلبات الأنماط ومربعات الخرائط إلى https://tile.kaleidr.com.

استكشاف الأخطاء وإصلاحها

يسجّل SDK فشل التثبيت في وحدة التحكم بصيغة [kaleidr:editor] …. عند رفض الجلسة يسجل حالة HTTP فقط. يمكن قراءة السبب من استجابة طلب sessions في تبويب الشبكة؛ يحمل 403 رمزه في detail، ويحمل 429 رمزه في error مع التوضيح في detail.

العرَض	السبب	الحل
لا يظهر شيء. وحدة التحكم: `[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	لم يُمرَّر مفتاح.	مرّر `publishableKey`.
لا يظهر شيء مع خطأ CORS لطلب `…/sdk/sessions` وخطأ `[kaleidr:editor]`.	المفتاح غير معروف أو أُلغي أو أصل الصفحة غير مسموح.	تحقق من المفتاح وأضف الأصل الدقيق ببروتوكوله ومضيفه ومنفذه في kaleidr.com/api-keys، وانتظر بضع دقائق.
`[kaleidr:editor] kaleidr session exchange failed (403)`	المفتاح بلا نطاق `design` (`insufficient_scope`)، أو مقيّد بمنتجات أخرى (`product_not_allowed`)، أو الخطة لا تسمح (`tier_capability_not_allowed`).	اقرأ `detail` وأنشئ مفتاحاً بالنطاقات الافتراضية.
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	تم استخدام مفتاح خادم.	استخدم مفتاحاً قابلاً للنشر ودوّر مفتاح الخادم إذا عُرض في صفحة عامة.
الحاوية فارغة ولا ارتفاع لها.	حاوية التثبيت بلا ارتفاع.	حدد ارتفاعاً، وأضف `display:block` في Safari قبل 16.4.
تظهر اللوحات لكن الخريطة فارغة، و`https://tile.kaleidr.com` يعيد 429 مع `"error":"tile_access_restricted"`.	خادم الخريطة الأساسية يرفض الطلب.	تأكد من صحة المفتاح والأصل المسموح، وانتظر بعد التعديل ثم أعد التحميل؛ تواصل مع الدعم إن استمرت المشكلة. `[kaleidr:editor] …`
تظهر اللوحات والخريطة فارغة مع مخالفة CSP في وحدة التحكم.	السياسة تحظر الخريطة الأساسية أو العامل أو الصور.	أضف توجيهات المحرّر من Content Security Policy.
لا تظهر تنسيقات المحرّر.	السياسة تحظر التنسيقات المضمّنة.	اسمح بـ `'unsafe-inline'` في `style-src`.
يتعطل المحرّر الثاني أو يتوقف الأول.	يوجد محرّران مثبتان.	أزل الأول قبل تثبيت الثاني.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	المظهر يُقرأ وقت التثبيت فقط.	مرّر `theme` عند التثبيت.
`[kaleidr] theme string must be JSON…`	سمة `theme` ليست كائن JSON.	استخدم علامات اقتباس مفردة حول السمة ومزدوجة داخل JSON.
مفتاح مظهر لا يعمل.	المفتاح غير معروف أو مكتوب خطأ؛ تُتجاهل المفاتيح المجهولة.	تحقق من القائمة.
اختفت التعديلات.	أُعيد تحميل الصفحة أو أُزيل المحرّر أو نُقل العنصر أو حُذف.	سلوك متوقع؛ راجع التنبيه في الأعلى.

القيود

لا يُحفظ شيء أو يُصدّر أو يُنشر من التضمين.
لا توجد استدعاءات للتغيير أو إشارات جاهزية أو أخطاء.
لا يوجد وصول إلى كائن الخريطة؛ لذا لا يمكن إضافة طبقات خاصة أو قراءة الرسم.
لا توجد علامة تبويب Data أو كتالوج التصميم أو لوحة الذكاء الاصطناعي أو مكتبة نماذج 3D أو المشاركة أو المشاريع. يحتوي شريط الأدوات على Text وImage وMarker وPopup وBackground وLayer وDesign وLegend؛ راجع النطاق.
محرّر واحد لكل صفحة.
لا يمكن تغيير الخريطة الأساسية أو المظهر بعد التثبيت.

الخطوات التالية

مرجع المحرّر: جميع الخيارات ومفاتيح المظهر.
تكامل أطر العمل: التثبيت والإزالة من React وNext.js وVue.
Content Security Policy: توجيهات أمان المحرّر.
تضمين خريطة منشورة: عند الحاجة إلى خرائط دائمة.

قبل البدء​

الخطوة 1: إضافة حاوية بأبعاد محددة وتثبيت المحرّر​

الخطوة 2: اختيار الخريطة الأساسية والكاميرا الأولية​

الخطوة 3: تخصيص مظهر اللوحات (اختياري)​

الخطوة 4: تحريك الكاميرا من صفحتك (اختياري)​

الخطوة 5: إزالة المحرّر​

صفحة كاملة​

طريقة العمل​

إبلاغ المستخدمين​

التحقق من نجاح الإعداد​

استكشاف الأخطاء وإصلاحها​

القيود​

الخطوات التالية​