Trước khi thiết lập dự án Flutter, hãy đảm bảo bạn đã hoàn thành điều kiện tiên quyết trong phần Trước khi bắt đầu. Sau khi bạn bật thanh toán và tạo một khoá API, bạn có thể thiết lập dự án Flutter mà bạn dùng để phát triển ứng dụng của bạn.
Bước 1: Cài đặt phần mềm cần thiết
Để xây dựng một dự án bằng gói Google Maps cho Flutter, bạn phải cài đặt Flutter SDK rồi thiết lập môi trường phát triển cho nền tảng mục tiêu của bạn. Xem hướng dẫn cài đặt Flutter để biết thông tin chi tiết.
Bước 2: Cài đặt gói Google Maps cho Flutter trong một dự án mới
Flutter cung cấp gói Google Maps cho Flutter dưới dạng một trình bổ trợ Flutter.
Tạo dự án Flutter và thêm trình bổ trợ Maps.
-
Tạo một dự án Flutter mới bằng lệnh "flutter create":
Mã xử lý ứng dụng của bạn nằm trongflutter 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
. Để chạy ứng dụng của bạn, nhập: Ứng dụng này nhắm đến iOS, Android và Web. SDK Google Maps không hỗ trợ các ứng dụng dành cho máy tính bên ngoài trình duyệt tại thời điểm này.cd google_maps_in_flutter
flutter run
-
Thêm trình bổ trợ gói Google Maps cho Flutter vào dự án này.
flutter pub add google_maps_flutter
Resolving dependencies... [Listing of dependencies elided] Changed 14 dependencies!
Bước 3: Thiết lập phiên bản nền tảng
Android
Đặt phiên bản SDK tối thiểu cho Android.
- Mở tệp cấu hình
android/app/build.gradle
trong IDE mà bạn muốn ưu tiên. - Thay đổi giá trị của
android.defaultConfig.minSdkVersion
thành21
:android { //... defaultConfig { applicationId "com.example.google_maps_in_flutter" minSdkVersion 21 // Set to 21 targetSdkVersion flutter.targetSdkVersion versionCode flutterVersionCode.toInteger() versionName flutterVersionName } //... }
- Khi định cấu hình
defaultConfig
, hãy chỉ định ApplicationID của riêng bạn. - Lưu tệp và đồng bộ hoá các thay đổi trong dự án với Gradle.
iOS
Đặt phiên bản nền tảng iOS tối thiểu.
- Mở tệp cấu hình
ios/Podfile
trong IDE mà bạn muốn ưu tiên. - Thêm các dòng sau vào đầu Podfile này:
# Set platform to 14.0 to enable latest Google Maps SDK platform :ios, '14.0'
Bước 4: Thêm khoá API vào dự án
Trong phần Trước khi bắt đầu, bạn đã tạo một khoá API cho ứng dụng của mình. Bây giờ, hãy thêm đó là chìa khoá cho dự án Flutter của bạn. Đối với Flutter, bạn nên thêm khoá API này vào tất cả các nền tảng mục tiêu: iOS, Android và Web.
Trong các ví dụ sau, hãy thay thế YOUR_API_KEY
bằng khoá API.
Android
Để đơn giản hoá tác vụ này, bạn nên sử dụng Trình bổ trợ Secrets Gradle cho Android.
Cách cài đặt trình bổ trợ Secrets Gradle cho Android trong dự án Google Maps:
-
Trong Android Studio, hãy mở
build.gradle.kts
hoặcbuild.gradle
cấp cao nhất rồi thêm mã sau vào phần tửdependencies
trongbuildscript
.Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
Mở tệp
build.gradle.kts
hoặcbuild.gradle
ở cấp mô-đun rồi thêm mã sau đây vào phần tửplugins
.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- Trong tệp
build.gradle.kts
hoặcbuild.gradle
ở cấp mô-đun, hãy đảm bảo rằngtargetSdk
vàcompileSdk
đã được đặt đến 34. - Lưu tệp và đồng bộ hoá dự án với Gradle.
-
Mở tệp
secrets.properties
trong thư mục cấp cao nhất của bạn, sau đó thêm sau đây. Thay thếYOUR_API_KEY
bằng khoá API. Lưu trữ khoá của bạn trong tệp này vìsecrets.properties
không được kiểm tra trong phần kiểm soát phiên bản hệ thống.MAPS_API_KEY=YOUR_API_KEY
- Lưu tệp.
-
Tạo tệp
local.defaults.properties
trong thư mục cấp cao nhất cũng bằng cách này làm tệpsecrets.properties
, rồi thêm mã sau.MAPS_API_KEY=DEFAULT_API_KEY
Mục đích của tệp này là cung cấp vị trí sao lưu cho khoá API nếu Không tìm thấy tệp
secrets.properties
để các bản dựng không bị lỗi. Điều này có thể xảy ra nếu bạn sao chép ứng dụng từ một hệ thống quản lý phiên bản, trong đó bỏ quasecrets.properties
và bạn chưa tạo tệpsecrets.properties
cục bộ để cung cấp Khoá API. - Lưu tệp.
-
Trong tệp
AndroidManifest.xml
, chuyển đếncom.google.android.geo.API_KEY
rồi cập nhậtandroid:value attribute
. Nếu thẻ<meta-data>
không tồn tại, hãy tạo thẻ này làm thẻ con của Thẻ<application>
.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Lưu ý:
com.google.android.geo.API_KEY
là tên siêu dữ liệu nên dùng cho khoá API. Bạn có thể dùng khoá có tên này để xác thực với nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm Flutter SDK. Để có khả năng tương thích ngược, API này cũng hỗ trợ têncom.google.android.maps.v2.API_KEY
. Kiểu cũ này tên chỉ cho phép xác thực API Android Maps v2. Một ứng dụng có thể chỉ định một trong các tên siêu dữ liệu khoá API. Nếu cả hai đều được chỉ định, thì API trả về một ngoại lệ. -
Trong Android Studio, hãy mở
build.gradle.kts
ở cấp mô-đun hoặcbuild.gradle
rồi chỉnh sửa thuộc tínhsecrets
. Nếu Thuộc tínhsecrets
không tồn tại, hãy thêm thuộc tính này.Chỉnh sửa các thuộc tính của trình bổ trợ để đặt
propertiesFileName
thànhsecrets.properties
, đặtdefaultPropertiesFileName
thànhlocal.defaults.properties
và đặt bất kỳ thuộc tính nào khác.Kotlin
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" // 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.*" }
Groovy
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" // 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.*" }
Lưu ý: Như đã trình bày ở trên,
com.google.android.geo.API_KEY
là tên siêu dữ liệu nên dùng
cho khoá API. Bạn có thể dùng khoá có tên này để xác thực với nhiều
API dựa trên Google Maps trên nền tảng Android, bao gồm
Flutter SDK. Để có khả năng tương thích ngược, API này cũng
hỗ trợ tên com.google.android.maps.v2.API_KEY
. Kiểu cũ này
tên chỉ cho phép xác thực API Android Maps v2. Một ứng dụng có thể
chỉ định một trong các tên siêu dữ liệu khoá API. Nếu cả hai đều được chỉ định, thì API
trả về một ngoại lệ.
iOS
Thêm khoá API vào tệp AppDelegate.swift
.
- Mở tệp
ios/Runner/AppDelegate.swift
trong dự án Flutter bằng IDE mà bạn muốn. - Thêm câu lệnh nhập sau để thêm gói Google Maps cho Flutter vào ứng dụng của bạn:
- Thêm API vào phương thức
application(_:didFinishLaunchingWithOptions:)
, thay thế khoá API cho YOUR_API_KEY:GMSServices.provideAPIKey("YOUR_API_KEY")
- Lưu và đóng tệp
AppDelegate.swift
.
import GoogleMaps
Tệp AppDelegate.swift
hoàn chỉnh sẽ có dạng như sau:
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) } }
Web
Thêm khoá API vào tệp ứng dụng index.html
.
- Mở tệp
web/index.html
trong dự án Flutter bằng IDE mà bạn muốn. - Thêm thẻ tập lệnh dưới đây vào thẻ
<head>
, thay thế khoá API của bạn choYOUR_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>
- Lưu và đóng tệp
index.html
.Phần
head
hoàn chỉnh củaindex.html
sẽ có dạng như sau:<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>
Bước 5: Thêm bản đồ
Mã sau đây minh hoạ cách thêm một bản đồ đơn giản vào một ứng dụng Flutter mới.
- Mở tệp
lib/main.dart
trong dự án Flutter bằng IDE mà bạn muốn. - Thêm hoặc cập nhật các phương thức trong phương thức chính mặc định của ứng dụng để tạo và khởi chạy một thực thể của
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, ), ), ), ); } }
- Khởi động mọi trình mô phỏng hoặc thiết bị mà bạn muốn chạy ứng dụng.
- Chạy ứng dụng của bạn. Bạn sẽ thấy kết quả như sau:
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"):Nhập số nền tảng bạn muốn chạy. Mỗi khi bạn gọi
flutter run
, Flutter sẽ hiển thị cho bạn các lựa chọn này. Nếu hệ thống phát triển của bạn không có trình mô phỏng đang chạy hoặc thiết bị thử nghiệm được kết nối, Flutter sẽ chọn mở Chrome.Mỗi nền tảng phải hiển thị một bản đồ ở trung tâm Sydney, Úc. Nếu không thấy bản đồ, hãy kiểm tra để chắc chắn rằng bạn đã thêm khoá API vào dự án mục tiêu thích hợp.
Các bước tiếp theo
Giờ đây, khi đã có khoá API và một dự án Flutter, bạn có thể tạo và chạy ứng dụng. Gói Google Maps cho Flutter cung cấp nhiều hướng dẫn và ứng dụng mẫu có thể giúp bạn bắt đầu. Để tìm hiểu thêm, hãy xem các tài nguyên sau:
- Hướng dẫn về Thêm bản đồ bằng Điểm đánh dấu
- Lớp học lập trình cho Flutter cùng Nền tảng Google Maps
- Mã mẫu trên GitHub