零、写在前面
📌 本系列教程完整目录:ArcGIS JS 系列基础教程(100个项目常用热门功能)
💡 在线示例:完整可运行的 HTML 示例,无需任何环境配置,可直接在浏览器中打开体验 🗂️ 专栏导航:收藏 + 关注,专栏文章第一时间送达 ❤️ 一键三连:点赞 + 评论 + 收藏
一、功能介绍
第 31 课的 popupEnabled 只能开关弹窗。本课深入弹窗内容:点击一个体素,能看到它的空间位置、深度、时间、当前变量值——这是体元数据「可查」的关键。
体元弹窗的独特之处:Voxel 固定字段
普通图层的弹窗只有业务字段,而体元图层(4.31+)额外提供 5 个固定字段(Voxel. 前缀,避免与变量字段冲突):
| 固定字段 | 含义 | 适用体积类型 |
|---|---|---|
Voxel.CurrentVariable | 当前显示的变量 | 全部 |
Voxel.Position | 点击体素的位置 | 全部 |
Voxel.Depth | 点击体素的深度 | 仅 xyz / xyzt |
Voxel.LocalTime | 体素本地时间 | 仅 xyt / xyzt |
Voxel.SourceTime | 体素源时间 | 仅 xyt / xyzt |
⚠️ 固定字段是否可用取决于
volumeType:Depth只在 xyz/xyzt 有值,LocalTime/SourceTime只在 xyt/xyzt 有值。配置弹窗前先读getVolume(null).volumeType。
相关 API(均 4.31+,popupEnabled 为 4.26+)
| API | 说明 |
|---|---|
layer.fields | 只读,固定体素字段 + 各变量字段的完整列表 |
layer.popupTemplate | 弹窗模板(autocast) |
layer.createPopupTemplate() | 生成官方默认模板(自动填充固定字段与变量字段) |
layer.getField(name) | 按字段名取 Field(不区分大小写) |
layer.getVariable(id | null) | 取 VoxelVariable;传 null 返回当前变量 |
参考:VoxelLayer API | 官方示例:Configuring the popup of a VoxelLayer
二、功能实现
2.1 开启弹窗
voxelLayer.popupEnabled = true; // 默认 false,必须显式开启
2.2 动态构建自定义模板
layer.fields 动态枚举全部字段(固定 + 变量),避免硬编码字段名:
function buildCustomTemplate() {
const infos = voxelLayer.fields.map(f => ({
fieldName: f.name, // 如 "Voxel.Position" 或变量字段名
label: f.alias || f.name // 优先用别名(可自定义中文标签)
}));
return {
title: "体素详情({Voxel.Position})", // 标题也可引用字段
content: [{ type: "fields", fieldInfos: infos }]
};
}
voxelLayer.popupTemplate = buildCustomTemplate();
2.3 官方默认模板
voxelLayer.popupTemplate = voxelLayer.createPopupTemplate();
2.4 字段与变量查询
const field = voxelLayer.getField("Voxel.Depth"); // 不区分大小写
const variable = voxelLayer.getVariable(null); // 当前变量
三、功能应用
| 场景 | 说明 |
|---|---|
| 地下污染排查 | 点击体素读浓度与深度,定位污染源 |
| 大气监测 | 结合 LocalTime/SourceTime 对比时间维度 |
| 地质勘察 | 沿剖面点击查看地层变量值 |
| 数据质检 | 用 createPopupTemplate 快速核对字段 |
| 自定义图例联动 | getField 取字段元信息构建 UI |
四、核心代码
📦 完整代码 已保存至
sample/lesson30a_voxel_popup.html,可直接在浏览器打开。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>第30a课:体元弹窗与数据查询</title>
<link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css">
<script type="module" src="https://js.arcgis.com/5.0/"></script>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: "Microsoft YaHei", sans-serif; }
#mapContainer { width: 100vw; height: 100vh; }
.page-title {
position: absolute; top: 20px; left: 50%; transform: translateX(-50%);
background: rgba(255,255,255,0.95); padding: 10px 24px; border-radius: 6px;
font-size: 18px; font-weight: bold; z-index: 100;
box-shadow: 0 2px 8px rgba(0,0,0,0.15);
}
.control-panel {
position: absolute; top: 80px; right: 20px;
background: rgba(255,255,255,0.95); padding: 16px; border-radius: 8px;
box-shadow: 0 2px 12px rgba(0,0,0,0.15);
z-index: 100; min-width: 320px;
}
.control-panel h3 { margin: 0 0 8px 0; font-size: 14px; color: #333; }
.section { margin-bottom: 12px; padding-bottom: 10px; border-bottom: 1px solid #eee; }
.section:last-child { border-bottom: none; margin-bottom: 0; }
.btn-row { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 6px; }
.btn-row button {
flex: 1; min-width: 90px; padding: 6px 0;
border: 1px solid #d9d9d9; border-radius: 4px;
background: white; cursor: pointer; font-size: 12px;
}
.btn-row button:hover { border-color: #1890ff; color: #1890ff; }
.btn-row button.on { background: #1890ff; color: white; border-color: #1890ff; }
.info-card {
margin-top: 10px; padding: 10px 12px;
background: #f0f5ff; border-radius: 6px;
border-left: 3px solid #1890ff; font-size: 12px; line-height: 1.7;
}
.info-card .val { font-weight: bold; color: #1890ff; }
.status-text {
position: absolute; bottom: 20px; left: 50%; transform: translateX(-50%);
background: rgba(0,0,0,0.7); color: white; padding: 8px 20px;
border-radius: 20px; font-size: 13px; z-index: 100; pointer-events: none;
white-space: nowrap;
}
</style>
</head>
<body>
<h1 class="page-title">第30a课:体元弹窗与数据查询</h1>
<div class="control-panel">
<div class="section">
<h3>🖱️ 弹窗开关</h3>
<div class="btn-row">
<button id="btnEnabled" class="on">popupEnabled:开</button>
</div>
</div>
<div class="section">
<h3>🧾 弹窗模板</h3>
<div class="btn-row">
<button id="btnCustom" class="on">自定义模板(含 Voxel 字段)</button>
</div>
<div class="btn-row">
<button id="btnDefault">createPopupTemplate 官方默认</button>
</div>
</div>
<div class="section">
<h3>🔎 字段查询</h3>
<div class="btn-row">
<button id="btnGetField">getField("Voxel.Depth")</button>
<button id="btnGetVar">getVariable(null)</button>
</div>
</div>
<div class="info-card">
<div>固定字段数:<span class="val" id="fixedCount">-</span>(Voxel.* 前缀)</div>
<div>变量字段数:<span class="val" id="varFieldCount">-</span></div>
<div>弹窗模板:<span class="val" id="curTpl">自定义</span></div>
</div>
</div>
<div class="status-text" id="statusText">体元弹窗 | 点击体素查看属性(含 Voxel 固定字段)</div>
<div id="mapContainer"></div>
<script type="module">
const Map = await $arcgis.import("@arcgis/core/Map.js");
const SceneView = await $arcgis.import("@arcgis/core/views/SceneView.js");
const VoxelLayer = await $arcgis.import("@arcgis/core/layers/VoxelLayer.js");
const getTianditu = await $arcgis.import("https://openlayers.vip/examples/resources/tianditu.js");
const vecLayers = getTianditu.default({ type: "vec_w" });
const map = new Map({ basemap: { baseLayers: [vecLayers.base, vecLayers.anno] } });
const view = new SceneView({
container: "mapContainer", map: map,
viewingMode: "local",
camera: { position: { longitude: 116.4, latitude: 39.9, z: 2000000 }, heading: 0, tilt: 60 }
});
window.view = view;
const voxelLayer = new VoxelLayer({
url: "https://gs3d.geosceneonline.cn/server/rest/services/Hosted/VoxelPM10/SceneServer"
});
map.add(voxelLayer);
const FIXED_PREFIX = "Voxel.";
// 自定义弹窗模板:动态枚举 layer.fields(固定字段 + 变量字段)
function buildCustomTemplate() {
const infos = voxelLayer.fields.map(f => ({
fieldName: f.name,
label: f.alias || f.name
}));
return {
title: "体素详情({Voxel.Position})",
content: [{
type: "fields",
fieldInfos: infos
}]
};
}
view.when(() => {
voxelLayer.when(() => {
voxelLayer.popupEnabled = true;
// fields(4.31+):固定体素字段 + 各变量字段
const fixed = [], vars = [];
voxelLayer.fields.forEach(f => {
(f.name.startsWith(FIXED_PREFIX) ? fixed : vars).push(f.name);
});
document.getElementById("fixedCount").textContent = fixed.length;
document.getElementById("varFieldCount").textContent = vars.length;
// 默认使用自定义模板
voxelLayer.popupTemplate = buildCustomTemplate();
view.goTo(voxelLayer.fullExtent, { duration: 2000 });
}).catch(err => {
document.getElementById("statusText").textContent = "体元图层加载失败";
console.error(err);
});
});
function setStatus(msg) { document.getElementById("statusText").textContent = msg; }
// 弹窗开关(popupEnabled,4.26+)
document.getElementById("btnEnabled").addEventListener("click", function () {
voxelLayer.popupEnabled = !voxelLayer.popupEnabled;
this.classList.toggle("on", voxelLayer.popupEnabled);
this.textContent = "popupEnabled:" + (voxelLayer.popupEnabled ? "开" : "关");
setStatus("popupEnabled = " + voxelLayer.popupEnabled);
});
// 自定义模板:手动组织 fieldInfos,可控制顺序与中文标签
document.getElementById("btnCustom").addEventListener("click", function () {
voxelLayer.popupTemplate = buildCustomTemplate();
document.querySelectorAll("#btnCustom, #btnDefault").forEach(b => b.classList.remove("on"));
this.classList.add("on");
document.getElementById("curTpl").textContent = "自定义";
setStatus("已应用自定义模板(固定字段 + 变量字段,中文标签)");
});
// 官方默认模板:createPopupTemplate() 自动填充体素固定字段与变量字段
document.getElementById("btnDefault").addEventListener("click", function () {
const tpl = voxelLayer.createPopupTemplate();
if (tpl) voxelLayer.popupTemplate = tpl;
document.querySelectorAll("#btnCustom, #btnDefault").forEach(b => b.classList.remove("on"));
this.classList.add("on");
document.getElementById("curTpl").textContent = "官方默认";
setStatus("已应用 createPopupTemplate() 生成的官方默认模板");
});
// getField(4.31+):按字段名取 Field(不区分大小写)
document.getElementById("btnGetField").addEventListener("click", () => {
const f = voxelLayer.getField("Voxel.Depth");
if (f) {
setStatus(`getField("Voxel.Depth") → alias="${f.alias}", type=${f.type}(仅 xyz/xyzt 体积类型有深度)`);
} else {
setStatus('getField("Voxel.Depth") → 未找到(该体积类型可能无 Depth 字段)');
}
});
// getVariable(null):返回当前变量
document.getElementById("btnGetVar").addEventListener("click", () => {
const v = voxelLayer.getVariable(null);
if (v) {
setStatus(`getVariable(null) → #${v.id} ${v.name}(unit: ${v.unit}),当前显示中`);
} else {
setStatus("getVariable(null) → 未取到当前变量");
}
});
</script>
</body>
</html>
五、在线示例
操作说明:
- 点击「popupEnabled:开」后点击体素,弹窗展示全部字段(含 Voxel 固定字段)。
- 切换「自定义模板 / createPopupTemplate 官方默认」,对比两种模板的字段组织。
- 点击「getField("Voxel.Depth")」在状态栏查看字段元信息(注意 volumeType 决定该字段是否存在)。
- 点击「getVariable(null)」查看当前显示的变量。
六、关键 API 说明
| API | 说明 |
|---|---|
popupEnabled | 弹窗开关(4.26+,默认 false) |
popupTemplate | 弹窗模板(4.31+),autocast |
fields | 只读字段列表(4.31+):固定体素字段 + 变量字段 |
| 固定字段 | Voxel.CurrentVariable / Position / Depth / LocalTime / SourceTime |
createPopupTemplate() | 生成官方默认模板(4.31+) |
getField(name) | 按名取 Field,不区分大小写(4.31+) |
getVariable(id | null) | 取变量,null 返回当前变量 |
要点:
- 固定字段可用性取决于
volumeType(Depth 仅 xyz/xyzt;LocalTime/SourceTime 仅 xyt/xyzt) fields动态枚举是构建 fieldInfos 的最稳写法(避免硬编码字段名)- 标题也可引用字段:
title: "体素详情({Voxel.Position})"
参考链接:
七、系列导航
💡 小贴士:体元弹窗最常踩的坑是字段不存在——
Depth在 xyt 体积下永远查不到。稳妥做法是先用getVolume(null).volumeType判断体积类型,再决定 fieldInfos 里放不放Depth/Time字段。另外createPopupTemplate()返回的模板已自动跳过当前体积类型不支持的字段,懒人首选。