arcgis-charts（地理信息系统图表）

ArcGIS Charts

Use this skill when visualizing layer data as charts (bar, line, pie, histogram, scatter, etc.) using the @arcgis/charts-components package. This is a new component package in 5.0 with no 4.x equivalent.

Import Patterns

CDN (No Build Tools)

<!-- Load ArcGIS Maps SDK -->
<script src="https://js.arcgis.com/5.0/"></script>
<!-- Load Charts Components -->
<script
  type="module"
  src="https://js.arcgis.com/5.0/charts-components/"
></script>

Direct ESM Imports (Build Tools)

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

Chart Models (for programmatic configuration)

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";

Supported Chart Types

arcgis-chart Component

Core Properties

Display Properties

Data and Filtering Properties

Formatter Callbacks

Methods

Events

Basic Usage

Chart from a 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>

Chart with WebChart Spec (JSON Configuration)

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",
    },
  ],
};

Pie Chart

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;

Line Chart

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 Component

Provides a toolbar for chart interactions (export, selection, filtering, zoom).

Setup

<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>

Key Action Bar Properties

Action states can be "enabled", "disabled", or "hidden".

Selection and Filtering

Sync Selection Between Chart and Map

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);
});

Filter Chart by Map Extent

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

Runtime Data Filters

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

Export

Export as Image

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

Export as CSV

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

Custom Formatters

Data Label Formatter

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);
};

Tooltip Formatter

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

Axis Label Formatter

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

CDN Full Example

<!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>

Common Pitfalls

1. Missing layer property: The chart requires a layer data source. Setting only model without layer produces an empty chart. // 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; Impact: The chart renders its frame and axes but shows no data.
2. Chart component not loaded: The charts package must be explicitly loaded via CDN or imported. <!-- Anti-pattern: missing charts-components script --> <script src="https://js.arcgis.com/5.0/"></script> <arcgis-chart></arcgis-chart> <!-- Correct: include charts-components --> <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> Impact: The arcgis-chart element is not defined and renders as an empty inline element.
3. Setting model as an HTML attribute: The model property accepts complex objects and must be set via JavaScript, not as an HTML attribute. Impact: The attribute value is ignored; the chart shows no data.
4. Using filterByExtent without view: Extent filtering requires the view property to track the current map extent. // 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; Impact: The filter has no extent to reference and may throw errors or show all data.
5. Action bar not connected: The action bar needs a reference to the chart element. // Anti-pattern: action bar without chart reference const actionBar = document.querySelector("arcgis-charts-action-bar"); // Missing: actionBar.chartElement = chartElement; Impact: Action bar buttons are visible but do nothing when clicked.

Reference Samples

• arcade-execute-chart - Execute Arcade expressions and build charts from results
• featurereduction-cluster-popup-chart - Charts inside cluster popups
• featurereduction-cluster-pie-charts - Pie chart cluster representations
• visualization-pie-chart - Pie chart visualization

Related Skills

• See arcgis-layers for configuring FeatureLayers that supply chart data.
• See arcgis-core-maps for setting up the MapView referenced by charts.
• See arcgis-arcade for Arcade expressions used with chart data computation.
• See arcgis-widgets-ui for layout components to host chart panels.