使用CARTO v3和DeckGL动态控制地图图层可见性教程

花韻仙語

发布时间：2025-11-06 19:27:20

826人浏览过

来源于php中文网

原创

使用CARTO v3和DeckGL动态控制地图图层可见性教程

本教程详细介绍了如何利用carto v3和deckgl库在javascript中实现地图图层的动态显示与隐藏。核心机制在于通过修改`deckgl`实例的`layers`属性，特别是每个图层对象的`visible`属性，并结合`deckgl.setprops()`方法来实时更新地图视图。文章涵盖了环境设置、图层定义、交互式可见性控制以及工具提示的实现，旨在为开发者提供一个清晰、专业的迁移与开发指南。

使用CARTO v3和DeckGL管理地图图层可见性

随着Web GIS技术的不断发展，将旧版CartoDB项目迁移到基于CARTO v3和DeckGL的现代化平台已成为许多开发者的需求。其中一个核心功能是如何高效地管理地图上的多个图层，包括它们的显示与隐藏，以及提供丰富的用户交互。本教程将深入探讨如何利用DeckGL的强大能力，结合CARTO提供的图层类型，实现这些功能。

1. 环境准备与依赖导入

在开始之前，确保你的HTML文件中引入了必要的DeckGL、CARTO和MapLibre GL库。MapLibre GL作为DeckGL的底层地图库，用于提供底图和地图控制器。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>CARTO DeckGL 图层可见性控制</title>

    <!-- Bootstrap 5 CSS (可选，用于UI样式) -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">

    <!-- DeckGL, CARTO, MapLibre GL 库 -->
    <script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script> 
    <script src="https://unpkg.com/@deck.gl/carto@latest/dist.min.js"></script>
    <script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
    <link href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" rel="stylesheet" />

    <style>
      body { margin: 0; padding: 0; }
      #map { width: 100vw; height: 50vh; }
      /* 自定义工具提示样式 */
      .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;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <div style="padding: 10px;">
      图层可见性: 
      <input type="checkbox" id="layerToggle" checked>
    </div>

    <!-- Bootstrap 5 JS (可选) -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js" crossorigin="anonymous"></script>

    <script type="text/javascript">
      // JavaScript 代码将在此处添加
    </script>
  </body>
</html>

2. 初始化DeckGL与CARTO凭据

在JavaScript代码中，首先需要设置CARTO的默认凭据，以便DeckGL能够访问您的CARTO数据。然后初始化DeckGL实例，并将其绑定到HTML中的地图容器。

// 设置CARTO凭据
deck.carto.setDefaultCredentials({
  apiBaseUrl: "https://gcp-australia-southeast1.api.carto.com", // 替换为您的CARTO API基础URL
  accessToken: "YOUR_CARTO_ACCESS_TOKEN" // 替换为您的CARTO访问令牌
});

// 初始化DeckGL实例
const mydeckgl = new deck.DeckGL({
  container: "map", // 地图容器的ID
  map: maplibregl, // 使用MapLibre GL作为底层地图
  mapStyle: deck.carto.BASEMAP.DARK_MATTER, // 设置底图样式

  initialViewState: {
    latitude: -33.85,
    longitude: 151.20,
    zoom: 12
  },
  controller: true, // 启用地图控制器（缩放、平移等）
  // 初始图层将在 render() 函数中设置
});

重要提示：请将YOUR_CARTO_ACCESS_TOKEN替换为您的实际CARTO访问令牌。在生产环境中，应妥善管理API密钥，避免直接硬编码在客户端代码中。

3. 定义CARTO图层

DeckGL通过Layer对象来表示地图上的各种数据。对于CARTO数据，我们使用deck.carto.CartoLayer。每个图层都可以配置其数据源、样式、交互行为等。关键在于为图层设置一个唯一的id，并在需要时通过visible属性控制其显示状态。

// 定义一个用于控制图层可见性的状态对象
const layerState = {
  isVisible: document.getElementById('layerToggle').checked // 从复选框获取初始状态
};

/**
 * 根据当前图层状态渲染或更新DeckGL图层
 */
function renderLayers() {
  const layers = [
    new deck.carto.CartoLayer({ // 多边形图层
      id: 'heatmaps-polygons', // 唯一的图层ID
      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: layerState.isVisible // 根据状态控制图层可见性
    }),
    new deck.carto.CartoLayer({ // 文本标签图层
      id: 'heatmaps-labels',
      connection: "carto_dw",
      type: deck.carto.MAP_TYPES.QUERY,
      data: 'select Postcode, Ct_H22_num, Md_H22_txt, Suburbs, st_centroid(geom) as geom from carto-dw-ac-p76tk8ou.shared.2023FEB28_Postcode where Md_H22_num is not null',
      pointType: 'text', // 渲染为文本
      getText: f => f.properties.Md_H22_txt, // 获取文本内容
      textFontFamily: "sans-serif",
      textBackground: true,
      getTextBackgroundColor:  [0, 0, 0, 50],
      textBackgroundPadding: [2, 2],
      getTextSize: 12,
      getTextColor: [250,250,250],
      pickable: true,
      visible: layerState.isVisible // 根据状态控制图层可见性
    })
  ];

  // 更新DeckGL实例的图层
  mydeckgl.setProps({ layers });
}

// 首次渲染图层
renderLayers();

4. 实现图层动态显示/隐藏

DeckGL通过其setProps()方法提供了一种高效的方式来更新地图的属性，包括其图层数组。要实现图层的动态显示/隐藏，我们只需修改图层数组中相应图层对象的visible属性，然后调用mydeckgl.setProps({ layers: updatedLayers })。

Rezi.ai

一个使用 AI 自动化创建简历平台

下载

// 获取图层切换复选框元素
const layerToggleButton = document.getElementById('layerToggle');

// 为复选框添加事件监听器
layerToggleButton.addEventListener('change', () => {
  layerState.isVisible = layerToggleButton.checked; // 更新状态
  renderLayers(); // 重新渲染图层
});

在这个示例中，renderLayers()函数每次都会根据layerState.isVisible的当前值重新构建图层数组，并将其传递给mydeckgl.setProps()。DeckGL会智能地比较新旧图层数组，只更新发生变化的图层，从而实现高效的渲染。

5. 添加交互式工具提示

为了增强用户体验，当用户悬停或点击地图上的多边形时，可以显示包含详细信息的工具提示。这通过在DeckGL实例初始化时提供一个getTooltip回调函数来实现。

// 将 getTooltip 回调添加到 mydeckgl 实例中
const mydeckgl = new deck.DeckGL({
  container: "map",
  map: maplibregl,
  mapStyle: deck.carto.BASEMAP.DARK_MATTER,
  initialViewState: {
    latitude: -33.85,
    longitude: 151.20,
    zoom: 12
  },
  controller: true,
  // ... 其他配置 ...

  getTooltip: ({ object }) => {
    if (!object) return false; // 如果没有拾取到对象，则不显示工具提示
    return {
      className: `vptooltip`, // 应用自定义CSS类
      html: `
        <div style='width:250px'>
          <span class='vptooltip-title'>邮政编码:</span>            <p class='vptooltip-value'>${object.properties.Postcode}</p>
          <span class='vptooltip-title'>区域:</span>             <p class='vptooltip-value'>${object.properties.Suburbs}</p>
          <span class='vptooltip-title'>房屋中位数价格:</span>  <p class='vptooltip-value'>${object.properties.Md_H22_txt}</p>
          <span class='vptooltip-title'>售出房屋数量:</span>         <p class='vptooltip-value'>${object.properties.Ct_H22_num}</p>
        </div>
      `,
    };
  }
});

注意事项：

确保您的图层设置了pickable: true，这样DeckGL才能检测到鼠标交互并触发getTooltip回调。
工具提示的样式可以通过CSS进行完全自定义，如示例中的.vptooltip类。

6. 完整代码示例

将上述所有代码片段整合，您将得到一个功能完整的HTML文件，演示了如何使用CARTO v3和DeckGL实现图层可见性控制和工具提示。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>CARTO DeckGL 图层可见性控制</title>

    <!-- Bootstrap 5 CSS (可选，用于UI样式) -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">

    <!-- DeckGL, CARTO, MapLibre GL 库 -->
    <script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script> 
    <script src="https://unpkg.com/@deck.gl/carto@latest/dist.min.js"></script>
    <script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
    <link href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" rel="stylesheet" />

    <style>
      body { margin: 0; padding: 0; font-family: sans-serif; }
      #map { width: 100vw; height: 50vh; }
      .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;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <div style="padding: 10px;">
      图层可见性: 
      <input type="checkbox" id="layerToggle" checked>
    </div>

    <!-- Bootstrap 5 JS (可选) -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js" crossorigin="anonymous"></script>

    <script type="text/javascript">
      // 设置CARTO凭据
      deck.carto.setDefaultCredentials({
        apiBaseUrl: "https://gcp-australia-southeast1.api.carto.com", // 替换为您的CARTO API基础URL
        accessToken: "YOUR_CARTO_ACCESS_TOKEN" // 替换为您的CARTO访问令牌
      });

      // 定义一个用于控制图层可见性的状态对象
      const layerState = {
        isVisible: document.getElementById('layerToggle').checked
      };

      // 初始化DeckGL实例
      const mydeckgl = new deck.DeckGL({
        container: "map",
        map: maplibregl,
        mapStyle: deck.carto.BASEMAP.DARK_MATTER,
        initialViewState: {
          latitude: -33.85,
          longitude: 151.20,
          zoom: 12
        },
        controller: true,
        getTooltip: ({ object }) => {
          if (!object) return false;
          return {
            className: `vptooltip`,
            html: `
              <div style='width:250px'>
                <span class='vptooltip-title'>邮政编码:</span>            <p class='vptooltip-value'>${object.properties.Postcode}</p>
                <span class='vptooltip-title'>区域:</span>             <p class='vptooltip-value'>${object.properties.Suburbs}</p>
                <span class='vptooltip-title'>房屋中位数价格:</span>  <p class='vptooltip-value'>${object.properties.Md_H22_txt}</p>
                <span class='vptooltip-title'>售出房屋数量:</span>         <p class='vptooltip-value'>${object.properties.Ct_H22_num}</p>
              </div>
            `,
          };
        }
      });

      /**
       * 根据当前图层状态渲染或更新DeckGL图层
       */
      function renderLayers() {
        const layers = [
          new deck.carto.CartoLayer({ // 多边形图层
            id: 'heatmaps-polygons',
            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-ac-p76tk8ou.shared.2023FEB28_Postcode where Md_H22_num is not null",
            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: layerState.isVisible
          }),
          new deck.carto.CartoLayer({ // 文本标签图层
            id: 'heatmaps-labels',
            connection: "carto_dw",
            type: deck.carto.MAP_TYPES.QUERY,
            data: 'select Postcode, Ct_H22_num, Md_H22_txt, Suburbs, st_centroid(geom) as geom from carto-dw-ac-p76tk8ou.shared.2023FEB28_Postcode where Md_H22_num is not null',
            pointType: 'text', 
            getText: f => f.properties.Md_H22_txt,
            textFontFamily: "sans-serif",
            textBackground: true,
            getTextBackgroundColor:  [0, 0, 0, 50],
            textBackgroundPadding: [2, 2],
            getTextSize: 12,
            getTextColor: [250,250,250],
            pickable: true,
            visible: layerState.isVisible
          })
        ];
        mydeckgl.setProps({ layers });
      }

      // 为复选框添加事件监听器
      const layerToggleButton = document.getElementById('layerToggle');
      layerToggleButton.addEventListener('change', () => {
        layerState.isVisible = layerToggleButton.checked;
        renderLayers();
      });

      // 首次渲染图层
      renderLayers();
    </script>
  </body>
</html>

总结与最佳实践

通过本教程，您应该已经掌握了使用CARTO v3和DeckGL动态控制地图图层可见性的基本方法。核心在于：

利用visible属性：在CartoLayer或其他DeckGL图层定义中设置visible: true或visible: false来控制图层的初始显示状态。
使用deckgl.setProps({ layers })：当需要改变图层数组时（例如，改变某个图层的visible属性），通过调用mydeckgl.setProps()方法将新的图层数组传递给DeckGL实例。DeckGL会智能地处理更新，实现高效渲染。
状态管理：对于简单的应用，可以使用一个全局JavaScript对象来管理图层状态。对于更复杂的应用，特别是当图层数量众多或交互逻辑复杂时，可以考虑引入前端框架（如React、Vue）及其状态管理机制来更优雅地处理。
交互性：利用pickable: true和getTooltip回调函数可以轻松实现地图对象的悬停工具提示和点击事件，为用户提供丰富的交互体验。

掌握这些技术，将使您能够构建出功能强大、交互流畅的现代化Web GIS应用程序。

如何在滚动到视口时触发动画效果

如何在网页滚动时触发动画效果

如何实现滚动到指定区域时触发动画线条效果

如何优雅地禁用按钮并阻止点击事件处理

Puppeteer 数据抓取中定位嵌套元素的 CSS 选择器正确写法