首页 / MapLibre / API 文档
setLayoutProperty
先看结论
改布局属性，控制图层显隐、标注文字与图标大小，部分改动会触发重新排布。
map.setLayoutProperty(layerId, 'visibility', 'none')
参数
| 参数 | 类型 | 说明 |
|---|---|---|
layerId | string | 目标图层 id |
name | string | 布局属性名 |
value | any | 字面量或表达式 |
options.validate | boolean | 默认 true，校验值合法性 |
常见属性
| 属性 | 默认 | 说明 |
|---|---|---|
visibility | 'visible' | 另一个值为 'none' |
text-field | — | 标注内容，常用 ['get', 'NAME'] |
text-size | 16 | 字号，像素 |
text-anchor | 'center' | 文字相对锚点的方位 |
text-allow-overlap | false | true 时不避让，全部显示 |
icon-image | — | 图标名，需先用 addImage 注册 |
icon-size | 1 | 图标缩放倍数 |
icon-allow-overlap | false | 同文字避让开关 |
line-cap | 'butt' | 线端样式，可选 round、square |
symbol-placement | 'point' | 沿线的文字用 'line' |
相关成员
| 成员 | 说明 |
|---|---|
getLayoutProperty(layerId, name) | 读取当前布局值 |
setPaintProperty(layerId, name, value) | 改绘制属性，不触发重排 |
setFilter(layerId, filter) | 按属性筛选要素 |
getLayer(layerId) | 判断图层是否已存在 |
示例
/* 显隐：布局属性里代价最低的一项 */
document.getElementById('toggle').addEventListener('change', function () {
map.setLayoutProperty(
'world-name',
'visibility',
this.checked ? 'visible' : 'none'
);
});
/* 字随缩放变大 */
map.setLayoutProperty('world-name', 'text-size', [
'interpolate', ['linear'], ['zoom'], 2, 9, 6, 14
]);
/* 关闭避让，所有标注都画出来 */
map.setLayoutProperty('world-name', 'text-allow-overlap', true);
map.setLayoutProperty('world-name', 'text-ignore-placement', true);
/* 线的端点改成圆头 */
map.setLayoutProperty('world-line', 'line-cap', 'round');注意事项
visibility 只是跳过绘制，图层与数据都还在，切回来立即出现。
需要真正释放资源时用 removeLayer，代价是重新添加要重建索引。
文字、图标相关的布局属性改动会触发重新排布与碰撞检测， 一次拖拽中连续修改几十次就会卡。做动画时改用绘制属性， 或用节流限制到每帧一次。
text-field 空值。属性缺失时表达式返回空，
标注只剩图标。给 get 套一层
coalesce 提供兜底文字，避免出现半截符号。
经纬志（2026）。《setLayoutProperty》。https://www.jingweizhi.com/maplibre/api/set-layout-property.html（访问日期 2026-11-03）。