arcgis-charts

ArcGIS 图表

使用 @arcgis/charts-components 包将图层数据可视化为图表（条形图、折线图、饼图、直方图、散点图等）。这是 5.0 中新增的组件包，在 4.x 中没有对应版本。

导入方式

CDN（无需构建工具）

<script src="https://js.arcgis.com/5.0/"></script>

<script
  type="module"
  src="https://js.arcgis.com/5.0/charts-components/"
></script>

直接导入 ESM（构建工具）

import "@arcgis/charts-components/components/arcgis-chart";
import "@arcgis/charts-components/components/arcgis-charts-action-bar";

图表模型（用于编程配置）

import { BarChartModel } from "@arcgis/charts-components/model";
import { PieChartModel } from "@arcgis/charts-components/model";
import { LineChartModel } from "@arcgis/charts-components/model";
import { HistogramModel } from "@arcgis/charts-components/model";
import { ScatterplotModel } from "@arcgis/charts-components/model";
import { BoxPlotModel } from "@arcgis/charts-components/model";
import { GaugeModel } from "@arcgis/charts-components/model";
import { RadarChartModel } from "@arcgis/charts-components/model";
import { HeatChartModel } from "@arcgis/charts-components/model";
import { ComboBarLineChartModel } from "@arcgis/charts-components/model";

支持的图表类型

图表类型	模型类	说明
条形图	BarChartModel	水平或垂直条形图
折线图	LineChartModel	带系列的折线图
饼图	PieChartModel	饼图和圆环图
直方图	HistogramModel	频率分布直方图
散点图	ScatterplotModel	散点图和气泡图
箱线图	BoxPlotModel	箱线图
仪表图	GaugeModel	仪表图 / 速度计图
雷达图	RadarChartModel	雷达图 / 蜘蛛网图
热力图	HeatChartModel	热力图 / 矩阵图
组合图	ComboBarLineChartModel	条形图和折线图组合

arcgis-chart 组件

核心属性

属性	特性	类型	默认值	说明
model	-	ChartModel | WebChart	-	图表配置模型（通过 JS 设置）
layer	-	FeatureLayerView | SupportedLayer	-	数据源图层（通过 JS 设置）
view	-	MapView | SceneView	-	地图 / 场景视图引用（通过 JS 设置）
layerItemId	layer-item-id	string	-	图层门户项目 ID（可替代 layer）
chartIndex	chart-index	number	-	图层包含多个图表时，要渲染的图表索引
actionMode	action-mode	string	-	交互模式："zoom"、"multiSelection"、"multiSelectionWithCtrlKey"、"pan"

显示属性

属性	Attribute	类型	默认值	描述
disableInteractions	disable-interactions	boolean	false	禁用所有图表交互
enableConfiguration	enable-configuration	boolean	false	启用内置图表配置界面
enableResponsiveFeatures	enable-responsive-features	boolean	-	启用响应式行为
useAnimatedCharts	use-animated-charts	boolean	-	启用图表动画
hideEmptySeries	hide-empty-series	boolean	-	隐藏没有数据的系列
hideLicenseWatermark	hide-license-watermark	boolean	-	隐藏许可证水印
hideLoaderAnimation	hide-loader-animation	boolean	-	隐藏加载动画
placeholder	placeholder	string	-	没有数据时显示的占位文本
showUIMessages	show-ui-messages	boolean	-	显示面向用户的消息
errorPolicy	error-policy	string	"throw"	错误处理方式："throw" 或 "ignore"

数据和筛选属性

属性	Attribute	类型	默认值	描述
filterByExtent	filter-by-extent	boolean	-	按当前地图范围筛选图表数据
filterBySelection	filter-by-selection	boolean	-	按地图选区筛选图表数据
syncSelection	sync-selection	boolean	false	同步图表和地图之间的选区
runtimeDataFilters	-	WebChartDataFilters	-	运行时数据筛选器（通过 JS 设置）
selectionData	-	SelectionData	-	当前选区数据
nullAsValid	null-as-valid	boolean	false	将 null 值视为有效数据点
timeZone	time-zone	string	-	时间数据的时区

格式化回调

属性	类型	描述
dataLabelFormatter	function	自定义数据标签格式
tooltipFormatter	function	自定义工具提示格式
xAxisLabelFormatter	function	自定义 X 轴标签格式
yAxisLabelFormatter	function	自定义 Y 轴标签格式
gaugeInnerLabelFormatter	function	自定义仪表盘内部标签格式
guideTooltipFormatter	function	自定义指南工具提示格式

方法

方法	返回值	描述
loadModel()	Promise<void>	加载图表模型
refresh(props?)	Promise<void>	刷新图表；可选 { updateData, resetAxesBounds }
resetZoom()	Promise<void>	将缩放重置为默认视图
clearSelection()	Promise<void>	清除所有选择
switchSelection()	Promise<void>	切换选择状态
exportAsImage(format?)	Promise<void>	将图表导出为 "png"、"jpg" 或 "svg"
exportAsCSV(options?)	Promise<void>	将图表数据导出为 CSV 文件
errorAlert(message?)	Promise<void>	显示错误警报
notify(message?, heading?)	Promise<void>	显示通知
componentOnReady()	Promise<this>	组件完全加载后解析

事件

事件	详情	描述
arcgisSelectionChange	-	图表选择发生变化时触发
arcgisDataFetchComplete	WebChartDataTypes	数据获取完成时触发
arcgisDataProcessComplete	-	数据处理完成时触发
arcgisUpdateComplete	ValidationStatus	图表更新完成时触发
arcgisConfigChange	{ newConfig, oldConfig, functionCalled }	图表配置发生变化时触发
arcgisAxesMinMaxChange	AxesMinMaxChangePayload	计算出坐标轴最小值和最大值时触发
arcgisBadDataWarningRaise	DataWarningObject	检测到数据错误时触发
arcgisChartNotFoundWarning	string	找不到引用的图表时触发

基本用法

从 FeatureLayer 创建图表

<arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
  <arcgis-zoom slot="top-left"></arcgis-zoom>
</arcgis-map>
<div id="chart-container" style="width: 500px; height: 400px;">
  <arcgis-chart id="my-chart"></arcgis-chart>
</div>

<script type="module">
  const mapElement = document.querySelector("arcgis-map");
  const chartElement = document.querySelector("#my-chart");

  await mapElement.viewOnReady();
  const view = mapElement.view;

  // Get the layer
  const layer = view.map.layers.find((l) => l.title === "My Layer");
  await view.whenLayerView(layer);

  // Assign layer and view to chart
  chartElement.layer = layer;
  chartElement.view = view;

  // Create a bar chart model
  const { BarChartModel } = await $arcgis.import(
    "@arcgis/charts-components/model",
  );

  const model = new BarChartModel();
  model.layer = layer;

  chartElement.model = model;
</script>

使用 WebChart 规范（JSON 配置）创建图表

const chartElement = document.querySelector("arcgis-chart");
chartElement.layer = layer;
chartElement.view = view;

// WebChart JSON specification
chartElement.model = {
  type: "bar",
  title: { visible: true, text: "Population by State" },
  series: [
    {
      type: "bar",
      query: {
        orderByFields: ["Population DESC"],
        groupByFieldsForStatistics: ["State"],
        outStatistics: [
          {
            statisticType: "sum",
            onStatisticField: "Population",
            outStatisticFieldName: "TotalPop",
          },
        ],
      },
      x: "State",
      y: "TotalPop",
    },
  ],
};

饼图

const { PieChartModel } = await $arcgis.import(
  "@arcgis/charts-components/model",
);

const model = new PieChartModel();
model.layer = layer;

const chartElement = document.querySelector("arcgis-chart");
chartElement.layer = layer;
chartElement.view = view;
chartElement.model = model;

折线图

const { LineChartModel } = await $arcgis.import(
  "@arcgis/charts-components/model",
);

const model = new LineChartModel();
model.layer = layer;

const chartElement = document.querySelector("arcgis-chart");
chartElement.layer = layer;
chartElement.view = view;
chartElement.model = model;

arcgis-charts-action-bar 组件

提供用于图表交互（导出、选择、筛选、缩放）的工具栏。

设置

<div style="position: relative; width: 600px; height: 400px;">
  <arcgis-chart id="my-chart"></arcgis-chart>
  <arcgis-charts-action-bar id="my-action-bar"></arcgis-charts-action-bar>
</div>

<script type="module">
  const chart = document.querySelector("#my-chart");
  const actionBar = document.querySelector("#my-action-bar");

  // Connect action bar to chart
  actionBar.chartElement = chart;
</script>

操作栏关键属性

属性	Attribute	类型	默认值	描述
chartElement	chart-element	ArcgisChart	-	对图表组件的引用
expanded	expanded	boolean	false	操作栏是否已展开
exportAsImageState	export-as-image-state	string	"enabled"	图像导出按钮的状态
exportAsCSVState	export-as-csv-state	string	"enabled"	CSV 导出按钮的状态
filterByExtentState	filter-by-extent-state	string	"enabled"	按范围筛选按钮的状态
filterBySelectionState	filter-by-selection-state	string	"enabled"	按选择筛选按钮的状态
zoomState	zoom-state	string	"enabled"	缩放按钮的状态
forceDisableActions	force-disable-actions	boolean	false	一次性禁用所有操作
hiddenActions	-	DefaultChartActions[]	-	要隐藏的操作数组

操作状态可以是 "enabled"、"disabled" 或 "hidden"。

选择与筛选

在图表和地图之间同步选择

const chart = document.querySelector("arcgis-chart");
chart.syncSelection = true;
chart.layer = layer;
chart.view = view;

// Listen for selection changes
chart.addEventListener("arcgisSelectionChange", () => {
  console.log("Selection changed:", chart.selectionData);
});

按地图范围筛选图表

const chart = document.querySelector("arcgis-chart");
chart.filterByExtent = true;
chart.view = view;
chart.layer = layer;

运行时数据筛选器

const chart = document.querySelector("arcgis-chart");
chart.runtimeDataFilters = {
  where: "Population > 100000",
  orderByFields: ["Population DESC"],
};

导出

导出为图像

const chart = document.querySelector("arcgis-chart");
await chart.exportAsImage("png"); // "png", "jpg", or "svg"

导出为 CSV

const chart = document.querySelector("arcgis-chart");
await chart.exportAsCSV();

自定义格式化器

数据标签格式化器

const chart = document.querySelector("arcgis-chart");
chart.dataLabelFormatter = (value, field) => {
  if (typeof value === "number") {
    return value.toLocaleString("en-US", {
      style: "currency",
      currency: "USD",
    });
  }
  return String(value);
};

工具提示格式化器

chart.tooltipFormatter = (tooltipData) => {
  return `<b>${tooltipData.category}</b>: ${tooltipData.value.toLocaleString()}`;
};

坐标轴标签格式化器

chart.xAxisLabelFormatter = (value) => {
  // Truncate long labels
  return String(value).length > 15
    ? String(value).slice(0, 12) + "..."
    : String(value);
};

CDN 完整示例

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Chart from Feature Layer</title>
    <script src="https://js.arcgis.com/5.0/"></script>
    <script
      type="module"
      src="https://js.arcgis.com/5.0/charts-components/"
    ></script>
    <script
      type="module"
      src="https://js.arcgis.com/5.0/map-components/"
    ></script>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
        display: flex;
      }
      arcgis-map {
        flex: 1;
      }
      #chart-panel {
        width: 400px;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <arcgis-map id="map" item-id="YOUR_WEBMAP_ID">
      <arcgis-zoom slot="top-left"></arcgis-zoom>
    </arcgis-map>
    <div id="chart-panel">
      <arcgis-chart id="chart"></arcgis-chart>
      <arcgis-charts-action-bar id="action-bar"></arcgis-charts-action-bar>
    </div>

    <script type="module">
      const mapElement = document.querySelector("#map");
      const chartElement = document.querySelector("#chart");
      const actionBar = document.querySelector("#action-bar");

      await mapElement.viewOnReady();
      const view = mapElement.view;
      const layer = view.map.layers.getItemAt(0);
      await view.whenLayerView(layer);

      const { BarChartModel } = await $arcgis.import(
        "@arcgis/charts-components/model",
      );

      const model = new BarChartModel();
      model.layer = layer;

      chartElement.layer = layer;
      chartElement.view = view;
      chartElement.model = model;
      chartElement.syncSelection = true;

      actionBar.chartElement = chartElement;
    </script>
  </body>
</html>

常见问题

1. 缺少 layer 属性：图表需要图层数据源。只设置 model 而不设置 layer 会生成空图表。

   // Anti-pattern: model without layer
   chartElement.model = new BarChartModel();
   

   // Correct: set both layer and model
   const model = new BarChartModel();
   model.layer = layer;
   chartElement.layer = layer;
   chartElement.model = model;
   

   **影响：**图表会渲染边框和坐标轴，但不显示数据。

2. 未加载图表组件：必须通过 CDN 显式加载或导入图表包。

   
   <script src="https://js.arcgis.com/5.0/"></script>
   <arcgis-chart></arcgis-chart>
   

   
   <script src="https://js.arcgis.com/5.0/"></script>
   <script
     type="module"
     src="https://js.arcgis.com/5.0/charts-components/"
   ></script>
   <arcgis-chart></arcgis-chart>
   

   影响：arcgis-chart 元素未定义，并会渲染为空的内联元素。

3. 将 model 设置为 HTML 属性：model 属性接受复杂对象，必须通过 JavaScript 设置，而不能作为 HTML 属性设置。

   **影响：**属性值会被忽略；图表不显示数据。

4. 在没有 view 的情况下使用 filterByExtent：范围筛选需要 view 属性来跟踪当前地图范围。

   // Anti-pattern: filterByExtent without view
   chart.filterByExtent = true;
   chart.layer = layer;
   

   // Correct: set view for extent filtering
   chart.filterByExtent = true;
   chart.layer = layer;
   chart.view = view;
   

   **影响：**筛选器没有可供参考的范围，可能会抛出错误或显示所有数据。

5. 操作栏未连接：操作栏需要引用图表元素。

   // Anti-pattern: action bar without chart reference
   const actionBar = document.querySelector("arcgis-charts-action-bar");
   // Missing: actionBar.chartElement = chartElement;
   

   **影响：**操作栏按钮可见，但点击后不起作用。

参考示例

• arcade-execute-chart - 执行 Arcade 表达式并根据结果构建图表
• featurereduction-cluster-popup-chart - 集群弹出窗口中的图表
• featurereduction-cluster-pie-charts - 饼图集群表示
• visualization-pie-chart - 饼图可视化

相关技能

• 查看 arcgis-layers，了解如何配置提供图表数据的 FeatureLayers。
• 查看 arcgis-core-maps，了解如何设置图表引用的 MapView。
• 查看 arcgis-arcade，了解用于计算图表数据的 Arcade 表达式。
• 查看 arcgis-widgets-ui，了解用于承载图表面板的布局组件。