Controlli

Panoramica dei controlli

Le mappe visualizzate tramite l'API Maps JavaScript contengono elementi UI per consentire l'interazione dell'utente con la mappa. Questi elementi sono noti come controlli e puoi includere varianti di questi controlli nella tua applicazione. In alternativa, puoi non fare nulla e lasciare che l'API Maps JavaScript gestisca tutto il comportamento dei controlli.

La mappa seguente mostra l'insieme predefinito di controlli visualizzati dall'API Maps JavaScript:

In senso orario da sinistra in alto: Tipo di mappa, Schermo intero, Fotocamera, Street View, Scorciatoie da tastiera.

Di seguito è riportato un elenco dei controlli che puoi utilizzare nelle tue mappe:

• Il controllo Tipo di mappa è disponibile in un menu a discesa o in una barra dei pulsanti orizzontale, che consente all'utente di scegliere un tipo di mappa (ROADMAP, SATELLITE, HYBRID o TERRAIN). Questo controllo viene visualizzato per impostazione predefinita nell'angolo in alto a sinistra della mappa.
• Il controllo Schermo intero offre la possibilità di aprire la mappa in modalità a schermo intero. Questo controllo è attivo per impostazione predefinita su computer e dispositivi mobili. Nota: iOS non supporta la funzionalità a schermo intero. Il controllo per lo schermo intero non è quindi visibile sui dispositivi iOS.
• La funzionalità Controllo della videocamera include i controlli di zoom e panoramica.
• Il controllo Street View contiene un'icona Pegman che può essere trascinata sulla mappa per attivare Street View. Questo controllo viene visualizzato per impostazione predefinita nell'angolo in basso a destra della mappa.
• Il controllo di rotazione fornisce una combinazione di opzioni di inclinazione e rotazione per le mappe contenenti immagini 3D. Questo controllo viene visualizzato per impostazione predefinita in basso a destra della mappa. Per saperne di più, consulta la panoramica 3D.
• Il controllo della scala mostra un elemento della scala della mappa. Questo controllo è disattivato per impostazione predefinita.
• Il controllo delle scorciatoie da tastiera mostra un elenco di scorciatoie da tastiera per interagire con la mappa.

Non accedi a questi controlli della mappa né li modifichi direttamente. Devi invece modificare i campi MapOptions della mappa che influiscono sulla visibilità e sulla presentazione dei controlli. Puoi modificare la presentazione dei controlli quando crei un'istanza della mappa (con l'oggetto MapOptions appropriato) o modificare una mappa in modo dinamico chiamando setOptions() per cambiare le opzioni della mappa.

Non tutti questi controlli sono attivi per impostazione predefinita. Per scoprire di più sul comportamento predefinito della UI (e su come modificarlo), consulta la sezione UI predefinita di seguito.

La UI predefinita

Per impostazione predefinita, tutti i controlli scompaiono se la mappa è troppo piccola (200 x 200 px). Puoi eseguire l'override di questo comportamento impostando esplicitamente il controllo in modo che sia visibile. Consulta Aggiunta di controlli alla mappa.

Il comportamento e l'aspetto dei controlli sono gli stessi su dispositivi mobili e computer, ad eccezione del controllo per lo schermo intero (vedi il comportamento descritto nell'elenco dei controlli).

Inoltre, la gestione della tastiera è attiva per impostazione predefinita su tutti i dispositivi.

Disattiva l'UI predefinita

Potresti voler disattivare completamente i pulsanti dell'interfaccia utente predefinita dell'API. Per farlo, imposta la proprietà disableDefaultUI della mappa (all'interno dell'oggetto MapOptions) su true. Questa proprietà disattiva tutti i pulsanti di controllo dell'interfaccia utente dell'API Maps JavaScript. Tuttavia, non influisce sui gesti del mouse o sulle scorciatoie da tastiera sulla mappa base, che sono controllati rispettivamente dalle proprietà gestureHandling e keyboardShortcuts.

Il seguente codice disattiva i pulsanti della UI:

innerMap.setOptions({
    // Disable the default UI.
    disableDefaultUI: true,
});
index.ts

innerMap.setOptions({
    // Disable the default UI.
    disableDefaultUI: true,
});
index.js

Aggiungi controlli alla mappa

Potresti voler personalizzare l'interfaccia rimuovendo, aggiungendo o modificando il comportamento o i controlli della UI e assicurarti che gli aggiornamenti futuri non alterino questo comportamento. Se vuoi solo aggiungere o modificare il comportamento esistente, devi assicurarti che il controllo venga aggiunto esplicitamente alla tua applicazione.

Alcuni controlli vengono visualizzati sulla mappa per impostazione predefinita, mentre altri non vengono visualizzati, a meno che non li richiedi espressamente. L'aggiunta o la rimozione di controlli dalla mappa viene specificata nei seguenti campi dell'oggetto MapOptions, che imposti su true per renderli visibili o su false per nasconderli:

{
  cameraControl: boolean,
  mapTypeControl: boolean,
  scaleControl: boolean,
  streetViewControl: boolean,
  rotateControl: boolean,
  fullscreenControl: boolean
}

Per impostazione predefinita, tutti i controlli scompaiono se la mappa è più piccola di 200 x 200 px. Puoi eseguire l'override di questo comportamento impostando esplicitamente il controllo in modo che sia visibile. Ad esempio, la tabella seguente mostra se il controllo della fotocamera è visibile o meno, in base alle dimensioni della mappa e all'impostazione del campo cameraControl:

L'esempio seguente imposta la mappa in modo da nascondere il controllo della fotocamera e visualizzare il controllo della scala. Tieni presente che non disattiviamo esplicitamente la UI predefinita, pertanto queste modifiche si aggiungono al comportamento della UI predefinita.

innerMap.setOptions({
    cameraControl: false,
    scaleControl: true,
});
index.ts

innerMap.setOptions({
    cameraControl: false,
    scaleControl: true,
});
index.js

Opzioni di controllo

Diversi controlli sono configurabili, il che ti consente di modificarne il comportamento o l'aspetto. Ad esempio, il controllo Tipo di mappa può essere visualizzato come una barra orizzontale o un menu a discesa.

Questi controlli vengono modificati alterando i campi options di controllo appropriati all'interno dell'oggetto MapOptions al momento della creazione della mappa.

Ad esempio, le opzioni per modificare il controllo Tipo di mappa sono indicate nel campo mapTypeControlOptions. Il controllo Tipo di mappa può essere visualizzato in una delle seguenti opzioni style:

• google.maps.MapTypeControlStyle.HORIZONTAL_BAR mostra l'array di controlli come pulsanti in una barra orizzontale, come mostrato su Google Maps.
• google.maps.MapTypeControlStyle.DROPDOWN_MENU mostra un singolo controllo pulsante che consente di selezionare il tipo di mappa utilizzando un menu a discesa.
• google.maps.MapTypeControlStyle.DEFAULT mostra il comportamento predefinito, che dipende dalle dimensioni dello schermo e potrebbe cambiare nelle versioni future dell'API.

Tieni presente che se modifichi le opzioni di controllo, devi anche attivare esplicitamente il controllo impostando il valore MapOptions appropriato su true. Ad esempio, per impostare un controllo Tipo di mappa in modo che mostri lo stile DROPDOWN_MENU, utilizza il seguente codice all'interno dell'oggetto MapOptions:

  ...
  mapTypeControl: true,
  mapTypeControlOptions: {
    style: google.maps.MapTypeControlStyle.DROPDOWN_MENU
  }
  ...

L'esempio seguente mostra come modificare la posizione e lo stile predefiniti dei controlli.

innerMap.setOptions({
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [MapTypeId.ROADMAP, MapTypeId.TERRAIN],
        position: ControlPosition.TOP_CENTER,
    },
});
index.ts

innerMap.setOptions({
    mapTypeControl: true,
    mapTypeControlOptions: {
        style: MapTypeControlStyle.DROPDOWN_MENU,
        mapTypeIds: [MapTypeId.ROADMAP, MapTypeId.TERRAIN],
        position: ControlPosition.TOP_CENTER,
    },
});
index.js

In genere, i controlli vengono configurati al momento della creazione della mappa. Tuttavia, puoi modificare la presentazione dei controlli in modo dinamico chiamando il metodo setOptions() di Map e passandogli nuove opzioni di controllo.

Modifica controlli

Puoi specificare la presentazione di un controllo quando crei la mappa tramite i campi all'interno dell'oggetto MapOptions della mappa. Questi campi sono indicati di seguito:

• cameraControl attiva/disattiva il controllo della fotocamera che consente all'utente di aumentare lo zoom e spostarsi sulla mappa. Questo controllo è visibile per impostazione predefinita su tutte le mappe. Il campo cameraControlOptions specifica inoltre il CameraControlOptions da utilizzare per questo controllo.
• mapTypeControl attiva/disattiva il controllo Tipo di mappa, che consente all'utente di passare da un tipo di mappa all'altro (ad esempio Mappa e Satellite). Per impostazione predefinita, questo controllo è visibile e viene visualizzato nell'angolo in alto a sinistra della mappa. Il campo mapTypeControlOptions specifica inoltre l'MapTypeControlOptions da utilizzare per questo controllo.
• streetViewControl attiva/disattiva il controllo di Pegman che consente all'utente di attivare una panoramica in Street View. Per impostazione predefinita, questo controllo è visibile e viene visualizzato in basso a destra nella mappa. Il campo streetViewControlOptions specifica inoltre l'StreetViewControlOptions da utilizzare per questo controllo.
• rotateControl attiva/disattiva la visualizzazione di un controllo di rotazione per controllare l'orientamento delle immagini 3D. Per impostazione predefinita, la presenza del controllo è determinata dalla presenza o dall'assenza di immagini 3D per il tipo di mappa specificato allo zoom e alla posizione correnti. Puoi modificare il comportamento del controllo impostando la proprietà rotateControlOptions della mappa per specificare l'oggetto RotateControlOptions da utilizzare. Il controllo verrà visualizzato solo sulle mappe base 3D.
• scaleControl attiva/disattiva il controllo della scala che fornisce una scala della mappa. Per impostazione predefinita, questo controllo non è visibile. Se attivato, verrà sempre visualizzato nell'angolo in basso a destra della mappa. scaleControlOptions specifica inoltre l'oggetto ScaleControlOptions da utilizzare per questo controllo.
• fullscreenControl attiva/disattiva il controllo che apre la mappa in modalità a schermo intero. Per impostazione predefinita, questo controllo è attivo su computer e dispositivi Android. Se abilitato, il controllo viene visualizzato in alto a destra nella mappa. fullscreenControlOptions specifica inoltre l'oggetto FullscreenControlOptions da utilizzare per questo controllo.

Tieni presente che puoi specificare le opzioni per i controlli che disattivi inizialmente.

Posizionamento dei controlli

La maggior parte delle opzioni di controllo contiene una proprietà position (di tipo ControlPosition) che indica dove posizionare il controllo sulla mappa. Il posizionamento di questi controlli non è assoluto. L'API, invece, disporrà i controlli in modo intelligente, facendoli scorrere intorno agli elementi della mappa esistenti o ad altri controlli, entro determinati vincoli (come le dimensioni della mappa).

Esistono due tipi di posizioni di controllo: legacy e logica. Ti consigliamo di utilizzare i valori logici per supportare automaticamente i contesti di layout da sinistra a destra (LTR) e da destra a sinistra (RTL). Consulta la guida di riferimento.

Le seguenti tabelle mostrano le posizioni dei controlli supportate nei contesti LTR e RTL.

Fai clic sulle etichette per passare dalla modalità LTR a quella RTL e viceversa.

Tieni presente che queste posizioni potrebbero coincidere con quelle degli elementi UI i cui posizionamenti non possono essere modificati (come i copyright e il logo Google). In questi casi, i controlli verranno visualizzati in base alla logica indicata per ogni posizione e il più vicino possibile alla posizione indicata. Non è possibile garantire che i controlli non si sovrappongano a causa di layout complicati, anche se l'API tenterà di disporli in modo intelligente.

L'esempio seguente mostra una mappa di base con tutti i controlli attivati, in posizioni diverse.

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    // Request needed libraries.
    const [{ MapTypeControlStyle }, { ControlPosition }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('core'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;

    // Set the map's controls options.
    innerMap.setOptions({
        mapTypeControl: true,
        mapTypeControlOptions: {
            style: MapTypeControlStyle.HORIZONTAL_BAR,
            position: ControlPosition.BLOCK_START_INLINE_CENTER,
        },
        zoomControl: true,
        zoomControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_CENTER,
        },
        scaleControl: true,
        streetViewControl: true,
        streetViewControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_START,
        },
        fullscreenControl: true,
    });
}

void init();
index.ts

const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    // Request needed libraries.
    const [{ MapTypeControlStyle }, { ControlPosition }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('core'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;

    // Set the map's controls options.
    innerMap.setOptions({
        mapTypeControl: true,
        mapTypeControlOptions: {
            style: MapTypeControlStyle.HORIZONTAL_BAR,
            position: ControlPosition.BLOCK_START_INLINE_CENTER,
        },
        zoomControl: true,
        zoomControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_CENTER,
        },
        scaleControl: true,
        streetViewControl: true,
        streetViewControlOptions: {
            position: ControlPosition.INLINE_START_BLOCK_START,
        },
        fullscreenControl: true,
    });
}

void init();
index.js

Controlli personalizzati

Oltre a modificare lo stile e la posizione dei controlli API esistenti, puoi creare i tuoi controlli per gestire l'interazione con l'utente. I controlli sono widget fissi che fluttuano sopra una mappa in posizioni assolute, a differenza degli overlay, che si spostano con la mappa sottostante. Più fondamentalmente, un controllo è un elemento <div> che ha una posizione assoluta sulla mappa, mostra una UI all'utente e gestisce l'interazione con l'utente o con la mappa, di solito tramite un gestore di eventi.

Per creare un controllo personalizzato, sono necessarie alcune regole. Tuttavia, le seguenti linee guida possono fungere da best practice:

• Definisci il CSS appropriato per gli elementi di controllo da visualizzare.
• Gestisci l'interazione con l'utente o la mappa tramite i gestori di eventi per le modifiche alle proprietà della mappa o gli eventi utente (ad esempio gli eventi 'click').
• Crea un elemento <div> per contenere il controllo e aggiungi questo elemento alla proprietà controls di Map.

Ognuno di questi problemi è descritto di seguito.

Disegna controlli personalizzati

Sta a te decidere come disegnare il controllo. In genere, ti consigliamo di inserire tutta la presentazione del controllo all'interno di un singolo elemento <div> in modo da poter manipolare il controllo come un'unica unità. Utilizzeremo questo pattern di progettazione negli esempi mostrati di seguito.

La progettazione di controlli accattivanti richiede una certa conoscenza di CSS e della struttura DOM. Gli esempi di codice riportati di seguito mostrano l'aggiunta di un controllo personalizzato utilizzando sia metodi HTML dichiarativi sia metodi programmatici.

CSS dichiarativo

I seguenti stili CSS forniscono un aspetto coerente con i controlli predefiniti. Utilizza questi stili con entrambi gli esempi riportati di seguito:

.streetview-toggle-button {
  align-items: center;
  background: white;
  border: none;
  border-radius: 2px;
  box-shadow: 0 1px 4px -1px rgba(0, 0, 0, 0.3);
  color: rgb(86, 86, 86);
  cursor: pointer;
  display: flex;
  font-family: Roboto, Arial, sans-serif;
  font-size: 18px;
  font-weight: 400;
  height: 40px;
  justify-content: center;
  margin: 10px 0;
  padding: 0 17px;
}

.streetview-toggle-button:hover {
  background: #f4f4f4;
  color: #000;
}

HTML dichiarativo

Questi snippet di codice mostrano come creare un controllo personalizzato in modo dichiarativo. Nel codice HTML, per posizionare il controllo viene utilizzato un DIV con l'ID container, nidificato all'interno dell'elemento gmp-map, e il pulsante viene aggiunto al DIV. L'attributo slot è impostato su control-inline-start-block-start per posizionare il controllo nell'angolo in alto a sinistra della mappa.

<gmp-map
  center="41.027748173921374, -92.41852445367961"
  zoom="13"
  map-id="DEMO_MAP_ID">
  <div id="container" slot="control-inline-start-block-start">
    <input type="button"
    id="streetview-toggle-button"
    class="button"
    value="Click this button" />
  </div>
</gmp-map>

In JavaScript, getElementById() viene utilizzato per trovare il DIV e il pulsante, un listener di eventi viene aggiunto al pulsante e il pulsante viene aggiunto al DIV.

// Create a DIV to attach the control UI to the Map.
const container = document.getElementById("container");

// Get the control button from the HTML page.
const controlButton = document.getElementById("streetview-toggle-button");

// Add a click event listener.
controlButton.addEventListener("click", () => {
  window.alert("You clicked the button!");
});

// Add the control to the DIV.
container.append(controlButton);

JavaScript programmatico

Questo snippet di codice mostra la creazione di un controllo pulsante in modo programmatico. Gli stili CSS sono definiti sopra.

// Create a DIV to attach the control UI to the Map.
const container = document.getElementById("container");

// Position the control in the top left corner of the map.
container.slot = "control-block-start-inline-start";

// Create the control.
const controlButton = document.createElement("button");
controlButton.classList.add("streetview-toggle-button");
controlButton.textContent = "Click this button";
controlButton.type = "button";

// Add a click event listener.
controlButton.addEventListener("click", () => {
  window.alert("You clicked the button!");
});

// Add the control to the DIV.
container.append(controlButton);

Gestisci gli eventi dai controlli personalizzati

Per essere utile, un controllo deve effettivamente fare qualcosa. La funzione del controllo dipende da te. Il controllo può rispondere all'input dell'utente o alle modifiche dello stato di Map.

Per rispondere all'input dell'utente, utilizza addEventListener(), che gestisce gli eventi DOM supportati. Il seguente snippet di codice aggiunge un listener per l'evento 'click' del browser. Tieni presente che questo evento viene ricevuto dal DOM, non dalla mappa.

// Setup the click event listener: set the map to center on Chicago
var chicago = {lat: 41.850, lng: -87.650};

controlButton.addEventListener('click', () => {
  map.setCenter(chicago);
});

Rendi accessibili i controlli personalizzati

Per assicurarti che i controlli ricevano gli eventi della tastiera e vengano visualizzati correttamente dagli screen reader:

• Utilizza sempre elementi HTML nativi per pulsanti, elementi dei moduli ed etichette. Utilizza un elemento DIV solo come contenitore per i controlli nativi; non riutilizzare mai un DIV come elemento UI interattivo.
• Utilizza l'elemento label, l'attributo title o l'attributo aria-label, se opportuno, per fornire informazioni su un elemento UI.

Posiziona i controlli personalizzati

Utilizza l'attributo slot per posizionare i controlli personalizzati, specificando la posizione del controllo necessaria. Per informazioni su queste posizioni, consulta Posizionamento dei controlli sopra.

Ogni ControlPosition memorizza un MVCArray dei controlli visualizzati in quella posizione. Di conseguenza, quando i controlli vengono aggiunti o rimossi dalla posizione, l'API li aggiornerà di conseguenza.

Il codice seguente crea un nuovo controllo personalizzato (il relativo costruttore non è mostrato) e lo aggiunge alla mappa nella posizione BLOCK_START_INLINE_END (in alto a destra nel contesto LTR).

// Create a DIV to attach the control UI to the Map.
const centerControlDiv = document.createElement("div");

// Create the control. This code calls a function that
// creates a new instance of a button control.
const centerControl = createCenterControl(map);

// Append the control to the DIV.
centerControlDiv.appendChild(centerControl);

// Push the control to the BLOCK_START_INLINE_END position.
innerMap.controls[google.maps.ControlPosition.BLOCK_START_INLINE_END].push(centerControlDiv);

Per impostare la posizione di un controllo personalizzato in modo dichiarativo, imposta l'attributo slot nel codice HTML:

<gmp-map center="30.72851568848909, -81.54675994068873" zoom="12">
  <div slot="control-block-start-inline-end">
    <!-- Control HTML -->
  </div>
</gmp-map>

Esempio di controllo personalizzato

Il seguente controllo è semplice (anche se non particolarmente utile) e combina i pattern mostrati sopra. Questo controllo risponde agli eventi DOM 'click' centrando la mappa in una determinata località predefinita:

const chicago = { lat: 41.85, lng: -87.65 };

// Get the gmp-map element
const mapElement = document.querySelector('gmp-map')!;

async function init() {
    (await google.maps.importLibrary('maps')) as typeof google.maps;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the button element from the HTML
    const centerButton = document.getElementById(
        'btnCenterMap'
    ) as HTMLButtonElement;
    // Move the event listener here
    centerButton.addEventListener('click', () => {
        innerMap.setCenter(chicago);
    });
}

void init();
index.ts

const chicago = { lat: 41.85, lng: -87.65 };
// Get the gmp-map element
const mapElement = document.querySelector('gmp-map');
async function init() {
    (await google.maps.importLibrary('maps'));
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the button element from the HTML
    const centerButton = document.getElementById('btnCenterMap');
    // Move the event listener here
    centerButton.addEventListener('click', () => {
        innerMap.setCenter(chicago);
    });
}
void init();
index.js

Aggiungi lo stato ai controlli

I controlli possono anche memorizzare lo stato. L'esempio seguente è simile a quello mostrato in precedenza, ma il controllo contiene un pulsante "Imposta casa" aggiuntivo che imposta il controllo in modo che mostri una nuova posizione di casa. Per farlo, creiamo una proprietà home_ all'interno del controllo per archiviare questo stato e forniamo getter e setter per lo stato.

let innerMap: google.maps.Map;
const mapElement = document.querySelector('gmp-map')!;

let center: google.maps.LatLngLiteral | google.maps.LatLng = {
    lat: 41.85,
    lng: -87.65,
};

async function init() {
    await google.maps.importLibrary('maps');

    innerMap = mapElement.innerMap;

    // Get the button UI elements.
    const centerMapButton = document.getElementById(
        'btnCenterMap'
    ) as HTMLInputElement;
    const setCenterButton = document.getElementById(
        'btnSetCenter'
    ) as HTMLInputElement;

    // Set up the click event listener for the 'Center Map' button. Set the map
    // to the currently stored center.
    centerMapButton.addEventListener('click', () => {
        const currentCenter = center;
        innerMap.setCenter(currentCenter);
    });

    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterButton.addEventListener('click', () => {
        const newCenter = innerMap.getCenter();

        if (newCenter) {
            center = newCenter;
        }
    });
}

void init();
index.ts

let innerMap;
const mapElement = document.querySelector('gmp-map');

let center = {
    lat: 41.85,
    lng: -87.65,
};

async function init() {
    await google.maps.importLibrary('maps');

    innerMap = mapElement.innerMap;

    // Get the button UI elements.
    const centerMapButton = document.getElementById('btnCenterMap');
    const setCenterButton = document.getElementById('btnSetCenter');

    // Set up the click event listener for the 'Center Map' button. Set the map
    // to the currently stored center.
    centerMapButton.addEventListener('click', () => {
        const currentCenter = center;
        innerMap.setCenter(currentCenter);
    });

    // Set up the click event listener for 'Set Center': Set the center of
    // the control to the current center of the map.
    setCenterButton.addEventListener('click', () => {
        const newCenter = innerMap.getCenter();

        if (newCenter) {
            center = newCenter;
        }
    });
}

void init();
index.js