Espressioni di stile basate sui dati (Web SDK)

Articolo
10/18/2023

Le espressioni consentono di applicare la logica di business alle opzioni di applicazione di stili che osservano le proprietà definite in ogni forma in un'origine dati. Le espressioni possono filtrare i dati in un'origine dati o in un livello. Le espressioni possono essere costituite da logica condizionale, ad esempio istruzioni if. E possono essere usati per modificare i dati usando: operatori stringa, operatori logici e operatori matematici.

Gli stili basati sui dati riducono la quantità di codice necessaria per implementare la logica di business per lo stile. Se usato con i livelli, le espressioni vengono valutate in fase di rendering in un thread separato. Questa funzionalità offre prestazioni migliori rispetto alla valutazione della logica di business nel thread dell'interfaccia utente.

Questo video offre una panoramica dello stile basato sui dati in Mappe di Azure Web SDK.

Le espressioni sono rappresentate come matrici JSON. Il primo elemento di un'espressione nella matrice è una stringa che specifica il nome dell'operatore di espressione. Ad esempio, "+" o "case". Gli elementi successivi (se presenti) sono gli argomenti dell'espressione. Ogni argomento è un valore letterale (stringa, numero, booleano o ) o nullun'altra matrice di espressioni. Lo pseudocodice seguente definisce la struttura di base di un'espressione.

[ 
    expression_operator, 
    argument0, 
    argument1, 
    …
]

L'SDK Web di Mappe di Azure supporta molti tipi di espressioni. Le espressioni possono essere usate autonomamente o in combinazione con altre espressioni.

Tipo di espressioni	Descrizione
Espressione di aggregazione	Espressione che definisce un calcolo elaborato su un set di dati e che può essere usata con l'opzione `clusterProperties` di un oggetto `DataSource`.
Espressioni booleane	Le espressioni booleane forniscono un set di espressioni di operatori booleani per la valutazione di confronti booleani.
Espressioni di colore	Le espressioni di colore semplificano la creazione e la modifica dei valori dei colori.
Espressioni condizionali	Le espressioni condizionali forniscono operazioni logiche simili alle istruzioni if.
Espressioni di dati	Fornisce l'accesso ai dati della proprietà in una funzionalità.
Interpolare ed eseguire l'interpolazione delle espressioni step	È possibile usare espressioni interpolate e passo per calcolare i valori lungo una curva interpolata o una funzione passo.
Espressioni specifiche del livello	Espressioni speciali applicabili solo a un singolo livello.
Espressioni matematiche	Fornisce operatori matematici per eseguire calcoli basati sui dati all'interno del framework delle espressioni.
Espressioni dell'operatore String	Le espressioni dell'operatore stringa eseguono operazioni di conversione su stringhe, ad esempio la concatenazione e la conversione della distinzione tra maiuscole e minuscole.
Espressioni di tipo	Le espressioni di tipo forniscono strumenti per il test e la conversione di tipi di dati diversi, ad esempio stringhe, numeri e valori booleani.
Espressioni di associazione di variabili	Le espressioni di associazione di variabili archiviano i risultati di un calcolo in una variabile e fanno riferimento altrove in un'espressione più volte senza dover ricalcolare il valore archiviato.
Espressione zoom	Recupera il livello di zoom corrente della mappa in fase di rendering.

Tutti gli esempi in questo documento usano la funzionalità seguente per illustrare i diversi modi in cui è possibile usare i diversi tipi di espressioni.

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-122.13284, 47.63699]
    },
    "properties": {
        "id": 123,
        "entityType": "restaurant",
        "revenue": 12345,
        "subTitle": "Building 40", 
        "temperature": 64,
        "title": "Cafeteria", 
        "zoneColor": "purple",
        "abcArray": ["a", "b", "c"],
        "array2d": [["a", "b"], ["x", "y"]],
        "_style": {
            "fillColor": "red"
        }
    }
}

Espressioni di dati

Le espressioni di dati forniscono l'accesso ai dati della proprietà in una funzionalità.

Expression	Tipo restituito	Descrizione
`['at', number, array]`	value	Recupera un elemento da una matrice.
`['geometry-type']`	stringa	Ottiene il tipo di geometria della funzionalità: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon.
`['get', string]`	value	Ottiene il valore della proprietà dalle proprietà della funzionalità corrente. Restituisce Null se la proprietà richiesta non è presente.
`['get', string, object]`	value	Ottiene il valore della proprietà dalle proprietà dell'oggetto fornito. Restituisce Null se la proprietà richiesta non è presente.
`['has', string]`	boolean	Determina se le proprietà di una funzionalità hanno la proprietà specificata.
`['has', string, object]`	boolean	Determina se le proprietà dell'oggetto hanno la proprietà specificata.
`['id']`	value	Ottiene l'ID della funzionalità, se presente.
`['in', boolean \| string \| number, array]`	boolean	Determina se un elemento esiste in una matrice
`['in', substring, string]`	boolean	Determina se una sottostringa esiste in una stringa
`['index-of', boolean \| string \| number, array \| string]` `['index-of', boolean \| string \| number, array \| string, number]`	number	Restituisce la prima posizione in cui è possibile trovare un elemento in una matrice o in una `-1` sottostringa oppure se l'input non viene trovato. Accetta un indice facoltativo da dove iniziare la ricerca.
`['length', string \| array]`	number	Ottiene la lunghezza di una stringa o di una matrice.
`['slice', array \| string, number]` `['slice', array \| string, number, number]`	string \| Matrice	Restituisce un elemento da una matrice o una sottostringa da una stringa da un indice iniziale specificato oppure tra un indice iniziale e un indice finale, se impostato. Il valore restituito è inclusivo dell'indice iniziale, ma non dell'indice finale.

Esempi

Le proprietà di una funzionalità possono essere accessibili direttamente in un'espressione usando un'espressione get . In questo esempio viene utilizzato il zoneColor valore della funzionalità per specificare la proprietà color di un livello a bolle.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: ['get', 'zoneColor'] //Get the zoneColor value.
});

L'esempio precedente funziona correttamente, se tutte le caratteristiche del punto hanno la zoneColor proprietà . In caso contrario, il colore predefinito è "nero". Per modificare il colore di fallback, utilizzare un'espressione case in combinazione con l'espressione has per verificare se la proprietà esiste. Se la proprietà non esiste, restituire un colore di fallback.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'case', //Use a conditional case expression.

        ['has', 'zoneColor'],   //Check to see if feature has a "zoneColor" property
        ['get', 'zoneColor'],   //If it does, use it.

        'blue'  //If it doesn't, default to blue.
    ]
});

Per impostazione predefinita, i livelli bolle e simboli eseguono il rendering delle coordinate di tutte le forme in un'origine dati. Questo comportamento può evidenziare i vertici di un poligono o di una linea. L'opzione filter del livello può essere usata per limitare il tipo di geometria delle caratteristiche di cui esegue il rendering, usando un'espressione ['geometry-type'] all'interno di un'espressione booleana. Nell'esempio seguente viene limitato un livello a bolle in modo che venga eseguito il rendering solo Point delle funzionalità.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    filter: ['==', ['geometry-type'], 'Point']
});

L'esempio seguente consente il rendering di entrambe Point le funzionalità e MultiPoint .

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    filter: ['any', ['==', ['geometry-type'], 'Point'], ['==', ['geometry-type'], 'MultiPoint']]
});

Analogamente, il contorno dei poligoni esegue il rendering nei livelli di linea. Per disabilitare questo comportamento in un livello linea, aggiungere un filtro che consenta LineString solo le funzionalità e MultiLineString .

Di seguito sono riportati altri esempi di come usare espressioni di dati:

//Get item [2] from an array "properties.abcArray[1]" = "c"
['at', 2, ['get', 'abcArray']]

//Get item [0][1] from a 2D array "properties.array2d[0][1]" = "b"
['at', 1, ['at', 0, ['get', 'array2d']]]

//Check to see if a value is in an array "properties.abcArray.indexOf('a') !== -1" = true
['in', 'a', ['get', 'abcArray']]

//Gets the index of the value 'b' in an array "properties.abcArray.indexOf('b')" = 1
['index-of', 'b', ['get', 'abcArray']]

//Get the length of an array "properties.abcArray.length" = 3
['length', ['get', 'abcArray']]

//Get the value of a subproperty "properties._style.fillColor" = "red"
['get', 'fillColor', ['get', '_style']]

//Check that "fillColor" exists as a subproperty of "_style".
['has', 'fillColor', ['get', '_style']]

//Slice an array starting at index 2 "properties.abcArray.slice(2)" = ['c']
['slice', ['get', 'abcArray'], 2]

//Slice a string from index 0 to index 4 "properties.entityType.slice(0, 4)" = 'rest'
['slice', ['get', 'entityType'], 0, 4]

Espressioni matematiche

Le espressioni matematiche forniscono operatori matematici per eseguire calcoli basati sui dati all'interno del framework delle espressioni.

Expression	Tipo restituito	Descrizione
`['+', number, number, …]`	number	Calcola la somma dei numeri specificati.
`['-', number]`	number	Sottrae 0 in base al numero specificato.
`['-', number, number]`	number	Sottrae i primi numeri in base al secondo numero.
`['*', number, number, …]`	number	Moltiplica i numeri specificati insieme.
`['/', number, number]`	number	Divide il primo numero per il secondo numero.
`['%', number, number]`	number	Calcola il resto durante la divisione del primo numero per il secondo numero.
`['^', number, number]`	number	Calcola il valore del primo valore elevato alla potenza del secondo numero.
`['abs', number]`	number	Calcola il valore assoluto del numero specificato.
`['acos', number]`	number	Calcola l'arcocosina del numero specificato.
`['asin', number]`	number	Calcola l'arcosine del numero specificato.
`['atan', number]`	number	Calcola l'arcotangente del numero specificato.
`['ceil', number]`	number	Arrotonda il numero fino all'intero intero successivo.
`['cos', number]`	number	Calcola il cos del numero specificato.
`['distance', Point \\| MultiPoint \\| LineString \\| MultiLineString \\| Polygon \\| MultiPolygon \\| Feature \\| FeatureCollection]`	number	Calcola la distanza più breve in metri tra la caratteristica valutata e la geometria di input. I valori di distanza restituiti possono variare in base alla precisione dovuta alla perdita di precisione rispetto alle geometrie di codifica, in particolare al di sotto del livello di zoom 13.
`['e']`	number	Restituisce la costante `e`matematica .
`['floor', number]`	number	Arrotonda il numero verso il basso fino all'intero intero precedente.
`['ln', number]`	number	Calcola il logaritmo naturale del numero specificato.
`['ln2']`	number	Restituisce la costante `ln(2)`matematica .
`['log10', number]`	number	Calcola il logaritmo di base dieci del numero specificato.
`['log2', number]`	number	Calcola il logaritmo in base due del numero specificato.
`['max', number, number, …]`	number	Calcola il numero massimo nel set specificato di numeri.
`['min', number, number, …]`	number	Calcola il numero minimo nel set specificato di numeri.
`['pi']`	number	Restituisce la costante `PI`matematica .
`['round', number]`	number	Arrotonda il numero all'intero più vicino. I valori a metà strada vengono arrotondati a distanza da zero. Ad esempio, `['round', -1.5]` restituisce `-2`.
`['sin', number]`	number	Calcola il seno del numero specificato.
`['sqrt', number]`	number	Calcola la radice quadrata del numero specificato.
`['tan', number]`	number	Calcola la tangente del numero specificato.

Espressione di aggregazione

Un'espressione di aggregazione definisce un calcolo elaborato su un set di dati e può essere usato con l'opzione clusterProperties di un oggetto DataSource. L'output di queste espressioni deve essere un numero o un valore booleano.

Un'espressione di aggregazione accetta tre valori: un valore dell'operatore e un valore iniziale e un'espressione per recuperare una proprietà da ogni funzionalità di un dato per applicare l'operazione di aggregazione. Questa espressione ha il formato seguente:

[operator: string, initialValue: boolean | number, mapExpression: Expression]

operator: funzione di espressione che viene quindi applicata a su tutti i valori calcolati da mapExpression per ogni punto del cluster. Operatori supportati:
- Per i numeri: +, *, max, min
- Per i valori booleani: all, any
initialValue: valore iniziale in cui viene aggregato il primo valore calcolato.
mapExpression: espressione applicata a ogni punto del set di dati.

Esempi

Se tutte le funzionalità di un set di dati hanno una revenue proprietà , ovvero un numero. È quindi possibile calcolare i ricavi totali di tutti i punti in un cluster, creati dal set di dati. Questo calcolo viene eseguito usando l'espressione di aggregazione seguente: ['+', 0, ['get', 'revenue']]

Espressione accumulata

L'espressione accumulated ottiene il valore di una proprietà del cluster accumulata finora, usata nell'opzione di un'origine clusterProperties cluster DataSource .

Utilizzo

["accumulated"]

Espressioni booleane

Le espressioni booleane forniscono un set di espressioni di operatori booleani per la valutazione di confronti booleani.

Il confronto viene rigorosamente tipizzato quando vengono confrontati i valori. I valori di tipi diversi sono sempre considerati diversi. I casi in cui i tipi sono noti come diversi in fase di analisi sono considerati non validi e generano un errore di analisi.

Expression	Tipo restituito	Descrizione
`['!', boolean]`	boolean	Negazione logica. Restituisce `true` se l'input è `false`e `false` se l'input è `true`.
`['!=', value, value]`	boolean	Restituisce `true` se i valori di input non sono uguali, `false` in caso contrario.
`['<', value, value]`	boolean	Restituisce `true` se il primo input è rigorosamente minore del secondo, `false` in caso contrario. Gli argomenti devono essere entrambe stringhe o entrambi i numeri.
`['<=', value, value]`	boolean	Restituisce `true` se il primo input è minore o uguale al secondo, `false` in caso contrario. Gli argomenti devono essere entrambe stringhe o entrambi i numeri.
`['==', value, value]`	boolean	Restituisce `true` se i valori di input sono uguali, `false` in caso contrario. Gli argomenti devono essere entrambe stringhe o entrambi i numeri.
`['>', value, value]`	boolean	Restituisce `true` se il primo input è strettamente maggiore del secondo, `false` in caso contrario. Gli argomenti devono essere entrambe stringhe o entrambi i numeri.
`['>=' value, value]`	boolean	Restituisce `true` se il primo input è maggiore o uguale al secondo, `false` in caso contrario. Gli argomenti devono essere entrambe stringhe o entrambi i numeri.
`['all', boolean, boolean, …]`	boolean	Restituisce `true` se tutti gli input sono `true`, `false` in caso contrario.
`['any', boolean, boolean, …]`	boolean	Restituisce `true` se uno degli input è `true`, `false` in caso contrario.
`['within', Polygon \| MultiPolygon \| Feature<Polygon \| MultiPolygon>]`	boolean	Restituisce `true` se la funzionalità valutata è completamente contenuta all'interno di un limite della geometria di input, false in caso contrario. Il valore di input può essere un geoJSON valido di tipo `Polygon`, `MultiPolygon`, `Feature`o `FeatureCollection`. Funzionalità supportate per la valutazione: - Punto: restituisce `false` se un punto si trova sul limite o non rientra nel limite. - LineString: restituisce `false` se una parte di una riga non rientra nel limite, la riga interseca il limite o l'endpoint di una riga si trova al limite.

Espressioni condizionali

Le espressioni condizionali forniscono operazioni logiche simili alle istruzioni if.

Le espressioni seguenti eseguono operazioni per la logica condizionale sui dati di input. Ad esempio, l'espressione case fornisce la logica "if/then/else" mentre l'espressione match è simile a "switch-statement".

Espressione case

Un'espressione case è un tipo di espressione condizionale che fornisce la logica "if/then/else". Questo tipo di espressione consente di eseguire un elenco di condizioni booleane. Restituisce il valore di output della prima condizione booleana da restituire true.

Lo pseudocodice seguente definisce la struttura dell'espressione case .

[
    'case',
    condition1: boolean, 
    output1: value,
    condition2: boolean, 
    output2: value,
    ...,
    fallback: value
]

Esempio

Nell'esempio seguente vengono illustrate le diverse condizioni booleane fino a quando non ne trova una che restituisce truee quindi restituisce tale valore associato. Se nessuna condizione booleana restituisce true, viene restituito un valore di fallback.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'case',

        //Check to see if the first boolean expression is true, and if it is, return its assigned result.
        ['has', 'zoneColor'],
        ['get', 'zoneColor'],

        //Check to see if the second boolean expression is true, and if it is, return its assigned result.
        ['all', ['has', ' temperature '], ['>', ['get', 'temperature'], 100]],
        'red',

        //Specify a default value to return.
        'green'
    ]
});

Espressione di corrispondenza

Un'espressione match è un tipo di espressione condizionale che fornisce una logica simile all'istruzione switch. L'input può essere qualsiasi espressione, ['get', 'entityType'] ad esempio che restituisce una stringa o un numero. Ogni etichetta deve essere un singolo valore letterale o una matrice di valori letterali, i cui valori devono essere tutte stringhe o tutti i numeri. L'input corrisponde se uno dei valori nella matrice corrisponde. Ogni etichetta deve essere univoca. Se il tipo di input non corrisponde al tipo delle etichette, il risultato è il valore di fallback.

Lo pseudocodice seguente definisce la struttura dell'espressione match .

[
    'match',
    input: number | string,
    label1: number | string | (number | string)[], 
    output1: value,
    label2: number | string | (number | string)[], 
    output2: value,
    ...,
    fallback: value
]

Esempi

Nell'esempio seguente viene esaminata la entityType proprietà di una funzionalità Point in un livello a bolle per cercare una corrispondenza. Se trova una corrispondenza, il valore specificato viene restituito o restituisce il valore di fallback.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'match',

        //Get the property to match.
        ['get', 'entityType'],

        //List the values to match and the result to return for each match.
        'restaurant', 'red',
        'park', 'green',

        //Specify a default value to return if no match is found.
        'black'
    ]
});

Nell'esempio seguente viene utilizzata una matrice per elencare un set di etichette che devono restituire lo stesso valore. Questo approccio è molto più efficiente rispetto all'inserimento di ogni etichetta singolarmente. In questo caso, se la entityType proprietà è "ristorante" o "grocery_store", viene restituito il colore "rosso".

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'match',

        //Get the property to match.
        ['get', 'entityType'],

        //List the values to match and the result to return for each match.
        ['restaurant', 'grocery_store'], 'red',

        'park', 'green',

        //Specify a default value to return if no match is found.
        'black'
    ]
});

Espressione Coalesce

Un'espressione coalesce passa attraverso un set di espressioni fino a quando non viene ottenuto il primo valore non Null e restituisce tale valore.

Lo pseudocodice seguente definisce la struttura dell'espressione coalesce .

[
    'coalesce', 
    value1, 
    value2, 
    …
]

Esempio

Nell'esempio seguente viene utilizzata un'espressione coalesce per impostare l'opzione textField di un livello simbolo. Se la title proprietà non è presente nella funzionalità o impostata su null, l'espressione tenta di cercare la subTitle proprietà, se manca o null, restituisce una stringa vuota.

var layer = new atlas.layer.SymbolLayer(datasource, null, {
    textOptions: {
        textField: [
            'coalesce',

            //Try getting the title property.
            ['get', 'title'],

            //If there is no title, try getting the subTitle. 
            ['get', 'subTitle'],

            //Default to an empty string.
            ''
        ]
    }
});

Nell'esempio seguente viene usata un'espressione coalesce per recuperare la prima icona di immagine disponibile disponibile nello sprite della mappa da un elenco di nomi di immagine specificati.

var layer = new atlas.layer.SymbolLayer(datasource, null, {
    iconOptions: {
        image: [
            'coalesce',

            //Try getting the image with id 'missing-image'.
            ['image', 'missing-image'],

            //Specify an image id to fallback to. 
            'marker-blue'
        ]
    }
});

Espressioni di tipo

Le espressioni di tipo forniscono strumenti per il test e la conversione di tipi di dati diversi, ad esempio stringhe, numeri e valori booleani.

Expression	Tipo restituito	Descrizione
`['array', value]` \| `['array', type: "string" \| "number" \| "boolean", value]`	Oggetto[]	Afferma che l'input è una matrice.
`['boolean', value]` \| `["boolean", value, fallback: value, fallback: value, ...]`	boolean	Afferma che il valore di input è un valore booleano. Se vengono forniti più valori, ognuno viene valutato in ordine finché non viene ottenuto un valore booleano. Se nessuno degli input è booleano, l'espressione è un errore.
`['collator', { 'case-sensitive': boolean, 'diacritic-sensitive': boolean, 'locale': string }]`	collator	Restituisce un collator da usare nelle operazioni di confronto dipendenti dalle impostazioni locali. Le opzioni con distinzione tra maiuscole e minuscole e con diacritica per impostazione predefinita sono false. L'argomento delle impostazioni locali specifica il tag di lingua IETF delle impostazioni locali da usare. Se non viene specificato nessuno, vengono usate le impostazioni locali predefinite. Se le impostazioni locali richieste non sono disponibili, il collator usa impostazioni locali di fallback definite dal sistema. Usare le impostazioni locali risolte per testare i risultati del comportamento di fallback delle impostazioni locali.
`['literal', array]` `['literal', object]`	matrice \| Oggetto	Restituisce una matrice letterale o un valore dell'oggetto. Utilizzare questa espressione per impedire che una matrice o un oggetto venga valutato come espressione, necessario quando viene restituita da un'espressione una matrice o un oggetto .
`['image', string]`	stringa	Verifica se un ID immagine specificato viene caricato nello sprite dell'immagine di mappe. In caso affermativo, viene restituito l'ID. In caso contrario, viene restituito null.
`['number', value]` \| `["number", value, fallback: value, fallback: value, ...]`	number	Asserisce che il valore di input è un numero. Se vengono forniti più valori, ognuno viene valutato in ordine fino a quando non viene ottenuto un numero. Se nessuno degli input è numeri, l'espressione è un errore.
`['object', value]` \| `["object", value, fallback: value, fallback: value, ...]`	Oggetto	Asserisce che il valore di input è un oggetto . Se vengono forniti più valori, ognuno viene valutato in ordine fino a quando non viene ottenuto un oggetto. Se nessuno degli input è oggetti, l'espressione è un errore.
`['string', value]` \| `["string", value, fallback: value, fallback: value, ...]`	stringa	Afferma che il valore di input è una stringa. Se vengono forniti più valori, ognuno viene valutato in ordine fino a quando non viene ottenuta una stringa. Se nessuno degli input è costituito da stringhe, l'espressione è un errore.
`['to-boolean', value]`	boolean	Converte il valore di input in un valore booleano. Il risultato è `false` quando l'input è una stringa vuota, `0`, `false`, `null`o ; in `NaN`caso contrario, .`true`
`['to-color', value]` `['to-color', value1, value2…]`	colore	Converte il valore di input in un colore. Se vengono specificati più valori, ognuno viene valutato in ordine fino a quando non viene ottenuta la prima conversione riuscita. Se nessuno degli input può essere convertito, l'espressione è un errore.
`['to-number', value]` `['to-number', value1, value2, …]`	number	Converte il valore di input in un numero, se possibile. Se l'input è `null` o `false`, il risultato è 0. Se l'input è `true`, il risultato è 1. Se l'input è una stringa, viene convertito in un numero usando la funzione di stringa ToNumber della specifica del linguaggio ECMAScript. Se vengono specificati più valori, ognuno viene valutato in ordine fino a quando non viene ottenuta la prima conversione riuscita. Se nessuno degli input può essere convertito, l'espressione è un errore.
`['to-string', value]`	stringa	Converte il valore di input in una stringa. Se l'input è `null`, il risultato è `""`. Se l'input è un valore booleano, il risultato è `"true"` o `"false"`. Se l'input è un numero, viene convertito in una stringa usando la funzione numero ToString della specifica del linguaggio ECMAScript. Se l'input è un colore, viene convertito in stringa `"rgba(r,g,b,a)"`di colore RGBA CSS. In caso contrario, l'input viene convertito in una stringa usando la funzione JSON.stringify della specifica del linguaggio ECMAScript.
`['typeof', value]`	stringa	Restituisce una stringa che descrive il tipo del valore specificato.

Suggerimento

Se nella console del browser viene visualizzato un messaggio di errore simile a Expression name must be a string, but found number instead. If you wanted a literal array, use ["literal", [...]]. , significa che nel codice è presente un'espressione che contiene una matrice che non ha una stringa per il primo valore. Se si desidera che l'espressione restituisca una matrice, eseguire il wrapping della matrice con l'espressione literal . Nell'esempio seguente viene impostata l'opzione icona di un livello simbolo, che deve essere una matrice contenente due numeri, usando un'espressione offsetmatch per scegliere tra due valori di offset in base al valore della entityType proprietà della caratteristica punto.

var layer = new atlas.layer.SymbolLayer(datasource, null, {
    iconOptions: {
        offset: [
            'match',

            //Get the entityType value.
            ['get', 'entityType'],

            //If the entity type is 'restaurant', return a different pixel offset. 
            'restaurant', ['literal', [0, -10]],

            //Default to value.
            ['literal', [0, 0]]
        ]
    }
});

Espressioni di colore

Le espressioni di colore semplificano la creazione e la modifica dei valori dei colori.

Expression	Tipo restituito	Descrizione
`['interpolate-hcl', interpolation: ["linear"] \\| ["exponential", base] \\| ["cubic-bezier", x1, y1, x2, y2], input: number, stop_input_1: number, stop_output_1: Color, stop_input_n: number, stop_output_n: Color, ...]`	color	Produce risultati continui e uniformi interpolando tra coppie di valori di input e output ("stop"). Funziona come `interpolate`, ma il tipo di output deve essere un colore e l'interpolazione viene eseguita nello spazio colore Hue-Chroma-Luminance.
`['interpolate-lab', interpolation: ["linear"] \\| ["exponential", base] \\| ["cubic-bezier", x1, y1, x2, y2], input: number, stop_input_1: number, stop_output_1: Color, stop_input_n: number, stop_output_n: Color, ...]`	colore	Produce risultati continui e uniformi interpolando tra coppie di valori di input e output ("stop"). Funziona come `interpolate`, ma il tipo di output deve essere un colore e l'interpolazione viene eseguita nello spazio dei colori CIELAB.
`['rgb', number, number, number]`	colore	Crea un valore di colore dai componenti rosso, verde e blu compresi tra `0` e `255`e un componente alfa di `1`. Se un componente non è compreso nell'intervallo, l'espressione è un errore.
`['rgba', number, number, number, number]`	colore	Crea un valore di colore da componenti rosso, verde, blu compreso tra `0` e `255`e un componente alfa all'interno di un intervallo di `0` e `1`. Se un componente non è compreso nell'intervallo, l'espressione è un errore.
`['to-rgba']`	[number, number, number, number]	Restituisce una matrice a quattro elementi contenente i componenti rosso, verde, blu e alfa del colore di input, in tale ordine.

Esempio

Nell'esempio seguente viene creato un valore di colore RGB con un valore rosso di 255, e i valori verde e blu calcolati moltiplicando 2.5 per il valore della temperature proprietà . Man mano che la temperatura cambia, il colore cambia in tonalità diverse di rosso.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'rgb', //Create a RGB color value.

        255,    //Set red value to 255.

        ['*', 2.5, ['get', 'temperature']], //Multiple the temperature by 2.5 and set the green value.

        ['*', 2.5, ['get', 'temperature']]  //Multiple the temperature by 2.5 and set the blue value.
    ]
});

Espressioni dell'operatore String

Le espressioni dell'operatore stringa eseguono operazioni di conversione su stringhe, ad esempio la concatenazione e la conversione della distinzione tra maiuscole e minuscole.

Expression	Tipo restituito	Descrizione
`['concat', string, string, …]`	stringa	Concatena più stringhe insieme. Ogni valore deve essere una stringa. Usare l'espressione `to-string` di tipo per convertire altri tipi di valore in stringa, se necessario.
`['downcase', string]`	stringa	Converte la stringa specificata in minuscolo.
`['is-supported-script', string]` \| `['is-supported-script', Expression]`	boolean	Determina se la stringa di input utilizza un set di caratteri supportato dallo stack di caratteri corrente. Ad esempio: `['is-supported-script', 'ಗೌರವಾರ್ಥವಾಗಿ']`
`['resolved-locale', string]`	stringa	Restituisce il tag di lingua IETF delle impostazioni locali utilizzate dal collator fornito che può essere utilizzato per determinare le impostazioni locali di sistema predefinite o per determinare se le impostazioni locali richieste sono state caricate correttamente.
`['upcase', string]`	stringa	Converte la stringa specificata in maiuscolo.

Esempio

L'esempio seguente converte la temperature proprietà della caratteristica punto in una stringa e quindi concatena "°F" alla fine di essa.

var layer = new atlas.layer.SymbolLayer(datasource, null, {
    textOptions: {
        textField: ['concat', ['to-string', ['get', 'temperature']], '°F'],

        //Some additional style options.
        offset: [0, -1.5],
        size: 12,
        color: 'white'
    }
});

L'espressione precedente esegue il rendering di un segnaposto sulla mappa con il testo "64°F" sovrapposto, come illustrato nell'immagine seguente.

Screenshot of a map that demonstrates the string operator expression example.

Interpolare ed eseguire l'interpolazione delle espressioni step

È possibile usare espressioni interpolate e passo per calcolare i valori lungo una curva interpolata o una funzione passo. Queste espressioni accettano un'espressione che restituisce un valore numerico come input, ad esempio ['get', 'temperature']. Il valore di input viene valutato in base a coppie di valori di input e output, per determinare il valore più adatto alla curva interpolata o alla funzione di passaggio. I valori di output sono denominati "stop". I valori di input per ogni arresto devono essere un numero e essere in ordine crescente. I valori di output devono essere un numero e una matrice di numeri o un colore.

Interpolare un'espressione

Un'espressione interpolate può essere usata per calcolare un set continuo e uniforme di valori interpolando tra i valori di arresto. Un'espressione che restituisce interpolate valori di colore produce una sfumatura di colore da cui vengono selezionati i valori dei risultati.

Esistono tre tipi di metodi di interpolazione che possono essere usati in un'espressione interpolate :

['linear'] - Interpola in modo lineare tra la coppia di arresti.
['exponential', base] - Interpola in modo esponenziale tra gli arresti. Il base valore controlla la frequenza con cui aumenta l'output. I valori più elevati rendono l'output più elevato verso l'estremità superiore dell'intervallo. Un base valore vicino a 1 produce un output che aumenta in modo più lineare.
['cubic-bezier', x1, y1, x2, y2] - Interpola usando una curva di Bézier cubica definita dai punti di controllo specificati.

Ecco un esempio dell'aspetto di questi diversi tipi di interpolazioni.

Lineare	Esponenziale	Bézier cubico

Lo pseudocodice seguente definisce la struttura dell'espressione interpolate .

[
    'interpolate',
    interpolation: ['linear'] | ['exponential', base] | ['cubic-bezier', x1, y1, x2, y2],
    input: number,
    stopInput1: number, 
    stopOutput1: value1,
    stopInput2: number, 
    stopOutput2: value2, 
    ...
]

Esempio

Nell'esempio seguente viene utilizzata un'espressione linear interpolate per impostare la color proprietà di un livello a bolle in base alla temperature proprietà della funzionalità punto. Se il temperature valore è minore di 60, viene restituito "blue". Se è compreso tra 60 e meno di 70, viene restituito il giallo. Se è compreso tra 70 e meno di 80, viene restituito "arancione". Se è maggiore o uguale a 80, viene restituito il valore "rosso".

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'interpolate',
        ['linear'],
        ['get', 'temperature'],
        50, 'blue',
        60, 'yellow',
        70, 'orange',
        80, 'red'
    ]
});

L'immagine seguente illustra come vengono scelti i colori per l'espressione precedente.

Interpolate expression example

Espressione del passaggio

Un'espressione step può essere utilizzata per calcolare valori di risultato discreti e con rientri valutando una funzione costante a fasi definita da stop.

Lo pseudocodice seguente definisce la struttura dell'espressione step .

[
    'step',
    input: number,
    output0: value0,
    stop1: number, 
    output1: value1,
    stop2: number, 
    output2: value2, 
    ...
]

Le espressioni di passaggio restituiscono il valore di output dell'arresto subito prima del valore di input o il primo valore di input se l'input è minore del primo arresto.

Esempio

Nell'esempio seguente viene utilizzata un'espressione step per impostare la color proprietà di un livello a bolle in base alla temperature proprietà della funzionalità punto. Se il temperature valore è minore di 60, viene restituito "blue". Se è compreso tra 60 e meno di 70, viene restituito il valore "giallo". Se è compreso tra 70 e meno di 80, viene restituito "arancione". Se è maggiore o uguale a 80, viene restituito il valore "rosso".

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        'step',
        ['get', 'temperature'],
        'blue',
        60, 'yellow',
        70, 'orange',
        80, 'red'
    ]
});

L'immagine seguente illustra come vengono scelti i colori per l'espressione precedente.

Step expression example

Espressioni specifiche del livello

Espressioni speciali che si applicano solo a livelli specifici.

Espressione densità mappa termica

Un'espressione di densità della mappa termica recupera il valore di densità della mappa termica per ogni pixel in un livello mappa termica ed è definito come ['heatmap-density']. Questo valore è un numero compreso tra 0 e 1. Viene usato in combinazione con un'espressione interpolation o step per definire la sfumatura di colore usata per colorare la mappa termica. Questa espressione può essere usata solo nell'opzione colore del livello mappa termica.

Suggerimento

Il colore in corrispondenza dell'indice 0, in un'espressione di interpolazione o il colore predefinito di un colore di passaggio, definisce il colore dell'area in cui non sono presenti dati. Il colore in corrispondenza dell'indice 0 può essere usato per definire un colore di sfondo. Molti preferiscono impostare questo valore su un nero trasparente o semitrasparente.

Esempio

In questo esempio viene utilizzata un'espressione di interpolazione liner per creare una sfumatura di colore uniforme per il rendering della mappa termica.

var layer = new atlas.layer.HeatMapLayer(datasource, null, {
    color: [
        'interpolate',
        ['linear'],
        ['heatmap-density'],
        0, 'transparent',
        0.01, 'purple',
        0.5, '#fb00fb',
        1, '#00c3ff'
    ]
});

Oltre a usare una sfumatura liscia per colorare una mappa termica, è possibile specificare i colori all'interno di un set di intervalli usando un'espressione step . L'uso di un'espressione step per colorare visivamente la mappa termica suddivide visivamente la densità in intervalli simili a una mappa dello stile di contorno o radar.

var layer = new atlas.layer.HeatMapLayer(datasource, null, {
    color: [
        'step',
        ['heatmap-density'],
        'transparent',
        0.01, 'navy',
        0.25, 'navy',
        0.5, 'green',
        0.75, 'yellow',
        1, 'red'
    ]
});

Per altre informazioni, vedere la documentazione Relativa all'aggiunta di un livello mappa termica.

Espressione di avanzamento riga

Un'espressione di avanzamento riga recupera lo stato di avanzamento lungo una linea sfumata in un livello linea ed è definito come ['line-progress']. Questo valore è un numero compreso tra 0 e 1. Viene usato in combinazione con un'espressione interpolation o step . Questa espressione può essere usata solo con l'opzione strokeGradient del livello linea.

Nota

L'opzione strokeGradient del livello linea richiede che l'opzione lineMetrics dell'origine dati sia impostata su true.

Esempio

In questo esempio viene utilizzata l'espressione ['line-progress'] per applicare una sfumatura di colore al tratto di una linea.

var layer = new atlas.layer.LineLayer(datasource, null, {
    strokeGradient: [
        'interpolate',
        ['linear'],
        ['line-progress'],
        0, "blue",
        0.1, "royalblue",
        0.3, "cyan",
        0.5, "lime",
        0.7, "yellow",
        1, "red"
    ]
});

Per un esempio di lavoro interattivo, vedere Aggiungere una sfumatura di tratto a una linea.

Espressione di formato campo di testo

L'espressione formato campo di testo può essere usata con l'opzione textField della proprietà layer textOptions simbolo per fornire formattazione testo misto. Questa espressione consente di specificare un set di stringhe di input e opzioni di formattazione. È possibile specificare le opzioni seguenti per ogni stringa di input in questa espressione.

'font-scale' - Specifica il fattore di ridimensionamento per la dimensione del carattere. Se specificato, questo valore esegue l'override della size proprietà dell'oggetto textOptions per la singola stringa.
'text-font' - Specifica una o più famiglie di caratteri che devono essere usate per questa stringa. Se specificato, questo valore esegue l'override della font proprietà dell'oggetto textOptions per la singola stringa.

Lo pseudocodice seguente definisce la struttura dell'espressione di formato del campo di testo.

[
    'format', 
    input1: string, 
    options1: { 
        'font-scale': number, 
        'text-font': string[]
    },
    input2: string, 
    options2: { 
        'font-scale': number, 
        'text-font': string[]
    },
    …
]

Esempio

Nell'esempio seguente il campo di testo viene formattato aggiungendo un carattere in grassetto e aumentando le dimensioni del carattere della title proprietà della funzionalità. In questo esempio viene aggiunta anche la subTitle proprietà della funzionalità in una nuova riga, con una dimensione del carattere ridotta.

var layer = new atlas.layer.SymbolLayer(datasource, null, {
    textOptions: {
        textField: [
            'format',

            //Bold the title property and scale its font size up.
            ['get', 'title'],
            {
                'text-font': ['literal', ['StandardFont-Bold']],
                'font-scale': 1.25
            },

            '\n', {},   //Add a new line without any formatting.

            //Scale the font size down of the subTitle property. 
            ['get', 'subTitle'],
            { 
                'font-scale': 0.75
            }
        ]
    }
});

Questo livello esegue il rendering della funzionalità punto come illustrato nell'immagine seguente:

Image of Point feature with formatted text field

Espressione di formato numerico

L'espressione number-format può essere usata solo con l'opzione textField di un livello simbolo. Questa espressione converte il numero specificato in una stringa formattata. Questa espressione esegue il wrapping della funzione Number.toLocalString di JavaScript e supporta il set di opzioni seguente.

locale - Specificare questa opzione per convertire i numeri in stringhe in modo che sia allineato alla lingua specificata. Passare un tag di lingua BCP 47 a questa opzione.
currency - Per convertire il numero in una stringa che rappresenta una valuta. I valori possibili sono i codici di valuta ISO 4217, ad esempio "USD" per il dollaro statunitense, "EUR" per l'euro o "CNY" per il RMB cinese.
'min-fraction-digits' - Specifica il numero minimo di posizioni decimali da includere nella versione stringa del numero.
'max-fraction-digits' - Specifica il numero massimo di posizioni decimali da includere nella versione stringa del numero.

Lo pseudocodice seguente definisce la struttura dell'espressione di formato del campo di testo.

[
    'number-format', 
    input: number, 
    options: {
        locale: string, 
        currency: string, 
        'min-fraction-digits': number, 
        'max-fraction-digits': number
    }
]

Esempio

Nell'esempio seguente viene utilizzata un'espressione number-format per modificare il modo in cui viene eseguito il revenue rendering della proprietà della funzionalità punto nell'opzione textField di un livello simbolo in modo che venga visualizzato un valore del dollaro statunitense.

var layer = new atlas.layer.SymbolLayer(datasource, null, {
    textOptions: {
        textField: [
            'number-format', 
            ['get', 'revenue'], 
            { 'currency': 'USD' }
        ],

        offset: [0, 0.75]
    }
});

Questo livello esegue il rendering della funzionalità punto come illustrato nell'immagine seguente:

Number format expression example

Espressione immagine

Un'espressione di immagine può essere usata con le image opzioni e textField di un livello simbolo e l'opzione fillPattern del livello poligono. Questa espressione verifica che l'immagine richiesta esista nello stile e restituisca il nome dell'immagine risolta o null, a seconda che l'immagine sia attualmente nello stile. Questo processo di convalida è sincrono e richiede che l'immagine sia stata aggiunta allo stile prima di richiederla nell'argomento immagine.

Esempio

Nell'esempio seguente viene usata un'espressione image per aggiungere un'icona inline con testo in un livello simbolo.

 //Load the custom image icon into the map resources.
map.imageSprite.add('wifi-icon', 'wifi.png').then(function () {

    //Create a data source and add it to the map.
    datasource = new atlas.source.DataSource();
    map.sources.add(datasource);
    
    //Create a point feature and add it to the data source.
    datasource.add(new atlas.data.Point(map.getCamera().center));
    
    //Add a layer for rendering point data as symbols.
    map.layers.add(new atlas.layer.SymbolLayer(datasource, null, {
        iconOptions: {
            image: 'none'
        },
        textOptions: {
            //Create a formatted text string that has an icon in it.
            textField: ["format", 'Ricky\'s ', ["image", "wifi-icon"], ' Palace']
        }
    }));
});

Questo livello esegue il rendering del campo di testo nel livello simbolo, come illustrato nell'immagine seguente:

Image expression example

Espressione zoom

Un'espressione zoom viene usata per recuperare il livello di zoom corrente della mappa in fase di rendering ed è definito come ['zoom']. Questa espressione restituisce un numero compreso tra l'intervallo minimo e massimo del livello di zoom della mappa. Il Mappe di Azure controlli mappa interattivi per Web e Android supporta 25 livelli di zoom, numerati da 0 a 24. L'uso dell'espressione zoom consente di modificare gli stili in modo dinamico quando viene modificato il livello di zoom della mappa. L'espressione zoom può essere usata solo con interpolate le espressioni e step .

Esempio

Per impostazione predefinita, i raggi dei punti dati di cui viene eseguito il rendering nel livello mappa termica hanno un raggio di pixel fisso per tutti i livelli di zoom. Con lo zoom della mappa, i dati vengono aggregati insieme e il livello mappa termica ha un aspetto diverso. Un'espressione zoom può essere usata per ridimensionare il raggio per ogni livello di zoom in modo che ogni punto dati copre la stessa area fisica della mappa. Rende il livello mappa termica più statico e coerente. Ogni livello di zoom della mappa ha il doppio dei pixel verticalmente e orizzontalmente del livello di zoom precedente. Il ridimensionamento del raggio, in modo che raddoppii con ogni livello di zoom, crei una mappa termica che abbia un aspetto coerente su tutti i livelli di zoom. Può essere eseguita usando l'espressione con un'espressione zoombase 2 exponential interpolation , con il raggio del pixel impostato per il livello di zoom minimo e un raggio ridimensionato per il livello di zoom massimo calcolato come 2 * Math.pow(2, minZoom - maxZoom) illustrato nell'esempio seguente.

var layer = new atlas.layer.HeatMapLayer(datasource, null, {
    radius: [
        'interpolate',
        ['exponential', 2],
        ['zoom'],
        
        //For zoom level 1 set the radius to 2 pixels.
        1, 2,

        //Between zoom level 1 and 19, exponentially scale the radius from 2 pixels to 2 * Math.pow(2, 19 - 1) pixels (524,288 pixels).
        19, 2 * Math.pow(2, 19 - 1)
    ]
};

Per un esempio di lavoro interattivo, vedere Mappa termica con zoom coerente.

Espressioni di associazione di variabili

Le espressioni di associazione di variabili archiviano i risultati di un calcolo in una variabile. Pertanto, è possibile fare riferimento ai risultati del calcolo in un'altra posizione in un'espressione più volte. È un'ottimizzazione utile per le espressioni che coinvolgono molti calcoli.

Expression	Tipo restituito	Descrizione
[ 'let', name1: string, value1: any, name2: string, value2: any, ... childExpression ]		Archivia uno o più valori come variabili per l'uso da parte dell'espressione nell'espressione `var` figlio che restituisce il risultato.
`['var', name: string]`	qualsiasi	Fa riferimento a una variabile creata usando l'espressione `let` .

Esempio

In questo esempio viene usata un'espressione che calcola i ricavi relativi al rapporto di temperatura e quindi usa un'espressione case per valutare diverse operazioni booleane su questo valore. L'espressione let viene usata per archiviare i ricavi relativi al rapporto di temperatura, in modo che debba essere calcolata una sola volta. L'espressione var fa riferimento a questa variabile con la frequenza necessaria senza doverla ricalcolare.

var layer = new atlas.layer.BubbleLayer(datasource, null, {
    color: [
        //Divide the point features `revenue` property by the `temperature` property and store it in a variable called `ratio`.
        'let', 'ratio', ['/', ['get', 'revenue'], ['get', 'temperature']],
        //Evaluate the child expression in which the stored variable is used.
        [
            'case',

            //Check to see if the ratio is less than 100, return 'red'.
            ['<', ['var', 'ratio'], 100],
            'red',

            //Check to see if the ratio is less than 200, return 'green'.
            ['<', ['var', 'ratio'], 200],
            'green',

            //Return `blue` for values greater or equal to 200.
            'blue'
        ]
    ]
});