F
فلِت.عربي

توثيق فلِت

دليل شامل لبناء تطبيقات بواجهات Flutter باستخدام لغة Python من خلال إطار عمل فلِت. تعلم كيفية إنشاء تطبيقات جذابة ومتعددة المنصات بسهولة.

البدء السريع

يعتبر فلِت (Flet) إطار عمل مفتوح المصدر يتيح لك بناء واجهات مستخدم تفاعلية باستخدام Flutter من خلال لغة Python. حتى إذا لم تكن على دراية بـ Flutter أو Dart، يمكنك بناء تطبيقات رائعة عبر الاستفادة من معرفتك بـ Python.

لماذا فلت؟

  • بناء واجهات مستخدم جميلة بلغة Python فقط
  • دعم متعدد المنصات (سطح المكتب، الويب، الموبايل)
  • تجربة تطوير تفاعلية مع تحديث مباشر للواجهة
  • استخدام مكونات Flutter الغنية دون الحاجة لتعلم Dart

لنبدأ مع تطبيق "مرحباً بالعالم" بسيط لنفهم كيفية عمل فلت:

hello_world.py 
import flet as ft

def main(page: ft.Page):
    # تعيين عنوان الصفحة ودعم RTL
    page.title = "مرحباً بالعالم"
    page.rtl = True
    
    # إضافة نص للصفحة
    page.add(
        ft.Text(
            value="مرحباً بالعالم من فلت!",
            size=30,
            color="blue",
            weight="bold",
            text_align=ft.TextAlign.CENTER,
        )
    )

# تشغيل التطبيق
ft.app(target=main)

شرح الكود

  • السطر 1: استيراد مكتبة فلت واختصارها باسم ft
  • السطر 3: تعريف دالة main التي تستقبل كائن الصفحة
  • السطر 5-6: تعيين عنوان الصفحة وتفعيل دعم RTL للعربية
  • السطر 9-15: إضافة عنصر نصي للصفحة مع تخصيص مظهره
  • السطر 18: تشغيل التطبيق وتمرير دالة main كنقطة البداية
مرحباً بالعالم

مرحباً بالعالم من فلت!

هذا مثال بسيط لكنه يوضح الهيكل الأساسي لتطبيق فلت. في الأقسام التالية سنتعمق أكثر في كيفية بناء واجهات أكثر تعقيداً وتفاعلية.

تثبيت فلت

قبل البدء في استخدام فلت، تحتاج إلى تثبيت حزمة فلت من خلال مدير الحزم pip. تأكد من أن لديك Python بإصدار 3.7 أو أحدث.

Terminal 
pip install flet

متطلبات النظام

التطوير على سطح المكتب

  • Python 3.7 أو أحدث
  • Windows 10 أو أحدث
  • macOS 10.14 أو أحدث
  • Linux (Ubuntu 18.04، Fedora 33 أو أحدث)

تطوير تطبيقات الويب

  • Python 3.7 أو أحدث
  • متصفح حديث: Chrome، Firefox، Safari، Edge
  • يدعم WebAssembly

تثبيت إضافي لـ macOS/Linux 

pip3 install flet

تحديث فلت 

pip install flet --upgrade

ملاحظة للمستخدمين الجدد

بعد تثبيت فلت، ننصح بمتابعة دليل البدء السريع وتجربة الأمثلة البسيطة لفهم كيفية عمل فلت قبل الشروع في بناء تطبيق معقد.

المفاهيم الأساسية

يتبع فلت نموذج برمجة بسيط وسهل الفهم. دعنا نستعرض المفاهيم الأساسية التي ستحتاجها لبناء تطبيقات فلت.

Page (الصفحة)

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

الخصائص الأساسية للصفحة:

  • title - عنوان النافذة أو صفحة الويب
  • rtl - لتحديد اتجاه النص من اليمين لليسار
  • window_width و window_height - لتحديد أبعاد النافذة
  • padding - للتحكم في المساحة الداخلية للصفحة
  • theme - لتعيين سمة التطبيق (ألوان، خطوط، الخ)

Controls (عناصر التحكم)

عناصر التحكم هي المكونات الأساسية لواجهة المستخدم مثل النصوص والأزرار وحقول الإدخال. يمكنك إضافتها إلى الصفحة باستخدام page.add() أو إضافتها إلى حاويات أخرى.

controls_example.py 
import flet as ft

def main(page: ft.Page):
    # إضافة عناصر تحكم متنوعة
    page.add(
        ft.Text("هذا نص بسيط"),
        ft.ElevatedButton("زر"),
        ft.TextField(label="حقل إدخال")
    )

ft.app(target=main)

حدث التحديث (Update)

عندما تقوم بتغيير خصائص عناصر التحكم، تحتاج إلى استدعاء page.update() لتعكس هذه التغييرات على واجهة المستخدم. هذا ما يسمح لك بإنشاء تطبيقات تفاعلية.

counter_example.py 
import flet as ft

def main(page: ft.Page):
    # إنشاء متغيرات العناصر
    text_counter = ft.Text("0", size=30)
    
    def increment(e):
        # تحديث قيمة النص واستدعاء page.update()
        text_counter.value = str(int(text_counter.value) + 1)
        page.update()
    
    # إضافة العناصر
    page.add(
        text_counter,
        ft.ElevatedButton("زيادة العداد", on_click=increment)
    )

ft.app(target=main)

الأحداث (Events)

تستجيب عناصر التحكم لتفاعلات المستخدم من خلال الأحداث. يمكنك تعيين دوال معالجة الأحداث لتنفيذ إجراءات عندما يتفاعل المستخدم مع العناصر.

بعض الأحداث الشائعة:

  • on_click - يحدث عند النقر على العنصر
  • on_change - يحدث عند تغيير قيمة العنصر
  • on_hover - يحدث عند تمرير المؤشر فوق العنصر
  • on_focus - يحدث عند التركيز على العنصر
  • on_blur - يحدث عند فقدان التركيز

نصيحة: تتلقى دوال معالجة الأحداث معامل (e) يحتوي على معلومات حول الحدث مثل العنصر الذي تسبب في الحدث وأي بيانات أخرى مرتبطة به.

عناصر واجهة المستخدم

يوفر فلت مجموعة غنية من عناصر واجهة المستخدم (Controls) التي يمكنك استخدامها لبناء تطبيقات جذابة وتفاعلية. فيما يلي استعراض لأهم العناصر المتاحة.

العنصر الوصف مثال
Text يستخدم لعرض النصوص بأحجام وألوان وأنماط مختلفة ft.Text("نص")
TextField حقل إدخال للنصوص والبيانات ft.TextField(label="الاسم")
ElevatedButton زر بتأثير ثلاثي الأبعاد ft.ElevatedButton("انقر هنا")
Checkbox مربع اختيار ft.Checkbox(label="موافق")
Image لعرض الصور من مصادر مختلفة ft.Image(src="logo.png")

عناصر النصوص

نبدأ بأكثر العناصر استخداماً: عنصر Text الذي يتيح عرض النصوص بأشكال مختلفة.

text_examples.py 
import flet as ft

def main(page: ft.Page):
    page.add(
        ft.Text(
            value="نص عادي",
        ),
        ft.Text(
            value="نص كبير ملون",
            size=30,
            color="blue",
            weight="bold",
        ),
        ft.Text(
            value="نص بخط مائل",
            italic=True,
        ),
        ft.Text(
            value="نص يحتوي على خط تحته",
            selectable=True,
            no_wrap=True,
            weight=ft.FontWeight.W_700,
            decoration=ft.TextDecoration.UNDERLINE,
        ),
    )

ft.app(target=main)

خصائص إضافية للنص:

  • text_align - محاذاة النص
  • font_family - نوع الخط
  • max_lines - الحد الأقصى لعدد الأسطر
  • overflow - كيفية التعامل مع النص الزائد
  • selectable - إمكانية تحديد النص
  • style - أسلوب النص من نماذج جاهزة

الأزرار

الأزرار هي عناصر تفاعلية أساسية في أي تطبيق، تتيح للمستخدم تنفيذ إجراءات. فلت يوفر عدة أنواع من الأزرار:

button_examples.py 
import flet as ft

def main(page: ft.Page):
    def button_clicked(e):
        page.add(ft.Text(f"تم النقر على: {e.control.data}"))
    
    page.add(
        ft.ElevatedButton(
            text="زر بارز",
            icon=ft.icons.PLAY_ARROW,
            on_click=button_clicked,
            data="زر بارز",
        ),
        
        ft.TextButton(
            text="زر نصي",
            icon=ft.icons.INFO,
            on_click=button_clicked,
            data="زر نصي",
        ),
        
        ft.OutlinedButton(
            text="زر مخطط",
            icon=ft.icons.SETTINGS,
            on_click=button_clicked,
            data="زر مخطط",
        ),
        
        ft.FilledButton(
            text="زر ممتلئ",
            icon=ft.icons.DONE,
            on_click=button_clicked,
            data="زر ممتلئ",
        ),
        
        ft.IconButton(
            icon=ft.icons.FAVORITE,
            on_click=button_clicked,
            data="زر أيقونة",
            icon_color="pink",
        ),
    )

ft.app(target=main)

خصائص مشتركة للأزرار:

  • on_click - دالة معالجة النقر
  • text - النص المعروض على الزر
  • icon - الأيقونة المستخدمة في الزر
  • disabled - لتعطيل الزر
  • style - تخصيص مظهر الزر بشكل أكبر
  • data - بيانات مخصصة يمكن ربطها بالزر

حقول الإدخال

حقول الإدخال تسمح للمستخدمين بإدخال البيانات في التطبيق، وتتراوح من حقول النص البسيطة إلى عناصر أكثر تخصصاً.

input_examples.py 
import flet as ft

def main(page: ft.Page):
    def input_changed(e):
        output_text.value = f"مرحباً بك {text_name.value}!"
        page.update()
        
    text_name = ft.TextField(
        label="الاسم",
        hint_text="أدخل اسمك هنا",
        prefix_icon=ft.icons.PERSON,
        helper_text="الاسم مطلوب",
        on_change=input_changed,
    )
    
    password = ft.TextField(
        label="كلمة المرور",
        password=True,
        can_reveal_password=True,
    )
    
    output_text = ft.Text("")
    
    page.add(
        ft.Text("أمثلة على حقول الإدخال:", size=20),
        text_name,
        password,
        ft.Dropdown(
            label="اختر بلدك",
            options=[
                ft.dropdown.Option("مصر"),
                ft.dropdown.Option("السعودية"),
                ft.dropdown.Option("الإمارات"),
                ft.dropdown.Option("المغرب"),
            ],
        ),
        ft.Checkbox(label="الموافقة على الشروط"),
        ft.Switch(label="تفعيل الإشعارات"),
        ft.Slider(min=0, max=100, divisions=10, label="{value}%"),
        output_text,
    )

ft.app(target=main)

تخطيطات الصفحة

تخطيطات الصفحة هي العناصر المسؤولة عن تنظيم وترتيب عناصر واجهة المستخدم. فلت يوفر عدة تخطيطات تمكنك من بناء واجهات معقدة بسهولة.

الصفوف والأعمدة

Row و Column هما الحاويات الأساسية لترتيب العناصر أفقياً وعمودياً على التوالي.

مثال استخدام Row (صف):

ft.Row(
    controls=[
        ft.Text("العنصر 1"),
        ft.Text("العنصر 2"),
        ft.Text("العنصر 3"),
    ],
    alignment=ft.MainAxisAlignment.CENTER,
    spacing=20,
)
العنصر 1
العنصر 2
العنصر 3

مثال استخدام Column (عمود):

ft.Column(
    controls=[
        ft.Text("العنصر 1"),
        ft.Text("العنصر 2"),
        ft.Text("العنصر 3"),
    ],
    alignment=ft.MainAxisAlignment.CENTER,
    spacing=20,
)
العنصر 1
العنصر 2
العنصر 3

خصائص مشتركة للصفوف والأعمدة:

  • alignment - محاذاة العناصر على المحور الرئيسي
  • vertical_alignment - محاذاة العناصر على المحور العرضي
  • spacing - المسافة بين العناصر
  • tight - التفاف العناصر بشكل محكم
  • wrap - السماح بالتفاف العناصر عند الحاجة
  • scroll - تفعيل التمرير إذا تجاوزت العناصر الحجم المتاح

الحاويات (Container)

الحاوية Container هي عنصر متعدد الاستخدامات يمكن تخصيصه لتحقيق تأثيرات مرئية مختلفة. يمكن استخدامه لإضافة حشو، هوامش، خلفيات، وحدود للعناصر.

container_example.py 
import flet as ft

def main(page: ft.Page):
    page.add(
        ft.Container(
            content=ft.Text("نص داخل حاوية", size=20),
            width=200,
            height=100,
            padding=10,
            margin=10,
            alignment=ft.alignment.center,
            bgcolor=ft.colors.BLUE_100,
            border=ft.border.all(2, ft.colors.BLUE_500),
            border_radius=10,
        ),
        
        ft.Container(
            content=ft.Icon(name=ft.icons.FAVORITE, size=40, color=ft.colors.RED_400),
            width=100,
            height=100,
            bgcolor=ft.colors.RED_50,
            border_radius=50,  # قيمة كبيرة لجعله دائري
            alignment=ft.alignment.center,
            margin=20,
            ink=True,  # تأثير الانتشار عند النقر
            on_click=lambda e: print("تم النقر على الحاوية"),
        )
    )

ft.app(target=main)

خصائص الحاوية الأساسية:

  • content - المحتوى الذي سيتم وضعه داخل الحاوية
  • alignment - محاذاة المحتوى داخل الحاوية
  • padding - المساحة الداخلية للحاوية
  • margin - المساحة الخارجية للحاوية
  • bgcolor - لون خلفية الحاوية
  • border - حدود الحاوية
  • border_radius - انحناء زوايا الحاوية
  • gradient - تدرج لوني للخلفية
  • shadow - ظل للحاوية
  • on_click - تفاعل النقر على الحاوية

التصميم المتجاوب

يمكن استخدام فلت لبناء واجهات متجاوبة تعمل بشكل جيد على جميع أحجام الشاشات. باستخدام MediaQuery يمكنك الاستعلام عن حجم الشاشة وتكييف واجهتك وفقًا لذلك.

responsive_example.py 
import flet as ft

def main(page: ft.Page):
    # تعريف العناصر
    title = ft.Text("مثال على التصميم المتجاوب", size=20, weight="bold")
    description = ft.Text(
        "هذا المثال يوضح كيفية استخدام MediaQuery للتكيف مع حجم الشاشة",
        size=16,
    )
    
    # إنشاء حاويات العناصر
    items = []
    for i in range(1, 9):
        items.append(
            ft.Container(
                content=ft.Text(f"عنصر {i}", size=16),
                width=150,
                height=150,
                alignment=ft.alignment.center,
                bgcolor=ft.colors.BLUE_100,
                border=ft.border.all(1, ft.colors.BLUE_300),
                border_radius=10,
                margin=5,
            )
        )
    
    # حاوية العناصر المرنة
    items_grid = ft.Row(
        controls=items,
        wrap=True,
        alignment=ft.MainAxisAlignment.CENTER,
        spacing=0,
    )
    
    # دالة لتحديث التخطيط استناداً لحجم الشاشة
    def page_resize(e):
        # تغيير حجم العناصر حسب عرض الشاشة
        if page.width < 600:
            title.size = 16
            description.size = 14
            for item in items:
                item.width = (page.width - 20) / 2
                item.height = 100
        elif page.width < 1000:
            title.size = 18
            description.size = 16
            for item in items:
                item.width = (page.width - 40) / 3
                item.height = 120
        else:
            title.size = 20
            description.size = 16
            for item in items:
                item.width = (page.width - 80) / 4
                item.height = 150
        
        page.update()
    
    # تسجيل حدث تغيير حجم الصفحة
    page.on_resize = page_resize
    
    # إضافة العناصر للصفحة
    page.add(
        ft.Column([
            title,
            description,
            ft.Divider(),
            items_grid,
        ])
    )
    
    # تنفيذ الدالة مرة واحدة عند تحميل الصفحة
    page_resize(None)

ft.app(target=main)

نصائح للتصميم المتجاوب:

  • استخدم خاصية wrap=True مع Row للسماح بالتفاف العناصر عند تصغير النافذة.
  • تعامل مع حدث page.on_resize لإعادة تنظيم واجهتك عند تغيير حجم النافذة.
  • قم بتعديل خصائص النص والحاويات بناءً على حجم الشاشة.
  • استخدم قيم نسبية للعرض والارتفاع بدلاً من قيم ثابتة.
  • اختبر تطبيقك على أحجام مختلفة من الشاشات.

آخر تحديث: 21/04/2025

تحرير هذه الصفحة عرض على GitHub

هل وجدت هذا المحتوى مفيداً؟

ساعدنا في تحسين التوثيق من خلال تقديم ملاحظاتك