Expressões de estilo orientadas por dados (SDK da Web)

Artigo
10/18/2023

As expressões permitem que você aplique a lógica de negócios às opções de estilo que observam as propriedades definidas em cada forma em uma fonte de dados. As expressões podem filtrar dados em uma fonte de dados ou em uma camada. As expressões podem consistir em lógica condicional, como instruções if. E eles podem ser usados para manipular dados usando: operadores de cadeia de caracteres, operadores lógicos e operadores matemáticos.

Os estilos orientados por dados reduzem a quantidade de código necessária para implementar a lógica de negócios em torno do estilo. Quando usadas com camadas, as expressões são avaliadas no momento da renderização em um thread separado. Essa funcionalidade oferece maior desempenho em comparação com a avaliação da lógica de negócios no thread da interface do usuário.

Este vídeo fornece uma visão geral do estilo controlado por dados no SDK da Web do Azure Maps.

As expressões são representadas como matrizes JSON. O primeiro elemento de uma expressão na matriz é uma cadeia de caracteres que especifica o nome do operador de expressão. Por exemplo, "+" ou "caso". Os próximos elementos (se houver) são os argumentos para a expressão. Cada argumento é um valor literal (uma cadeia de caracteres, número, booleano ou ), ou nulloutra matriz de expressão. O pseudocódigo a seguir define a estrutura básica de uma expressão.

[ 
    expression_operator, 
    argument0, 
    argument1, 
    …
]

O SDK da Web do Azure Maps dá suporte a muitos tipos de expressões. As expressões podem ser usadas isoladamente ou em combinação com outras expressões.

Tipo de expressões	Descrição
Expressão agregada	Uma expressão que define um cálculo que é processado sobre um conjunto de dados e pode ser usado com a `clusterProperties` opção de um `DataSource`.
Expressões booleanas	As expressões booleanas fornecem um conjunto de expressões de operadores booleanos para avaliar comparações booleanas.
Expressões de cores	As expressões de cores facilitam a criação e manipulação de valores de cores.
Expressões condicionais	As expressões condicionais fornecem operações lógicas que são como instruções if.
Expressões de dados	Fornece acesso aos dados da propriedade em um recurso.
Interpolar e Observar expressões	As expressões interpoladas e step podem ser usadas para calcular valores ao longo de uma curva interpolada ou função step.
Expressões específicas da camada	Expressões especiais que só são aplicáveis a uma única camada.
Expressões matemáticas	Fornece operadores matemáticos para executar cálculos orientados por dados dentro da estrutura de expressão.
Expressões do operador de cadeia de caracteres	As expressões do operador de cadeia de caracteres executam operações de conversão em cadeias de caracteres, como concatenar e converter maiúsculas e minúsculas.
Expressões de tipo	As expressões de tipo fornecem ferramentas para testar e converter diferentes tipos de dados, como cadeias de caracteres, números e valores booleanos.
Expressões de vinculação variável	As expressões de vinculação de variáveis armazenam os resultados de um cálculo em uma variável e são referenciadas em outro lugar em uma expressão várias vezes sem ter que recalcular o valor armazenado.
Expressão de zoom	Recupera o nível de zoom atual do mapa no momento da renderização.

Todos os exemplos neste documento usam o recurso a seguir para demonstrar diferentes maneiras pelas quais os diferentes tipos de expressões podem ser usados.

{
    "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"
        }
    }
}

Expressões de dados

As expressões de dados fornecem acesso aos dados de propriedade em um recurso.

Expression	Tipo devolvido	Descrição
`['at', number, array]`	valor	Recupera um item de uma matriz.
`['geometry-type']`	string	Obtém o tipo de geometria do recurso: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon.
`['get', string]`	valor	Obtém o valor da propriedade das propriedades do recurso atual. Retorna null se a propriedade solicitada estiver ausente.
`['get', string, object]`	valor	Obtém o valor da propriedade das propriedades do objeto fornecido. Retorna null se a propriedade solicitada estiver ausente.
`['has', string]`	boolean	Determina se as propriedades de um recurso têm a propriedade especificada.
`['has', string, object]`	boolean	Determina se as propriedades do objeto têm a propriedade especificada.
`['id']`	valor	Obtém o ID do recurso, se ele tiver um.
`['in', boolean \| string \| number, array]`	boolean	Determina se um item existe em uma matriz
`['in', substring, string]`	boolean	Determina se uma substring existe em uma cadeia de caracteres
`['index-of', boolean \| string \| number, array \| string]` `['index-of', boolean \| string \| number, array \| string, number]`	Número	Retorna a primeira posição na qual um item pode ser encontrado em uma matriz ou uma substring pode ser encontrada em uma cadeia de caracteres, ou `-1` se a entrada não puder ser encontrada. Aceita um índice opcional de onde começar a pesquisa.
`['length', string \| array]`	Número	Obtém o comprimento de uma cadeia de caracteres ou de uma matriz.
`['slice', array \| string, number]` `['slice', array \| string, number, number]`	corda \| matriz	Retorna um item de uma matriz ou uma subcadeia de caracteres de uma cadeia de caracteres de um índice inicial especificado ou entre um índice inicial e um índice final, se definido. O valor de retorno inclui o índice inicial, mas não o índice final.

Exemplos

As propriedades de um recurso podem ser acessadas diretamente em uma expressão usando uma get expressão. Este exemplo usa o zoneColor valor do recurso para especificar a propriedade color de uma camada de bolha.

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

O exemplo acima funciona bem, se todos os recursos de ponto tiverem a zoneColor propriedade. Caso contrário, o padrão da cor é "preto". Para modificar a cor de fallback, use uma case expressão em combinação com a expressão para verificar se a has propriedade existe. Se a propriedade não existir, retorne uma cor de 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.
    ]
});

As camadas de bolhas e símbolos renderizam as coordenadas de todas as formas em uma fonte de dados, por padrão. Esse comportamento pode destacar os vértices de um polígono ou uma linha. A filter opção da camada pode ser usada para limitar o tipo de geometria dos recursos que ela renderiza, usando uma expressão dentro de uma ['geometry-type'] expressão booleana. O exemplo a seguir limita uma camada de bolha para que apenas Point os recursos sejam renderizados.

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

O exemplo a seguir permite que ambos os Point recursos sejam MultiPoint renderizados.

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

Da mesma forma, o contorno dos polígonos são renderizados em camadas de linha. Para desativar esse comportamento em uma camada de linha, adicione um filtro que permita apenas LineString e MultiLineString recursos.

Aqui estão mais alguns exemplos de como usar expressões de dados:

//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]

Expressões matemáticas

As expressões matemáticas fornecem operadores matemáticos para executar cálculos orientados por dados dentro da estrutura de expressão.

Expression	Tipo devolvido	Descrição
`['+', number, number, …]`	Número	Calcula a soma dos números especificados.
`['-', number]`	Número	Subtrai 0 pelo número especificado.
`['-', number, number]`	Número	Subtrai os primeiros números pelo segundo número.
`['*', number, number, …]`	Número	Multiplica os números especificados juntos.
`['/', number, number]`	Número	Divide o primeiro número pelo segundo número.
`['%', number, number]`	Número	Calcula o restante ao dividir o primeiro número pelo segundo número.
`['^', number, number]`	Número	Calcula o valor do primeiro valor elevado à potência do segundo número.
`['abs', number]`	Número	Calcula o valor absoluto do número especificado.
`['acos', number]`	Número	Calcula o arco cosseno do número especificado.
`['asin', number]`	Número	Calcula o arco seno do número especificado.
`['atan', number]`	Número	Calcula o arco tangente do número especificado.
`['ceil', number]`	Número	Arredonda o número para cima para o próximo inteiro inteiro.
`['cos', number]`	Número	Calcula os cos do número especificado.
`['distance', Point \\| MultiPoint \\| LineString \\| MultiLineString \\| Polygon \\| MultiPolygon \\| Feature \\| FeatureCollection]`	Número	Calcula a menor distância em metros entre a característica avaliada e a geometria de entrada. Os valores de distância retornados podem variar em precisão devido à perda de precisão das geometrias de codificação, particularmente abaixo do nível de zoom 13.
`['e']`	Número	Devolve a constante `e`matemática .
`['floor', number]`	Número	Arredonda o número para baixo para o inteiro anterior.
`['ln', number]`	Número	Calcula o logaritmo natural do número especificado.
`['ln2']`	Número	Devolve a constante `ln(2)`matemática .
`['log10', number]`	Número	Calcula o logaritmo de base dez do número especificado.
`['log2', number]`	Número	Calcula o logaritmo de base dois do número especificado.
`['max', number, number, …]`	Número	Calcula o número máximo no conjunto de números especificado.
`['min', number, number, …]`	Número	Calcula o número mínimo no conjunto de números especificado.
`['pi']`	Número	Devolve a constante `PI`matemática .
`['round', number]`	Número	Arredonda o número para o número inteiro mais próximo. Os valores intermédios são arredondados para longe de zero. Por exemplo, `['round', -1.5]` avalia como `-2`.
`['sin', number]`	Número	Calcula o seno do número especificado.
`['sqrt', number]`	Número	Calcula a raiz quadrada do número especificado.
`['tan', number]`	Número	Calcula a tangente do número especificado.

Expressão agregada

Uma expressão agregada define um cálculo que é processado sobre um conjunto de dados e pode ser usado com a clusterProperties opção de um DataSourcearquivo . A saída dessas expressões deve ser um número ou um booleano.

Uma expressão agregada recebe três valores: um valor de operador e um valor inicial, e uma expressão para recuperar uma propriedade de cada recurso em um dado para aplicar a operação de agregação. Esta expressão tem o seguinte formato:

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

operador: uma função de expressão que é então aplicada a todos os valores calculados pelo mapExpression para cada ponto do cluster. Operadores suportados:
- Para os números: +, , , , *maxmin
- Para os booleanos: all, any
initialValue: um valor inicial no qual o primeiro valor calculado é agregado.
mapExpression: uma expressão aplicada em cada ponto do conjunto de dados.

Exemplos

Se todos os recursos em um conjunto de dados tiverem uma revenue propriedade, que é um número. Em seguida, a receita total de todos os pontos em um cluster, que são criados a partir do conjunto de dados, pode ser calculada. Este cálculo é feito usando a seguinte expressão agregada: ['+', 0, ['get', 'revenue']]

Expressão acumulada

A accumulated expressão obtém o valor de uma propriedade de cluster acumulada até agora, usada na clusterProperties opção de uma fonte clusterizada DataSource .

Utilização

["accumulated"]

Expressões booleanas

As expressões booleanas fornecem um conjunto de expressões de operadores booleanos para avaliar comparações booleanas.

A comparação é estritamente tipada quando os valores são comparados. Valores de diferentes tipos são sempre considerados desiguais. Os casos em que os tipos são conhecidos por serem diferentes no momento da análise são considerados inválidos e produzem um erro de análise.

Expression	Tipo devolvido	Descrição
`['!', boolean]`	boolean	Negação lógica. Retorna `true` se a entrada for , e `false` se a entrada for `falsetrue`.
`['!=', value, value]`	boolean	Retorna `true` se os valores de entrada não forem iguais, `false` caso contrário.
`['<', value, value]`	boolean	Retorna `true` se a primeira entrada for estritamente menor do que a segunda, `false` caso contrário. Os argumentos devem ser ambas as cadeias de caracteres ou ambos os números.
`['<=', value, value]`	boolean	Retorna `true` se a primeira entrada for menor ou igual à segunda, `false` caso contrário. Os argumentos devem ser ambas as cadeias de caracteres ou ambos os números.
`['==', value, value]`	boolean	Retorna `true` se os valores de entrada forem iguais, `false` caso contrário. Os argumentos devem ser ambas as cadeias de caracteres ou ambos os números.
`['>', value, value]`	boolean	Retorna `true` se a primeira entrada for estritamente maior do que a segunda, `false` caso contrário. Os argumentos devem ser ambas as cadeias de caracteres ou ambos os números.
`['>=' value, value]`	boolean	Retorna `true` se a primeira entrada for maior ou igual à segunda, `false` caso contrário. Os argumentos devem ser ambas as cadeias de caracteres ou ambos os números.
`['all', boolean, boolean, …]`	boolean	Retorna `true` se todas as entradas forem `true`, `false` caso contrário.
`['any', boolean, boolean, …]`	boolean	Retorna `true` se qualquer uma das entradas for `true`, `false` caso contrário.
`['within', Polygon \| MultiPolygon \| Feature<Polygon \| MultiPolygon>]`	boolean	Retorna `true` se o recurso avaliado estiver totalmente contido dentro de um limite da geometria de entrada, falso caso contrário. O valor de entrada pode ser um GeoJSON válido do tipo `Polygon`, , , `MultiPolygonFeature`ou `FeatureCollection`. Recursos suportados para avaliação: - Ponto: Devolve `false` se um ponto estiver no limite ou estiver fora do limite. - LineString: retorna `false` se qualquer parte de uma linha estiver fora do limite, a linha cruzar o limite ou o ponto final de uma linha estiver no limite.

Expressões condicionais

As expressões condicionais fornecem operações lógicas que são como instruções if.

As expressões a seguir executam operações lógicas condicionais nos dados de entrada. Por exemplo, a expressão fornece a lógica "if/then/else" enquanto a casematch expressão é como uma "switch-statement".

Expressão de caso

Uma case expressão é um tipo de expressão condicional que fornece lógica "se/então/senão". Esse tipo de expressão percorre uma lista de condições booleanas. Ele retorna o valor de saída da primeira condição booleana a ser avaliada como true.

O pseudocódigo a seguir define a estrutura da case expressão.

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

Exemplo

O exemplo a seguir percorre diferentes condições booleanas até encontrar uma que seja avaliada como e, em trueseguida, retorne esse valor associado. Se nenhuma condição booleana for avaliada como true, um valor de fallback será retornado.

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'
    ]
});

Expressão de correspondência

Uma match expressão é um tipo de expressão condicional que fornece lógica semelhante à instrução switch. A entrada pode ser qualquer expressão, como ['get', 'entityType'] a que retorna uma cadeia de caracteres ou um número. Cada rótulo deve ser um único valor literal ou uma matriz de valores literais, cujos valores devem ser todas as cadeias de caracteres ou todos os números. A entrada corresponde se qualquer um dos valores na matriz corresponder. Cada rótulo deve ser único. Se o tipo de entrada não corresponder ao tipo dos rótulos, o resultado será o valor de fallback.

O pseudocódigo a seguir define a estrutura da match expressão.

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

Exemplos

O exemplo a seguir examina a entityType propriedade de um recurso Point em uma camada de bolha que procura uma correspondência. Se encontrar uma correspondência, esse valor especificado será retornado ou retornará o valor de 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'
    ]
});

O exemplo a seguir usa uma matriz para listar um conjunto de rótulos que devem retornar o mesmo valor. Esta abordagem é muito mais eficiente do que listar cada rótulo individualmente. Neste caso, se o entityType estabelecimento for "restaurante" ou "grocery_store", a cor "vermelho" é devolvida.

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'
    ]
});

Expressão de coalescência

Uma coalesce expressão percorre um conjunto de expressões até que o primeiro valor não nulo seja obtido e retorne esse valor.

O pseudocódigo a seguir define a estrutura da coalesce expressão.

[
    'coalesce', 
    value1, 
    value2, 
    …
]

Exemplo

O exemplo a seguir usa uma expressão para definir a textField opção de uma coalesce camada de símbolo. Se a propriedade estiver ausente do recurso ou definida como null, a expressão tentará procurar a propriedade, se ela estiver faltando ou null, ela retornará a titlesubTitle uma cadeia de caracteres vazia.

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.
            ''
        ]
    }
});

O exemplo a seguir usa uma expressão para recuperar o primeiro ícone de imagem disponível disponível no sprite de mapa de uma coalesce lista de nomes de imagem especificados.

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'
        ]
    }
});

Expressões de tipos

As expressões de tipo fornecem ferramentas para testar e converter diferentes tipos de dados, como cadeias de caracteres, números e valores booleanos.

Expression	Tipo devolvido	Descrição
`['array', value]` \| `['array', type: "string" \| "number" \| "boolean", value]`	Objeto[]	Afirma que a entrada é uma matriz.
`['boolean', value]` \| `["boolean", value, fallback: value, fallback: value, ...]`	boolean	Afirma que o valor de entrada é um booleano. Se vários valores forem fornecidos, cada um é avaliado em ordem até que um booleano seja obtido. Se nenhuma das entradas for booleana, a expressão é um erro.
`['collator', { 'case-sensitive': boolean, 'diacritic-sensitive': boolean, 'locale': string }]`	colador	Retorna um agrupador para uso em operações de comparação dependentes de localidade. As opções que diferenciam maiúsculas de minúsculas e diacríticas, o padrão é false. O argumento locale especifica a marca de idioma IETF da localidade a ser usada. Se nenhum for fornecido, a localidade padrão será usada. Se a localidade solicitada não estiver disponível, o agrupador usará uma localidade de fallback definida pelo sistema. Use resolved-locale para testar os resultados do comportamento de fallback de localidade.
`['literal', array]` `['literal', object]`	matriz \| objeto	Retorna uma matriz literal ou um valor de objeto. Use esta expressão para impedir que uma matriz ou objeto seja avaliado como uma expressão, necessária quando uma matriz ou objeto é retornado por uma expressão.
`['image', string]`	string	Verifica se um ID de imagem especificado é carregado no sprite de imagem do mapa. Se for, o ID é retornado, caso contrário, null é retornado.
`['number', value]` \| `["number", value, fallback: value, fallback: value, ...]`	Número	Afirma que o valor de entrada é um número. Se forem fornecidos vários valores, cada um é avaliado em ordem até que um número seja obtido. Se nenhuma das entradas for números, a expressão é um erro.
`['object', value]` \| `["object", value, fallback: value, fallback: value, ...]`	Objeto	Afirma que o valor de entrada é um objeto. Se vários valores forem fornecidos, cada um é avaliado em ordem até que um objeto seja obtido. Se nenhuma das entradas for objeto, a expressão é um erro.
`['string', value]` \| `["string", value, fallback: value, fallback: value, ...]`	string	Afirma que o valor de entrada é uma cadeia de caracteres. Se vários valores forem fornecidos, cada um será avaliado em ordem até que uma cadeia de caracteres seja obtida. Se nenhuma das entradas for strings, a expressão será um erro.
`['to-boolean', value]`	boolean	Converte o valor de entrada em booleano. O resultado é quando a entrada é `false` uma cadeia de caracteres vazia, , , , ou `NaN`; caso contrário, `null0false`seu .`true`
`['to-color', value]` `['to-color', value1, value2…]`	color	Converte o valor de entrada em uma cor. Se vários valores forem fornecidos, cada um é avaliado em ordem até que a primeira conversão bem-sucedida seja obtida. Se nenhuma das entradas puder ser convertida, a expressão é um erro.
`['to-number', value]` `['to-number', value1, value2, …]`	Número	Converte o valor de entrada em um número, se possível. Se a entrada for `null` ou `false`, o resultado será 0. Se a entrada for `true`, o resultado é 1. Se a entrada for uma cadeia de caracteres, ela será convertida em um número usando a função de cadeia de caracteres ToNumber da especificação de linguagem ECMAScript. Se vários valores forem fornecidos, cada um é avaliado em ordem até que a primeira conversão bem-sucedida seja obtida. Se nenhuma das entradas puder ser convertida, a expressão é um erro.
`['to-string', value]`	string	Converte o valor de entrada em uma cadeia de caracteres. Se a entrada for `null`, o resultado é `""`. Se a entrada for booleana, o resultado é `"true"` ou `"false"`. Se a entrada for um número, ela será convertida em uma cadeia de caracteres usando a função de número ToString da especificação de linguagem ECMAScript. Se a entrada for uma cor, ela será convertida em cadeia de caracteres `"rgba(r,g,b,a)"`de cores CSS RGBA. Caso contrário, a entrada é convertida em uma cadeia de caracteres usando a função JSON.stringify da especificação de linguagem ECMAScript.
`['typeof', value]`	string	Retorna uma cadeia de caracteres que descreve o tipo do valor fornecido.

Gorjeta

Se uma mensagem de erro semelhante aparecer Expression name must be a string, but found number instead. If you wanted a literal array, use ["literal", [...]]. no console do navegador, isso significa que há uma expressão em algum lugar no seu código que tem uma matriz que não tem uma cadeia de caracteres para seu primeiro valor. Se desejar que a expressão retorne uma matriz, envolva a matriz com a literal expressão. O exemplo a seguir define a opção de ícone offset de uma camada de símbolo, que precisa ser uma matriz contendo dois números, usando uma match expressão para escolher entre dois valores de deslocamento com base no valor da propriedade do recurso de entityType ponto.

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]]
        ]
    }
});

Expressões de cores

As expressões de cores facilitam a criação e manipulação de valores de cores.

Expression	Tipo devolvido	Descrição
`['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	Produz resultados contínuos e suaves interpolando entre pares de valores de entrada e saída ("stops"). Funciona como `interpolate`, mas o tipo de saída deve ser uma cor, e a interpolação é realizada no espaço de cores 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, ...]`	color	Produz resultados contínuos e suaves interpolando entre pares de valores de entrada e saída ("stops"). Funciona como `interpolate`, mas o tipo de saída deve ser uma cor, e a interpolação é realizada no espaço de cores do CIELAB.
`['rgb', number, number, number]`	color	Cria um valor de cor dos componentes vermelho, verde e azul que variam entre `0` e , e `255`um componente alfa do `1`. Se algum componente estiver fora do intervalo, a expressão será um erro.
`['rgba', number, number, number, number]`	color	Cria um valor de cor a partir de componentes vermelho, verde, azul que variam entre `0` e , e um componente alfa dentro de um intervalo de `0` e `2551`. Se algum componente estiver fora do intervalo, a expressão será um erro.
`['to-rgba']`	[número, número, número, número]	Retorna uma matriz de quatro elementos contendo os componentes vermelho, verde, azul e alfa da cor de entrada, nessa ordem.

Exemplo

O exemplo a seguir cria um valor de cor RGB que tem um valor vermelho de 255, e valores verdes e azuis calculados multiplicando 2.5 pelo valor da temperature propriedade. À medida que a temperatura muda, a cor muda para diferentes tons de vermelho.

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.
    ]
});

Expressões do operador de cadeia de caracteres

As expressões do operador de cadeia de caracteres executam operações de conversão em cadeias de caracteres, como concatenar e converter maiúsculas e minúsculas.

Expression	Tipo devolvido	Descrição
`['concat', string, string, …]`	string	Concatena várias cadeias de caracteres juntas. Cada valor deve ser uma cadeia de caracteres. Use a `to-string` expressão de tipo para converter outros tipos de valor em cadeia de caracteres, se necessário.
`['downcase', string]`	string	Converte a cadeia de caracteres especificada em minúsculas.
`['is-supported-script', string]` \| `['is-supported-script', Expression]`	boolean	Determina se a cadeia de caracteres de entrada usa um conjunto de caracteres suportado pela pilha de fontes atual. Por exemplo: `['is-supported-script', 'ಗೌರವಾರ್ಥವಾಗಿ']`
`['resolved-locale', string]`	string	Retorna a marca de idioma IETF da localidade que está sendo usada pelo collator fornecido que pode ser usada para determinar a localidade padrão do sistema ou para determinar se uma localidade solicitada foi carregada com êxito.
`['upcase', string]`	string	Converte a cadeia de caracteres especificada em maiúsculas.

Exemplo

O exemplo a seguir converte a temperature propriedade do recurso de ponto em uma cadeia de caracteres e, em seguida, concatena "°F" para o final dela.

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'
    }
});

A expressão acima renderiza um pino no mapa com o texto "64°F" sobreposto sobre ele, como mostrado na imagem a seguir.

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

Interpolar e Observar expressões

As expressões interpoladas e step podem ser usadas para calcular valores ao longo de uma curva interpolada ou função step. Essas expressões aceitam uma expressão que retorna um valor numérico como entrada, por exemplo ['get', 'temperature']. O valor de entrada é avaliado em relação a pares de valores de entrada e saída, para determinar o valor que melhor se ajusta à curva interpolada ou função de passo. Os valores de saída são chamados de "stops". Os valores de entrada para cada parada devem ser um número e estar em ordem crescente. Os valores de saída devem ser um número, uma matriz de números ou uma cor.

Expressão interpolada

Uma interpolate expressão pode ser usada para calcular um conjunto contínuo e suave de valores interpolando entre valores de parada. Uma interpolate expressão que retorna valores de cor produz um gradiente de cores no qual os valores de resultado são selecionados.

Existem três tipos de métodos de interpolação que podem ser usados em uma interpolate expressão:

['linear'] - Interpola linearmente entre o par de paragens.
['exponential', base] - Interpola exponencialmente entre as paragens. O base valor controla a taxa na qual a produção aumenta. Valores mais altos fazem com que a produção aumente mais para o topo da faixa. Um base valor próximo de 1 produz uma saída que aumenta de forma mais linear.
['cubic-bezier', x1, y1, x2, y2] - Interpola utilizando uma curva cúbica de Bezier definida pelos pontos de controlo indicados.

Aqui está um exemplo de como são esses diferentes tipos de interpolações.

Linear	Exponencial	Bezier cúbico

O pseudocódigo a seguir define a estrutura da interpolate expressão.

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

Exemplo

O exemplo a seguir usa uma expressão para definir a color propriedade de uma linear interpolate camada de bolha com base na temperature propriedade do recurso de ponto. Se o valor for inferior a temperature 60, "azul" é retornado. Se estiver entre 60 e menos de 70, o amarelo é devolvido. Se estiver entre 70 e menos de 80, "laranja" é devolvido. Se for 80 ou maior, "vermelho" é retornado.

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

A imagem a seguir demonstra como as cores são escolhidas para a expressão acima.

Interpolate expression example

Expressão de passo

Uma step expressão pode ser usada para calcular valores de resultados discretos e escalonados avaliando uma função constante por partes definida por paradas.

O pseudocódigo a seguir define a estrutura da step expressão.

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

As expressões de etapa retornam o valor de saída da parada imediatamente antes do valor de entrada, ou o primeiro valor de entrada se a entrada for menor que a primeira parada.

Exemplo

O exemplo a seguir usa uma expressão para definir a color propriedade de uma step camada de bolha com base na temperature propriedade do recurso de ponto. Se o valor for inferior a temperature 60, "azul" é retornado. Se estiver entre 60 e menos de 70, "amarelo" é retornado. Se estiver entre 70 e menos de 80, "laranja" é devolvido. Se for 80 ou maior, "vermelho" é retornado.

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

A imagem a seguir demonstra como as cores são escolhidas para a expressão acima.

Step expression example

Expressões específicas da camada

Expressões especiais que se aplicam apenas a camadas específicas.

Expressão da densidade do mapa de calor

Uma expressão de densidade de mapa de calor recupera o valor de densidade do mapa de calor para cada pixel em uma camada de mapa de calor e é definida como ['heatmap-density']. Este valor é um número entre 0 e 1. É usado em combinação com uma interpolation expressão ou step para definir o gradiente de cor usado para colorir o mapa de calor. Esta expressão só pode ser usada na opção de cor da camada de mapa de calor.

Gorjeta

A cor no índice 0, em uma expressão de interpolação ou a cor padrão de uma cor de etapa, define a cor da área onde não há dados. A cor no índice 0 pode ser usada para definir uma cor de fundo. Muitos preferem definir esse valor como transparente ou um preto semitransparente.

Exemplo

Este exemplo usa uma expressão de interpolação de linha para criar um gradiente de cor suave para renderizar o mapa de calor.

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

Além de usar um gradiente suave para colorir um mapa de calor, as cores podem ser especificadas dentro de um conjunto de intervalos usando uma step expressão. O uso de uma expressão para colorir o mapa de calor divide visualmente a densidade em intervalos que se assemelham a um mapa de step contorno ou estilo de 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'
    ]
});

Para obter mais informações, consulte a documentação Adicionar uma camada de mapa de calor.

Expressão de progresso de linha

Uma expressão de progresso de linha recupera o progresso ao longo de uma linha de gradiente em uma camada de linha e é definida como ['line-progress']. Este valor é um número entre 0 e 1. É usado em combinação com uma interpolation ou step expressão. Esta expressão só pode ser usada com a opção strokeGradient da camada de linha.

Nota

A strokeGradient opção da camada de linha requer que a lineMetrics opção da fonte de dados seja definida como true.

Exemplo

Este exemplo usa a ['line-progress'] expressão para aplicar um gradiente de cor ao traçado de uma linha.

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"
    ]
});

Para obter um exemplo de trabalho interativo, consulte Adicionar um gradiente de traçado a uma linha.

Expressão de formato de campo de texto

A expressão de formato de campo de texto pode ser usada com a textField opção da propriedade symbol layers textOptions para fornecer formatação de texto mista. Esta expressão permite especificar um conjunto de cadeias de caracteres de entrada e opções de formatação. As opções a seguir podem ser especificadas para cada cadeia de caracteres de entrada nesta expressão.

'font-scale' - Especifica o fator de escala para o tamanho da fonte. Se especificado, esse valor substitui a propriedade do para a size cadeia de textOptions caracteres individual.
'text-font' - Especifica uma ou mais famílias de fontes que devem ser usadas para esta cadeia de caracteres. Se especificado, esse valor substitui a propriedade do para a font cadeia de textOptions caracteres individual.

O pseudocódigo a seguir define a estrutura da expressão de formato de campo de texto.

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

Exemplo

O exemplo a seguir formata o campo de texto adicionando uma fonte em negrito e aumentando o tamanho da fonte da title propriedade do recurso. Este exemplo também adiciona a subTitle propriedade do recurso em uma nova linha, com um tamanho de fonte reduzido.

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
            }
        ]
    }
});

Essa camada renderiza o recurso de ponto conforme mostrado na imagem a seguir:

Image of Point feature with formatted text field

Expressão de formato de número

A number-format expressão só pode ser usada com a textField opção de uma camada de símbolo. Esta expressão converte o número fornecido em uma cadeia de caracteres formatada. Esta expressão encapsula a função Number.toLocalString do JavaScript e suporta o seguinte conjunto de opções.

locale - Especifique esta opção para converter números em strings de uma forma que se alinhe com o idioma especificado. Passe uma marca de idioma BCP 47 para esta opção.
currency - Para converter o número em uma string que representa uma moeda. Os valores possíveis são os códigos de moeda ISO 4217, como "USD" para o dólar americano, "EUR" para o euro ou "CNY" para o RMB chinês.
'min-fraction-digits' - Especifica o número mínimo de casas decimais a incluir na versão da cadeia de caracteres do número.
'max-fraction-digits' - Especifica o número máximo de casas decimais a incluir na versão da cadeia de caracteres do número.

O pseudocódigo a seguir define a estrutura da expressão de formato de campo de texto.

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

Exemplo

O exemplo a seguir usa uma expressão para modificar como a revenue propriedade do recurso de ponto é renderizada na textField opção de uma number-format camada de símbolo de modo que pareça um valor em dólares dos EUA.

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

        offset: [0, 0.75]
    }
});

Essa camada renderiza o recurso de ponto conforme mostrado na imagem a seguir:

Number format expression example

Expressão da imagem

Uma expressão de imagem pode ser usada com as image opções e de uma camada de símbolo e textField a fillPattern opção da camada de polígono. Essa expressão verifica se a imagem solicitada existe no estilo e retorna o nome da imagem resolvida ou , dependendo se a imagem está ou nullnão no estilo. Esse processo de validação é síncrono e requer que a imagem tenha sido adicionada ao estilo antes de solicitá-la no argumento image.

Exemplo

O exemplo a seguir usa uma expressão para adicionar um ícone embutido com texto em uma image camada de símbolo.

 //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']
        }
    }));
});

Essa camada renderiza o campo de texto na camada de símbolo, conforme mostrado na imagem a seguir:

Image expression example

Expressão de zoom

Uma zoom expressão é usada para recuperar o nível de zoom atual do mapa em tempo de renderização e é definida como ['zoom']. Esta expressão retorna um número entre o intervalo de nível de zoom mínimo e máximo do mapa. Os controles de mapa interativo do Azure Maps para Web e Android suportam 25 níveis de zoom, numerados de 0 a 24. O uso da expressão permite que os zoom estilos sejam modificados dinamicamente à medida que o nível de zoom do mapa é alterado. A zoom expressão só pode ser usada com interpolate e step expressões.

Exemplo

Por padrão, os raios dos pontos de dados renderizados na camada de mapa de calor têm um raio de pixel fixo para todos os níveis de zoom. À medida que o mapa é ampliado, os dados se agregam e a camada do mapa de calor parece diferente. Uma zoom expressão pode ser usada para dimensionar o raio para cada nível de zoom de modo que cada ponto de dados cubra a mesma área física do mapa. Isso faz com que a camada de mapa de calor pareça mais estática e consistente. Cada nível de zoom do mapa tem o dobro de pixels vertical e horizontalmente do que o nível de zoom anterior. Dimensionar o raio, de modo que ele duplique a cada nível de zoom, cria um mapa de calor que parece consistente em todos os níveis de zoom. Isso pode ser feito usando a expressão com uma base 2 exponential interpolation expressão, com o raio de pixel definido para o nível mínimo de zoom e um raio dimensionado para o nível de zoom máximo calculado como 2 * Math.pow(2, minZoom - maxZoom) demonstrado no exemplo a zoom seguir.

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)
    ]
};

Para obter um exemplo de trabalho interativo, consulte Mapa de calor com zoom consistente.

Expressões de vinculação variável

As expressões de vinculação de variáveis armazenam os resultados de um cálculo em uma variável. Assim, que os resultados do cálculo podem ser referenciados em outro lugar em uma expressão várias vezes. É uma otimização útil para expressões que envolvem muitos cálculos.

Expression	Tipo devolvido	Descrição
[ «Vamos», nome1: string, valor1: qualquer, nome2: string, valor2: qualquer, ... childExpression ]		Armazena um ou mais valores como variáveis para uso pela `var` expressão na expressão filho que retorna o resultado.
`['var', name: string]`	qualquer	Faz referência a uma variável que foi criada usando a `let` expressão.

Exemplo

Este exemplo usa uma expressão que calcula a receita relativa à razão de temperatura e, em seguida, usa uma case expressão para avaliar diferentes operações booleanas nesse valor. A let expressão é usada para armazenar a receita relativa à razão de temperatura, de modo que ela só precisa ser calculada uma vez. A var expressão faz referência a essa variável quantas vezes forem necessárias, sem ter que recalculá-la.

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'
        ]
    ]
});