首页 / MapLibre / API 文档

样式表达式

先看结论

把样式属性写成数组形式的小表达式，按要素属性或缩放级别算值，一份配置覆盖多档显示。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-28 · 引用本文

['interpolate', ['linear'], ['zoom'], 4, 1, 10, 6]

基本规则

规则	说明
数组第一个元素	操作符名，其余位置是参数
字面量数组	参数本身就是数组时用 `['literal', [...]]` 包一层
数据表达式	依赖 `['get']` 等读取要素属性
相机表达式	依赖 `['zoom']`，不允许混入 `get`
类型	结果必须是该属性要求的类型，颜色、数字、字符串不能互串

常用操作符

操作符	用途	要点
`get`	读取属性	`['get', 'NAME']`
`has`	属性是否存在	返回布尔值
`match`	离散分类	最后一对是默认值，可省略
`case`	条件分支	条件必须是布尔表达式
`step`	分段常量	比 `interpolate` 省，图标尺寸常用
`interpolate`	连续插值	需指定插值方式与输入
`coalesce`	取第一个非空值	处理缺失属性的兜底
`zoom`	当前缩放级别	只在相机表达式里可用
`feature-state`	读取要素状态	需要要素 id 与 `setFeatureState`
`literal`	原样返回数组	避免被当成表达式解析
`to-number`	类型转换	属性常以字符串存放
`concat`	拼接字符串	拼名称与数值

示例

/* 按属性分类着色，未命中的走默认色 */
map.setPaintProperty('world-fill', 'fill-color', [
  'match', ['get', 'CONTINENT'],
  'Asia', '#dbe7f3',
  'Europe', '#e6e0f3',
  'Africa', '#f3ecdb',
  '#e9ecef'
]);

/* 线宽随缩放连续变化 */
map.setPaintProperty('world-line', 'line-width', [
  'interpolate', ['linear'], ['zoom'],
  2, 0.5,
  6, 2,
  10, 5
]);

/* 数值分段，避免连续插值造成图标忽大忽小 */
map.setPaintProperty('city-dot', 'circle-radius', [
  'step', ['to-number', ['get', 'pop']],
  3,
  1000000, 6
]);

/* 缺属性时的兜底 */
map.setLayoutProperty('city-label', 'text-field', [
  'coalesce', ['get', 'NAME'], ['get', 'name'], '未命名'
]);

注意事项

表达式在样式解析阶段就会校验，写错类型通常在控制台给出「Expected value to be of type …」而不是运行时静默失败。把错误信息里的属性名与表达式对照，能快速定位。

['zoom'] 与 ['get'] 不能出现在同一个表达式里。需要「缩放 + 属性」双重控制时，用 interpolate 的输入包一层 get，或拆成两个图层分别控制。

旧写法不要混用。stops 形式的属性函数与表达式结构不同，同一属性只保留一种写法，混写会让样式校验报错，排查成本很高。

引用本文

经纬志（2026）。《样式表达式》。https://www.jingweizhi.com/maplibre/api/style-expression.html（访问日期 2026-11-03）。