地圖物件
地圖是在 API 中是由
GoogleMap 與 MapFragment 類別代表。新增地圖到 Android 應用程式
新增地圖的基本步驟如下：
- (您只需要執行此步驟一次)。依照專案設定指南中的步驟執行以取得 API，取得金鑰並將必要的屬性新增至您的 Android 宣示說明。
- 將
Fragment物件新增到將會處理地圖的Activity。 最簡單的執行方式是將<fragment>元素新增到Activity的版面配置檔案。 - 實作
OnMapReadyCallback介面並使用onMapReady(GoogleMap)回呼方法取得GoogleMap物件的控制代碼。GoogleMap物件是地圖本身的內部呈現方式。 如果要設定地圖的檢視選項，您可以修改地圖的GoogleMap物件。 - 呼叫片段上的
getMapAsync()以註冊回呼。
以下是每個步驟更詳細的資料。
新增片段
將
<fragment> 元素新增到活動的版面配置檔案，以定義 Fragment 物件。 在此元素中，將 android:name 屬性設定為 "com.google.android.gms.maps.MapFragment"。 這會自動將 MapFragment 附加到活動。
下列版面配置檔案包含
<fragment> 元素：
<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
android:name="com.google.android.gms.maps.MapFragment"
android:id="@+id/map"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
您也可以在程式碼中將
MapFragment 新增到 Activity。 如果要這樣做，請建立新的 MapFragment 實例，然後呼叫 FragmentTransaction.add() 以將 Fragment 新增到目前的 Activity。
mMapFragment = MapFragment.newInstance();
FragmentTransaction fragmentTransaction =
getFragmentManager().beginTransaction();
fragmentTransaction.add(R.id.my_container, mMapFragment);
fragmentTransaction.commit();
新增地圖程式碼
如果要使用您的應用程式內的地圖，您必須實作
OnMapReadyCallback 介面，並針對 MapFragment 或 MapView 物件設定回呼的實例。本教學課程使用 MapFragment，因為這是新增地圖到應用程式最常見的方法 。第一個步驟是實作回呼介面：
public class MainActivity extends FragmentActivity
implements OnMapReadyCallback {
...
}
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
...
}
透過呼叫
FragmentManager.findFragmentById()，再將 <fragment> 元素的資源 ID 傳遞給它，以取得片段的控制代碼。請注意，當您建置版面配置檔案時，資源 ID R.id.map 會自動新增到 Android 專案。
接著，使用
getMapAsync() 在片段上設定回呼。
MapFragment mapFragment = (MapFragment) getFragmentManager()
.findFragmentById(R.id.map);
mapFragment.getMapAsync(this);
注意：Google Maps Android API 需要 API 層級 12 或更高版本，才能支援
MapFragment 物件。 如果您以 API 層級 21 以前的應用程式為目標，您可以透過 SupportMapFragment 類別存取相同的功能。您也必須包括 Android 支援程式庫。
注意：
getMapAsync() 必須從主要執行緒呼叫，然後回呼才會在主要執行緒中執行。 如果使用者的裝置上未安裝 Google Play 服務，在使用者安裝 Play 服務之前，都不會觸發回呼。
使用
onMapReady(GoogleMap) 回呼方法取得 GoogleMap 物件的控制代碼。 地圖就緒可供使用時時，就會觸發回呼。 它提供不是 Null 的 GoogleMap 實例。 例如，您可以使用 GoogleMap 物件設定地圖的檢視選項，或新增標記。
@Override
public void onMapReady(GoogleMap map) {
map.addMarker(new MarkerOptions()
.position(new LatLng(0, 0))
.title("Marker"));
}
地圖物件
Google Maps Android API 允許在您的 Android 應用程式中顯示 Google 地圖。 這些地圖和您在 Google Maps for Mobile (GMM) 應用程式中看到的地圖外觀相同，而且 API 會公開許多相同的功能。GMM 應用程式與由 Google Maps Android API 顯示的地圖之間有兩個明顯差異：
- 由 API 顯示的地圖方塊不包含任何個人化內容，例如個人化的智慧圖示。
- 並非地圖上的所有圖示都可以點選。 例如，您無法點選大眾運輸車站圖示。 然而，您新增到地圖的標記可以點選，而 API 會有接聽程式回呼介面可用於各種標記互動。
除了地圖功能之外，API 也完全支援和 Android UI 模型一致的各種互動。 例如，您可以透過定義會回應使用者手勢的接聽程式，以設定與地圖的互動。
GoogleMap 會自動處理下列操作：- 連線到「Google 地圖」服務。
- 下載地圖方塊。
- 在裝置螢幕上顯示地圖方塊。
- 顯示各種控制項，例如平移和縮放。
- 透過移動地圖和放大或縮小地圖，以回應平移和縮放手勢。
除了這些自動化操作之外，您還可以使用 API 的物件與方法來控制地圖行為。 例如，
GoogleMap 具有的回呼方法，可以回應按鍵與地圖上的輕觸手勢。您也可以在地圖上設定標記圖示，然後使用您提供給 GoogleMap 的物件在它上面加上疊加層。MapFragment
MapFragment 是 Android Fragment 類別的子類別，允許您在 Android 片段中放置地圖。MapFragment 物件可以當成地圖的容器，並提供對 GoogleMap 物件的存取。
和
View 不同，Fragment 代表一種行為或活動中的一部分使用者介面。 您可以合併單一活動中的多個片段，以建置多窗格 UI 以及在多個活動中重複使用片段。 請參閱有關片段的 Android 文件以深入瞭解。MapView
MapView 是 Android View 類別的子類別，允許您在 Android View 片段中放置地圖。View 代表畫面的矩形區域，而且是 Android 應用程式與小工具的基礎建置區塊。MapView很像MapFragment，可以當成地圖容器，透過 GoogleMap 物件公開核心地圖功能。
以完全互動模式使用 API 時，此類別的使用者必須將所有活動生命週期方法轉送給
MapView 類別中的對應方法。生命週期方法的範例包括 onCreate()、onDestroy()、onResume() 及 onPause()。 在精簡版中使用 API 時，可以選擇性地轉送生命週期事件。 如需詳細資料，請參閱精簡版文件。地圖類型
Google Maps Android API 提供許多地圖類型。 地圖的類型規範整體的地圖呈現方式。 例如，地圖集通常包含著重於顯示邊界的政治地圖，以及顯示某城市或地區所有道路的道路地圖。
Google Maps Android API 提供四種地圖類型，以及完全不顯示地圖的選項：
- 標準
- 一般道路地圖。 道路會有一些人造特徵和重要的自然特徵，例如會顯示河流。 也可以看見道路與特徵標籤。
- 混合
- 衛星圖資料加上道路地圖。 也可以看見道路與特徵標籤。
- 衛星
- 衛星圖資料。 看不見道路與特徵標籤。
- 地形
- 地形測量資料。 地圖包括色彩、等高線與標籤，以及透視陰影。 也可以看見一些道路與標籤。
- 無
- 無地圖方塊。 地圖會轉譯為不載入任何地圖方塊的空網格。
變更地圖類型
GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);
下列影像顯示比較相同位置的一般、混合及地形地圖：
室內地圖
在高縮放層級中，地圖將顯示室內空間 (例如機場、大型購物中心、大型零售商店及大眾運輸車站) 的樓層平面圖。這些樓層平面圖稱為室內地圖，顯示於「一般」與「衛星」地圖類型 (
GoogleMap.MAP_TYPE_NORMAL 與 GoogleMap.MAP_TYPE_SATELLITE)。當使用者放大時會自動啟用，並在地圖縮小時自動淡去。在 API 中使用室內地圖
以下摘要說明 API 中的室內地圖功能：
- 您可以透過呼叫
GoogleMap.setIndoorEnabled(false)以停用室內地圖。預設會啟用室內地圖。 一次只會在一個地圖上顯示室內地圖。根據預設，這是第一個新增至您應用程式的地圖。 如果要在不同的地圖上顯示室內地圖，請先在第一個地圖上將它們停用，再於第二個地圖上呼叫setIndoorEnabled(true)。 - 如果要停用預設的樓層挑選器，請呼叫
GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false)。如需詳細資料，請參閱與地圖互動。GoogleMap 上的介面OnIndoorStateChangeListener可讓您設定當新建築物成為焦點，或在建築中啟用新樓層時要呼叫的接聽程式。如需詳細資料，請參閱與地圖互動。 GoogleMap.getFocusedBuilding()可提供目前聚焦的建築物。您接下來可以透過呼叫IndoorBuilding.getActiveLevelIndex()，以尋找目前的作用中樓層。請參閱參考文件，以查看IndoorBuilding與IndoorLevel物件中可用的所有資訊。
新增樓層平面圖
室內地圖 (樓層平面圖) 可在選取位置取得。如果您要在應用程式中著重展示的建築物沒有樓層平面圖資料，您可以：
- 直接新增樓層平面圖至「Google 地圖」。 這樣一來，「Google 地圖」的所有使用者就能使用您的樓層平面圖。
- 在您的地圖上將樓層平面圖顯示為地面疊加層或地圖方塊疊加層。 這樣只有您應用程式的使用者才能檢視您的樓層平面圖。
設定初始狀態
Maps API 可讓您針對應用程式的需求設定適當的地圖初始狀態。 您可以指定下列各項：
- 相機位置，包括：位置、縮放、方位及傾斜度。 如需相機位置的詳細資訊，請參閱變更地圖檢視。
- 地圖類型。
- 是否要在畫面上顯示縮放按鈕和/或指南針。
- 使用者可用來操縱相機的手勢。
- 是否要啟用精簡版。 精簡版地圖是地圖的點陣圖影像，可支援完整 API 提供的功能子集。
如果您已將地圖新增至活動的版面配置檔案，可以透過 XML 設定地圖的初始狀態，或如果以程式設計方式新增地圖，可以使用同樣的方式來設定。
使用 XML 屬性
本節說明如果使用 XML 版面配置檔案將地圖新增至您的應用程式，應該如何設定地圖的初始狀態。
mapType。 這可讓您指定要顯示的地圖類型： 有效值包括：none、normal、hybrid、satellite及terrain。cameraTargetLat、cameraTargetLng、cameraZoom、cameraBearing、cameraTilt。 這些可讓您指定初始相機位置。 如需相機位置與其屬性的詳細資訊，請參閱這裡。uiZoomControls、uiCompass。 這些可讓您指定是否要在地圖上顯示縮放控制項與指南針。 如需更多詳細資料，請參閱UiSettings。uiZoomGestures、uiScrollGestures、uiRotateGestures、uiTiltGestures。 這些可讓您指定要啟用/停用哪個與地圖互動的手勢。 如需詳細資料，請參閱UiSettings。zOrderOnTop。 控制是否要將地圖檢視的介面放在其視窗上方。 如需詳細資料，請參閱 SurfaceView.setZOrderOnTop(boolean)。 請注意，這將涵蓋可在地圖上顯示的所有其他檢視 (例如，縮放控制項、我的位置按鈕)。useViewLifecycle。 只有搭配MapFragment使用時才有效。 此屬性指定地圖生命週期應該繫結至片段的檢視或片段本身。如需更多詳細資料，請參閱這裡。liteMode。true的值會將地圖設定為精簡版。 精簡版地圖是地圖的點陣圖影像，可支援完整 API 提供的功能子集。此屬性的預設值為false。
如果要在您的 XML 版面配置檔案內使用這些自訂屬性，您必須先新增下列命名空間宣告。 您可以選擇任何命名空間，它不一定要是
map：
xmlns:map="http://schemas.android.com/apk/res-auto"
接著，您可以如同使用標準 Android 屬性一樣，將前置詞為
map: 的屬性新增到您的版面配置元件。
下列 XML 程式碼片段說明如何使用一些自訂選項設定
MapFragment。 相同的屬性也適用於 MapView。
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:map="http://schemas.android.com/apk/res-auto"
android:name="com.google.android.gms.maps.SupportMapFragment"
android:id="@+id/map"
android:layout_width="match_parent"
android:layout_height="match_parent"
map:cameraBearing="112.5"
map:cameraTargetLat="-33.796923"
map:cameraTargetLng="150.922433"
map:cameraTilt="30"
map:cameraZoom="13"
map:mapType="normal"
map:uiCompass="false"
map:uiRotateGestures="true"
map:uiScrollGestures="false"
map:uiTiltGestures="true"
map:uiZoomControls="false"
map:uiZoomGestures="true"/>
注意：如果您正在使用 Google Maps Mobile SDK for Work，您必須在每個屬性加上前置詞
m4b_。 例如，指定地圖類型屬性時，請使用 m4b_mapType，而不是 mapType。 或者，指定縮放控制項時，請使用 m4b_uiZoomControls，而不是 uiZoomControls 等等。以程式設計方式
本節說明如果以程式設計方式將地圖新增至您的應用程式，應該如何設定地圖的初始狀態。
如果您以程式設計方式新增
MapFragment(或 MapView)，接下來您可以透過以您指定的選項傳遞 GoogleMapOptions 物件，以設定其初始狀態。可以使用的選項和可透過 XML 使用的那些選項一樣。您可以建立 GoogleMapOptions 物件，如下所示：
GoogleMapOptions options = new GoogleMapOptions();
然後設定如下：
options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
.compassEnabled(false)
.rotateGesturesEnabled(false)
.tiltGesturesEnabled(false);
如果要在您建立地圖時套用這些選項，請執行下列其中一個動作：
- 如果您正在使用
MapFragment，請使用MapFragment.newInstance(GoogleMapOptions options)靜態程式庫方法來建構片段並傳遞自訂的設定選項。 - 如果您正在使用
MapView，請使用MapView(Context, GoogleMapOptions)建構函式並傳遞自訂的設定選項。
地圖邊框間距
此影片展示地圖邊框間距範例。
Google 地圖的設計是填滿其容器元素 (通常是
MapView 或 MapFragment) 定義的整個區域。 地圖容器的維度可定義數個地圖如何顯示和運作的層面：- 相機的目標將會反映填補區域的中心。
- 地圖控制項會放在地圖邊緣的相對位置。
- 法律資訊 (例如著作權聲明或 Google 標誌) 會出現在地圖下緣。
您可以使用
GoogleMapsetPadding() 方法，在地圖邊緣加上邊框間距。 地圖會持續填滿整個容器，但文字與控制項位置、地圖手勢及相機移動方向，運作上就有如放在較小的空間。這會導致下列變更：- 透過 API 呼叫或按下按鈕的相機移動方向 (例如，指南針、我的位置、縮放按鈕) 將會相對於填上邊框的區域。
getCameraPosition()將會傳回填上邊框的區域中心。Projection.getVisibleRegion()將會傳回填上邊框的區域。- UI 控制項會依照指定的像素數目從容器邊緣偏移。
設計和地圖有部分重疊的 UI 時，邊框間距會非常有用。 例如，下列影像中的地圖會在上邊緣與右邊緣填上邊框間距。 可見的地圖控制項與法律文字會沿著填上邊框的區域邊緣 (以綠色顯示) 顯示，同時地圖會持續填滿整個容器 (以藍色顯示)。在此範例中，您可以讓選單浮在地圖右側，而不會遮住地圖控制項。
注意：根據 Google Maps API 服務條款，您的應用程式不得移除或遮蓋 Google 標誌或著作權聲明。地圖邊框間距可讓您視需要重新放置這些元素的位置。如果您要在地圖底部顯示自訂 UI，請在地圖底部加上邊框間距，使標誌與法律聲明隨時可見。
沒有留言:
張貼留言