name	minemap-style-and-data
description	MineMap 样式规范（style v8）、source/layer 管理、图标资源、GeoJSON 更新与数据源组织，重点补全 VectorTileSource 参数与约束。

MineMap Style and Data

Quick Start

map.on("style.load", () => {
	map.addSource("poi", {
		type: "geojson",
		data: { type: "FeatureCollection", features: [] }
	});

	map.addLayer({
		id: "poi-circle",
		type: "circle",
		source: "poi",
		paint: {
			"circle-radius": 5,
			"circle-color": "#2d8cf0"
		}
	});
});

Core Concepts

1) Style 版本与结构

MineMap 使用 style spec version: 8，核心字段仍然是：

sources
layers
sprite
glyphs

2) 常用 source 类型

vector
raster
geojson
image

补充结论：

历史上的 3d-model / 3d-tiles source/layer 方式已不推荐
新三维对象统一优先 map.addSceneComponent()

3) Layer 基础操作

addLayer(layer, before?)
removeLayer(id)
moveLayer(id, beforeId?)
setFilter(layerId, filter)
setLayoutProperty() / setPaintProperty()

4) GeoJSON 聚合与批量合并

可用 addSourceGroup(id, source) 处理多份 GeoJSON 异步合并；引擎会先注入临时数据，避免 addLayer 时 source 不存在。

5) 图像资源

loadImage(url, cb) + addImage(id, image, options)
loadImages([{ id, url, imageOptions? }], cb, options)
updateImage(id, image)
hasImage(id) / removeImage(id) / listImages()

最近版本补充结论：

loadImages 当前主路径是描述符数组，不再推荐只传 string[]
描述符模式下会在内部自动执行 addImage(...)
单项结果按数组返回，每项包含 id、url、isOk、image/error
每个图片项可带 imageOptions，会透传到内部 addImage(...)

兼容说明：

string[] 仍兼容，但已进入弃用兼容模式
兼容模式下不会自动 addImage(...)
回调第二个参数是以原始 URL 为 key 的图片对象，而不是新数组结果结构

6) WMTS、RTL 与辅助数据工具

source/index.js 暴露了几类容易漏掉、但确实属于正式开发面的数据入口：

WMTSCapabilities
optionsFromCapabilities(...)
setRTLTextPlugin(...)
getRTLTextPluginStatus()
minemap.util.getJSON(...)
minemap.util.getString(...)

这些更适合放在“数据接入层”。

VectorTileSource 深入说明

这一节以 source/data-source/source-cache/VectorTileSource.js 为准，不按旧博客或旧版 Mapbox 经验脑补。

创建方式

map.addSource("road-source", {
	type: "vector",
	tiles: ["https://example.com/mvt/{z}/{x}/{y}.pbf"],
	minzoom: 1,
	maxzoom: 20
});

参数总表

必备或常见字段

type: 'vector'
url
tiles
scheme
projection
attribution
tileSize
minzoom
maxzoom
bounds
adcode
promoteId
adaptTerrain

`url` 和 `tiles`

两者二选一即可：

url：通过 TileJSON 地址间接拿瓦片描述
tiles：直接给瓦片模板 URL 数组

业务上更常见的是直接给 tiles。

`scheme`

注释给的标准值：

xyz
tms

默认是 xyz。

`projection`

注释写法是字符串，如 MERCATOR；源码里实际走投影类型判断。

实际建议：

非必要不要乱改
除非明确知道服务端输出不是常规墨卡托瓦片

`tileSize`

这是最容易被写错的点。

源码构造器里直接做了硬校验：

vector tile sources must have a tileSize of 512

也就是说：

VectorTileSource 的 tileSize 必须是 512
不是“推荐 512”，而是“不是 512 就抛错”

`minzoom` / `maxzoom`

源码真实默认值来自 LayerZoomConfig.VECTOR_DEFAULT_ZOOM：

minzoom = 0
maxzoom = 20

这点比一些注释旧文本更重要，因为运行时实际就是这么取默认值。

使用建议：

如果你的服务有 20 级以上更细数据，必须主动把 source 的 maxzoom 往上提
否则 layer 再设更大 maxzoom 也只是继续放大旧层级

`bounds`

格式：

[west, south, east, north]

作用：

限制 source 的有效空间范围
避免在全球范围无意义发请求

`adcode`

这是 MineMap 自己扩的重点参数。

含义：

按行政区划编码过滤数据

源码还实现了 adcode 的 setter：

修改后会触发 source reload

因此它不是静态元数据，而是可以作为运行时切区工具使用。

前提：

服务端必须真的支持按行政区划编码返回数据

`promoteId`

作用：

指定哪个属性作为 feature id，用于 feature-state 之类的能力

可写法：

直接字符串：对所有 source-layer 统一用同一字段
对象：按 source-layer 分别指定字段

这是做 setFeatureState()、交互高亮、运行时状态染色时的重要前置。

`adaptTerrain`

这是 MineMap 的重点扩展能力。

作用：

让 vector source 级别的数据贴合 DEM 地形

源码注释明确写了边界：

在 source 上设置后，layer 上无需再设
这样只能贴合 terrain / DEM
不能贴合 3D Tiles 和模型
当前主要适用于 LineStyleLayer、FillStyleLayer

这点很关键：

贴地 terrain 和贴 3D Tiles / 模型不是一回事
不要把 adaptTerrain 当成“万能贴所有三维表面”

`clippingPlanes`

源码里 VectorTileSource 也挂了 clippingPlanes 字段，但这不是常规对外主能力，技能库不把它当作常规 vector source 首选参数。

贴地推荐写法

map.addSource("line-source", {
	type: "vector",
	tiles: ["https://example.com/mvt/{z}/{x}/{y}.pbf"],
	tileSize: 512,
	adaptTerrain: true,
	minzoom: 1,
	maxzoom: 20
});

什么时候优先 vector，而不是 GeoJSON

优先 vector 的典型场景：

数据量大
需要分层级加载
同一数据有多个 source-layer
想把贴地、大范围路网、行政区、建筑分层统一进瓦片服务

优先 geojson 的典型场景：

小规模临时数据
前端实时生成数据
只做局部交互实验

Common Patterns

`loadImages` 新主路径

map.loadImages(
	[
		{ id: "cat", url: "https://example.com/cat.png", imageOptions: { pixelRatio: 2 } },
		{ id: "dog", url: "https://example.com/dog.png" }
	],
	(error, result) => {
		if (error) console.error(error);
		console.log(result);
	},
	{
		onProgress: (loaded, total) => console.log(loaded, total)
	}
);

这条路径的优点是：

加载完成后自动 addImage(...)
图片 id 明确，不再依赖 URL 推导
单项失败不会把成功项的结果结构抹平

`loadImages` 兼容旧写法时要知道的边界

const legacyUrls = ["https://example.com/cat.png"];
map.loadImages(legacyUrls, (error, images) => {
	if (!error) {
		map.addImage("cat", images[legacyUrls[0]]);
	}
});

这是兼容路径，不是当前推荐路径。

`addSource` / `addLayer` 先后添加的当前行为

最近 master 有专门修复 addSource、addLayer 场景下“不加载”的问题，但该修复主要落在历史 3d-model source/layer 路径。

对 style/source/layer 的常规结论是：

当前版本 map.addSource(...) 会先执行 _lazyInitEmptyStyle()
然后 style.addSource(...)
最后 _update(true)

因此在空样式、晚绑定样式或运行时动态加 source/layer 的场景里，现版本比旧版本更稳。

但推荐顺序仍然不变：

常规二维图层尽量放在 style.load 后添加
不要因为修复了历史问题，就把所有时序都写成“随便什么时候加都行”

样式加载后再添加数据

map.on("style.load", () => {
	if (!map.getSource("lineSource")) {
		map.addSource("lineSource", { type: "geojson", data: geojson });
	}
	if (!map.getLayer("lineLayer")) {
		map.addLayer({ id: "lineLayer", type: "line", source: "lineSource" });
	}
});

无闪烁数据刷新

更新 GeoJSON source 数据（而不是 remove/add layer）
动态路况可按 source 刷新机制做定时更新

对于 vector source，如果服务端数据更新而 source id 不变，优先触发 reload 或切换服务参数，不要反复销毁整套 layer/source。

WMTS 能力解析

const parser = new minemap.WMTSCapabilities();
const capabilities = parser.read(xmlText);
const wmtsSource = minemap.optionsFromCapabilities(capabilities, {
	layer: "img",
	matrixSet: "EPSG:4326",
	format: "image/png"
});

map.addSource("wmts", wmtsSource);

适用场景：

第三方 WMTS 服务参数不想手写
需要从 capabilities 自动提取 tile matrix、style、format

RTL 插件配置

minemap.setRTLTextPlugin("https://example.com/rtl-text.js");

约束：

应在地图初始化前或非常早期调用
不要重复调用，源码里会直接抛错
getRTLTextPluginStatus() 只用于状态判定，不替代初始化逻辑

Performance Tips

高频变化优先改 paint/layout/filter，少做整套 setStyle
大 GeoJSON 数据考虑切片、聚合、分级加载
大规模业务数据优先 VectorTileSource，不要把所有内容一次性灌进 GeoJSON
VectorTileSource 的 bounds、minzoom、maxzoom 要收紧
promoteId 提前设计好，避免后期 feature-state 很难补
queryRenderedFeatures 指定 layers 范围，减少遍历
loadImages 批量图标场景优先用 maxConcurrent、timeout、retryCount 做受控加载，不要手搓一层并发队列

minemap-style-and-data

Más de este repositorio