‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

راه‌اندازی پروژه Flutter

قبل‌از راه‌اندازی پروژه Flutter، مطمئن شوید که مراحل پیش‌نیاز را در بخش قبل‌از شروع تکمیل کرده‌اید. پس‌از فعال کردن صدور صورت‌حساب و ایجاد کلید میانای API، می‌توانید پروژه Flutter را که برای توسعه برنامه‌تان استفاده می‌کنید راه‌اندازی کنید.

مرحله ۱: نصب نرم‌افزار موردنیاز

برای ساختن پروژه بااستفاده از بسته Google Maps for Flutter، باید کیت توسعه نرم‌افزار Flutter را نصب کنید و محیط توسعه نرم‌افزار را برای پلاتفرم هدف خود راه‌اندازی کنید. برای جزئیات، راهنمای نصب Flutter را بررسی کنید.

مرحله ۲: نصب بسته Google Maps برای Flutter در پروژه جدید

‫Flutter بسته Google Maps برای Flutter را به‌عنوان افزایه Flutter ارائه می‌دهد.

پروژه Flutter را ایجاد کنید و افزونه Maps را اضافه کنید.

بااستفاده از `flutter create` پروژه Flutter جدیدی ایجاد کنید:
```
  flutter create google_maps_in_flutter --platforms=android,ios,web
  
  Creating project google_maps_in_flutter...
  [Listing of created files elided]
  Wrote 127 files.

  All done!
```
کد برنامه شما در google_maps_in_flutter/lib/main.dart است. برای اجرای برنامه، این دستور را تایپ کنید:
```
  cd google_maps_in_flutter
  flutter run
```
این برنامه iOS،‏ Android، و وب را هدف قرار می‌دهد. درحال‌حاضر Google Maps SDK از برنامه‌های رایانه خارج از مرورگر پشتیبانی نمی‌کند.

افزایه بسته Google Maps برای Flutter را به این پروژه اضافه کنید.

flutter pub add google_maps_flutter
  
  Resolving dependencies...
  [Listing of dependencies elided]

  Changed 14 dependencies!

مرحله ۳: تنظیم نسخه پلاتفرم

Android

حداقل نسخه کیت توسعه نرم‌افزار را برای Android تنظیم کنید.

فایل پیکربندی android/app/build.gradle را در IDE ترجیحی‌تان باز کنید.

تغییر دادن مقدار android.defaultConfig.minSdkVersion به 21:

  android {
    //...
    defaultConfig {
        applicationId "com.example.google_maps_in_flutter"
        minSdkVersion 21     // Set to 21
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    //...
  }

هنگام پیکربندی defaultConfig، ApplicationID یکتای خودتان را مشخص کنید.
تغییرات پروژه را با Gradle همگام‌سازی کنید.

iOS

حداقل نسخه پلاتفرم iOS را تنظیم کنید.

فایل پیکربندی ios/Podfile را در IDE ترجیحی‌تان باز کنید.

خطوط زیر را به ابتدای این Podfile اضافه کنید:

  # Set platform to 14.0 to enable latest Google Maps SDK
  platform :ios, '14.0'

مرحله ۴: افزودن کلید میانای API به پروژه

در بخش پیش‌از شروع، کلید میانای برنامه‌سازی کاربردی برای برنامه‌تان ایجاد کردید. اکنون آن کلید را به پروژه Flutter خود اضافه کنید. برای Flutter، باید این کلید میانای API را به همه پلاتفرم‌های هدف اضافه کنید: iOS،‏ Android، و وب.

در مثال‌های زیر، YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید.

Android

برای ساده‌سازی این کار، توصیه می‌کنیم از افزایه Secrets Gradle ویژه Android استفاده کنید.

برای نصب «افزایه Secrets Gradle ویژه Android» و ذخیره کردن کلید میانای برنامه‌سازی کاربردی:

در Android Studio، فایل build.gradle.kts یا build.gradle سطح بالا را باز کنید و کد زیر را به بلوک plugins اضافه کنید.

Kotlin

plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

Groovy

plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}

فایل build.gradle.kts یا build.gradle در سطح ماژول را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

Kotlin

plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

Groovy

plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
فایل secrets.properties را در دایرکتوری سطح بالا باز کنید، و سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید. حتماً secrets.properties را به فایل .gitignore خود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید.
توجه: اگر فایل secrets.properties وجود ندارد، آن را در همان پوشه فایل local.properties ایجاد کنید.
```
MAPS_API_KEY=YOUR_API_KEY
```
فایل local.defaults.properties را در دایرکتوری سطح بالا، همان پوشه فایل secrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.

توجه: کد را همان‌طور که نشان داده شده است وارد کنید. DEFAULT_API_KEY را با کلید میانای API خودتان جایگزین نکنید.
```
MAPS_API_KEY=DEFAULT_API_KEY
```
هدف این فایل ارائه مکان پشتیبان‌گیری برای کلید میانای برنامه‌سازی کاربردی است تا اگر فایل secrets.properties پیدا نشد، ساخت‌ها ناموفق نباشند. این مشکل زمانی رخ می‌دهد که برنامه را از سیستم کنترل نسخه‌ای شبیه‌سازی کنید که secrets.properties را حذف می‌کند و هنوز فایل secrets.properties را به‌صورت محلی برای ارائه کلید میانای برنامه‌سازی کاربردی خود ایجاد نکرده‌اید.
در فایل AndroidManifest.xml، به com.google.android.geo.API_KEY بروید و مشخصه android:value را به‌صورت زیر به‌روز کنید:
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
    
```
توجه: com.google.android.geo.API_KEY نام فراداده توصیه‌شده برای کلید میانای API است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله Flutter SDK، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه فقط می‌تواند یکی از نام‌های فراداده کلید میانای برنامه‌سازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، API استثنایی را ایجاد می‌کند.

در Android Studio، فایل build.gradle.kts یا build.gradle سطح ماژول را باز کنید و ویژگی secrets را ویرایش کنید. اگر دارایی secrets وجود ندارد، آن را اضافه کنید.

مشخصه‌های افزونه را ویرایش کنید تا propertiesFileName روی "secrets.properties" تنظیم شود، defaultPropertiesFileName روی "local.defaults.properties" تنظیم شود، و هر مشخصه دیگری را تنظیم کنید.

Kotlin

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

Groovy

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

توجه: همان‌طور که در بالا نشان داده شده است، com.google.android.geo.API_KEY نام فراداده توصیه‌شده برای کلید میانای API است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله Flutter SDK، استفاده کرد. برای سازگاری با نسخه قدیمی، این API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه فقط می‌تواند یکی از نام‌های فراداده کلید میانای برنامه‌سازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند.

iOS

کلید میانای برنامه‌سازی کاربردی خود را به فایل AppDelegate.swift اضافه کنید.

فایل ios/Runner/AppDelegate.swift را در پروژه Flutter با IDE ترجیحی‌تان باز کنید.
عبارت وارد کردن زیر را اضافه کنید تا بسته Google Maps برای Flutter به برنامه‌تان اضافه شود:

import GoogleMaps

میانای برنامه‌سازی کاربردی را به روش application(_:didFinishLaunchingWithOptions:) اضافه کنید و کلید میانای برنامه‌سازی کاربردی را جایگزین YOUR_API_KEY کنید:
```
GMSServices.provideAPIKey("YOUR_API_KEY")
```
فایل AppDelegate.swift را ذخیره کنید و ببندید.

فایل AppDelegate.swift تکمیل‌شده باید شبیه به این باشد:

import UIKit
import Flutter
import GoogleMaps  // Add this import

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    // TODO: Add your Google Maps API key
    GMSServices.provideAPIKey("YOUR_API_KEY")

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

وب

کلید میانای برنامه‌سازی کاربردی را به فایل برنامه index.html اضافه کنید.

فایل web/index.html را در پروژه Flutter با IDE ترجیحی‌تان باز کنید.

برچسب دستورگان زیر را در برچسب <head> اضافه کنید و کلید میانای برنامه‌سازی کاربردی خود را جایگزین YOUR_API_KEY کنید.

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

فایل index.html را ذخیره کنید و ببندید.

بخش کامل head از index.html باید شبیه به موارد زیر باشد:

    <head>
      <base href="/">
      
      <meta charset="UTF-8">
      <meta content="IE=Edge" http-equiv="X-UA-Compatible">
      <meta name="description" content="A new Flutter project.">
      
      <!-- iOS meta tags & icons -->
      <meta name="apple-mobile-web-app-capable" content="yes">
      <meta name="apple-mobile-web-app-status-bar-style" content="black">
      <meta name="apple-mobile-web-app-title" content="google_maps_in_flutter">
      <link rel="apple-touch-icon" href="icons/Icon-192.png">
      
      <script>
        (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
          key: "YOUR_API_KEY",
          v: "weekly",
          // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
          // Add other bootstrap parameters as needed, using camel case.
          });
      </script>
      
      <title>google_maps_in_flutter</title>
      <link rel="manifest" href="manifest.json">
    </head>

مرحله ۵: افزودن نقشه

کد زیر نحوه افزودن نقشه‌ای ساده به برنامه Flutter جدید را نشان می‌دهد.

فایل lib/main.dart را در پروژه Flutter با IDE ترجیحی‌تان باز کنید.

برای ایجاد و مقداردهی اولیه نمونه‌ای از mapController، روش‌ها را در روش اصلی پیش‌فرض برنامه‌تان اضافه یا به‌روز کنید.

      import 'package:flutter/material.dart';
      import 'package:google_maps_flutter/google_maps_flutter.dart';
      
      void main() => runApp(const MyApp());
      
      class MyApp extends StatefulWidget {
        const MyApp({super.key});
      
        @override
        State<MyApp> createState() => _MyAppState();
      }
      
      class _MyAppState extends State<MyApp> {
        late GoogleMapController mapController;
      
        final LatLng _center = const LatLng(-33.86, 151.20);
      
        void _onMapCreated(GoogleMapController controller) {
          mapController = controller;
        }
      
        @override
        Widget build(BuildContext context) {
          return MaterialApp(
            home: Scaffold(
              appBar: AppBar(
                title: const Text('Maps Sample App'),
                backgroundColor: Colors.green[700],
              ),
              body: GoogleMap(
                onMapCreated: _onMapCreated,
                initialCameraPosition: CameraPosition(
                  target: _center,
                  zoom: 11.0,
                ),
              ),
            ),
          );
        }
      }

هر شبیه‌ساز یا دستگاهی را که می‌خواهید برنامه‌تان در آن اجرا شود راه‌اندازی کنید.
برنامه‌تان را اجرا کنید. باید بروندادی شبیه به زیر ببینید:
```
  flutter run

   
    Multiple devices found:
    Android phone (mobile) • emulator-5554 • android-arm64  • Android 13 (API 33) (emulator)
    iPhone (mobile)  • ios • com.apple.CoreSimulator.SimRuntime.iOS-16-2 (simulator)
    Chrome (web) • chrome • web-javascript • Google Chrome 108.0.5359.124
    [1]: Android phone
    [2]: iPhone
    [3]: Chrome
    
    Please choose one (To quit, press "q/Q"): 
```
شماره پلاتفرمی را که می‌خواهید اجرا شود تایپ کنید. هر بار که flutter run را فراخوانی می‌کنید، Flutter این گزینه‌ها را به شما ارائه می‌دهد. اگر سیستم توسعه شما شبیه‌ساز درحال اجرا یا دستگاه آزمایشی متصل ندارد، Flutter باید Chrome را برای باز کردن انتخاب کند.

هر پلاتفرم باید نقشه‌ای را نمایش دهد که مرکز آن سیدنی، استرالیا باشد. اگر نقشه را ندیدید، بررسی کنید که کلید میانای برنامه‌سازی کاربردی را به پروژه هدف مناسب اضافه کرده باشید.

مراحل بعدی

اکنون که کلید میانای API و پروژه Flutter دارید، می‌توانید برنامه‌ها را ایجاد و اجرا کنید. بسته Google Maps برای Flutter آموزش‌های گام‌به‌گام و برنامه‌های نمونه بسیاری ارائه می‌دهد که می‌تواند به شما در شروع کار کمک کند. برای کسب اطلاعات بیشتر، منابع زیر را بررسی کنید:

آموزش افزودن نقشه با نشانگر
Codelabs برای Flutter با «پلاتفرم Google Maps»
نمونه‌های کد در GitHub

راه‌اندازی پروژه Flutter با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مرحله ۱: نصب نرم‌افزار موردنیاز

مرحله ۲: نصب بسته Google Maps برای Flutter در پروژه جدید

مرحله ۳: تنظیم نسخه پلاتفرم

Android

iOS

مرحله ۴: افزودن کلید میانای API به پروژه

Android

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Groovy

iOS

وب

مرحله ۵: افزودن نقشه

مراحل بعدی

راه‌اندازی پروژه Flutter