設定地圖

選取平台： Android iOS

如要在消費者應用程式中追蹤行程，您必須先定義地圖，並視需要新增向量地圖支援功能。

如要在應用程式中設定地圖，請按照下列步驟操作：

  1. 定義地圖片段，以便追蹤行程。
  2. 新增地圖基本圖層和檢視區塊控制器的支援功能。
  3. 視需要新增對 Android 向量圖形的支援，顯示向量地圖。

定義地圖後，您可以新增其他檢視畫面和攝影機控制項，自訂視覺體驗。詳情請參閱「設定地圖樣式」。

步驟 1：定義地圖片段，以便追蹤行程

如要定義地圖，請新增地圖片段或檢視區塊，在消費者應用程式中建立地圖，以便分享隨選行程。如要定義地圖，請按照下列任一方法操作：

  • ConsumerMapFragment：用來透過 Fragment 定義地圖。

  • ConsumerMapView：用來定義具有 View 的對應。

這兩種方法提供的功能相同，因此請選擇較適合應用程式的方法。

我們會在下一節詳細說明這兩種方法。

新增地圖片段或檢視區塊

如要建立地圖來顯示行程進度，請使用 Android 片段或檢視區塊，然後按照下列步驟操作並參閱程式碼範例。

  1. 在 /res/layout 中的應用程式版面配置 XML 檔案中，定義片段或檢視畫面。將行程地圖定義為使用 ConsumerMapFragment 的片段，或使用 ConsumerMapView 的檢視區塊。

    然後，片段或檢視畫面會提供行程地圖的存取權，供應用程式存取及修改。地圖也會提供 ConsumerController 的控制代碼，讓應用程式控管及自訂消費者體驗。

  2. 在 onCreate() 方法中呼叫 getConsumerGoogleMapAsync(callback)，這會在回呼中以非同步方式傳回 ConsumerGoogleMap。

  3. 使用 ConsumerGoogleMap 顯示行程進度，並視需要更新。

新增 ConsumerMapFragment 的範例

  1. 在應用程式版面配置 XML 檔案中定義片段，如下列程式碼範例所示。

    <fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

  2. 從 onCreate() 方法呼叫 getConsumerGoogleMapAsync()。

Java

 public class SampleAppActivity extends AppCompatActivity {

   @Override
   protected void onCreate(Bundle savedInstanceState) {

     // Find the ConsumerMapFragment.
     ConsumerMapFragment consumerMapFragment =
         (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

     // Initiate the callback that returns the map.
     if (consumerMapFragment != null) {
       consumerMapFragment.getConsumerGoogleMapAsync(
           new ConsumerMapReadyCallback() {
             // The map returned in the callback is used to access the ConsumerController.
             @Override
             public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
               ConsumerController consumerController = consumerGoogleMap.getConsumerController();
             }
           });
     }
   }

 }

Kotlin

 class SampleAppActivity : AppCompatActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     // Find the ConsumerMapFragment.
     val consumerMapFragment =
       fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

     consumerMapFragment.getConsumerGoogleMapAsync(
       object : ConsumerMapReadyCallback() {
         override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
           val consumerController = consumerGoogleMap.getConsumerController()!!
         }
       }
     )
   }
 }

新增 ConsumerMapView 的範例

  1. 在片段或活動中使用檢視區塊，如 XML 檔案所定義。

     <com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
     xmlns:android="http://schemas.android.com/apk/res/android"
     android:id="@+id/consumer_map_view"
     android:layout_width="match_parent"
     android:layout_height="match_parent" />

  2. 從 onCreate() 撥打電話給 getConsumerGoogleMapAsync()。除了回呼參數，請一併提供下列詳細資料：

    • 包含的活動或片段。活動或片段基礎類別必須是 FragmentActivity 或支援 Fragment (分別)，因為這些類別可提供生命週期的存取權。

    • GoogleMapOptions (可為空值)，內含 MapView 的設定屬性。

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

片段中的 MapView 與活動中 MapView 的前一個範例相同，但片段會擴充包含片段 onCreateView() 方法中 MapView 的版面配置。

Java

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

Kotlin

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

步驟 2：新增地圖基本圖層和檢視畫面控制器支援

如要在應用程式中分享行程進度，請在應用程式中加入下列類別：ConsumerGoogleMap 和 ConsumerController。

  • 從 ConsumerMapFragment 或 ConsumerMapView 取得 ConsumerGoogleMap，兩者都會在 ConsumerMapReadyCallback 中非同步傳回 ConsumerGoogleMap。

    ConsumerGoogleMap 是 GoogleMap 類別的包裝函式類別。這個 API 相當於 GoogleMap，可讓應用程式與地圖互動。這樣一來，您的應用程式就能與相同的基礎 Google 地圖無縫互動。舉例來說，GoogleMap 只允許單一回呼註冊，但 ConsumerGoogleMap 支援雙重註冊回呼。這些回呼可讓應用程式註冊依序呼叫的回呼。

  • 在「getConsumerController()」中取得「ConsumerController」的「ConsumerGoogleMap」。

    ConsumerController 可存取行程分享功能，例如監控行程、控管行程狀態及設定地點。

如要在 Java 和 Kotlin 中將 ConsumerGoogleMap 和 ConsumerController 新增至應用程式，請參閱下列範例。

Java

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

Kotlin

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

步驟 3：新增 Android 向量繪圖支援

如果應用程式設計需要支援向量繪圖，請按照下列步驟操作，為 Android 裝置和向量可繪項目新增支援：

  1. 將下列程式碼新增至 Activity。這個程式碼會擴充 AppCompatActivity，以便在 Consumer SDK 中使用向量可繪項目。

Java

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

Kotlin

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

後續步驟

在 Android 裝置上追蹤行程

設定地圖樣式