ArcGIS JS 基础教程(30a):体元系列 - 体元弹窗与数据查询

0 阅读6分钟

零、写在前面

📌 本系列教程完整目录: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>

五、在线示例

🔗 在线体验:southjor.github.io/arcgis-exam…

在这里插入图片描述

操作说明:

  1. 点击「popupEnabled:开」后点击体素,弹窗展示全部字段(含 Voxel 固定字段)。
  2. 切换「自定义模板 / createPopupTemplate 官方默认」,对比两种模板的字段组织。
  3. 点击「getField("Voxel.Depth")」在状态栏查看字段元信息(注意 volumeType 决定该字段是否存在)。
  4. 点击「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})"

参考链接:


七、系列导航

⬅️ 上一篇:ArcGIS JS 基础教程(35):体元系列 - VoxelLayer 时间维度动画

➡️ 下一篇:ArcGIS JS 基础教程(30b):体元系列 - 透明度 stops 与 Slice 组件


💡 小贴士:体元弹窗最常踩的坑是字段不存在——Depth 在 xyt 体积下永远查不到。稳妥做法是先用 getVolume(null).volumeType 判断体积类型,再决定 fieldInfos 里放不放 Depth/Time 字段。另外 createPopupTemplate() 返回的模板已自动跳过当前体积类型不支持的字段,懒人首选。