آموزش جامع ساخت پلاگین اندروید در فلاتر

با اینکه فلاتر مجموعه‌ی گسترده‌ای از کتابخانه‌ها و پکیج‌ها را در اختیار توسعه‌دهندگان قرار می‌دهد، گاهی نیاز داریم با قابلیت‌های خاص سیستم‌عامل مانند دوربین، حسگرها، بلوتوث، NFC، یا سرویس‌های پرداخت اندروید ارتباط برقرار کنیم ،قابلیت‌هایی که در Dart به‌صورت مستقیم در دسترس نیستند.

در چنین شرایطی، پلاگین (Plugin) وارد عمل می‌شود. پلاگین‌ها پل ارتباطی بین دنیای Dart و کدهای بومی (Native) مانند Java، Kotlin، Swift یا Objective-C هستند.

🔹 پلاگین چیست؟

در فلاتر، پلاگین (Plugin) بسته‌ای است که شامل کد Dart و کد بومی (Native) برای تعامل مستقیم با سیستم‌عامل میزبان (اندروید یا iOS) می‌باشد.

پلاگین‌ها دو بخش اصلی دارند:

1. کد Dart: رابط بین برنامه‌ی فلاتر و بخش بومی.
2. کد Native: پیاده‌سازی عملکرد واقعی در اندروید یا iOS.

به عنوان مثال، اگر بخواهیم سطح باتری دستگاه را بخوانیم:

• در Dart متدی به نام getBatteryLevel() تعریف می‌کنیم.
• در اندروید با Kotlin/Java مقدار واقعی باتری را از BatteryManager می‌خوانیم.
• سپس مقدار از اندروید به Dart ارسال می‌شود.

🔹 ضرورت استفاده از پلاگین

دلایل مهم برای ساخت یا استفاده از پلاگین‌ها عبارتند از:

1. دسترسی به قابلیت‌های بومی (Native Features)
   مثل GPS، دوربین، BLE، NFC، تماس تلفنی، یا پرداخت درون‌برنامه‌ای.
2. افزایش کارایی و عملکرد (Performance)
   اجرای برخی عملیات مستقیماً در کد بومی بسیار سریع‌تر از Dart است.
3. قابلیت استفاده مجدد (Reusability)
   می‌توان پلاگین را در پروژه‌های متعدد استفاده کرد یا در pub.dev منتشر کرد.
4. جداسازی منطق پلتفرمی از منطق اپلیکیشن
   کد بومی در پلاگین متمرکز می‌شود و کد اصلی فلاتر تمیز باقی می‌ماند.

🔹 فایل AAR چیست؟

فایل AAR (Android Archive) یک بسته‌ باینری مخصوص اندروید است که شامل:

• کدهای کامپایل‌شده Java/Kotlin،
• فایل‌های manifest،
• منابع (resources)،
• و سایر وابستگی‌های لازم برای اجرای یک کتابخانه‌ی اندروید می‌باشد.

در واقع aar. مشابه jar. است با این تفاوت که منابع گرافیکی، layout و manifest را نیز شامل می‌شود.
وقتی پلاگین اندرویدی خود را می‌سازیم، Gradle معمولاً خروجی را به‌صورت فایل .aar تولید می‌کند تا در سایر پروژه‌ها (مثلاً Flutter) استفاده شود.

🔹 مراحل ساخت پلاگین اندروید در فلاتر

در این بخش، با یک مثال عملی، پلاگینی می‌سازیم که مقدار باتری دستگاه را از اندروید گرفته و در فلاتر نمایش دهد.

🧩 مرحله ۱: ایجاد پروژه پلاگین

در ترمینال وارد مسیر دلخواه شوید و دستور زیر را اجرا کنید:

flutter create --org com.example --template=plugin --platforms=android flutter_battery_plugin

این دستور ساختار زیر را ایجاد می‌کند:

flutter_battery_plugin/
 ┣ android/
 ┣ lib/
 ┣ example/
 ┗ pubspec.yaml

🧩 مرحله ۲: ویرایش فایل android/src/main/kotlin/.../FlutterBatteryPlugin.kt

کد زیر را بنویسید:

package com.example.flutter_battery_plugin

import android.content.Context
import android.os.BatteryManager
import androidx.annotation.NonNull
import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel

class FlutterBatteryPlugin : FlutterPlugin, MethodChannel.MethodCallHandler {

    private lateinit var channel: MethodChannel
    private lateinit var context: Context

    override fun onAttachedToEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {
        context = binding.applicationContext
        channel = MethodChannel(binding.binaryMessenger, "flutter_battery_plugin")
        channel.setMethodCallHandler(this)
    }

    override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {
        if (call.method == "getBatteryLevel") {
            val batteryManager = context.getSystemService(Context.BATTERY_SERVICE) as BatteryManager
            val level = batteryManager.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
            result.success(level)
        } else {
            result.notImplemented()
        }
    }

    override fun onDetachedFromEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {
        channel.setMethodCallHandler(null)
    }
}

🧩 مرحله ۳: ارتباط با Dart

در فایل lib/flutter_battery_plugin.dart بنویسید:

import 'package:flutter/services.dart';

class FlutterBatteryPlugin {
  static const MethodChannel _channel = MethodChannel('flutter_battery_plugin');

  static Future<int> getBatteryLevel() async {
    final int level = await _channel.invokeMethod('getBatteryLevel');
    return level;
  }
}

🧩 مرحله ۴: تست در پروژه‌ی مثال

در پوشه‌ی example/lib/main.dart:

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

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Battery Plugin Example')),
        body: Center(
          child: FutureBuilder<int>(
            future: FlutterBatteryPlugin.getBatteryLevel(),
            builder: (context, snapshot) {
              if (snapshot.connectionState == ConnectionState.waiting) {
                return const CircularProgressIndicator();
              }
              return Text('Battery Level: ${snapshot.data}%', style: const TextStyle(fontSize: 20));
            },
          ),
        ),
      ),
    );
  }
}

🧩 مرحله ۵: بیلد گرفتن AAR (اختیاری)

اگر می‌خواهید فقط خروجی اندروید را به‌صورت کتابخانه جداگانه بسازید:

cd flutter_battery_plugin/android
./gradlew assembleRelease

فایل .aar در مسیر:

flutter_battery_plugin/android/build/outputs/aar/

تولید خواهد شد و می‌توانید در پروژه‌های دیگر استفاده کنید.

🔹 نتیجه‌گیری

پلاگین‌ها قلب تپنده‌ی فلاتر برای اتصال به دنیای بومی هستند.
با آن‌ها می‌توانیم محدودیت‌های Dart را کنار بزنیم و از تمام قابلیت‌های اندروید یا iOS بهره‌مند شویم.

در این مقاله یاد گرفتیم:

• پلاگین چیست و چرا استفاده می‌شود.
• فایل .aar چه نقشی دارد.
• و چگونه یک پلاگین واقعی اندروید را گام‌به‌گام بسازیم.

با همین روش می‌توانید پلاگین‌های حرفه‌ای‌تری مانند پرداخت بانکی، BLE، یا تشخیص صدا را نیز پیاده‌سازی کنید و آن‌ها را در Pub.dev منتشر نمایید.