Auraの地図表示をLWCへ移すときの変更点まとめ

なぜ書き直しが要るのか

Auraコンポーネントは、いまも動きます。ですが公式のガイドは、Auraコンポーネントはc:タグとしてLWCを内側に含められる一方、LWCの中にAuraコンポーネントを含めることはできないと明記しています。この非対称な関係があるので、AuraをベースにLWCを部分的に足していく方向は無理なく進められても、Aura自体を書き直す作業は避けて通れません。

変わるところの一覧

Aura版の地図表示コンポーネントをLWCへ移すときに変わる項目です。

項目	Aura	LWC
コンポーネントの構成ファイル	.cmp・controller.js・helper.js・.design など複数	.html・.js・.js-meta.xmlの3点が基本
属性の受け渡し	<aura:attribute>をマークアップで宣言	JSクラスの@apiプロパティ
マークアップでの属性名	camelCase(例:mapMarkers)	ケバブケース(例:map-markers)
Apexの呼び出し	$A.enqueueActionとコールバック	@wire、または命令的呼び出し（Promise）
画面への反映	cmp.set('v.属性名', 値)	フィールドへの再代入だけで反映される
イベントの発火	event.fire()	this.dispatchEvent(new CustomEvent(...))
イベントの受け取り	<aura:handler>をマークアップで宣言	on接頭辞の属性、またはaddEventListener
配置先の指定	アプリケーション・タブを個別に作成	.js-meta.xmlのtargetsに書く

Apexクラスの変更点

Auraのコントローラは@AuraEnabledだけで、命令的な呼び出しに使っていました。LWCでも同じ形のまま使えます。

public with sharing class LightningAuraMapController {
    @AuraEnabled
    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呼び出しで使うので、cacheable=trueは必須ではありません。

コンポーネントの変更点

Auraのコントローラは、$A.enqueueActionでApexを呼び、setCallbackの中でcmp.set('v.mapMarkers', markerList)を実行して画面を更新していました。LWCでは、この一連の流れが命令的なApex呼び出しと通常のフィールド代入に置き換わります。

import { LightningElement } from 'lwc';
import getAccList from '@salesforce/apex/LightningAuraMapController.getAccList';

export default class AuraMapMigration extends LightningElement {
    mapMarkers = [{ location: {} }];
    selectedMarkerValue;

    async connectedCallback() {
        try {
            const accList = await getAccList();
            if (accList.length !== 0) {
                this.mapMarkers = accList.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
                }));
            }
        } catch (error) {
            // 実運用ではShowToastEventなどでユーザーに伝えます
            console.error(error);
        }
    }

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

Auraのaction.setCallbackに近い、命令的なApex呼び出しです。cmp.setの代わりに、フィールドへ代入するだけで画面に反映されます。

Auraでは<aura:handler name="init" value="{! this }" action="{! c.init }"/>という専用タグで初期化処理を呼んでいました。LWCにaura:handlerはありません。同じ「コンポーネント生成時に1回だけ実行する処理」は、ライフサイクルフックのconnectedCallback()に書きます。

マークアップ側の属性名も変わります。AuraのmapMarkers・selectedMarkerValue・markersTitle・listView・showFooterは、LWCではmap-markers・selected-marker-value・markers-title・list-view・show-footerとケバブケースになります。

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

AuraのshowFooter相当も指定できます。真偽値の属性は、LWCでは値を書かずに属性名だけを置くと有効になります。

配置設定の変更点

Aura版では、コンポーネントをタブとして使うために、Lightningアプリケーションの新規作成・Lightningコンポーネントタブの新規作成・作成したタブをアプリへ追加、という3つの設定操作が別々に必要でした。LWCでは、この配置先の指定を.js-meta.xmlのtargetsへ書くだけで済ませられます。

<?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__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>

apiVersionはSummer '26の67.0です。targetsに複数指定すると、その分だけ配置先の候補が増えます。

isExposedをtrueにしてtargetを1つ以上指定すると、Lightningアプリケーションビルダーの部品一覧に表示されます。あとは対象のアプリページやホームページを開き、部品として配置するだけです。Auraのときのようにタブそのものを作る操作は要りません。

ここで間違えやすい

間違い	何が起きるか
aura:attributeの名前をそのままcamelCaseでLWCのHTML属性に書く	反映されない。ケバブケースに直す
cmp.set('v.mapMarkers', ...)をLWCでも書こうとする	LWCにcmp.set相当のAPIはない。フィールドへの再代入で足りる
event.fire()をLWCでも呼ぼうとする	存在しないメソッド。this.dispatchEvent(new CustomEvent(...))に直す
<aura:handler>をLWCのマークアップに残す	LWCに同タグはない。on接頭辞の属性かaddEventListenerに直す
LWCの中に既存のAuraコンポーネントを配置しようとする	LWCはAuraコンポーネントを含められない。含められるのはAura側からLWCへの一方向だけ

確認した環境

• 2026年9月／Salesforce Summer '26（APIバージョン67.0）時点のLWC開発者ガイド（Aura Coexistence、Migrate Events）とlightning-mapコンポーネントリファレンスで、AuraとLWCの違いを確認しています

まとめ

• AuraはLWCを含められますが、LWCはAuraを含められません。この関係は一方向です
• マークアップの属性名は、AuraのcamelCaseからLWCのケバブケースに直します
• event.fire()と<aura:handler>は、this.dispatchEvent(new CustomEvent(...))と宣言的なon属性に置き換えます
• cmp.set()は不要です。LWCのフィールドは再代入するだけで画面に反映されます
• アプリケーション・タブの個別作成は、.js-meta.xmlのtargets指定で代替できます
• apiVersionはSummer '26の67.0を指定します

参考：当時の画面

記事を最初に書いた当時の画面です。いまの手順と違うところは、各画像の説明に書いています。