full_svg_flutter 1.5: أداة فحص في DevTools لملفات SVG أثناء التشغيل

شهد full_svg_flutter خمسة إصدارات منذ 1.4.2: إصلاحان للمنصات، وأداة جديدة للمطورين، ومراجعة واسعة لصحة الحسابات الهندسية، وإصدار يجعل ملفات SVG المعتمدة على JavaScript تعمل على iOS. إليك ما تغيّر ولماذا يهمّ.

أداة الفحص FullSVG في DevTools (1.5.0)

عندما يبدو ملف SVG متحرك صحيحاً في المتصفح وخاطئاً في التطبيق، تحتاج إلى أن ترى ما فعله الـ renderer حقاً. بدءاً من الإصدار 1.5.0، يأتي full_svg_flutter مع إضافة رسمية لـ Flutter DevTools. تتصل الإضافة بتطبيق يعمل في وضع debug وتفحص الـ renderers الحقيقية: المستند والخط الزمني للحركة والـ painter، وهي نفسها التي ترسم شاشتك.

ما الذي تحصل عليه:

النسخ الحية. يظهر كل renderer مُركَّب في الشجرة على حدة، حتى لو رُكِّب الأصل نفسه مرتين، مع مصدره وحالة حركته وعدد عُقد DOM فيه.
شجرة SVG DOM بتحميل كسول. لا تُحمَّل العُقد الفرعية إلا عند توسيع الصف، فتبقى المستندات الكبيرة سريعة الاستجابة. وعند اختيار عقدة يظهر وسمها والـ id والـ classes، وقيم سماتها الخام والنهائية، والسمات المتحركة في هذه اللحظة، وحركات SMIL و CSS التي تستهدفها.
التحكم في التشغيل. تشغيل وإيقاف مؤقت وإعادة تشغيل و seek، وسرعات من 0.25× إلى 2×. وتتحكم هذه الأدوات في الساعة الحتمية الخاصة بالـ renderer نفسه بدلاً من إنشاء خط زمني ثانٍ.
تمييز العُقد. تُحاط العقدة المختارة بإطار داخل التطبيق قيد التشغيل وفق هندستها الفعلية في العرض، من دون المساس بسمات ملف SVG.
إحصاءات صادقة. عُقد DOM، وعدد الحركات، والحركات النشطة، و filter primitives، والأقنعة، والتدرجات اللونية، ومسارات القص، ووجود JavaScript، والوقت الحالي، والمدة. ولا تختلق أداة الفحص توقيتات تحليل أو رسم لا يقيسها الـ renderer.

لفتحها:

شغّل تطبيقك في وضع debug.
افتح Flutter DevTools من بيئة التطوير لديك أو من مخرجات flutter run.
فعّل إضافات DevTools عندما يُطلب منك ذلك.
اختر إضافة full_svg_flutter. ستظهر أداة الفحص باسم FullSVG.

لا شيء يحتاج إلى إعداد. الجسر يعمل في وضع debug فقط: في بناء الـ release لا تُسجَّل الـ renderers، ولا تُحفَظ أشجار DOM، ولا تُجمَع بيانات لأداة الفحص. ويعتمد تتبّع النسخ على المراجع الضعيفة ويتبع دورة حياة الـ widget، وتعيد الإضافة الاتصال بعد hot restart.

ثمة حدود تستحق أن تعرفها. يجب أن يكون الـ isolate الرئيسي قيد التشغيل، لا معلّقاً عند نقطة توقف. وتُبلغ الأداة عن وجود JavaScript، لكنها عمداً لا تتيح تقييم كود JavaScript عشوائي. أما قيم CSS المحسوبة، ومصدر القيم في الـ cascade، واختيار نسخ <use> منفردة، وتوقيتات الإطارات، فمتروكة لعمل مستقبلي.

الدليل الكامل موجود في وثائق أداة الفحص (يُفتح في علامة تبويب جديدة).

هندسة تتصرف كما في المتصفح (1.5.1)

الإصدار 1.5.1 يركّز على صحة العرض، وقد بُني في معظمه على pull requests من المجتمع.

النسب المئوية تُحسب على أساس منفذ العرض الصحيح. الأشكال الأساسية، وهندسة <use> ومنافذ عرض نسخه، و <svg> المتداخل، وإحداثيات النصوص، ومناطق الأقنعة، و hit testing، كلها تستخدم منفذ العرض الصحيح، بما في ذلك عنصر SVG الجذري الذي لا يحدد حجمه بنفسه، فيكون منفذ عرضه هو الـ widget.
الحركات تحتفظ بوحداتها. حركات SMIL بين قيم مئوية وقيم مطلقة تحتفظ بكلتا الوحدتين خلال الاستيفاء، والتركيب التراكمي، وتوقيت calcMode="paced".
objectBoundingBox يستخدم الصندوق الصحيح. تعتمد clipPathUnits و maskUnits و maskContentUnits على حدود الكائن من دون تأثيرات الرسم، فلم يعد الـ stroke يضخّم الصندوق، وصارت العناصر النصية المستهدفة تُسهم بحدود تخطيطها بدلاً من أن تُقصّ وتختفي.
صار لتحريك مناطق الفلاتر والأقنعة أثر فعلي. النسب المئوية المتحركة في مناطق <filter> و <mask> تُقرأ من جديد أثناء الحركة بدلاً من تحليلها مرة واحدة من المصدر.
توقيت لكل نسخة. الحركات ذات التوقيت paced داخل محتوى <symbol> المشترك تُحسب لمنفذ عرض كل نسخة <use> على حدة.

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

بناء أصلي على كل المنصات (1.4.3، 1.4.4، 1.5.2)

يشغّل full_svg_flutter الـ scripts المضمّنة وتصديرات SVGator عبر quickjs_engine، حزمتي التي تجلب QuickJS-NG إلى Flutter. وكانت ثلاثة إصدارات مخصّصة لجعل هذه الطبقة الأصلية مملّة، بالمعنى الجيد للكلمة:

1.4.3، Windows. كان البناء النظيف على Windows يفشل لأن ملف تسجيل الـ plugins الذي يولّده Flutter كان يستدعي رمزاً غير موجود. أُصلح ذلك عبر quickjs_engine 0.1.4.
1.4.4، macOS universal. صارت تطبيقات macOS من نوع universal تتضمّن جسر QuickJS بشريحتي Apple Silicon و Intel معاً.
1.5.2، iOS و Swift Package Manager و Android Gradle Plugin 9. صارت ملفات SVG المعتمدة على JavaScript تُهيَّأ على iOS مع CocoaPods. فالإصدارات السابقة من الـ pod لم تكن تصدّر أياً من دوال الجسر، لذا كان كل ملف SVG يحتوي على <script> يفشل بالخطأ «Failed to lookup symbol 'jsNewRuntime'‎». كما لم يعد Flutter يلجأ إلى CocoaPods بسبب quickjs_engine، وصارت تطبيقات Android على AGP 9 تُبنى مع Kotlin المدمج.

تفاصيل الطبقة الأصلية في منشور منفصل: quickjs_engine 0.1.6.

الترقية

dependencies:
  full_svg_flutter: ^1.5.2

أو شغّل flutter pub upgrade full_svg_flutter. تتطلب الحزمة Flutter 3.32 أو أحدث، ولا يذكر سجل التغييرات أي تغييرات في API تكسر التوافق بين 1.4.2 و 1.5.2.

شكراً لكم

أربعة من هذه الإصدارات الخمسة تضم مساهمات من المجتمع: بلاغات عن أخطاء، وأمثلة تعيد إنتاجها، و pull requests. شكراً لكلٍّ من ‎@oierxjn (يُفتح في علامة تبويب جديدة) و ‎@remtrik (يُفتح في علامة تبويب جديدة) و ‎@dariyooo (يُفتح في علامة تبويب جديدة) و ‎@OrPudding (يُفتح في علامة تبويب جديدة) و ‎@sufiyansayyed (يُفتح في علامة تبويب جديدة) و ‎@DomingoMG (يُفتح في علامة تبويب جديدة).

إذا اختلف عرض ملف SVG عمّا تراه في المتصفح، فافتح أداة الفحص، وتحقّق من القيم النهائية للسمات، ثم أرسل إليّ الملف (يُفتح في علامة تبويب جديدة). ما زالت هذه أسرع طريقة لتحسين الـ renderer.

سجل التغييرات الكامل: pub.dev/packages/full_svg_flutter/changelog (يُفتح في علامة تبويب جديدة)