Hướng dẫn di chuyển

Cảnh báo: Tài liệu này có thể chứa thông tin cũ. Chúng tôi đang nỗ lực giải quyết vấn đề này, nhưng bạn nên tạm thời xem trang Bắt đầu để xem các ứng dụng mẫu của chúng tôi. Chúng cho thấy các hành vi và mẫu sử dụng API hỗ trợ bạn di chuyển từ phiên bản 1.

Thay đổi lớn nhất mà Google thực hiện đối với SDK Điều hướng cho phiên bản 2 là chúng tôi đã thay thế một số lớp SDK Điều hướng bằng các bản tương ứng của chúng từ SDK Bản đồ dành cho Android.

Kể từ phiên bản 2.2, SDK Điều hướng là một ứng dụng thay thế (gần như) có thể thả xuống cho API Maps của Dịch vụ Google Play. Thay vì đóng gói lại tất cả API vào com.google.android.library.maps, các API này đã được đóng gói trong com.google.android.gms.maps giống như Dịch vụ Google Play. Điều này khiến việc chuyển đổi giữa phiên bản Dịch vụ Google Play và SDK điều hướng trở nên đơn giản hơn nhiều.

Cảnh báo: Những hướng dẫn này chỉ hợp lệ cho phiên bản 2.2 trở lên.

Lợi ích

• Sử dụng bộ nhớ hiệu quả hơn. Hiện tại, bạn sử dụng ít bộ nhớ và băng thông hơn so với khi sử dụng cả SDK Điều hướng và SDK Maps dành cho Android.
• Việc chuyển từ chế độ chế độ xem bản đồ sang chế độ chỉ đường giờ đây sẽ mượt mà và dễ sử dụng hơn.
• Giờ đây, bạn có thể kiểm soát camera tốt hơn.
• Giờ đây, bạn có thể làm những việc như vẽ hình nhiều đường và lớp phủ, đồng thời thêm các kiểu tuỳ chỉnh vào bản đồ.

Tuy nhiên, các tính năng như Chế độ xem đường phố và Chế độ Lite không được hỗ trợ.

Lưu ý quan trọng: SDK Điều hướng sẽ thay thế SDK Maps dành cho Android và bạn sẽ cần xoá mọi tham chiếu đến ứng dụng khách.

Điều kiện tiên quyết

• Phiên bản 2 của SDK điều hướng sử dụng Android Jetpack – một bộ thư viện, công cụ và hướng dẫn giúp bạn viết ứng dụng chất lượng cao dễ dàng hơn. Việc di chuyển này có nghĩa là bạn phải chuyển ứng dụng của mình từ việc sử dụng thư viện hỗ trợ sang sử dụng AndroidX. Để biết thêm thông tin, hãy xem phần Di chuyển sang AndroidX.

Bước 1. Di chuyển từ SDK Bản đồ dành cho Android

Hầu hết các chức năng trong SDK Maps dành cho Android hiện được đưa vào phiên bản 2 của SDK điều hướng. Một vài tính năng đã bị xoá vì không cần thiết trong ngữ cảnh điều hướng.

Những điểm khác biệt quan trọng

SDK Bản đồ dành cho Android có trong Dịch vụ Google Play.

Các tính năng của SDK Maps dành cho Android được đóng gói trong phiên bản 2 của SDK Điều hướng là dựa trên phiên bản mới của SDK Maps dành cho Android, và không có trong Dịch vụ Google Play. Những tính năng mới này chạy trên một công cụ mới hơn công cụ trong Dịch vụ Google Play và có một số điểm cải tiến. Điều này cũng có nghĩa là bản đồ sẽ chạy trong quy trình của ứng dụng chứ không phải trong quy trình của Dịch vụ Google Play.

Một số lớp đã được đổi tên

Bảng sau đây liệt kê các lớp đã được đổi tên. Chúng tôi thực hiện điều này để phân biệt chúng với SDK Maps dành cho Android.

SDK bản đồ dành cho tên lớp Android	Tên lớp SDK điều hướng
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

Các lớp này chứa sự kết hợp của các phương thức có trong lớp NavigationView cũ và lớp MapView hiện tại. Bạn có thể xem các lớp này giống như các lớp MapView và MapFragment, nhưng có hỗ trợ điều hướng.

Tính năng bị xoá

Một số tính năng của Maps đã bị xoá do không phù hợp trong ngữ cảnh chỉ đường hoặc do có sự không tương thích về kỹ thuật. Các tính năng bị xoá bao gồm:

• Chế độ xem đường phố.
• Chế độ thu gọn không đủ để điều hướng.
• Bạn không thể đặt LocationProvider khi máy ảnh ở Chế độ theo dõi. Nguyên nhân là do việc điều hướng phụ thuộc vào RoadSnappedLocationProvider và việc chuyển sang trình cung cấp này có thể gây ra sự cố khi điều hướng.
• Việc áp dụng mức thu phóng tối thiểu/tối đa và các giới hạn LatLng sẽ không có hiệu lực khi máy ảnh ở Chế độ theo dõi.
• Vui lòng trao đổi với người đại diện khách hàng của bạn nếu những tính năng bị thiếu này đang gây khó khăn cho bạn.

Các bước di chuyển

1. Xoá SDK Maps dành cho việc tích hợp Android khỏi bản dựng của bạn (tức là gradle). Việc có cả hai SDK sẽ gây ra lỗi biên dịch.
2. Thay thế các bản sao của MapView bằng các bản sao của NavigationView.
3. Thay thế các bản sao của MapFragment bằng các bản sao của NavigationSupportFragment.

Nếu ứng dụng của bạn trước đây chưa sử dụng SDK điều hướng, thì quá trình di chuyển của bạn đã hoàn tất.

Bước 2. Di chuyển từ SDK Điều hướng phiên bản 1.x

Thực hiện các bước sau để di chuyển nội dung tích hợp SDK Điều hướng phiên bản 1.x sang phiên bản 2.

1. Tải bản đồ bằng các phương thức mới

Cách bạn tải bản đồ đã thay đổi. Trước phiên bản 2, bạn có bản đồ bằng cách sử dụng một lệnh gọi đồng bộ. Bây giờ, bạn sẽ sử dụng lệnh gọi không đồng bộ. Bảng sau đây liệt kê các phương thức cũ cùng với các phương thức mới để tải bản đồ.

Phương pháp cũ	Phương thức mới
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

Lưu ý: Lớp NavigationFragment đã bị xoá vì lớp Fragment đã ngừng hoạt động, thay vào đó là lớp SupportFragment.

2. Di chuyển thư viện

Phiên bản 1.x của SDK Điều hướng chứa cách triển khai riêng một số SDK Bản đồ cho các lớp Android. Các lớp này thuộc về gói com.google.android.libraries.navigation.

Trong phiên bản 2, các lớp này đã được thay thế bằng SDK Maps cho Android, nằm trong gói com.google.android.gms.maps.model. Bạn có thể di chuyển ứng dụng của mình để tích hợp các lớp mới bằng cách tìm kiếm và thay thế.

Bảng sau đây liệt kê các lớp cũ cùng với các lớp mới.

Lớp cũ	Lớp học mới
com.google.android.libraries.navigation.LatLng	com.google.android.gms.maps.model.LatLng
com.google.android.libraries.navigation.LatLngBounds	com.google.android.gms.maps.model.LatLngBounds
com.google.android.libraries.navigation.Marker	com.google.android.gms.maps.model.Marker
com.google.android.libraries.navigation.MarkerOptions	com.google.android.gms.maps.model.MarkerOptions
com.google.android.libraries.navigation.VisibleRegion	com.google.android.gms.maps.model.VisibleRegion

3. Thích ứng với các thay đổi đối với API hiện có

Bảng sau đây liệt kê những thay đổi chính mà Google đã thực hiện đối với phiên bản 2 của SDK điều hướng.

Phương thức	Chuyển
NavigationApi.cleanup()	Đã xoá. Phương thức này không được dùng cho hoạt động bình thường và có thể gây ra các hành vi ngoài dự đoán. Bạn phải xoá các lệnh gọi đến phương thức này.
RoadSnappedLocationProvider.requestLocationUpdates()	Đã xoá. Thay vào đó, hãy sử dụng addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	Đã xoá. Thay vào đó, hãy sử dụng removeLocationListener().

4. Thay đổi sang lớp Marker mới

Phiên bản 2 của SDK Điều hướng hiện sử dụng cách triển khai tương tự của lớp Marker như SDK Bản đồ dành cho Android. Việc này gây ra những thay đổi sau.

Phương pháp liên quan đến điểm đánh dấu

Phương thức	Chuyển
addMarker(MarkerOptions markerOptions)	Nay sử dụng lớp com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	Phương thức này không còn tồn tại nữa. Thay vào đó, lớp Marker hiện có phương thức marker.remove().
removeAllMarkers()	Phương thức này không còn tồn tại nữa, mặc dù có một phương thức clear() giúp xoá tất cả các điểm đánh dấu, hình nhiều đường, đa giác và lớp phủ khỏi bản đồ.

Sự khác biệt của MarkerOptions

• Phương thức describeContents() không tồn tại trong phiên bản 2 của SDK Điều hướng. Lớp này cho phép bạn lưu dữ liệu khung hiển thị bằng cách gọi onSaveInstanceState(). Bây giờ, bạn sẽ phải tự theo dõi thông tin chi tiết về khung hiển thị để có thể tạo lại khung hiển thị đó khi có thay đổi về cấu hình.
• Phương thức navMarker#icon(BitMap) đã thay đổi thành mapMarker#icon(BitmapDescriptor). Thay đổi này yêu cầu bạn chuyển từ việc sử dụng BitMap sang BitmapDescriptor.

Phương thức đánh dấu

Bây giờ, bạn sẽ sử dụng lớp Marker trong gói com.google.android.gms.maps.model. Bảng sau đây liệt kê các điểm khác biệt khi sử dụng lớp Marker mới này.

Phương thức	Chuyển
getAnchorU()	Không còn tồn tại.
getAnchorV()	Không còn tồn tại.
getIcon()	Không còn tồn tại. Bạn phải tự duy trì tham chiếu đến biểu tượng để sử dụng sau khi thay đổi cấu hình, khi cần tạo lại trạng thái bản đồ.
getPosition()	Vẫn tồn tại.
getTitle()	Vẫn tồn tại.

Lưu ý: Nếu bạn cần sử dụng các phương thức đã xoá trên lớp Marker, hãy cho chúng tôi biết để chúng tôi có thể giúp bạn giải quyết vấn đề.

5. Điều khiển camera

Các tính năng điều khiển máy ảnh được cung cấp trong phiên bản 1.x của SDK Điều hướng tương đối hạn chế. Phiên bản 2 của SDK điều hướng hiện sử dụng cùng một mẫu máy ảnh mà SDK Maps dành cho Android sử dụng, ngoại trừ việc bạn cũng nhận được Chế độ theo dõi tương tự như trong phiên bản 1.x của SDK điều hướng.

Điểm khác biệt chính

• Lớp com.google.android.libraries.navigation.Camera đã bị xoá trong phiên bản 2.
  • Di chuyển Camera.showRouteOverview() sang NavigationView và SupportNavigationFragment.
  • Phương thức Camera.followMyLocation() đã được di chuyển sang GoogleMap.
• Bạn có thể thay thế các lệnh gọi đến Camera.setLocation() bằng GoogleMap.moveCamera() hoặc GoogleMap.animateCamera().
• setOnFollowMyLocationCallback() và isCameraFollowingMyLocation() đã được thêm vào GoogleMap để cung cấp thêm thông tin về chế độ theo dõi.

Bước 3. Hợp nhất các luồng hoạt động

Nếu trước đây bạn đang sử dụng phiên bản 1 của SDK Điều hướng và làm theo hướng dẫn ở trên, thì bạn đã di chuyển các trường hợp sử dụng bản đồ để sử dụng lớp NavigationView, đồng thời bạn cũng đã di chuyển các trường hợp sử dụng chỉ đường để sử dụng GoogleMap. Tuy nhiên, bạn sẽ có 2 thực thể của GoogleMap và 2 thực thể của NavigationView. Điều này có nghĩa là bạn vẫn sẽ sử dụng nhiều bộ nhớ hơn mức cần thiết và việc chuyển đổi giữa hai thực thể có thể dẫn đến các trường hợp tạm dừng nhận biết được trong quá trình kết xuất giao diện người dùng mượt mà. Để giải quyết vấn đề này, bạn nên hợp nhất các luồng hoạt động/mảnh để chúng có thể chia sẻ một thực thể duy nhất. Điều này mang lại trải nghiệm người dùng mượt mà hơn và tinh giản ứng dụng của bạn.