本教程详细介绍了如何在 am5charts 地图中为国家多边形添加点击事件监听器，并根据点击的国家数据（如url）实现页面跳转。文章将涵盖图表初始化、数据绑定、事件监听的设置，以及如何正确从 `datacontext` 中获取自定义数据，确保地图交互功能按预期工作。
1. 引言
am5charts 是一个功能强大的 JavaScript 图表库，能够创建高度可定制的交互式地图。在构建世界地图时，一个常见的需求是当用户点击某个国家时，能够触发特定的操作，例如打开与该国家相关的网页链接。本文将指导您如何在 am5charts 地图中实现这一功能，确保数据绑定和事件监听正确无误。
2. am5charts 基础设置 (HTML & CSS)
首先，我们需要一个基本的 HTML 结构来承载地图，并引入 am5charts 库文件。
2.1 HTML 结构
创建一个 div 元素作为图表的容器，并引入 am5charts 的核心库、地图模块、动画主题以及世界地图的地理数据。
am5charts 地图点击事件
2.2 CSS 样式
为图表容器定义基本的样式，确保它在页面上可见并占据合适的空间。
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
}
#chartdiv {
width: 100%;
height: 95vh; /* 占据视口高度的95% */
}3. JavaScript 初始化 am5charts 地图
接下来，我们将编写 JavaScript 代码来初始化 am5charts 地图，包括创建根元素、设置主题、配置地图投影以及添加地图多边形系列。
3.1 创建 Root 和 Chart
所有 am5charts 组件都必须在 am5.Root 实例下创建。然后，我们创建 am5map.MapChart。
// 创建根元素
var root = am5.Root.new("chartdiv");
// 设置主题
root.setThemes([
am5themes_Animated.new(root)
]);
// 创建地图图表
var chart = root.container.children.push(
am5map.MapChart.new(root, {
panX: "rotateX", // 允许水平旋转
projection: am5map.geoNaturalEarth1(), // 使用自然地球投影
wheelY: "none", // 默认禁用滚轮缩放，稍后会条件性启用
maxPanOut: 0.0 // 限制地图不能平移出屏幕
})
);3.2 背景与缩放控制
为了美化地图，可以添加一个背景系列来模拟海洋，并实现一个带有 Ctrl 键的条件式滚轮缩放功能。
// 添加背景系列（海洋）
var backgroundSeries = chart.series.unshift(
am5map.MapPolygonSeries.new(root, {})
);
backgroundSeries.mapPolygons.template.setAll({
fill: am5.color(0xd4f1f9), // 海洋颜色
stroke: am5.color(0xd4f1f9),
});
backgroundSeries.data.push({
geometry: am5map.getGeoRectangle(90, 180, -90, -180) // 覆盖全球的矩形
});
// 条件性滚轮缩放
chart.events.on("wheel", function (ev) {
if (ev.originalEvent.ctrlKey) {
ev.originalEvent.preventDefault(); // 阻止默认滚轮行为
chart.set("wheelY", "zoom"); // 启用缩放
} else {
chart.set("wheelY", "none"); // 禁用缩放
// 可以添加其他提示或UI交互
}
});3.3 创建地图多边形系列
创建 MapPolygonSeries 来显示国家多边形。我们将使用 worldHigh.js 获取详细的地理数据。
// 创建国家多边形系列
var polygonSeries = chart.series.push(
am5map.MapPolygonSeries.new(root, {
geoJSON: am5geodata_worldHigh, // 使用世界高精度地理数据
exclude: ["AQ", "FK", "GS", "TF", "HM"], // 排除一些不常显示或有争议的区域
fill: am5.color(0x095256) // 国家默认填充色
})
);
// 定义鼠标悬停时的颜色
polygonSeries.mapPolygons.template.states.create("hover", {
fill: am5.color(0x677935),
});4. 绑定国家数据与自定义属性
为了在点击国家时打开特定链接，我们需要将这些链接作为自定义属性绑定到每个国家的数据项上。这通过 polygonSeries.data.setAll() 方法实现。
// 为特定国家添加自定义数据，包括一个“description”属性用于存储URL
polygonSeries.data.setAll([
{
id: "FR", // 国家ID，必须与geoJSON中的ID匹配
name: "France",
description: "https://www.google.com" // 关联的URL
},
{
id: "ES",
name: "Spain",
description: "https://www.bing.com"
},
// 可以继续添加更多国家及其链接
]);重要提示： polygonSeries.data.setAll() 会根据 id 属性将您提供的数据与 geoJSON 中的国家多边形进行匹配。确保 id 值与 geoJSON 中定义的国家ID一致。
5. 实现国家点击事件与链接跳转
现在，我们将为国家多边形添加点击事件监听器。当用户点击一个国家时，我们将获取其绑定的 description 属性并打开对应的链接。
5.1 事件监听器设置
通过 polygonSeries.mapPolygons.template.events.on("click", ...) 为所有国家多边形模板添加点击事件。
polygonSeries.mapPolygons.template.events.on("click", function (ev) {
// 获取被点击国家的数据项
var dataItem = ev.target.dataItem;
// 从 dataContext 中获取自定义的 description 属性
// dataContext 包含了通过 polygonSeries.data.setAll() 设置的所有自定义数据
var pageToOpen = dataItem.dataContext.description;
// 安全地打开链接
if (pageToOpen) { // 检查 description 是否存在且不为空
window.open(pageToOpen, "_blank"); // 在新标签页中打开链接
} else {
console.log("该国家没有关联的链接或链接为空。", dataItem.get("id"));
}
});5.2 获取点击国家的数据
在事件回调函数中，ev.target.dataItem 提供了对被点击多边形数据项的访问。要获取通过 polygonSeries.data.setAll() 添加的自定义属性（如 description），应通过 dataItem.dataContext 来访问。
- ev.target.dataItem.get("id") 可以获取国家的标准 ID。
- ev.target.dataItem.dataContext.description 是获取自定义 description 属性的正确方式。
5.3 安全地打开链接
在尝试打开链接之前，建议检查 pageToOpen 变量是否有效，以避免因缺少链接而导致的错误。window.open(url, "_blank") 会在新标签页中打开指定的 URL。
6. 完整示例代码
以下是整合了所有上述步骤的完整 JavaScript 代码：
// script.js
// 创建根元素
var root = am5.Root.new("chartdiv");
// 设置主题
root.setThemes([
am5themes_Animated.new(root)
]);
// 创建地图图表
var chart = root.container.children.push(
am5map.MapChart.new(root, {
panX: "rotateX",
projection: am5map.geoNaturalEarth1(),
wheelY: "none",
maxPanOut: 0.0
})
);
// 添加背景系列（海洋）
var backgroundSeries = chart.series.unshift(
am5map.MapPolygonSeries.new(root, {})
);
backgroundSeries.mapPolygons.template.setAll({
fill: am5.color(0xd4f1f9),
stroke: am5.color(0xd4f1f9),
});
backgroundSeries.data.push({
geometry: am5map.getGeoRectangle(90, 180, -90, -180)
});
// 条件性滚轮缩放
chart.events.on("wheel", function (ev) {
if (ev.originalEvent.ctrlKey) {
ev.originalEvent.preventDefault();
chart.set("wheelY", "zoom");
} else {
chart.set("wheelY", "none");
// 可以添加其他提示或UI交互
}
});
// 创建国家多边形系列
var polygonSeries = chart.series.push(
am5map.MapPolygonSeries.new(root, {
geoJSON: am5geodata_worldHigh,
exclude: ["AQ", "FK", "GS", "TF", "HM"],
fill: am5.color(0x095256)
})
);
// 定义鼠标悬停时的颜色
polygonSeries.mapPolygons.template.states.create("hover", {
fill: am5.color(0x677935),
});
// 为特定国家添加自定义数据，包括一个“description”属性用于存储URL
polygonSeries.data.setAll([
{
id: "FR",
name: "France",
description: "https://www.google.com"
},
{
id: "ES",
name: "Spain",
description: "https://www.bing.com"
},
{
id: "DE",
name: "Germany",
description: "https://www.amcharts.com/"
},
{
id: "US",
name: "United States",
// 注意：这里故意不提供description，用于演示处理无链接情况
}
]);
// 添加点击事件监听器
polygonSeries.mapPolygons.template.events.on("click", function (ev) {
var dataItem = ev.target.dataItem;
var clickedCountryId = dataItem.get("id");
var pageToOpen = dataItem.dataContext.description; // 从 dataContext 获取自定义属性
console.log("点击了国家:", clickedCountryId);
if (pageToOpen) { // 检查 description 是否存在且不为空
window.open(pageToOpen, "_blank"); // 在新标签页中打开链接
} else {
console.log("国家 " + clickedCountryId + " 没有关联的链接或链接为空。");
}
});7. 注意事项与最佳实践
- 数据匹配： 确保 polygonSeries.data.setAll() 中 id 属性的值与 geoJSON 数据中国家的 ID 严格匹配。不匹配会导致自定义数据无法正确关联。
- dataContext 的使用： 当通过 polygonSeries.data.setAll() 添加自定义数据时，这些数据会存储在每个数据项的 dataContext 属性中。因此，在事件监听器中，需要通过 ev.target.dataItem.dataContext.yourPropertyName 来访问这些自定义属性。
- 错误处理： 在尝试打开链接之前，始终检查链接变量是否有效（例如，if (pageToOpen)）。这可以防止因数据缺失或格式错误而导致的运行时错误。
- 用户体验： 考虑在没有链接的国家上添加视觉提示（例如，不同的颜色或鼠标样式），或者在点击时显示一条消息，告知用户该国家没有可用信息。
- 异步数据加载： 如果您的国家数据来自异步 API 调用，请确保在数据完全加载并设置到 polygonSeries.data 之后，再创建并附加事件监听器。
8. 总结
通过本教程，您已经学会了如何在 am5charts 地图中为国家多边形添加交互式点击事件，并根据国家数据动态打开相应的网页链接。关键在于正确地将自定义数据绑定到 polygonSeries.data，并通过 dataItem.dataContext 在事件监听器中访问这些数据。掌握这些技术将使您能够创建功能更丰富、用户体验更佳的交互式地图应用。
