lightning-mapとApexで取引先の住所を地図表示する実装

なぜ標準コンポーネントで地図を出すのか

取引先の住所を一覧で眺めても、地理的な偏りには気づきにくいものです。エリアごとの商圏を見たい、訪問ルートを組みたいというときは、地図に並べたほうが早く判断できます。

Salesforceにはlightning-mapという標準コンポーネントがあり、外部の地図APIキーを自分で用意しなくても、住所や緯度経度を渡すだけでマーカー付きの地図が表示できます。この記事では、取引先の住所をApexで取得し、lightning-mapにマーカーとして渡すLWCを作ります。

Apexで住所を返す

マーカーに使う取引先を10件取得します。件数を10件に絞っているのは、後述する住所ジオコーディングの上限に合わせているためです。

public with sharing class LightningWebMapController {
    @AuraEnabled(cacheable=true)
    public static List<Account> getAccList() {
        return [
            SELECT Id, Name, BillingCountry, BillingState,
                   BillingCity, BillingStreet, Description
            FROM Account
            WHERE BillingCity != NULL
            AND BillingStreet != NULL
            ORDER BY Name
            LIMIT 10
        ];
    }
}

住所が入っている取引先を10件返します。読み取り専用のApexで、レコードは変更しません。

LWCでマーカーの配列を作る

取得した取引先を、lightning-mapが読める形のオブジェクト配列へ組み立てます。

import { LightningElement, wire } from 'lwc';
import getAccList from '@salesforce/apex/LightningWebMapController.getAccList';

export default class MapDisplay extends LightningElement {
    mapMarkers = [];
    selectedMarkerValue;

    @wire(getAccList)
    wiredAccList({ data }) {
        if (data) {
            this.mapMarkers = data.map((acc) => ({
                location: {
                    Country: acc.BillingCountry,
                    State: acc.BillingState,
                    City: acc.BillingCity,
                    Street: acc.BillingStreet
                },
                icon: 'standard:account',
                value: acc.Id,
                title: acc.Name,
                description: acc.Description
            }));
        }
    }

    handleMarkerSelect(event) {
        this.selectedMarkerValue = event.target.selectedMarkerValue;
    }
}

Apexの結果をmapMarkersへ変換します。フィールドはApexの取得結果を再代入しているだけなので@trackは不要です。

@trackは付けていません。LWCのフィールドは、テンプレートで使われていれば既定でリアクティブです。@trackが要るのは、配列やオブジェクトの中身だけを書き換えるときに限られます。ここではthis.mapMarkersを丸ごと差し替えているので不要です。選択したマーカーの値は、公式リファレンスの通りevent.target.selectedMarkerValueから取ります。event.target.selectedMarkerというプロパティは存在しないので、値が取れません。

<template>
    <lightning-map
        map-markers={mapMarkers}
        selected-marker-value={selectedMarkerValue}
        markers-title="取引先リスト"
        list-view="auto"
        onmarkerselect={handleMarkerSelect}>
    </lightning-map>
</template>

lightning-mapへマーカー配列と選択中の値を渡します。属性名はJavaScript側のcamelCaseに対してケバブケースになります。

マーカーの位置をどう指定するか

mapMarkersの各要素が持つlocationには、住所と緯度経度のどちらかを指定します。

titleは吹き出しの見出し文字列でHTMLタグは使えません。descriptionは一部のHTMLタグ(b・br・em・h1〜h6・p・strongなど)だけ使えます。iconはLightning Design Systemのアイコン名しか指定できず、任意の画像URLは使えません。

表示できる件数とズーム

公式リファレンスには、地図1つあたりの件数とズームの範囲が明記されています。

⚠️ 住所だけで10件を超えるマーカーを出したいときは、取引先の地理コード項目（BillingLatitude・BillingLongitude）のように、あらかじめ持たせた緯度経度を渡す構成にします。住所を11件以上渡しても、10件を超えた分は座標に変換されません。

Homeページへ配置する

.js-meta.xmlでコンポーネントを公開し、配置先を指定します。apiVersionはSummer '26の67.0へ上げました。

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>67.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>

apiVersionタグはSalesforce API version 45.0以上を指定する決まりで、現在は指定自体が必須です。当時の50.0から67.0へ上げています。

動作を確かめる手順です。

1. 確認用の取引先を作る

   取引先レコードを新規作成し、取引先名・都道府県・市区町村・番地を入力して保存します。住所は実在する場所でなくてもジオコーディングできる形式であれば構いません。

2. Lightningアプリのホームページを開く

   設定のLightningアプリケーションビルダーで、対象アプリのホームページに本コンポーネントを配置し、有効化します。

3. アプリケーションランチャーからアプリを開く

   配置したアプリを開き、ホームタブに地図が表示されることを確かめます。

4. 作成した取引先を選択する

   マーカー一覧または地図上のマーカーから、作成した取引先を選びます。該当の場所にピンが立ち、吹き出しに取引先名と説明が表示されれば成功です。

ここで間違えやすい

確認した環境

• 2026年9月／Salesforce Summer '26（APIバージョン67.0）時点のlightning-mapコンポーネントリファレンスとLWC開発者ガイドで、マーカーの仕様と.js-meta.xmlの決まりを確認しています
• 開発者コンソールやVS Codeで、ご自身の組織のApexクラス名に合わせて確かめてください

まとめ

• lightning-mapのマーカーは、住所（Country・PostalCode・State・City・Street）か緯度経度（Latitude・Longitude）で位置を指定します
• Streetを指定するときは、City・Country・PostalCode・Stateの少なくとも1つも合わせて指定します
• 住所からのジオコーディングは1つの地図につき最大10件です。緯度経度指定のマーカーは別枠で最大95件まで追加できます
• マーカー選択イベントの値はevent.target.selectedMarkerValueから取得します。selectedMarkerでは値が取れません
• .js-meta.xmlのapiVersionは67.0（Summer '26）へ上げました。指定自体が現在は必須です