本教程详细介绍了如何利用 CARTO v3 和 DeckGL 库构建交互式地图应用，重点讲解了动态显示/隐藏地图层、实现悬停工具提示以及管理图层状态的核心技术。通过 deckgl.setProps() 方法，结合 visible 属性和事件监听，开发者可以高效地控制地图元素的可见性，并提升用户体验。
1. 引言：CARTO v3 与 DeckGL 结合构建交互式地图
随着地理空间数据可视化需求的日益增长，现代 Web 地图库如 CARTO v3 和 DeckGL 提供了强大且灵活的工具来创建高性能、数据驱动的交互式地图。CARTO v3 专注于数据管理和空间分析，而 DeckGL 则是一个基于 webgl 的高性能可视化框架，擅长渲染大量数据层。两者的结合，为开发者提供了从数据到可视化的完整解决方案。
对于从旧版 CartoDB 迁移至新平台的开发者而言，理解如何有效地管理和操作地图层是关键。本教程将重点探讨如何在纯 javaScript 环境下，利用 CARTO v3 和 DeckGL 实现地图层的动态显示/隐藏、交互式工具提示以及基础的用户点击响应。
2. DeckGL 核心概念与层级初始化
在使用 DeckGL 构建地图时，首先需要初始化一个 DeckGL 实例，并定义其包含的图层。每个图层都是 deck.Layer 的一个子类，例如 deck.carto.CartoLayer 用于从 CARTO 数据源加载数据。
2.1 初始化 DeckGL 实例
DeckGL 实例是地图的核心，它负责管理视图状态、渲染图层以及处理用户交互。
const mydeckgl = new deck.DeckGL({ container: "map", // 地图容器的 DOM 元素 ID map: maplibregl, // 底图库实例，例如 MapLibre GL js 或 Mapbox GL JS mapStyle: deck.carto.BASEMAP.DARK_MATTER, // 底图样式 initialViewState: { // 初始视图状态 latitude: -33.85, longitude: 151.20, zoom: 12 }, controller: true, // 启用用户通过鼠标/触摸控制地图 // layers: [] // 初始图层数组，稍后通过 setProps 更新 });2.2 定义 CartoLayer
deck.carto.CartoLayer 是 DeckGL 专门用于集成 CARTO 数据的图层。它允许直接从 CARTO 平台查询并渲染地理空间数据。
new deck.carto.CartoLayer({ id: 'heatmaps', // 图层唯一标识 connection: "carto_dw", // CARTO 数据仓库连接名称 type: deck.carto.MAP_TYPES.QUERY, // 数据类型：通过 SQL 查询获取 data: "select geom, Postcode, Md_H22_num, Md_H22_txt, Ct_H22_num, Suburbs from carto-dw-ac-p76tk8ou.shared.2023FEB28_Postcode where Md_H22_num is not null", // SQL 查询语句 getFillColor: deck.carto.colorContinuous({ // 填充颜色，基于数据属性进行连续着色 attr: "Md_H22_num", domain: [0, 5000000], colors: "PinkYl" // 颜色方案 }), getLineColor:[255,255,255], // 边框颜色 lineWidthMinPixels: 1, // 最小线宽 pickable: true, // 启用图层对象的拾取（鼠标悬停/点击） getLineWidth: 2, // 线宽 opacity: 0.7, // 透明度 visible: true // 初始可见性 });CARTO 凭证设置: 在加载任何 CARTO 数据之前，需要设置 CARTO 凭证：
deck.carto.setDefaultCredentials({ apiBaseUrl: "https://gcp-australia-southeast1.api.carto.com", accessToken: "YOUR_CARTO_ACCESS_TOKEN" // 替换为你的 CARTO 访问令牌 });3. 实现层级的动态显示与隐藏
DeckGL 提供了一种高效的机制来更新地图上的图层：通过 deckgl.setProps({layers}) 方法。当需要改变图层的属性（包括可见性 visible）时，只需构建一个新的图层数组，并将其传递给 setProps()。
3.1 核心原理：setProps() 与 visible 属性
每个 DeckGL 图层都含有一个 visible 属性，控制该图层是否在地图上渲染。通过修改这个属性，并调用 deckgl.setProps() 来更新整个图层集合，即可实现图层的动态显示与隐藏。DeckGL 会智能地比较新旧图层数组，只对发生变化的图层进行更新，从而优化性能。
3.2 状态管理与更新函数
为了方便管理多个图层的可见性，可以使用一个 javascript 对象来存储每个图层的状态。然后，封装一个函数来根据这些状态构建图层数组并更新 DeckGL 实例。
// 示例：管理图层可见性的状态对象 const layerVisibility = { heatmaps: true // 初始时 'heatmaps' 图层可见 }; // 更新 DeckGL 图层的函数 function updateDeckGLLayers() { const currentLayers = [ new deck.carto.CartoLayer({ id: 'heatmaps', connection: "carto_dw", type: deck.carto.MAP_TYPES.QUERY, data: "select geom, Postcode, Md_H22_num, Md_H22_txt, Ct_H22_num, Suburbs from carto-dw-XXX", // 替换为你的数据源 getFillColor: deck.carto.colorContinuous({ attr: "Md_H22_num", domain: [0, 5000000], colors: "PinkYl" }), getLineColor:[255,255,255], lineWidthMinPixels: 1, pickable: true, getLineWidth: 2, opacity: 0.7, visible: layerVisibility.heatmaps // 根据状态对象设置可见性 }) // 如果有其他图层，在此处继续添加，并根据其在 layerVisibility 中的状态设置 visible 属性 ]; mydeckgl.setProps({layers: currentLayers}); // 更新 DeckGL 实例的图层 } // 首次加载时调用，以渲染初始图层 updateDeckGLLayers();3.3 用户界面交互
通过 html 元素（如复选框、按钮或菜单项）触发 updateDeckGLLayers() 函数，即可实现用户控制图层可见性。
<!-- HTML 示例：一个复选框来控制 'heatmaps' 图层的可见性 --> Visibility: <input type="checkbox" id="toggleHeatmaps" checked onclick="toggleLayerVisibility('heatmaps')">// 绑定到 HTML 元素的点击事件 function toggleLayerVisibility(layerId) { layerVisibility[layerId] = !layerVisibility[layerId]; // 切换指定图层的可见状态 updateDeckGLLayers(); // 调用更新函数以重新渲染图层 }4. 实现地图交互：悬停提示与点击事件
DeckGL 提供了强大的拾取（picking）功能，允许开发者轻松实现地图元素的交互，如悬停显示工具提示或点击触发特定操作。
4.1 悬停工具提示 (getTooltip)
要启用图层对象的拾取功能，首先需将图层的 pickable 属性设置为 true。然后，可以在 DeckGL 实例中定义 getTooltip 回调函数。当鼠标悬停在可拾取对象上时，此函数会被调用，并返回用于显示工具提示的内容。
const mydeckgl = new deck.DeckGL({ // ... 其他配置 ... getTooltip: ({ object }) => { if (!object) return false; // 如果没有悬停对象，则不显示提示 // 从悬停对象的 properties 中提取数据 const { Postcode, Suburbs, Md_H22_txt, Ct_H22_num } = object.properties; // 返回一个包含 HTML 内容的对象，用于自定义工具提示样式 return { className: `vptooltip`, // 自定义 css 类名 html: `<div> <span class='vptooltip-title'>邮政编码:</span><p class='vptooltip-value'>${Postcode}</p> <span class='vptooltip-title'>郊区:</span><p class='vptooltip-value'>${Suburbs}</p> <span class='vptooltip-title'>房屋中位数价格:</span><p class='vptooltip-value'>${Md_H22_txt}</p> <span class='vptooltip-title'>售出房屋数量:</span><p class='vptooltip-value'>${Ct_H22_num}</p> </div>`, }; } });为了美化工具提示，可以添加一些 CSS 样式：
.vptooltip { color: #fff !important; font: 400 11px "Helvetica Neue",Helvetica,Arial !important; background: rgba(0,0,0,.75) !important; padding: 10px !important; border-radius: 3px !important; } .vptooltip-title { color: #999; margin: 0 0 1px; font-weight: 600; } .vptooltip-value { padding: 0 0 7px; margin: 0 0 1px; }4.2 点击事件 (onClick)
DeckGL 的图层也支持 onClick 回调函数，当用户点击图层上的可拾取对象时触发。这对于实现更复杂的交互（例如，点击地图区域以更新外部图表数据）非常有用。
new deck.carto.CartoLayer({ // ... 其他属性 ... pickable: true, // 确保可拾取 onClick: info => { if (info.object) { console.log('点击了对象:', info.object.properties); // 在这里可以编写逻辑，例如： // - 获取 info.object.properties 中的数据 // - 调用函数更新页面上的图表或显示详细信息 } } });5. 完整代码示例
以下是一个整合了上述所有功能的完整 HTML/JavaScript 示例，展示了如何设置 CARTO v3 和 DeckGL，并实现图层的动态显示/隐藏和工具提示。