关于 arcgis-advanced-layers
arcgis-advanced-layers 是 ArcGIS Maps SDK for JavaScript 高级图层的开发参考 Skill,面向构建地图应用的开发者。内容涵盖 OGC 服务、KML/KMZ、媒体图层及动态数据图层的导入、配置示例与常见问题。
主要功能
- 01WMS、WFS、WMTS 和 OGC API 图层
- 02KML/KMZ 地理数据加载
- 03MapImageLayer 与动态数据图层
- 04CatalogLayer、MediaLayer 和 VideoLayer
- 05图层配置示例与常见问题
适用场景
- 01在地图应用中显示 OGC 服务数据
- 02加载 KML/KMZ 地理数据
- 03配置服务端地图图像及动态数据源
- 04在地图中展示地理配准图像或视频
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ saschabrunnerch/ arcgis-maps-sdk-js-ai-context --skill arcgis-advanced-layers安装后在 Claude Code 中输入/arcgis-advanced-layers确认已加载。
详细介绍
ArcGIS 高级图层
使用此技能处理 OGC 服务(WMS、WFS、WMTS、OGC API Features)、KML/KMZ 文件、MapImageLayer、CatalogLayer、MediaLayer 和动态数据图层。
相关技能: 有关常见图层类型(FeatureLayer、GraphicsLayer、GeoJSONLayer 等),请参阅
arcgis-layers。
导入模式
直接 ESM 导入
import WMSLayer from "@arcgis/core/layers/WMSLayer.js";
import WFSLayer from "@arcgis/core/layers/WFSLayer.js";
import WMTSLayer from "@arcgis/core/layers/WMTSLayer.js";
import OGCFeatureLayer from "@arcgis/core/layers/OGCFeatureLayer.js";
import KMLLayer from "@arcgis/core/layers/KMLLayer.js";
import MapImageLayer from "@arcgis/core/layers/MapImageLayer.js";
import CatalogLayer from "@arcgis/core/layers/CatalogLayer.js";
import MediaLayer from "@arcgis/core/layers/MediaLayer.js";
动态导入(CDN)
const WMSLayer = await $arcgis.import("@arcgis/core/layers/WMSLayer.js");
const [WFSLayer, wfsUtils] = await $arcgis.import([
"@arcgis/core/layers/WFSLayer.js",
"@arcgis/core/layers/ogc/wfsUtils.js",
]);
const MapImageLayer = await $arcgis.import(
"@arcgis/core/layers/MapImageLayer.js",
);
图层类型对比
| 图层类型 | 用例 | 数据源 |
|---|---|---|
| WMSLayer | 来自 OGC WMS 的栅格影像 | WMS 1.1.1 / 1.3.0 |
| WFSLayer | 来自 OGC WFS 的矢量要素 | WFS 2.0.0 |
| WMTSLayer | 来自 OGC WMTS 的缓存切片 | WMTS 1.0.0 |
| OGCFeatureLayer | 来自 OGC API - Features 的矢量数据 | OGC API |
| KMLLayer | KML/KMZ 地理数据 | KML 文件 |
| MapImageLayer | 服务器渲染的影像 | ArcGIS MapServer |
| CatalogLayer | 图层集合 | ArcGIS Catalog Service |
| MediaLayer | 地理配准的图像、视频、GIF | 本地/远程媒体 |
| VideoLayer | 实时视频流 | ArcGIS Video Server |
WMSLayer(Web 地图服务)
基本 WMSLayer
import WMSLayer from "@arcgis/core/layers/WMSLayer.js";
const layer = new WMSLayer({
url: "https://ows.terrestris.de/osm/service",
});
await layer.load();
// Find and use a specific sublayer
const sublayer = layer.findSublayerByName("OSM-WMS");
if (sublayer) {
layer.sublayers = [sublayer];
}
map.add(layer);
将 WMSLayer 用作底图(地图组件)
<arcgis-scene>
<arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-scene>
<script type="module">
import WMSLayer from "@arcgis/core/layers/WMSLayer.js";
const viewElement = document.querySelector("arcgis-scene");
const layer = new WMSLayer({
url: "https://ows.terrestris.de/osm/service",
});
await layer.load();
const sublayer = layer.findSublayerByName("OSM-WMS");
if (sublayer) {
layer.sublayers = [sublayer];
}
viewElement.map = {
basemap: {
baseLayers: [layer],
title: "WMS Basemap",
},
};
</script>
带自定义参数的 WMSLayer
const layer = new WMSLayer({
url: "https://example.com/wms",
sublayers: [
{
name: "LayerName",
visible: true,
},
],
customParameters: {
TRANSPARENT: "TRUE",
FORMAT: "image/png",
},
imageFormat: "png",
version: "1.3.0",
});
WFSLayer(Web 要素服务)
基本 WFSLayer
import WFSLayer from "@arcgis/core/layers/WFSLayer.js";
const layer = new WFSLayer({
url: "https://geobretagne.fr/geoserver/ows",
name: "fma:bvme_zhp_vs_culture",
copyright: "GeoBretagne",
});
map.add(layer);
WFS 能力发现
import WFSLayer from "@arcgis/core/layers/WFSLayer.js";
import wfsUtils from "@arcgis/core/layers/ogc/wfsUtils.js";
// Get capabilities from WFS endpoint
const capabilities = await wfsUtils.getCapabilities(
"https://geobretagne.fr/geoserver/ows",
);
// List available feature types
capabilities.featureTypes.forEach((featureType) => {
console.log(featureType.title, featureType.name);
});
// Create layer from specific feature type
const layerInfo = await wfsUtils.getWFSLayerInfo(
capabilities,
"featureTypeName",
);
const layer = WFSLayer.fromWFSLayerInfo(layerInfo);
map.add(layer);
带渲染器的 WFSLayer
const layer = new WFSLayer({
url: "https://geobretagne.fr/geoserver/ows",
name: "fma:bvme_zhp_vs_culture",
renderer: {
type: "simple",
symbol: {
type: "simple-fill",
color: [76, 129, 64, 0.6],
outline: { color: "white", width: 1 },
},
},
popupTemplate: {
title: "{nom}",
content: "Type: {type_cultu}",
},
});
WMTSLayer(Web 地图切片服务)
基本 WMTSLayer
import WMTSLayer from "@arcgis/core/layers/WMTSLayer.js";
const layer = new WMTSLayer({
url: "https://www.ign.es/wmts/ign-base",
activeLayer: {
id: "IGNBase-gris",
tileMatrixSetId: "GoogleMapsCompatible",
},
serviceMode: "KVP",
copyright: "Instituto Geografico Nacional",
});
map.add(layer);
将 WMTSLayer 用作底图
import Basemap from "@arcgis/core/Basemap.js";
import WMTSLayer from "@arcgis/core/layers/WMTSLayer.js";
const wmtsBasemap = new Basemap({
baseLayers: [
new WMTSLayer({
url: "https://www.ign.es/wmts/ign-base",
activeLayer: {
id: "IGNBase-gris",
tileMatrixSetId: "GoogleMapsCompatible",
},
serviceMode: "KVP",
}),
],
});
const map = new Map({ basemap: wmtsBasemap });
OGCFeatureLayer(OGC API - Features)
基本 OGCFeatureLayer
import OGCFeatureLayer from "@arcgis/core/layers/OGCFeatureLayer.js";
const layer = new OGCFeatureLayer({
url: "https://demo.ldproxy.net/vineyards",
collectionId: "vineyards",
minScale: 5000000,
renderer: {
type: "simple",
symbol: {
type: "simple-fill",
color: [76, 129, 64, 0.6],
},
},
popupTemplate: {
title: "{name}",
content: "Area: {area_ha} hectares",
},
});
map.add(layer);
带标注的 OGCFeatureLayer
const layer = new OGCFeatureLayer({
url: "https://demo.ldproxy.net/vineyards",
collectionId: "vineyards",
labelingInfo: [
{
labelExpressionInfo: {
expression: "$feature.NAME",
},
symbol: {
type: "text",
color: "#4a6741",
haloSize: 1,
haloColor: "white",
font: {
family: "Arial",
style: "italic",
},
},
minScale: 100000,
},
],
});
KMLLayer
基本 KMLLayer
import KMLLayer from "@arcgis/core/layers/KMLLayer.js";
const layer = new KMLLayer({
url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_month_age_animated.kml",
});
map.add(layer);
带子图层的 KMLLayer
const layer = new KMLLayer({
url: "https://example.com/data.kml",
});
await layer.load();
// Access KML sublayers
layer.sublayers.forEach((sublayer) => {
console.log(sublayer.title, sublayer.visible);
});
// Toggle sublayer visibility
const sublayer = layer.sublayers.getItemAt(0);
sublayer.visible = false;
从本地文件创建 KMLLayer
const layer = new KMLLayer({
url: "/data/places.kml",
title: "Places of Interest",
});
map.add(layer);
MapImageLayer
基本 MapImageLayer
import MapImageLayer from "@arcgis/core/layers/MapImageLayer.js";
// From URL
const layer = new MapImageLayer({
url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
});
// From portal item
const portalLayer = new MapImageLayer({
portalItem: {
id: "d7892b3c13b44391992ecd42bfa92d01",
},
});
map.add(layer);
带子图层的 MapImageLayer
const layer = new MapImageLayer({
url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
sublayers: [
{ id: 2, visible: true },
{ id: 1, visible: true },
{ id: 0, visible: true },
],
});
// Toggle sublayer visibility
layer.when(() => {
const sublayer = layer.findSublayerById(1);
sublayer.visible = !sublayer.visible;
});
带定义表达式的 MapImageLayer
const layer = new MapImageLayer({
url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
sublayers: [
{
id: 0,
definitionExpression: "pop2000 > 100000",
},
],
});
带自定义渲染器的 MapImageLayer
const layer = new MapImageLayer({
url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
sublayers: [
{
id: 2,
renderer: {
type: "simple",
symbol: {
type: "simple-fill",
color: [0, 100, 200, 0.5],
outline: { color: "white", width: 1 },
},
},
},
],
});
动态数据图层
从表创建数据图层
const layer = new MapImageLayer({
url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer",
sublayers: [
{
id: 4,
title: "Railroads",
renderer: {
type: "simple",
symbol: {
type: "simple-line",
color: [255, 255, 255, 0.5],
width: 0.75,
style: "long-dash-dot-dot",
},
},
source: {
type: "data-layer",
dataSource: {
type: "table",
workspaceId: "MyDatabaseWorkspaceIDSSR2",
dataSourceName: "ss6.gdb.Railroads",
},
},
},
],
});
带表连接的数据图层
const layer = new MapImageLayer({
url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer",
sublayers: [
{
id: 0,
opacity: 0.75,
source: {
type: "data-layer",
dataSource: {
type: "join-table",
leftTableSource: {
type: "map-layer",
mapLayerId: 3,
},
rightTableSource: {
type: "data-layer",
dataSource: {
type: "table",
workspaceId: "CensusFileGDBWorkspaceID",
dataSourceName: "ancestry",
},
},
leftTableKey: "STATE_NAME",
rightTableKey: "State",
joinType: "left-outer-join",
},
},
renderer: {
type: "class-breaks",
field: "ancestry.Norwegian",
normalizationField: "states.POP2007",
classBreakInfos: [
{
minValue: 0,
maxValue: 0.01,
symbol: { type: "simple-fill", color: "#f8e3c2" },
},
{
minValue: 0.01,
maxValue: 0.05,
symbol: { type: "simple-fill", color: "#d86868" },
},
],
},
},
],
});
CatalogLayer
基本 CatalogLayer
import CatalogLayer from "@arcgis/core/layers/CatalogLayer.js";
const layer = new CatalogLayer({
portalItem: {
id: "487cc66d305145d3b67fed383456af48",
portal: {
url: "https://jsapi.maps.arcgis.com/",
},
},
});
map.add(layer);
使用 CatalogLayer 足迹
import CatalogLayer from "@arcgis/core/layers/CatalogLayer.js";
const layer = new CatalogLayer({
portalItem: { id: "YOUR_CATALOG_ITEM_ID" },
});
map.add(layer);
const layerView = await view.whenLayerView(layer);
// Query all footprints
const result = await layer.queryFeatures({
where: "1=1",
returnGeometry: true,
outFields: ["*"],
orderByFields: [layer.itemNameField],
});
// Add labels to footprint layer
layer.footprintLayer.labelingInfo = [
{
labelExpressionInfo: {
expression: "$feature." + layer.itemNameField,
},
symbol: {
type: "text",
color: "white",
font: { size: 10 },
},
},
];
// Highlight a footprint
const highlight = layerView.footprintLayerView.highlight(feature);
// Create layer from footprint
const footprint = layer.createFootprintFromLayer(selectedLayer);
const newLayer = await layer.createLayerFromFootprint(footprint);
map.add(newLayer);
带 LayerList 的 CatalogLayer
<arcgis-map id="mapView">
<arcgis-layer-list slot="top-right"></arcgis-layer-list>
</arcgis-map>
<script type="module">
import CatalogLayer from "@arcgis/core/layers/CatalogLayer.js";
import catalogUtils from "@arcgis/core/layers/catalog/catalogUtils.js";
const viewElement = document.querySelector("arcgis-map");
const layerList = document.querySelector("arcgis-layer-list");
const catalogLayer = new CatalogLayer({
portalItem: { id: "YOUR_CATALOG_ITEM_ID" },
});
viewElement.map.add(catalogLayer);
layerList.catalogOptions = {
selectionMode: "single",
};
layerList.listItemCreatedFunction = (event) => {
if (catalogUtils.isLayerFromCatalog(event.item.layer)) {
event.item.actionsSections = [
[
{
title: "Add layer to map",
icon: "add-layer",
id: "add-layer",
},
],
];
}
};
</script>
MediaLayer
带图像的 MediaLayer
import MediaLayer from "@arcgis/core/layers/MediaLayer.js";
import ImageElement from "@arcgis/core/layers/support/ImageElement.js";
import ExtentAndRotationGeoreference from "@arcgis/core/layers/support/ExtentAndRotationGeoreference.js";
import Extent from "@arcgis/core/geometry/Extent.js";
const imageElement = new ImageElement({
image: "https://example.com/historical-map.png",
georeference: new ExtentAndRotationGeoreference({
extent: new Extent({
xmin: -10047456,
ymin: 3486722,
xmax: -10006982,
ymax: 3514468,
spatialReference: { wkid: 102100 },
}),
}),
});
const mediaLayer = new MediaLayer({
source: [imageElement],
title: "Historical Map",
});
map.add(mediaLayer);
带多张图像的 MediaLayer
const imageInfos = [
{ url: "image1.png", extent: { xmin: -100, ymin: 30, xmax: -90, ymax: 40 } },
{ url: "image2.png", extent: { xmin: -95, ymin: 35, xmax: -85, ymax: 45 } },
];
const imageElements = imageInfos.map(
(info) =>
new ImageElement({
image: info.url,
georeference: new ExtentAndRotationGeoreference({
extent: new Extent({
...info.extent,
spatialReference: { wkid: 4326 },
}),
}),
}),
);
const mediaLayer = new MediaLayer({
source: imageElements,
title: "Image Collection",
});
使用旋转进行地理配准
const georeference = new ExtentAndRotationGeoreference({
extent: new Extent({
xmin: -122.5,
ymin: 37.5,
xmax: -122.0,
ymax: 38.0,
spatialReference: { wkid: 4326 },
}),
rotation: 15, // Degrees clockwise
});
使用控制点进行地理配准
import ControlPointsGeoreference from "@arcgis/core/layers/support/ControlPointsGeoreference.js";
const georeference = new ControlPointsGeoreference({
controlPoints: [
{
sourcePoint: { x: 0, y: 0 }, // Top-left of image (pixels)
mapPoint: { x: -122.5, y: 38.0 }, // Map coordinates
},
{
sourcePoint: { x: 1000, y: 0 }, // Top-right
mapPoint: { x: -122.0, y: 38.0 },
},
{
sourcePoint: { x: 1000, y: 800 }, // Bottom-right
mapPoint: { x: -122.0, y: 37.5 },
},
{
sourcePoint: { x: 0, y: 800 }, // Bottom-left
mapPoint: { x: -122.5, y: 37.5 },
},
],
width: 1000,
height: 800,
});
带视频的 MediaLayer
import VideoElement from "@arcgis/core/layers/support/VideoElement.js";
const videoElement = new VideoElement({
video: "https://example.com/timelapse.mp4",
georeference: new ExtentAndRotationGeoreference({
extent: new Extent({
xmin: -122.5,
ymin: 37.5,
xmax: -122.0,
ymax: 38.0,
spatialReference: { wkid: 4326 },
}),
}),
});
const mediaLayer = new MediaLayer({
source: [videoElement],
});
// Control video playback
videoElement.content.play();
videoElement.content.pause();
videoElement.content.currentTime = 30;
带不透明度和混合模式的 MediaLayer
const mediaLayer = new MediaLayer({
source: [imageElement],
opacity: 0.7,
blendMode: "multiply", // normal, multiply, luminosity, etc.
});
// Change dynamically
mediaLayer.opacity = 0.5;
mediaLayer.blendMode = "luminosity";
// Individual element opacity
imageElement.opacity = 0.8;
交互式控制点
// Enable interactive editing of georeference control points
const mediaLayerView = await view.whenLayerView(mediaLayer);
mediaLayerView.interactive = true;
// Disable when done
mediaLayerView.interactive = false;
VideoLayer
显示来自 ArcGIS Video Server 的实时视频流。VideoLayer 扩展了 Layer,可像其他图层一样添加到 Map 中。将它与 arcgis-video-player widget 搭配使用(播放控件请参阅 arcgis-widgets-advanced)。
基本 VideoLayer
import VideoLayer from "@arcgis/core/layers/VideoLayer.js";
const videoLayer = new VideoLayer({
url: "https://your-server.com/arcgis/rest/services/VideoService/VideoServer",
});
map.add(videoLayer);
配合 VideoPlayer Widget 使用
<arcgis-map basemap="streets-vector">
<arcgis-video-player slot="top-right"></arcgis-video-player>
</arcgis-map>
import VideoLayer from "@arcgis/core/layers/VideoLayer.js";
const viewElement = document.querySelector("arcgis-map");
const videoPlayer = document.querySelector("arcgis-video-player");
await viewElement.viewOnReady();
const videoLayer = new VideoLayer({
url: "https://your-server.com/arcgis/rest/services/VideoService/VideoServer",
});
viewElement.map.add(videoLayer);
videoPlayer.layer = videoLayer;
限制
- 仅支持 2D
MapView,不支持 3DSceneView - 不支持 macOS 或 iOS 设备
- 需要有效的 ArcGIS Video Server 端点(不能使用通用视频文件 URL;对于本地或远程视频文件,请使用带
VideoElement的MediaLayer)
完整示例
<!DOCTYPE html>
<html>
<head>
<script
type="module"
src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"
></script>
<script src="https://js.arcgis.com/5.0/"></script>
<script
type="module"
src="https://js.arcgis.com/5.0/map-components/"
></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<calcite-shell>
<calcite-navigation slot="header">
<calcite-navigation-logo
slot="logo"
heading="Advanced Layers"
></calcite-navigation-logo>
</calcite-navigation>
<calcite-shell-panel slot="panel-start">
<calcite-panel heading="Layers">
<arcgis-layer-list reference-element="mapView"></arcgis-layer-list>
</calcite-panel>
</calcite-shell-panel>
<arcgis-map id="mapView" center="-89.93, 29.97" zoom="10">
<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-legend slot="bottom-left"></arcgis-legend>
</arcgis-map>
</calcite-shell>
<script type="module">
import Map from "@arcgis/core/Map.js";
import WMSLayer from "@arcgis/core/layers/WMSLayer.js";
import MediaLayer from "@arcgis/core/layers/MediaLayer.js";
import ImageElement from "@arcgis/core/layers/support/ImageElement.js";
import ExtentAndRotationGeoreference from "@arcgis/core/layers/support/ExtentAndRotationGeoreference.js";
import Extent from "@arcgis/core/geometry/Extent.js";
const viewElement = document.querySelector("arcgis-map");
await viewElement.viewOnReady();
// Add a WMS layer
const wmsLayer = new WMSLayer({
url: "https://ows.terrestris.de/osm/service",
title: "OpenStreetMap WMS",
});
// Add a media layer for a historical map overlay
const imageElement = new ImageElement({
image: "https://example.com/historical-map.png",
georeference: new ExtentAndRotationGeoreference({
extent: new Extent({
xmin: -10047456,
ymin: 3486722,
xmax: -10006982,
ymax: 3514468,
spatialReference: { wkid: 102100 },
}),
}),
});
const mediaLayer = new MediaLayer({
source: [imageElement],
title: "Historical Map",
opacity: 0.7,
});
viewElement.map.addMany([wmsLayer, mediaLayer]);
</script>
</body>
</html>
参考示例
layers-wms- 添加和配置 WMS 图层layers-wfs- 使用 WFS 图层layers-ogcfeaturelayer- OGC Features API 图层的用法layers-mapimagelayer- 配置动态 MapImageLayerlayers-mapimagelayer-dynamic-data- 使用联接的动态数据图层layers-kml- 加载 KML/KMZ 文件layers-cataloglayer- 使用 CatalogLayer 浏览门户内容layers-medialayer-images- 使用 MediaLayer 显示图像layers-medialayer-video- 在 MediaLayer 中播放视频layers-medialayer-control-points- 为媒体放置控制点
常见问题
-
WFS 版本要求:WFSLayer 需要 WFS 2.0.0,并使用 GeoJSON 输出格式。较旧的 WFS 版本或不支持 GeoJSON 的服务将无法使用。
-
OGC 服务的 CORS:外部 OGC 服务(WMS、WFS、WMTS)需要启用 CORS 响应头或配置代理。若未启用 CORS,浏览器会静默拦截跨域请求。
-
MapImageLayer 子图层 ID:子图层的
id值必须与服务图层 ID 完全一致。使用错误的 ID 会导致子图层为空或缺失。 -
动态数据源需要已注册的工作空间:数据图层源(
source.type: "data-layer")只能使用在 ArcGIS Server 上注册的工作空间 ID。工作空间必须由服务器管理员预先配置。 -
CatalogLayer 门户 URL:对于非 ArcGIS Online 项目,必须在
portalItem配置中指定portal.url。如果省略,则默认使用 ArcGIS Online。 -
联接表中的字段名称前缀:在 MapImageLayer 中使用表联接时,字段名称必须添加表名称前缀(例如,
ancestry.Norwegian、states.POP2007)。 -
媒体 CORS:MediaLayer 从外部服务器加载的图像和视频需要 CORS 响应头。若未启用 CORS,图像虽能加载,却无法在地图画布上渲染。
-
视频自动播放限制:浏览器可能会阻止 MediaLayer 中的视频元素自动播放。调用
videoElement.content.play()前,需要用户进行交互(例如点击按钮)。 -
KMLLayer 网络链接:包含网络链接的 KML 文件会发起额外的 HTTP 请求。请确保所有链接的 URL 均可访问且已启用 CORS。
-
WMSLayer 子图层选择:WMSLayer 加载后,默认显示所有子图层。请明确设置
layer.sublayers,仅包含所需的子图层;否则,对于包含许多图层的服务,性能可能会受到影响。
相关技能
- 有关常见图层类型(FeatureLayer、GraphicsLayer、GeoJSONLayer 等),请参阅
arcgis-layers - 有关影像专用图层(ImageryLayer、ImageryTileLayer),请参阅
arcgis-imagery - 有关渲染器和符号配置,请参阅
arcgis-visualization - 有关 3D 专用图层类型(SceneLayer、IntegratedMeshLayer),请参阅
arcgis-3d-layers