این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

یک پروژه فلاتر راه اندازی کنید

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

مرحله 1: نرم افزار مورد نیاز را نصب کنید

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

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

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

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

یک پروژه Flutter جدید با استفاده از "flutter create" ایجاد کنید:
```
  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 و Web را هدف قرار می دهد. Google Maps SDK در حال حاضر از برنامه های دسکتاپ خارج از مرورگر پشتیبانی نمی کند.

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

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

  Changed 14 dependencies!

مرحله 3: نسخه پلتفرم را تنظیم کنید

اندروید

حداقل نسخه SDK را برای اندروید تنظیم کنید.

فایل پیکربندی 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 دلخواه خود باز کنید.

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

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

مرحله 4: کلید API خود را به پروژه اضافه کنید

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

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

اندروید

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

برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:

در Android Studio، فایل build.gradle یا build.gradle.kts سطح بالای خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.

شیار

buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

کاتلین

buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

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

شیار

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

کاتلین

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

در فایل build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی 34 تنظیم شده اند.
فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی سیستم کنترل نسخه حذف شده است.
توجه: اگر فایل 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
```
هدف این فایل ارائه یک مکان پشتیبان برای کلید API در صورت یافت نشدن فایل secrets.properties است تا بیلدها خراب نشوند. اگر برنامه را از یک سیستم کنترل نسخه که secrets.properties را حذف می کند و هنوز فایل secrets.properties را به صورت محلی برای ارائه کلید API خود ایجاد نکرده اید، ممکن است اتفاق بیفتد.
فایل را ذخیره کنید.
در فایل AndroidManifest.xml خود، به com.google.android.geo.API_KEY بروید و android:value attribute به روز کنید. اگر تگ <meta-data> وجود ندارد، آن را به عنوان فرزند تگ <application> ایجاد کنید.
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```
Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Flutter SDK. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

Groovy

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

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

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

کاتلین

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

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

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

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

iOS

کلید API خود را به فایل AppDelegate.swift خود اضافه کنید.

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

import GoogleMaps

API خود را به application(_:didFinishLaunchingWithOptions:) اضافه کنید، کلید API خود را جایگزین 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)
  }
}

وب

کلید API خود را به فایل برنامه کاربردی index.html خود اضافه کنید.

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

تگ اسکریپت زیر را در تگ <head> اضافه کنید و کلید API خود را جایگزین 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>

مرحله 5: یک نقشه اضافه کنید

کد زیر نشان می دهد که چگونه می توان یک نقشه ساده را به یک برنامه جدید 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 خود را به پروژه هدف مناسب اضافه کرده اید.

مراحل بعدی

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

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