Appearance
图层简介
Layout 布局属性
布局属性定义了图层的结构、位置和可见性。修改这些属性通常会导致重新计算几何形状（开销较大）。
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| visibility | [通用] 控制图层的显示或隐藏。 | String | 'visible', 'none' | 'visible' |
| line-cap | [Line] 线条末端的形状。 | String | 'butt', 'round', 'square' | 'butt' |
| line-join | [Line] 线条拐角处的连接形状。 | String | 'bevel', 'round', 'miter' | 'miter' |
| line-miter-limit | [Line] 当 line-join 为 miter 时，用于限制尖角长度的阈值。 | Number | Number | 2 |
| line-round-limit | [Line] 当 line-join 为 round 时，用于平滑拐角的半径。 | Number | Number | 1.05 |
| line-sort-key | [Line] 根据数据字段对线条进行排序渲染（控制堆叠顺序）。 | Number | Number | - |
| symbol-placement | [Symbol] 符号放置策略。'point'为点，'line'沿线，'line-center'线中心。 | String | 'point', 'line', 'line-center' | 'point' |
| symbol-spacing | [Symbol] 当沿线放置时，符号之间的距离（像素）。 | Number | Number | 250 |
| symbol-avoid-edges | [Symbol] 是否避免符号在瓦片边界被裁剪。 | Boolean | true, false | false |
| symbol-sort-key | [Symbol] 控制符号的渲染顺序（z-index）。值越高越靠上。 | Number | Number | - |
| symbol-z-order | [Symbol] 符号排序策略。 | String | 'auto', 'viewport-y', 'source' | 'auto' |
| icon-image | [Symbol] 图标名称（对应 Sprite ID）。 | String | String | - |
| icon-size | [Symbol] 图标缩放比例。 | Number | Number | 1 |
| icon-rotate | [Symbol] 图标旋转角度。 | Number | Number | 0 |
| icon-offset | [Symbol] 图标相对于锚点的偏移 [x, y]。 | Array | [Number, Number] | [0, 0] |
| icon-anchor | [Symbol] 图标锚点位置。 | String | 'center', 'left', 'right', 'top', 'bottom'等 | 'center' |
| icon-allow-overlap | [Symbol] 是否允许图标重叠。 | Boolean | true, false | false |
| icon-ignore-placement | [Symbol] 是否忽略碰撞检测强制显示。 | Boolean | true, false | false |
| icon-optional | [Symbol] 如果图标与文本碰撞，是否仅隐藏图标保留文本。 | Boolean | true, false | false |
| icon-rotation-alignment | [Symbol] 图标旋转对齐方式。 | String | 'map', 'viewport', 'auto' | 'auto' |
| icon-text-fit | [Symbol] 图标是否缩放以适应文本（用于背景框）。 | String | 'none', 'width', 'height', 'both' | 'none' |
| icon-text-fit-padding | [Symbol] 图标适应文本时的内边距 [上, 右, 下, 左]。 | Array | [Number, Number, Number, Number] | [0,0,0,0] |
| icon-keep-upright | [Symbol] 当放置在直线上时，防止图标倒置。 | Boolean | true, false | false |
| text-field | [Symbol] 文本内容。支持格式化表达式 '{name}'。 | String | String | "" |
| text-font | [Symbol] 字体栈数组。 | Array | Array | ['Open Sans Regular'] |
| text-size | [Symbol] 字体大小（像素）。 | Number | Number | 16 |
| text-max-width | [Symbol] 文本最大宽度（em），超过换行。 | Number | Number | 10 |
| text-line-height | [Symbol] 行高（em）。 | Number | Number | 1.2 |
| text-letter-spacing | [Symbol] 字间距（em）。 | Number | Number | 0 |
| text-justify | [Symbol] 文本对齐方式。 | String | 'auto', 'left', 'center', 'right' | 'center' |
| text-anchor | [Symbol] 文本锚点位置。 | String | 'center', 'top', 'bottom', 'left', 'right'等 | 'center' |
| text-variable-anchor | [Symbol] 为了避免碰撞，允许文本自动尝试的一组锚点位置。 | Array | Array | - |
| text-radial-offset | [Symbol] 结合 variable-anchor 使用的径向偏移量。 | Number | Number | 0 |
| text-offset | [Symbol] 文本固定偏移 [x, y] (em)。 | Array | [Number, Number] | [0, 0] |
| text-allow-overlap | [Symbol] 是否允许文本重叠。 | Boolean | true, false | false |
| text-ignore-placement | [Symbol] 是否忽略碰撞检测强制显示。 | Boolean | true, false | false |
| text-optional | [Symbol] 如果文本与图标碰撞，是否仅隐藏文本保留图标。 | Boolean | true, false | false |
| text-rotation-alignment | [Symbol] 文本旋转对齐方式。 | String | 'map', 'viewport', 'auto' | 'auto' |
| text-pitch-alignment | [Symbol] 文本倾斜对齐方式。 | String | 'map', 'viewport', 'auto' | 'auto' |
| circle-sort-key | [Circle] 圆点排序键值（z-index）。 | Number | Number | - |
| fill-sort-key | [Fill] 根据数据字段对填充多边形进行排序渲染。 | Number | Number | - |
Paint 绘制属性
绘制属性定义了图层的颜色和视觉效果。修改这些属性通常由 GPU 处理（开销较小，适合动画）。
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| background-color | [Background] 背景色。 | Color | Hex, RGB, RGBA | '#000000' |
| background-pattern | [Background] 背景填充图案（Sprite ID）。 | String | String | - |
| background-opacity | [Background] 背景不透明度。 | Number | 0 ~ 1 | 1 |
| fill-color | [Fill] 填充颜色。 | Color | Hex, RGB, RGBA | '#000000' |
| fill-opacity | [Fill] 填充不透明度。 | Number | 0 ~ 1 | 1 |
| fill-outline-color | [Fill] 描边颜色（当 antialias 为 true 时生效）。 | Color | Hex, RGB, RGBA | - |
| fill-translate | [Fill] 几何体平移 [x, y] 像素。 | Array | [Number, Number] | [0, 0] |
| fill-translate-anchor | [Fill] 平移的参照系（地图或视口）。 | String | 'map', 'viewport' | 'map' |
| fill-pattern | [Fill] 填充图案（Sprite ID）。 | String | String | - |
| fill-antialias | [Fill] 是否开启抗锯齿。 | Boolean | true, false | true |
| line-opacity | [Line] 线条不透明度。 | Number | 0 ~ 1 | 1 |
| line-color | [Line] 线条颜色。 | Color | Hex, RGB, RGBA | '#000000' |
| line-width | [Line] 线条宽度（像素）。 | Number | Number | 1 |
| line-gap-width | [Line] 绘制双线时的中间间隙宽度（用于空心线）。 | Number | Number | 0 |
| line-offset | [Line] 线条相对于中心线的偏移量（像素）。 | Number | Number | 0 |
| line-blur | [Line] 线条边缘模糊程度（像素）。 | Number | Number | 0 |
| line-dasharray | [Line] 虚线模式 [实线长, 间隙长]。 | Array | [Number, Number] | - |
| line-pattern | [Line] 线条填充图案（Sprite ID）。 | String | String | - |
| line-gradient | [Line] 线条渐变色（仅当 source 为 GeoJSON 且 line-metrics=true 时有效）。 | Color | Hex, RGB, RGBA | - |
| line-translate | [Line] 线条整体平移 [x, y]。 | Array | [Number, Number] | [0, 0] |
| line-translate-anchor | [Line] 平移参照系。 | String | 'map', 'viewport' | 'map' |
| icon-opacity | [Symbol] 图标不透明度。 | Number | 0 ~ 1 | 1 |
| icon-color | [Symbol] 图标颜色（仅对 SDF 图标有效）。 | Color | Hex, RGB, RGBA | '#000000' |
| icon-halo-color | [Symbol] 图标光晕颜色（仅对 SDF 图标有效）。 | Color | Hex, RGB, RGBA | 'rgba(0,0,0,0)' |
| icon-halo-width | [Symbol] 图标光晕宽度。 | Number | Number | 0 |
| icon-halo-blur | [Symbol] 图标光晕模糊度。 | Number | Number | 0 |
| icon-translate | [Symbol] 图标平移 [x, y]。 | Array | [Number, Number] | [0, 0] |
| icon-translate-anchor | [Symbol] 平移参照系。 | String | 'map', 'viewport' | 'map' |
| text-opacity | [Symbol] 文本不透明度。 | Number | 0 ~ 1 | 1 |
| text-color | [Symbol] 文本颜色。 | Color | Hex, RGB, RGBA | '#000000' |
| text-halo-color | [Symbol] 文本光晕（描边）颜色。 | Color | Hex, RGB, RGBA | 'rgba(0,0,0,0)' |
| text-halo-width | [Symbol] 文本光晕宽度。 | Number | Number | 0 |
| text-halo-blur | [Symbol] 文本光晕模糊度。 | Number | Number | 0 |
| text-translate | [Symbol] 文本平移 [x, y]。 | Array | [Number, Number] | [0, 0] |
| text-translate-anchor | [Symbol] 平移参照系。 | String | 'map', 'viewport' | 'map' |
| circle-radius | [Circle] 圆半径（像素）。 | Number | Number | 5 |
| circle-color | [Circle] 圆颜色。 | Color | Hex, RGB, RGBA | '#000000' |
| circle-blur | [Circle] 圆边缘模糊度（0为锐利，1为模糊）。 | Number | Number | 0 |
| circle-opacity | [Circle] 圆不透明度。 | Number | 0 ~ 1 | 1 |
| circle-translate | [Circle] 圆平移 [x, y]。 | Array | [Number, Number] | [0, 0] |
| circle-translate-anchor | [Circle] 平移参照系。 | String | 'map', 'viewport' | 'map' |
| circle-stroke-width | [Circle] 圆外描边宽度。 | Number | Number | 0 |
| circle-stroke-color | [Circle] 圆外描边颜色。 | Color | Hex, RGB, RGBA | '#000000' |
| circle-stroke-opacity | [Circle] 圆外描边不透明度。 | Number | 0 ~ 1 | 1 |
| circle-pitch-scale | [Circle] 地图倾斜时圆的缩放策略。 | String | 'map', 'viewport' | 'map' |
| circle-pitch-alignment | [Circle] 地图倾斜时圆的对齐方式。 | String | 'map', 'viewport' | 'viewport' |
| fill-extrusion-opacity | [3D] 3D 模型不透明度。 | Number | 0 ~ 1 | 1 |
| fill-extrusion-color | [3D] 3D 模型颜色。 | Color | Hex, RGB, RGBA | '#000000' |
| fill-extrusion-translate | [3D] 几何体平移 [x, y]。 | Array | [Number, Number] | [0, 0] |
| fill-extrusion-height | [3D] 拉伸的高度（米）。 | Number | Number | 0 |
| fill-extrusion-base | [3D] 拉伸的底部离地高度（米）。 | Number | Number | 0 |
| fill-extrusion-vertical-gradient | [3D] 是否启用垂直方向的光影渐变。 | Boolean | true, false | true |
| raster-opacity | [Raster] 图片不透明度。 | Number | 0 ~ 1 | 1 |
| raster-hue-rotate | [Raster] 色相旋转角度（度）。 | Number | Number | 0 |
| raster-brightness-min | [Raster] 最小亮度（0~1）。 | Number | 0 ~ 1 | 0 |
| raster-brightness-max | [Raster] 最大亮度（0~1）。 | Number | 0 ~ 1 | 1 |
| raster-saturation | [Raster] 饱和度（-1~1）。 | Number | -1 ~ 1 | 0 |
| raster-contrast | [Raster] 对比度（-1~1）。 | Number | -1 ~ 1 | 0 |
| raster-resampling | [Raster] 重采样算法。 | String | 'linear', 'nearest' | 'linear' |
| raster-fade-duration | [Raster] 瓦片加载时的淡入时间（毫秒）。 | Number | Number | 300 |