MapboxGL Wiki

简体中文

English

简体中文

English

Appearance

表达式系统 ​

目的和范围 ​

表达式系统是 Mapbox GL JS 的核心组件,支持地图要素的动态、数据驱动样式。它提供了一种灵活的语言来定义可以基于要素属性、缩放级别和其他上下文信息在运行时计算的值。本文档描述了 Mapbox GL JS 样式规范内表达式的架构、语法和用法。

有关样式总体定义和结构的信息,请参阅 样式规范。

概述 ​

表达式系统允许地图动态响应数据,创建基于要素属性或地图状态变化的可视化。表达式可以在许多样式属性中使用,用计算值替换静态值。

SVG
100%

表达式结构 ​

Mapbox GL JS 中的表达式表示为 JSON 数组,其中第一个元素是运算符或表达式名称,其余元素是表达式的参数。

SVG
100%

表达式可以任意深度嵌套,允许进行复杂计算。在 TypeScript 中,表达式使用类型 ExpressionSpecification 定义:

export type ExpressionSpecification = [string, ...any[]];

表达式类型 ​

Mapbox GL JS 支持多种不同用途的表达式类型。以下是主要类别:

数据表达式 ​

数据表达式访问正在样式的要素的属性。

ExpressionDescriptionExample
["get", "property"]从当前要素检索属性值["get", "population"]
["has", "property"]检查当前要素上是否存在属性["has", "name"]
["properties"]获取当前要素的所有属性["properties"]

类型表达式 ​

类型表达式在类型之间转换值。

ExpressionDescriptionExample
["string", value]将值转换为字符串["string", ["get", "population"]]
["number", value]将值转换为数字["number", ["get", "code"]]
["boolean", value]将值转换为布尔值["boolean", ["get", "is_capital"]]

数学表达式 ​

数学表达式执行计算。

ExpressionDescriptionExample
["+", a, b, ...]加法["+", ["get", "x"], ["get", "y"]]
["-", a, b]减法["-", ["get", "total"], ["get", "used"]]
["*", a, b, ...]乘法["*", ["get", "rate"], 100]
["/", a, b]除法["/", ["get", "population"], 1000000]

字符串表达式 ​

字符串表达式操作文本。

ExpressionDescriptionExample
["concat", a, b, ...]连接字符串["concat", ["get", "first_name"], " ", ["get", "last_name"]]
["format", ...]创建格式化文本["format", ["get", "name"], {"font-scale": 1.2}]

颜色表达式 ​

颜色表达式创建和操作颜色。

ExpressionDescriptionExample
["rgb", r, g, b]从 RGB 值创建颜色["rgb", 255, 0, 0]
["rgba", r, g, b, a]创建带 Alpha 的颜色["rgba", 255, 0, 0, 0.5]

条件表达式 ​

条件表达式根据输入数据做出决策。

ExpressionDescriptionExample
["case", condition1, output1, condition2, output2, ..., default]选择第一个为真的条件的输出["case", ["<", ["get", "temp"], 32], "blue", ["<", ["get", "temp"], 60], "yellow", "red"]
["match", input, value1, output1, value2, output2, ..., default]将输入与值匹配["match", ["get", "building"], "restaurant", "red", "hotel", "blue", "gray"]
["coalesce", value1, value2, ...]返回第一个非空值["coalesce", ["get", "name"], ["get", "ref"], "Unnamed"]

表达式评估 ​

SVG
100%

表达式在以下情况下评估:

  1. 加载样式并计算初始图层属性值时
  2. 地图的缩放级别变化时(对于缩放相关表达式)
  3. 加载或更改要素数据时(对于数据驱动属性)

每个表达式类型都有自己的评估逻辑,但遵循以下一般模式:

  1. 评估任何嵌套表达式以获取其值
  2. 对这些值应用表达式的操作
  3. 返回结果

在样式属性中使用表达式 ​

表达式可以在许多样式属性中代替静态值使用。Style Specification 定义了哪些属性支持表达式以及它们支持哪种类型的表达式。

SVG
100%

以下是表达式如何与图层属性关联:

export type PropertyValueSpecification<T> =
    | T
    | CameraFunctionSpecification<T>
    | ExpressionSpecification;

export type DataDrivenPropertyValueSpecification<T> =
    | T
    | FunctionSpecification<T>
    | CameraFunctionSpecification<T>
    | SourceFunctionSpecification<T>
    | CompositeFunctionSpecification<T>
    | ExpressionSpecification;

常见用例 ​

数据驱动样式 ​

表达式最常见的用途之一是基于属性样式化地图要素:

{
  "circle-color": [
    "match",
    ["get", "land_use_type"],
    "park", "green",
    "residential", "yellow",
    "commercial", "blue",
    "gray"  // default
  ]
}

缩放相关样式 ​

表达式可以基于当前缩放级别更改属性值:

{
  "circle-radius": [
    "interpolate", ["linear"], ["zoom"],
    10, 2,
    15, 10,
    20, 20
  ]
}

复合表达式 ​

复杂的可视化通常组合多个表达式:

{
  "circle-color": [
    "case",
    [">=", ["get", "population"], 1000000], "red",
    [">=", ["get", "population"], 100000], "orange",
    [">=", ["get", "population"], 10000], "yellow",
    "blue"
  ],
  "circle-radius": [
    "*",
    ["log10", ["max", 1000, ["get", "population"]]],
    2
  ]
}

过滤器 ​

表达式还用于图层过滤器以确定应显示哪些要素:

{
  "filter": [
    "all",
    ["==", ["get", "type"], "restaurant"],
    [">", ["get", "rating"], 4.5]
  ]
}

过滤器表达式使用略有不同的规范,但遵循与属性值表达式相同的一般原则。

表达式类型系统 ​

Mapbox GL JS 中的表达式具有静态类型系统,确保评估期间的类型兼容性。表达式解析器验证表达式产生它们所使用的属性期望类型的值。

SVG
100%

每个属性都有关于它可以接受什么类型值的期望。例如,circle-radius 属性期望数字值,而 circle-color 属性期望颜色。

传统函数语法与表达式 ​

在表达式系统之前,Mapbox GL JS 使用函数语法进行数据驱动和缩放相关的样式。虽然为了向后兼容性仍支持此功能,但建议使用表达式:

/**
 * @deprecated 请改用 [Expressions](https://docs.mapbox.com/style-spec/reference/expressions/) 语法。
*/
export type FunctionSpecification<T> = {
    stops: Array<PropertyFunctionStop<T> | ZoomAndPropertyFunctionStop<T>>;
    base?: number;
    property?: string;
    type?: 'identity' | 'exponential' | 'interval' | 'categorical';
    colorSpace?: 'rgb' | 'lab' | 'hcl';
    default?: T;
};

结论 ​

表达式系统是 Mapbox GL JS 的强大功能,支持基于要素属性、缩放级别和其他因素的动态样式和过滤。它提供了一种灵活的语言来定义数据和呈现之间的复杂视觉关系。

Copyright © 2026 LZUGIS