الوثائق

وثائق حزم runtime وُلدت من حالات حدّية حقيقية.

ثلاث حزم Flutter مركّزة: runtime كامل لـ SVG، ومسار خطوط WOFF/WOFF2، ومحرك JavaScript حديث واحد عبر المنصات الأصلية. ابدأ من المشكلة، ثم انسخ أصغر مثال يعمل.

01 · Flutter package

full_svg_flutter

أبقِ SVG صيغةَ المصدر داخل Flutter.

Version: 1.4.2
Pub points: 140 / 160
License: MIT

لماذا وُجدت

الأيقونات الثابتة ليست سوى جزء صغير من SVG. قد تعتمد أصول المنتج على SMIL أو حركة CSS أو path morphing أو الفلاتر أو النصوص أو مشغّل JavaScript مضمّن. تحويلها يضيف مصدر حقيقة ثانياً، واستخدام WebView يضيف نظام عرض ثانياً.

التثبيت

flutter pub add full_svg_flutter

بداية سريعة

import 'package:full_svg_flutter/full_svg_flutter.dart';

// Static or animated — the runtime detects the document.
FSvgPicture.asset(
  'assets/hero.svg',
  width: 240,
  semanticsLabel: 'Product illustration',
);

// Existing static flutter_svg usage can keep the familiar API.
SvgPicture.asset('assets/icon.svg');

التغطية

Static SVG and DOM-preserving rendering
SMIL and CSS @keyframes animation
Path morphing and motion paths
All 17 SVG filter primitives
Masks, clipping, gradients, patterns, and rich text
Inline JavaScript and SVGator exports
Playback control and SVG <view> navigation
flutter_svg-compatible static API

كيف تعمل

تحلّل الحزمة مستند SVG إلى نموذج خاص بها يحافظ على DOM، وتحسب الأنماط وحالة الحركة، ثم ترسم عبر Flutter. يتشارك المحتوى الثابت والمتحرك المحرك نفسه، ولا يبدأ JavaScript إلا عند وجود عنصر script.

استخدمها عندما

تستقبل ملفات SVG متحركة أو أصول SVGator ولا تستطيع تغيير صيغة المصدر.
تحتاج إلى دقة في الفلاتر أو الأقنعة أو النصوص أو الحركة تتجاوز عرض الأيقونات الثابتة.
تريد API مألوفة على غرار flutter_svg ومسار ترحيل من دون WebView.

خريطة API

FSvgPicture: الـ widget الرئيسي للأصول الثابتة أو المتحركة من asset أو network أو string أو file أو bytes.
SvgPicture: نقطة دخول ثابتة متوافقة مع flutter_svg.
AnimatedSvgController: التشغيل والإيقاف المؤقت و seek وتغيير السرعة أو الاتجاه والتبديل بين SVG views.
renderSvgToPicture: تسجيل SVG في Picture للرسم المخصص أو التحويل إلى صورة نقطية.
svg.cache: ذاكرة تخزين مؤقت قابلة للضبط للمصادر المفكوكة، مشتركة بين الـ widgets.

اعرف قبل الإصدار

هي runtime لـ SVG، لا نسخة كاملة من DOM المتصفح؛ foreignObject والأطر المعتمدة على المتصفح خارج النطاق.
تحقّق بصرياً من الأصول ذات الفلاتر المعقدة أو النصوص مختلطة الاتجاه قبل الإصدار.

02 · Flutter package

woff2

حمّل حاويات خطوط الويب عبر FontLoader في Flutter.

Version: 0.1.0
Pub points: 150 / 160
License: Apache-2.0

لماذا وُجدت

يقبل Flutter ملفات TTF/OTF عبر FontLoader، لكنه لا يفكّ ترميز WOFF أو WOFF2. وتمرير bytes خط الويب المضغوط مباشرةً قد ينتج مربعات بدل الحروف من دون رسالة خطأ مفيدة.

التثبيت

flutter pub add woff2

بداية سريعة

import 'package:flutter/material.dart';
import 'package:woff2/woff2.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await loadWoffFontFromAsset(
    fontFamily: 'Inter',
    assetPath: 'assets/fonts/Inter.woff2',
  );
  runApp(const MyApp());
}

التغطية

WOFF1 and WOFF2 to SFNT decoding
One-call Flutter FontLoader integration
Pure-Dart font pipeline for app code
CSS @font-face parsing
Batch registration for weights and styles
Embedded data: URL fonts
Low-level byte decoder
35 focused unit tests in the public package

كيف تعمل

يعيد الـ decoder بناء bytes بصيغة SFNT من WOFF1/WOFF2، ثم يسجّل النتيجة عبر FontLoader. ويغطي محلّل CSS وسجلّ الخطوط ملفات SVG و HTML و EPUB وغيرها من المحتوى الذي يحمل قواعد @font-face.

استخدمها عندما

يضمّن ملف SVG أو EPUB أو تصدير HTML أو أصل تصميمي خطوطاً بصيغة WOFF/WOFF2.
تحتاج إلى تحميل خط نُزّل وقت التشغيل أو خُزّن كـ asset عادي.
تبني renderer وتحتاج إلى تحويل bytes بصيغة WOFF إلى SFNT على مستوى منخفض.

خريطة API

loadWoffFontFromAsset: فكّ ترميز asset بصيغة WOFF/WOFF2 وتسجيله بنداء واحد.
loadWoffFontFromBytes: تسجيل bytes خط جُلبت من الشبكة أو القرص أو الذاكرة.
WoffFontRegistry: تسجيل دفعي للعائلات والأوزان والأنماط.
extractFontFaceRules: استخراج قواعد @font-face بما فيها data URLs والقيم المقتبسة.
decodeFontIfWoff: كشف نوع الحاوية وتحويلها إلى bytes بصيغة SFNT على مستوى منخفض.

اعرف قبل الإصدار

مجموعات WOFF2 TTC غير مدعومة في الإصدار 0.1.0.
Flutter Web يتعامل مع WOFF2 في المتصفح أصلاً؛ الحزمة تستهدف منصات Flutter الأصلية.

03 · Flutter package

quickjs_engine

شغّل محرك JavaScript الحديث نفسه على كل منصات Flutter.

Version: 0.1.3
Pub points: 120 / 160
License: MIT

لماذا وُجدت

قد يتصرف مزيج JavaScriptCore و QuickJS القديم بشكل مختلف من منصة إلى أخرى، خصوصاً في الحالات الحدّية العددية و Proxy والتكرار و promises ومكتبات تشغيل الحركة. هذا التباعد يصعب إعادة إنتاجه، والوثوق به أصعب.

التثبيت

flutter pub add quickjs_engine

بداية سريعة

import 'package:quickjs_engine/quickjs_engine.dart';

final js = getJavascriptRuntime(xhr: false);
final result = js.evaluate('2 + 2');
print(result.stringResult); // 4

js.onMessage('bridge', (dynamic value) => 'pong');
js.evaluate('sendMessage("bridge", "ping")');
js.dispose();

التغطية

QuickJS-NG 0.14.0 bundled with Flutter
One engine across Android, iOS, macOS, Linux, and Windows
Modern ES2020+ language features
Dart ↔ JavaScript message bridge
Optional fetch, XHR, and Promise helpers
flutter_js-compatible entry points
Native builds integrated with Flutter tooling
16 KB Android ELF page alignment

كيف تعمل

تضمّ الحزمة QuickJS-NG 0.14.0 وتمرّر كل منصة أصلية مدعومة عبر المحرك نفسه وجسر FFI نفسه. يتولى نظام البناء في Flutter تجميع المكتبة الأصلية أو تضمينها، بينما يملك Dart التقييم والرسائل والمساعدات الاختيارية على نمط الويب.

استخدمها عندما

يحتاج منتج Flutter إلى تقييم JavaScript مضمّن بسلوك متسق عبر المنصات.
تنتقل من flutter_js وتريد نقاط الدخول المألوفة نفسها على محرك حديث.
تحتاج إلى طبقة scripting صغيرة أو محرك تعبيرات أو مدقّق أو مشغّل SVG من دون WebView.

خريطة API

getJavascriptRuntime: إنشاء runtime لـ QuickJS بسلوك متسق عبر المنصات.
evaluate: تقييم JavaScript وفحص النتيجة.
onMessage: إتاحة دوال Dart مسمّاة لاستدعائها من JavaScript.
enableFetch: تفعيل سلوك fetch/XHR عندما يتطلبه العمل.
enableHandlePromises: إعادة اكتمال Promise إلى Dart.

اعرف قبل الإصدار

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

التواصل

هل تحتاج إلى بناء منتج رقمي أو تحديثه أو إزالة ما يعطّله؟

حدّثنا عن القيد الحقيقي: منتج ويب، أو Mobile، أو تسليم الفريق، أو مسار عمل بالذكاء الاصطناعي يجب أن يصبح جاهزاً للإنتاج.

ناقش مشروعاً