세일즈포스 LWC로 lightning-map 활용한 지도 구현 가이드 (2부)

LWC에서 <lightning-map>을 활용하여 지도를 구현하는 방법을 자세히 알아보겠습니다. Apex로 생성한 샘플데이터의 정보를 가져오고 LWC로 데이터를 받아 지도에 표시하도록 하겠습니다.

 

<lightning-map>의 mapMarkers

Marker Properties

Property	Type	Description
location	object	Address elements (City, Country, PostalCode, State, and Street) to be geocoded, or a set of latitude and longitude coordinates. If you specify address elements and coordinates for one location, the map uses the coordinates. To support reliable geocoding of addresses, if you specify Street, you must also specify at least one of City, Country, PostalCode, or State.
title	string	Title text for the location, displayed in the location list and in the info window when you click a marker. HTML tags aren't supported and are displayed as unescaped markup.
description	string	Text describing the location, displayed in the info window when you click a marker or location title. A subset of HTML tags is supported. See Using HTML Tags in Descriptions.
icon	string	The icon that's displayed next to the location title in the list. Only Lightning Design System icons are supported. Custom icons are currently not supported in the location list. The default icon is standard:location. For more information, see Displaying Multiple Addresses and a Title.
value	string	An optional unique identifier for a marker. When you select a marker, its value is assigned to the selected-marker-value attribute.
type	string	A type of shape to use instead of the default map marker. Accepted values are Circle, Rectangle, and Polygon. See Marking Locations with Shapes.
mapIcon	object	A custom SVG icon to use instead of the default map marker. See Marking Locations with Custom Icons.

 

mapMarkers 예시

mapMarkers = [
    {
        location: {
            Street: '1 Market St',
            City: 'San Francisco',
            Country: 'USA',
        },
        title: 'The Landmark Building',
        description:
            'Historic <b>11-story</b> building completed in <i>1916</i>',
    },
];

 

개발

Apex로 아이스크림 가게 정보 SOQL로 가져오기

@AuraEnabled(cacheable=true)
    public static List<Account> initialize(){
        return [SELECT ID, Name, CompanyEmail__c, Phone, BillingAddress, BillingLatitude, BillingLongitude FROM Account WHERE BillingCity != NULL];
    }

 

LWC로 <lightning-map> 구현

Wire로 데이터 가져오기

//IceCreamStoreMap

import {LightningElement, wire} from 'lwc';
import init from "@salesforce/apex/IceCreamStoreMapController.initialize"

export default class IceCreamStoreMap extends LightningElement {
        @wire(init)
        stores({data, error}){
            console.log('data >> ' + JSON.stringify(data));
          }
            console.log('error >> ' + error)
        }
    }
}

• Apex에서 구현한 initialize 함수를 LWC의 wire를 통해 호출하여 데이터를 가져오도록 하겠습니다.
• 가져온 데이터는 위에 표기한 예시와 같은 구조를 구성하고 있습니다.

{
        "Id": "001J2000005Unj7IAC",
        "Name": "Scoops Delight",
        "CompanyEmail__c": "info@scoopsdelight.com",
        "Phone": "123-456-7890",
        "BillingAddress": {
          "street": "123 Elm St",
          "city": "Metropolis",
          "state": "NY",
          "postalCode": "10001",
          "country": "USA",
          "geocodeAccuracy": "Street"
        },
        "BillingLatitude": "40.714039000000000",
        "BillingLongitude": "-74.004460000000000"
}

받아온 데이터 가공하기

export default class IceCreamStoreMap extends LightningElement {
    mapMarkers = [];  // 맵에 표시할 데이터를 담을 변수
    isReady  = false; // 데이터가 준비되면 true

    @wire(init)
    stores({data, error}){
        if(data){
            data.forEach(mapMarker => {
                this.mapMarkers.push({
                    location : {
                        Latitude: mapMarker.BillingLatitude,
                        Longitude: mapMarker.BillingLongitude,
                        City: mapMarker.BillingAddress.city,
                        Country: mapMarker.BillingAddress.country,
                        PostalCode: mapMarker.BillingAddress.postalCode,
                        State: mapMarker.BillingAddress.state,
                        Street: mapMarker.BillingAddress.street
                    },
                    title: mapMarker.Name,
                    value: mapMarker.Id,
                    description: `${mapMarker.Name}\n 
                                  ${mapMarker.CompanyEmail__c}
                                  ${mapMarker.Phone}`,
                    icon: 'utility:checkin'
                });
            })
            this.isReady = true;
        }else{
            console.log('error >> ' + JSON.stringify(error, null, 2));
        }
    }
}

• <lightning-map>의 map-markers의 값은 리스트 타입을 받고 있습니다.
• wire를 통해 가져온 데이터를 forEach를 통해 mapMarkers에 하나씩 넣어줍니다.
• isReady는 변수는 dynamic rendering에 필요한 변수입니다. 이 변수를 활용하지 않는 경우 데이터가 준비되기전에 <lightning-map>이 먼저 렌더링이 되는데 이때 받아온 데이터를 반영하지 못 해 0개로 뜨는 현상이 발생합니다.
• location: 지도에 표시할 위치 정보를 담습니다.
• title: 맵 마커를 선택했을 때 뜨는 Tooltip의 헤더입니다.
• description: 맵 마커를 선택했을 때 뜨는 Tooltip의 내용입니다.
• icon: 맵 리스트의 아이콘을 정의합니다.

지도에 데이터 표시하기 (Map Markers)

<template>
    <template lwc:if={isReady}>
        <lightning-map map-markers={mapMarkers}> </lightning-map>
    </template>
</template>

 

Map List 보여주기

list-view="visible"
list-view="hidden"
list-view="auto"

• 리스트가 한 개 일때는 자동으로 hidden 처리 됨. 한 개일때도 리스트 뷰를 보여주고 싶다면 "visible"을 명시적으로 줘야함. 

 

onmarkerselect 활용 해보기

onmarkerselect를 활용하여 맵의 마커를 선택했을 때의 이벤트를 처리할 수 있습니다.

현재 상태는 마커를 선택했을 때 Tooltip만 뜨고 별 이벤트는 없습니다.

이번 작업을 통해 다음의 기능을 구현하고자 합니다.

• 마커 선택 시 해당 마커로 화면 중심 이동.
• 마커 선택 시 해당 마커로 확대.

import {LightningElement, wire} from 'lwc';
import init from "@salesforce/apex/IceCreamStoreMapController.initialize"

export default class IceCreamStoreMap extends LightningElement {
    mapMarkers    = [];
    mapMarkerObj  = new Object();
    isReady       = false;
    zoomLevel     = 5;  // 지도 기본 zoom 값을 5로 지정하였습니다. 
    center        = new Object();

    @wire(init)
    stores({data, error}){
        if(data){
            data.forEach(mapMarker => {
              // mapMarkerValue 변수를 새롭게 생성하였습니다.
                let mapMarkerValue = {
                    location : {
                        Latitude: mapMarker.BillingLatitude,
                        Longitude: mapMarker.BillingLongitude,
                        City: mapMarker.BillingAddress.city,
                        Country: mapMarker.BillingAddress.country,
                        PostalCode: mapMarker.BillingAddress.postalCode,
                        State: mapMarker.BillingAddress.state,
                        Street: mapMarker.BillingAddress.street
                    },
                    title: mapMarker.Name,
                    value: mapMarker.Id,
                    description: `${mapMarker.Name}\n 
                                  ${mapMarker.CompanyEmail__c}
                                  ${mapMarker.Phone}`,
                    icon: 'utility:checkin'
                };
                this.mapMarkers.push(mapMarkerValue);

                // mapMarkerObj를 통해 마커 선택 시 해당 마커의 주소를 center로 넣고자 합니다.
                this.mapMarkerObj[mapMarker.Id] = {location: mapMarkerValue.location};
            })
            this.isReady = true;
        }else{
            console.log('error >> ' + JSON.stringify(error, null, 2));
        }
    }

    markerSelectHandler(event){
        this.zoomLevel = 15;
        this.center    = this.mapMarkerObj[event.target.selectedMarkerValue];
    }
}

<template>
    <template lwc:if={isReady}>
        <lightning-map map-markers={mapMarkers}
                       list-view="visible"
                       zoom-level={zoomLevel}
                       center={center}
                       onmarkerselect={markerSelectHandler}> </lightning-map>
    </template>
</template>

• 맵 마커가 선택됬을 경우 선택된 마커의 value로 mapMarkerObj의 키 값을 찾아 해당 값의 주소 정보를 center로 넣어줍니다.
• zoomLevel은 15로 지정하였습니다.
  • 데스크탑 1-22 범위 지원.
  • 모바일 1-20 범위 지원.

options 활용 해보기

Property	Default Value	Description
draggable	true	Enables dragging to pan the map with the mouse. Set to false to prevent dragging. This property affects the map only. Markers aren't draggable.
zoomControl	true	Shows the +/- zoom controls on the bottom of the map. Set to false to remove the controls and prevent zooming.
scrollwheel	true	Permits zooming with the mouse wheel. Set to false to disable zooming with the mouse wheel when zooming is enabled. If zoomControl is false or disableDefaultUI is true, the scrollwheel setting has no effect because these settings disable zooming.
disableDefaultUI	false	Set to true to remove Map/Satellite and +/- zoom buttons. The satellite view and zooming are disabled. Mouse scrolling and dragging is not affected by disableDefaultUI.
disableDoubleClickZoom	false	Set to true to disable zooming with a mouse double-click when zooming is enabled.

 

 

고려 사항

1. 지도에 표시되는 위치가 완전히 정확하지는 않습니다.
2. 경험상 Data Integration Rules를 통해 생성되는 위도 경도 값이 실제 위치와 다른 경우가 많았습니다. 정확한 위치가 요구되는 경우 커스텀 필드를 생성하여 직접 값을 넣는것을 권합니다.
3. Geocoding을 통해 최대 10개까지 주소 값을 위도/경도 값으로 자동으로 바꾸어 줍니다.
4. 지도에는 최대 100개까지 표시할 수 있습니다 (Geocoding된 데이터 최대 10 개 포함).
   • Geocoding된 데이터 최대 10 개 없이 위도 경도 값이 있는 데이터로도 100개 표현 가능.

 

마무리

Apex와 LWC를 활용하여 <lightning-map>을 구현하는 방법을 알아보았습니다. 

다음 글에서는 lightning-map에 어떻게 CSS를 적용하는지 알아보도록 하겠습니다.