出典:ArcGIS Maps SDK for Kotlin - Tutorials - Display a map
このチュートリアルでは ArcGIS Maps SDK for Kotlin を使用して、マップとベースマップ レイヤーを表示する方法を紹介します。
マップには、地理データのレイヤーが含まれています。マップには、ベースマップ レイヤーと、オプションで 1 つ以上のデータ レイヤーを追加できます。マップ ビューを使用し、場所とズーム レベルを設定することで、マップの特定の領域を表示できます。
このチュートリアルでは、地形図ベースマップ レイヤーを使用して、富士山付近を表示する地図を作成します。
このチュートリアルのトピックの背景情報については、Mapping API and location services guide の Maps (2D) と ベースマップ を参照してください。
このチュートリアルを実施するには、以下が必要です。
Android Studio を使用してアプリを作成し、API を参照するように構成します。
Android Studio を開きます。
プロジェクトのツール ウィンドウで、現在のビューが Android であることを確認してください。チュートリアルの説明では、そのビューを参照しています。
ビュー名が Android 以外の名前 (プロジェクトやパッケージなど) の場合、プロジェクト ツール ウィンドウのタイトルバーの左端のコントロールをクリックし、リストから Android を選択します。
Android ビューから、[Gradle Scripts] > [build.gradle.kts (Project: Display_a_map)] を開きます。ファイルの内容を次のコードに置き換えます。
build.gradle.kts (Project: Display_a_map)
// すべてのサブプロジェクト/モジュールに共通の構成オプションを追加できる最上位のビルド ファイル
plugins {
alias(libs.plugins.android.application) apply false
alias(libs.plugins.kotlin.android) apply false
alias(libs.plugins.kotlin.compose) apply false
}
Android ビューから、[Gradle Scripts] > [build.gradle.kts (Module: app)] を開きます。ファイルの内容を次のコードに置き換えます。
build.gradle.kts (Module: app)
plugins {
alias(libs.plugins.android.application)
alias(libs.plugins.kotlin.android)
alias(libs.plugins.kotlin.compose)
}
android {
namespace = "com.example.app"
compileSdk = libs.versions.compileSdk.get().toInt()
defaultConfig {
applicationId = "com.example.app"
minSdk = libs.versions.minSdk.get().toInt()
targetSdk = libs.versions.targetSdk.get().toInt()
versionCode = 1
versionName = "1.0"
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
vectorDrawables {
useSupportLibrary = true
}
}
buildTypes {
release {
isMinifyEnabled = false
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
}
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}
buildFeatures {
compose = true
}
composeOptions {
kotlinCompilerExtensionVersion = "1.5.12"
}
packaging {
resources {
excludes += "/META-INF/{AL2.0,LGPL2.1}"
}
}
}
dependencies {
implementation(libs.androidx.core.ktx)
implementation(libs.androidx.lifecycle.runtime.ktx)
implementation(libs.androidx.activity.compose)
implementation(platform(libs.androidx.compose.bom))
implementation(libs.androidx.ui)
implementation(libs.androidx.ui.graphics)
implementation(libs.androidx.ui.tooling.preview)
implementation(libs.androidx.material3)
testImplementation(libs.junit)
androidTestImplementation(libs.androidx.junit)
androidTestImplementation(libs.androidx.espresso.core)
androidTestImplementation(platform(libs.androidx.compose.bom))
androidTestImplementation(libs.androidx.ui.test.junit4)
debugImplementation(libs.androidx.ui.tooling)
debugImplementation(libs.androidx.ui.test.manifest)
// ArcGIS Maps for Kotlin - SDK dependency
implementation(libs.arcgis.maps.kotlin)
// Toolkit dependencies
implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom))
implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose)
// Additional modules from Toolkit, if needed, such as:
// implementation(libs.arcgis.maps.kotlin.toolkit.authentication)
}
Android Studio の [New Project] ウィザードで生成されるモジュール レベルの build.gradle.kts
ファイルでは、Android と Kotlin のツールのバージョンが宣言されます。Kotlin Compiler (kotlinOptions
ブロック) のオプションは互換性がなければなりません。互換性は Android の Compose to Kotlin Compatibility Map を参照することで確認できます。
build.gradle.kts (Module: app)
kotlinOptions {
jvmTarget = "17"
}
composeOptions {
kotlinCompilerExtensionVersion = "1.5.12"
}
Android ビューから、[Gradle Scripts] > [libs.versions.toml] を開きます。[version]
セクションで、ArcGIS Maps SDK for Kotlin のバージョン番号を宣言します。また、[libraries]
セクションには、以下のライブラリの宣言を追加します。
ArcGIS Maps SDK for Kotlin SDK
ArcGIS Maps SDK for Kotlin Toolkit BOM
必要な Toolkit コンポーネント
このチュートリアルでは、コンポーザブル MapView を含む geoview-compose
コンポーネントのみが必要です。
Toolkit BOM のバージョンは、宣言したすべての Toolkit コンポーネントに適用されます。
Gradle バージョン カタログは依存関係のバージョンを宣言するための標準的な Android のアプローチです。build.gradle.kts
でバージョン番号を指定したり、version.gradle
でバージョン番号を列挙するよりも推奨されます。Android Studio の最近のリリースでは、[New Project Wizard] がこの標準をサポートする build.gradle.kts
と gradle/libs.version.toml
ファイルを生成します。
Gradle バージョン カタログでは、BOM ファイルを使用して、BOM 内のすべての成果物に対して単一のバージョン番号を指定することもできます。詳細については、ArcGIS Maps SDK for Kotlin Toolkit の README の Using the BOM を参照してください。
gradle/libs.versions.toml
[versions]
arcgisMapsKotlin = "200.6.0"
[libraries]
arcgis-maps-kotlin = { group = "com.esri", name = "arcgis-maps-kotlin", version.ref = "arcgisMapsKotlin" }
arcgis-maps-kotlin-toolkit-bom = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-bom", version.ref = "arcgisMapsKotlin" }
arcgis-maps-kotlin-toolkit-geoview-compose = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-geoview-compose" }
# Additional modules from Toolkit, if needed, such as:
# arcgis-maps-kotlin-toolkit-authentication = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-authentication" }
libs.versions.toml
を手で編集しないでください。代わりに、以下のコードを展開し、展開した内容をすべてコピーして libs.versions.toml
ファイルに貼り付け、新規プロジェクト ウィザードで生成された元の内容を置き換えてください。
[versions]
arcgisMapsKotlin = "200.6.0"
# Version numbers added by Android Studio New Project Wizard
agp = "8.7.1"
kotlin = "2.0.0"
coreKtx = "1.13.1"
junit = "4.13.2"
junitVersion = "1.2.1"
espressoCore = "3.6.1"
lifecycleRuntimeKtx = "2.8.4"
activityCompose = "1.9.3"
composeBom = "2024.10.00"
# Other version numbers
compileSdk = "35"
minSdk = "26"
targetSdk = "35"
[libraries]
arcgis-maps-kotlin = { group = "com.esri", name = "arcgis-maps-kotlin", version.ref = "arcgisMapsKotlin" }
arcgis-maps-kotlin-toolkit-bom = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-bom", version.ref = "arcgisMapsKotlin" }
arcgis-maps-kotlin-toolkit-geoview-compose = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-geoview-compose" }
# Additional modules from Toolkit, if needed, such as:
# arcgis-maps-kotlin-toolkit-authentication = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-authentication" }
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-ui = { group = "androidx.compose.ui", name = "ui" }
androidx-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
androidx-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
androidx-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
プロジェクト ツール ウィンドウから、[Gradle Scripts] > [settings.gradle.kts] を開きます。ファイルの内容を次のコードに置き換えます。
settings.gradle.kts (Display a map)
pluginManagement {
repositories {
google {
content {
includeGroupByRegex("com\\.android.*")
includeGroupByRegex("com\\.google.*")
includeGroupByRegex("androidx.*")
}
}
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") }
}
}
rootProject.name = "Display a map"
include(":app")
Gradle の変更を同期します。[Sync now] プロンプトをクリックするか、ツールバーの更新アイコン (Sync Project with Gradle Files) をクリックします。同期に数分かかるかもしれません。
プロジェクト ツール ウィンドウから、[app] > [manifests] > [AndroidManifest.xml] を開きます。Android マニフェストを更新して、インターネット接続を許可します。
これらの新しい要素を manifest
要素内に挿入します。 他のステートメントを変更または削除しないでください。
今後追加する ArcGIS の機能によっては、マニフェストに追加のアクセス許可を追加する必要がある可能性があります。
AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
// 追加開始
<uses-permission android:name="android.permission.INTERNET"/>
// 追加終了
プロジェクト ツール ウィンドウから、[app] > [Kotlin+java] > [com.example.app] を右クリックし、リストから [New] > [package] を選択します。パッケージ名に com.example.app.screens と入力し、キーボードの [Enter] キーを押します。このステップで、すべての UI ファイルを含む新しいパッケージが作成されます。
作成した screens パッケージを右クリックし、リストから [New] > [Kotlin Class/File] を選択します。ポップアップ ウィンドウで [File] を選択し、ファイル名に MainScreen と入力し、キーボードの [Enter] キーを押します。
MainScreen.kt で、Android Studio によって自動的に挿入されたコード行をすべて削除します。次に、以下のオプトイン アノテーション、パッケージ名、インポートを追加します。
以下のコード ブロックでコンポーザブル関数 com.arcgismaps.tookit.geoviewcompose.MapView をインポートしていることを確認してください。これは ArcGIS Maps SDK for Kotlin Toolkit で定義されています。コンポーザブルに対応したコードでは ArcGIS Maps SDK API の com.arcgismaps.mapping.view.MapView という名前のクラスは使用しないでください。
MainScreen.kt
@file:OptIn(ExperimentalMaterial3Api::class)
package com.example.app.screens
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import com.arcgismaps.mapping.ArcGISMap
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.toolkit.geoviewcompose.MapView
import com.example.app.R
ArcGISMap を返す createMap()
という名前のトップ レベル関数を作成します。
MainScreen.kt
fun createMap(): ArcGISMap {
}
BasemapStyle.ArcGISTopographic を使用して ArcGISMap を作成し、マップ上で apply{}
を呼び出します。この関数は ArcGISMap を返します。
apply{}
の詳細については Kotlin の Scope functions を参照してください。
MainScreen.kt
fun createMap(): ArcGISMap {
// 追加開始
return ArcGISMap(BasemapStyle.ArcGISTopographic).apply {
}
// 追加終了
}
apply
ブロックで、x (経度) と y (緯度) の座標と縮尺を持つ Viewpoint を作成します。この Viewpoint を ArcGISMap の initialViewpoint
プロパティに割り当てます。
また、ベースマップのデフォルトのラベル表示は英語のため、日本語に変更します。
MainScreen.kt
fun createMap(): ArcGISMap {
// 追加開始
val basemapStyleParams = BasemapStyleParameters()
basemapStyleParams.languageStrategy = BasemapStyleLanguageStrategy.Specific(Locale("ja"))
// 追加終了
return ArcGISMap(Basemap(BasemapStyle.ArcGISTopographic, basemapStyleParams)).apply {
// 追加開始
initialViewpoint = Viewpoint(
latitude = 35.360626,
longitude = 138.727363,
scale = 200000.0
)
// 追加終了
}
}
MapView を呼び出す MainScreen
という名前のコンポーザブル関数を作成します。
MainScreen.kt
// 追加開始
@Composable
fun MainScreen() {
}
// 追加終了
fun createMap(): ArcGISMap {
・・・
remember ブロックを追加し、その中で createMap()
を呼び出します。そして remember
を map
というローカル変数に割り当てます。
トップ レベルのコンポーザブル関数は再構成時に状態を保持するために使用されます。
MainScreen.kt
@Composable
fun MainScreen() {
// 追加開始
val map = remember {
createMap()
}
// 追加終了
}
Android Jetpack Compose からいくつかのコンポーザブル関数を呼び出します。Scaffold を呼び出し、アプリ名 (R.string.app_name
) を含む Text で TopAppBar を渡します。
MainScreen.kt
@Composable
fun MainScreen() {
val map = remember {
createMap()
}
// 追加開始
Scaffold(
topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
) {
}
// 追加終了
}
Scaffold の末尾のラムダで、ArcGIS Maps SDK for Kotlin Toolkit で定義されている MapView コンポーザブルを呼び出し、最大サイズとデフォルトのパディングを持つ Modifier を設定します。そして、map
を arcGISMap
パラメーターとして渡します。
MainScreen.kt
@Composable
fun MainScreen() {
val map = remember {
createMap()
}
Scaffold(
topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
) {
// 追加開始
MapView(
modifier = Modifier.fillMaxSize().padding(it),
arcGISMap = map
)
// 追加終了
}
}
[app] > [kotlin+java] > [com.example.app] の MainActivity.kt を開きます。パッケージ宣言 (最初の行) と MainActivity
クラスの定義以外のすべての行を削除します。
MainActivity.kt
package com.example.app
class MainActivity : ComponentActivity() {
}
MainActivity.kt に import 文を追加します。
MainActivity.kt
package com.example.app
// 追加開始
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import com.arcgismaps.ApiKey
import com.arcgismaps.ArcGISEnvironment
import com.example.app.screens.MainScreen
import com.example.app.ui.theme.DisplayAMapTheme
// 追加終了
class MainActivity : ComponentActivity() {
}
onCreate() ライフサイクル関数の setContent()
ブロックでは、デフォルトのテーマ設定を適用して、コンポーザブル関数である MainScreen
を呼び出します。これを行うには、onCreate()
に以下のコードを追加します。
MainActivity.kt
class MainActivity : ComponentActivity() {
// 追加開始
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
DisplayAMapTheme {
MainScreen()
}
}
}
// 追加終了
}
ArcGIS Online でホストされているサービス、Web マップ、Web シーンにアクセスできるようにするには、アクセストークンが必要です。 まだ作成していない場合は、ArcGIS Location Platform のダッシュボード に移動して、API キーを取得します。作成方法は「API キーの取得」をご覧ください。 このチュートリアルでは、ロケーションサービスのベースマップの権限が有効になっている API キーが必要です。
API キーを使用すると、ArcGIS Online でホストされているサービス、Web マップ、および Web シーンにアクセスできるようになります。
MainActivity
クラスで setApiKey()
メソッドを作成し、ApiKey.create() を呼び出し、API キーを文字列として渡すことで、ArcGISEnvironment.apiKey プロパティを設定します。引用符を忘れないでください。
MainActivity.kt
class MainActivity : ComponentActivity() {
・・・
}
// 追加開始
private fun setApiKey() {
ArcGISEnvironment.apiKey = ApiKey.create("API キー")
}
// 追加終了
このチュートリアルでは便宜上、API キーをコードに直接格納していますが、API キーをソース コードに格納するのはベスト プラクティスではありません。
onCreate() ライフサイクル メソッド内で setContent{} の前に setApiKey() を呼び出します。
MainActivity.kt
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// 追加開始
setApiKey()
// 追加終了
setContent {
DisplayAMapTheme {
MainScreen()
}
}
}
}
[Run] > [Run] > [app] をクリックして、アプリを実行します。
Android Studio では、アプリを実行するのに、実際の Android 端末と Android エミュレータの 2 通りの方法があります。
パソコンと Android 端末を、USB または Wi-Fi で接続します。詳しくは、「Android デバイスを接続する方法」をご覧ください。
Android エミュレータで動作させるための AVD(Android Virtual Device)を作成します。 詳しくは、「Android Emulator 上でアプリを実行する」をご覧ください。
Android Studio でアプリをビルドして実行する場合、まずデバイスを選択する必要があります。Android Studio のツールバーから、現在利用可能なデバイス(仮想および物理の両方)のドロップダウンリストにアクセスできます。
ツールバーのリストにアクセスできない場合は、[Tools] → [Device Manader] をクリックします。
富士山を中心に、地形ベースマップレイヤーが追加されたマップが表示されます。マップビュー上でマウス ホイールをダブルクリック、ドラッグ、およびスクロールして、マップを操作します。
「Web マップの作成」のガイドで Web マップを作成している場合は、作成した Web マップを ArcGISMap クラスから参照することができます。
プロジェクト ツール ウィンドウから [app] > [Kotlin+java] > [com.example.app] > [screens] の MainScreen.kt を開きます。
MainScreen.kt に以下のインポートを追加します。
MainScreen.kt
import com.arcgismaps.mapping.PortalItem
import com.arcgismaps.portal.Portal
createMap() 関数を以下のように記述します。
MainScreen.kt
fun createMap(): ArcGISMap {
val portal = Portal(
url = "https://www.arcgis.com", // 使用する ArcGIS ポータルの URL を記述
connection = Portal.Connection.Anonymous // ArcGIS ポータルへのアクセス方法を設定
)
val portalItem = PortalItem(
portal = portal,
itemId = "<Web マップの ID>"
)
return ArcGISMap(item = portalItem)
}
アプリの動作が確認できたら ArcGIS の セキュリティと認証について学びましょう!