يبدو GeoJSON بسيطًا: هو JSON فيه إحداثيات. ثم يرفض ملفٌ أن يُفتح في مكان ما، فتكتشف كم من القواعد الصغيرة تختبئ خلف هذه البساطة. حلقة مضلّع (ring) غير مغلقة. خط العرض وخط الطول بترتيب معكوس. حلقة ملفوفة في الاتجاه الخاطئ. عنصر crs لم تعد المواصفة الحالية تسمح به.
لأتعلّم هذه القواعد كما يجب، بنيت الأداة التي أريدها عندما يتصرف ملف بشكل غريب. geojson-editor عارض ومحرّر ومدقّق (validator) صغير لـ GeoJSON يعمل في المتصفح، مبني بـ MapLibre GL JS و terra-draw. كل شيء يعمل داخل المتصفح، ولا يُرفع أي شيء إلى أي خادم.
هذا مشروع تعليمي. والجزء المهم فيه ليس الخريطة، بل المنطق الصرف تحتها، والقرارات حول من يملك البيانات.
ماذا يقدّم
التحميل من أي مصدر. اختر ملفًا، أو اسحبه وأفلته على الخريطة، أو أعطِه رابطًا (URL، بشرط أن يسمح الخادم بـ CORS)، أو الصق النص مباشرة. إذا كان المحتوى Geometry مجردة أو Feature واحدة، تُغلَّف داخل FeatureCollection، فتعمل دائمًا على الشكل نفسه من المستند.
الرسم والتعديل. يمكنك رسم نقاط وخطوط ومضلعات ومستطيلات. ويمكنك سحب الرؤوس (vertices)، وإدراج نقاط وسطية، وتحريك عنصر كامل، والحذف بمفتاح Delete.
لوحة الخصائص (properties). أضِف المفاتيح وأعِد تسميتها وعدّلها واحذفها. نوع القيمة يُستنتج مما تكتبه: 42 يصبح عددًا، و true قيمة منطقية، و "42" نصًّا، و [1,2] مصفوفة. ترتيب المفاتيح محفوظ، فلا يعود الملف المُصدَّر مبعثرًا.
التدقيق وفق RFC 7946. الأخطاء تشمل إغلاق الحلقة، وطول الحلقة، وشكل الموضع (position)، وانعكاس lat/lon، والعناصر الخاطئة في الـ Feature. والتحذيرات تشمل اتجاه اللف (winding order)، ووجود crs، والمواضع بأكثر من ثلاثة أبعاد، وحالات GeometryCollection الغريبة. النقر على مشكلة يحدّد العنصر المعني، وزر "Fix winding" يطبّق قاعدة اليد اليمنى بنقرة واحدة.
التصدير. نزّل النتيجة أو انسخها، مع خيار تقريب الإحداثيات (precision) وخيار الإخراج المضغوط (compact).
الحفظ التلقائي. المستند الحالي يُحفظ في localStorage. وإذا كان التخزين محظورًا، يبقى المحرّر يعمل.
طريقة الاستعمال
لا شيء يحتاج تثبيتًا. النسخة التجريبية موقع ثابت على GitHub Pages، وملفاتك تبقى في المتصفح: https://abdeldjalilchougui.github.io/geojson-editor/
لتشغيله محليًّا أو استضافة نسختك الخاصة:
git clone https://github.com/AbdeldjalilChougui/geojson-editor.git cd geojson-editor pnpm install pnpm dev # http://localhost:5173/geojson-editor/, then Paste or Open file (try public/sample.geojson) pnpm test # vitest, pure logic only pnpm build # type-check + production build into dist/ بناء الإنتاج يستعمل مسار Vite الأساسي /geojson-editor/ (انظر vite.config.ts). غيّره إذا كنت تقدّم الموقع من مسار آخر.
طريقة سريعة لتجربة المدقّق: الصق مضلعًا حلقته غير مغلقة، أو مضلعًا كُتب فيه خط العرض أولًا. تظهر المشكلة في القائمة، والنقر عليها يحدّد العنصر على الخريطة.
ما بنيته من الصفر
الكود مقسوم إلى قسمين عن قصد. كل ما في src/lib/ منطق صرف، لا يلمس الـ DOM، ومغطّى باختبارات الوحدة (unit tests). أما src/main.ts فهو مجرد ربط: خريطة MapLibre، وأوضاع terra-draw، واللوحات.
src/lib/ pure, DOM-free, unit tested parse.ts text -> JSON -> FeatureCollection (friendly errors, never throws) validate.ts structural RFC 7946 validator, issues with JSONPath-like paths properties.ts value inference + immutable add/rename/set/delete winding.ts signed area, orientation, rewind (exterior CCW, holes CW) bbox.ts bounding boxes for fit-to-data export.ts precision rounding (coordinates only) + serialisation storage.ts injected key/value store with every access guarded model.ts document items with stable uids, which geometries are editable src/main.ts glue: MapLibre map, terra-draw modes, panels بعض هذه الملفات يحمل الدروس الحقيقية:
-
parse.tsلا يرمي استثناءً أبدًا. النص الخاطئ يعطي رسالة خطأ واضحة بدل استثناء يوقف الصفحة. -
validate.tsيُرفق بكل مشكلة مسارًا شبيهًا بـ JSONPath، وهذا ما يجعل "انقر على المشكلة لتحديد العنصر" ممكنًا. -
winding.tsيحسب المساحة الموقَّعة (signed area) للحلقة ليعرف اتجاهها، ثم يعيد لفّها لتكون الحلقات الخارجية عكس عقارب الساعة والثقوب مع عقارب الساعة. -
export.tsيقرّب الإحداثيات فقط. قيم الخصائص لا يمسّها إعداد الدقة أبدًا. -
storage.tsيستقبل مخزن مفتاح/قيمة يُحقن من الخارج ويحمي كل وصول إليه، ولهذا لا يتعطل المحرّر عندما يكونlocalStorageمحظورًا.
ما تعلّمته
احتفظ بمستندك الخاص كمصدر للحقيقة. كان هذا قرار التصميم الأساسي. المحرّر يحتفظ بقائمة عناصر من الشكل {uid, feature}. العناصر التي يستطيع terra-draw تعديلها (Point و LineString و Polygon بحلقة واحدة) تُنسخ إلى terra-draw بنفس الـ uid. وخصائص المستخدم تبقى في المستند، فلا تصل الخاصية mode المحجوزة لـ terra-draw إلى الملف المُصدَّر أبدًا.
لو كانت مكتبة الرسم هي التي تملك البيانات، لتسرّبت حقولها الداخلية إلى المخرجات، ولضاع كل ما لا تستطيع تمثيله. عندما يكون المستند عندي، تصبح مكتبة الرسم مجرد عرض مع مقابض للتحريك.
ليست كل الأشكال قابلة للتعديل، ولا بأس بذلك. الأشكال التي لا يستطيع terra-draw تعديلها (أنواع Multi*، و GeometryCollection، والمضلعات ذات الثقوب، وكل ما يرفضه تدقيقه الداخلي) تُرسم للقراءة فقط بطبقة MapLibre عادية. تبقى في المستند، فيمكن تعديل خصائصها، وتُصدَّر كما هي دون تغيير. أسوأ ما يمكن أن يحدث في أداة كهذه هو أن يضيع عنصر بصمت لأن المحرّر لم يستطع التعامل معه.
RFC 7946 أكثر صرامة من أغلب الملفات. كتابة المدقّق تعني قراءة المواصفة سطرًا سطرًا. ومن هنا جاء الفصل بين الأخطاء والتحذيرات: حلقة غير مغلقة خطأ، أما حلقة خارجية مع عقارب الساعة فأمر تطلب المواصفة تجنّبه لكنها توصي القارئ بتقبّله. وانعكاس lat/lon من الأخطاء التي يسهل الوقوع فيها ويستطيع المدقّق أن يلتقطها عنك.
المنطق الصرف هو الجزء الذي يستحق الاختبار. الأمر pnpm test يشغّل vitest على وحدات src/lib/ فقط. ولأن أيًّا منها لا يلمس الـ DOM، لا تحتاج الاختبارات إلى متصفح. ويبقى كود الربط مع الخريطة رقيقًا، فلا يكاد يوجد فيه ما يمكن أن يخطئ.
أشياء يجب معرفتها
- الأشكال المتعددة (Multi)، و GeometryCollection، والمضلعات ذات الثقوب للقراءة فقط على الخريطة.
- لا يوجد تراجع/إعادة (undo/redo) بعد.
- التدقيق بنيوي فقط. لا يكتشف التقاطعات الذاتية ولا الثقوب الواقعة خارج الحلقة الخارجية.
- بلاطات الخريطة الأساسية تأتي من tile.openstreetmap.org، وهذا مقبول للاستعمال الشخصي الخفيف حسب سياسة استعمال بلاطات OSM. غيّر الـ style في
src/main.tsلأي استعمال أثقل. - حزمة الإنتاج نحو 1.2 MB (MapLibre مع terra-draw) وليست مقسّمة (code-split).
- التحميل من رابط لا يعمل إلا إذا سمح الخادم البعيد بـ CORS.
- ملف العيّنة يحتوي أشكالًا تقريبية مرسومة يدويًّا، وليست بيانات حقيقية.
لماذا بنيته
مشاكل GeoJSON في العادة صغيرة ومزعجة: حلقة واحدة غير مغلقة أو زوج إحداثيات معكوس في ملف فيه مئات العناصر. ولرؤية المشكلة تحتاج ثلاثة أشياء معًا: الشكل على الخريطة، والخصائص، وقائمة بما يخالف المواصفة. وعندما يكون الملف غير قابل للمشاركة، تريد أداة تُبقيه داخل المتصفح.
بناء هذه الأداة كان أيضًا طريقًا مباشرًا لتعلّم RFC 7946 والتدرّب على فصل نظيف بين المنطق الصرف وكود الواجهة. هذا هو الدافع كله: محرّر صغير يشرح لماذا الملف خاطئ، مكتوب بطريقة أستطيع اختبارها.
احصل على الكود
الكود المصدري والاختبارات وملف العيّنة على GitHub: https://github.com/AbdeldjalilChougui/geojson-editor. الكود برخصة MIT. بيانات الخريطة © مساهمو OpenStreetMap (ODbL). الملاحظات (issues) وطلبات الدمج (pull requests) مرحّب بها.
نُشر في الأصل على abdeldjalilchougui.biz.

