arcgis-visualization

ArcGIS 可视化

使用此技能，通过渲染器、符号、视觉变量、标签和效果设置图层样式。

导入模式

直接 ESM 导入

import SimpleRenderer from "@arcgis/core/renderers/SimpleRenderer.js";
import UniqueValueRenderer from "@arcgis/core/renderers/UniqueValueRenderer.js";
import ClassBreaksRenderer from "@arcgis/core/renderers/ClassBreaksRenderer.js";
import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";
import SimpleLineSymbol from "@arcgis/core/symbols/SimpleLineSymbol.js";
import SimpleFillSymbol from "@arcgis/core/symbols/SimpleFillSymbol.js";

CDN 动态导入

const [SimpleRenderer, SimpleMarkerSymbol] = await $arcgis.import([
  "@arcgis/core/renderers/SimpleRenderer.js",
  "@arcgis/core/symbols/SimpleMarkerSymbol.js",
]);

**注意：**以下示例使用自动转换（带有 type 的普通对象）。使用 CDN 时，请将 import X from "path" 替换为 const X = await $arcgis.import("path")。

渲染器类型概览

渲染器	自动转换类型	用例
SimpleRenderer	"simple"	所有要素使用相同的符号
UniqueValueRenderer	"unique-value"	按类别使用不同的符号
ClassBreaksRenderer	"class-breaks"	按数值范围使用不同的符号
HeatmapRenderer	"heatmap"	密度可视化（仅限点）
DotDensityRenderer	"dot-density"	点密度地图（仅限面）
PieChartRenderer	"pie-chart"	为每个要素绘制饼图
DictionaryRenderer	"dictionary"	军事符号系统（MIL-STD-2525）
FlowRenderer	"flow"	动态流线（影像）

SimpleRenderer

const renderer = {
  type: "simple",
  symbol: {
    type: "simple-marker",
    color: "blue",
    size: 8,
    outline: {
      color: "white",
      width: 1,
    },
  },
};

layer.renderer = renderer;

使用视觉变量

const renderer = {
  type: "simple",
  symbol: {
    type: "simple-marker",
    color: "#13EB0C",
    outline: { color: "#A9A9A9", width: 0.5 },
  },
  visualVariables: [
    {
      type: "size",
      field: "population",
      stops: [
        { value: 1000, size: 4 },
        { value: 10000, size: 12 },
        { value: 100000, size: 24 },
      ],
    },
  ],
};

UniqueValueRenderer

基本唯一值

const renderer = {
  type: "unique-value",
  field: "type",
  defaultSymbol: { type: "simple-fill", color: "gray" },
  uniqueValueInfos: [
    {
      value: "residential",
      symbol: { type: "simple-fill", color: "#FFFF00" },
      label: "Residential",
    },
    {
      value: "commercial",
      symbol: { type: "simple-fill", color: "#FF0000" },
      label: "Commercial",
    },
    {
      value: "industrial",
      symbol: { type: "simple-fill", color: "#800080" },
      label: "Industrial",
    },
  ],
};

分组唯一值（图例中带有标题）

const renderer = {
  type: "unique-value",
  field: "zonecode",
  uniqueValueGroups: [
    {
      heading: "Commercial",
      classes: [
        {
          label: "C-1 | Neighborhood Commercial",
          symbol: createFillSymbol([189, 145, 145]),
          values: "C-1",
        },
        {
          label: "C-2 | Community Commercial",
          symbol: createFillSymbol([255, 179, 219]),
          values: "C-2",
        },
      ],
    },
    {
      heading: "Residential",
      classes: [
        {
          label: "R-1 | Low Density",
          symbol: createFillSymbol([255, 255, 224]),
          values: "R-1",
        },
        {
          label: "Special Areas",
          symbol: createFillSymbol([161, 237, 237]),
          values: ["S-DW", "S-DR", "S-RP"], // Multiple values
        },
      ],
    },
  ],
};

function createFillSymbol(color) {
  return {
    type: "simple-fill",
    color: color,
    outline: null,
  };
}

ClassBreaksRenderer

const renderer = {
  type: "class-breaks",
  field: "population",
  normalizationField: "area", // Optional: divide by this field
  legendOptions: {
    title: "Population Density",
  },
  defaultSymbol: {
    type: "simple-fill",
    color: "black",
    style: "backward-diagonal",
  },
  defaultLabel: "No data",
  classBreakInfos: [
    {
      minValue: 0,
      maxValue: 100,
      symbol: { type: "simple-fill", color: "#fffcd4" },
      label: "< 100",
    },
    {
      minValue: 100,
      maxValue: 500,
      symbol: { type: "simple-fill", color: "#b1cdc2" },
      label: "100 - 500",
    },
    {
      minValue: 500,
      maxValue: 1000,
      symbol: { type: "simple-fill", color: "#38627a" },
      label: "500 - 1,000",
    },
    {
      minValue: 1000,
      maxValue: Infinity,
      symbol: { type: "simple-fill", color: "#0d2644" },
      label: "> 1,000",
    },
  ],
};

HeatmapRenderer

const renderer = {
  type: "heatmap",
  colorStops: [
    { color: "rgba(63, 40, 102, 0)", ratio: 0 },
    { color: "#472b77", ratio: 0.083 },
    { color: "#563098", ratio: 0.25 },
    { color: "#7139d4", ratio: 0.5 },
    { color: "#853fff", ratio: 0.664 },
    { color: "#c29f80", ratio: 0.83 },
    { color: "#ffff00", ratio: 1 },
  ],
  maxDensity: 0.01,
  minDensity: 0,
  radius: 18, // Blur radius in pixels
};

PieChartRenderer

const renderer = {
  type: "pie-chart",
  attributes: [
    { field: "asian_pop", label: "Asian", color: "#ed5151" },
    { field: "black_pop", label: "Black", color: "#149ece" },
    { field: "white_pop", label: "White", color: "#a7c636" },
    { field: "other_pop", label: "Other", color: "#9e559c" },
  ],
  size: 18,
  othersCategory: {
    threshold: 0.05,
    color: "gray",
    label: "Other",
  },
};

2D 符号类型

SimpleMarkerSymbol（点）

const symbol = {
  type: "simple-marker",
  style: "circle", // circle, square, cross, x, diamond, triangle
  color: [255, 0, 0],
  size: 12,
  outline: {
    color: [255, 255, 255],
    width: 2,
  },
};

SimpleLineSymbol

const symbol = {
  type: "simple-line",
  style: "solid", // solid, dash, dot, dash-dot, etc.
  color: [0, 0, 255],
  width: 2,
  cap: "round", // round, butt, square
  join: "round", // round, miter, bevel
};

SimpleFillSymbol（面）

const symbol = {
  type: "simple-fill",
  style: "solid", // solid, none, horizontal, vertical, cross, etc.
  color: [255, 255, 0, 0.5], // RGBA
  outline: {
    type: "simple-line",
    color: [0, 0, 0],
    width: 1,
  },
};

PictureMarkerSymbol

const symbol = {
  type: "picture-marker",
  url: "https://example.com/icon.png",
  width: 24,
  height: 24,
  xoffset: 0,
  yoffset: 0,
};

TextSymbol

const symbol = {
  type: "text",
  text: "Label",
  color: "white",
  font: {
    family: "Arial",
    size: 12,
    weight: "bold",
  },
  haloColor: "black",
  haloSize: 1,
};

3D 符号类型

PointSymbol3D

// Icon marker
const symbol = {
  type: "point-3d",
  symbolLayers: [
    {
      type: "icon",
      resource: { primitive: "circle" },
      material: { color: "red" },
      size: 12,
    },
  ],
};

// Object marker
const objectSymbol = {
  type: "point-3d",
  symbolLayers: [
    {
      type: "object",
      resource: { primitive: "cylinder" }, // cone, cube, sphere, diamond
      material: { color: "blue" },
      height: 100,
      width: 10,
      depth: 10,
    },
  ],
};

WebStyleSymbol（图库中的 3D 图标）

const symbol = {
  type: "web-style",
  name: "Pushpin 1",
  styleName: "Esri2DPointSymbolsStyle",
};

MeshSymbol3D（用于 SceneLayer）

const symbol = {
  type: "mesh-3d",
  symbolLayers: [
    {
      type: "fill",
      material: { color: [244, 247, 134] },
    },
  ],
};

LineSymbol3D

const symbol = {
  type: "line-3d",
  symbolLayers: [
    {
      type: "path",
      profile: "quad", // circle, quad
      material: { color: "red" },
      width: 5,
      height: 5,
    },
  ],
};

PolygonSymbol3D

const symbol = {
  type: "polygon-3d",
  symbolLayers: [
    {
      type: "extrude",
      material: { color: "blue" },
      size: 100, // Extrusion height
    },
  ],
};

视觉变量

视觉变量类：ColorVariable、SizeVariable、OpacityVariable、RotationVariable。

import ColorVariable from "@arcgis/core/renderers/visualVariables/ColorVariable.js";
import SizeVariable from "@arcgis/core/renderers/visualVariables/SizeVariable.js";

大小变量

visualVariables: [
  {
    type: "size",
    field: "magnitude",
    stops: [
      { value: 1, size: 4 },
      { value: 5, size: 20 },
      { value: 10, size: 40 },
    ],
  },
];

颜色变量

visualVariables: [
  {
    type: "color",
    field: "temperature",
    stops: [
      { value: 0, color: "blue" },
      { value: 50, color: "yellow" },
      { value: 100, color: "red" },
    ],
  },
];

不透明度变量

visualVariables: [
  {
    type: "opacity",
    field: "confidence",
    stops: [
      { value: 0, opacity: 0.1 },
      { value: 100, opacity: 1 },
    ],
  },
];

旋转变量

visualVariables: [
  {
    type: "rotation",
    field: "heading",
    rotationType: "geographic", // or "arithmetic"
  },
];

标注

layer.labelingInfo = [
  {
    symbol: {
      type: "text",
      color: "white",
      font: {
        family: "Noto Sans",
        size: 10,
        weight: "bold",
      },
      haloColor: "#472b77",
      haloSize: 1,
    },
    labelPlacement: "above-center", // Various placement options
    labelExpressionInfo: {
      expression: "$feature.name", // Arcade expression
    },
    where: "population > 10000", // SQL filter
    minScale: 500000,
    maxScale: 0,
  },
];

layer.labelsVisible = true;

标注位置

• 点：above-center、below-center、center-center、above-left 等
• 线：above-along、below-along、center-along
• 面：always-horizontal

Arcade 标注表达式

labelExpressionInfo: {
  expression: `
    var pop = $feature.population;
    if (pop > 1000000) {
      return $feature.name + " (" + Round(pop/1000000, 1) + "M)";
    }
    return $feature.name;
  `;
}

自动转换

所有符号和渲染器对象都支持自动转换，可使用普通对象，而无需实例化类。

// Autocast: plain object with type property
layer.renderer = {
  type: "simple",
  symbol: {
    type: "simple-marker",
    color: "red",
    size: 8,
  },
};

对于 TypeScript，请使用 as const 或 satisfies：

layer.renderer = {
  type: "simple",
  symbol: {
    type: "simple-marker",
    color: "red",
    size: 8,
  },
} as const;

需要实例方法时，请使用显式类：

import SimpleRenderer from "@arcgis/core/renderers/SimpleRenderer.js";
import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";

layer.renderer = new SimpleRenderer({
  symbol: new SimpleMarkerSymbol({ color: "red", size: 8 }),
});

有关图层效果（发光、模糊、投影）和混合模式，请参阅 arcgis-feature-effects。

有关智能制图渲染器和数据驱动可视化，请参阅 arcgis-smart-mapping。

有关使用 CIM 的高级制图符号，请参阅 arcgis-cim-symbols。

参考示例

• get-started-visualization - 数据可视化入门
• visualization-classbreaks - 用于数值数据的 ClassBreaksRenderer
• visualization-unique-value-groups - 分组唯一值渲染器
• visualization-vv-color - 使用颜色的视觉变量
• visualization-pie-chart - 用于多变量数据的 PieChartRenderer
• visualization-heatmap - 热力图可视化
• visualization-dot-density - 点密度地图
• visualization-point-styles - 点符号样式
• labels-basic - 基本标注配置
• labels-multiline - 多行标注
• labels-multiple-classes - 多个标注类

常见问题

1. 缺少 type 属性：渲染器和符号都需要 type 属性才能自动转换。

   // Anti-pattern: missing type on renderer and symbol
   layer.renderer = {
     symbol: { color: "red", size: 8 },
   };
   

   // Correct: include type at both renderer and symbol level
   layer.renderer = {
     type: "simple",
     symbol: {
       type: "simple-marker",
       color: "red",
       size: 8,
     },
   };
   

   **影响：**缺少 type 时，自动转换会静默失败。要素会使用默认符号系统进行渲染。

2. 颜色格式：颜色可以是十六进制值、命名颜色、RGB 数组或 RGBA 数组。

   color: "red";
   color: "#FF0000";
   color: [255, 0, 0];
   color: [255, 0, 0, 0.5]; // With transparency
   

3. 视觉变量需要数值字段：使用字符串字段设置大小或颜色不会产生变化。

   // Anti-pattern: string field for size
   visualVariables: [
     {
       type: "size",
       field: "city_name", // String field - no variation
       stops: [
         { value: 0, size: 4 },
         { value: 100, size: 40 },
       ],
     },
   ];
   

   // Correct: numeric field for size
   visualVariables: [
     {
       type: "size",
       field: "population", // Numeric field
       stops: [
         { value: 10000, size: 4 },
         { value: 1000000, size: 40 },
       ],
     },
   ];
   

4. 标注表达式使用 Arcade：使用 Arcade 语法（$feature.fieldName），而不是 JavaScript。

5. 3D 符号需要 SceneView：PointSymbol3D、LineSymbol3D、PolygonSymbol3D 仅适用于 SceneView，不适用于 MapView。

相关技能

• arcgis-cim-symbols - 高级制图符号（CIM）
• arcgis-smart-mapping - 根据数据自动生成渲染器
• arcgis-feature-effects - 视觉效果和筛选器
• arcgis-core-maps - 地图和视图设置
• arcgis-layers - 图层类型和配置