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

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

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

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

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

مرحله 2: نصب بسته Google Maps برای 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، اندروید و وب طراحی شده است. در حال حاضر، Google Maps SDK از برنامه‌های دسکتاپ خارج از مرورگر پشتیبانی نمی‌کند.

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

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

  Changed 14 dependencies!

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

اندروید

حداقل نسخه 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/Podfile را در IDE مورد نظر خود باز کنید.

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

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

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

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

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

اندروید

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

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

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

کاتلین

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.jetbrains.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.secrets.gradle.plugin) apply false
}

گرووی

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

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

کاتلین

plugins {
    // ...
    alias(libs.plugins.secrets.gradle.plugin)
}

گرووی

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

در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی ۳۴ تنظیم شده‌اند.
پروژه خود را با Gradle همگام‌سازی کنید .
فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید API خود جایگزین کنید. کلید خود را در این فایل ذخیره کنید زیرا 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}" />
```
توجه: com.google.android.geo.API_KEY نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Flutter SDK، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

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

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

کاتلین

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"
}

گرووی

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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 است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Flutter SDK، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

آی‌او‌اس

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

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

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>

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

کد زیر نحوه اضافه کردن یک نقشه ساده به یک برنامه جدید 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
نمونه‌های کد در گیت‌هاب

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

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

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

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

اندروید

آی‌او‌اس

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

اندروید

کاتلین

گرووی

کاتلین

گرووی

کاتلین

گرووی

آی‌او‌اس

وب

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

مراحل بعدی

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