arcgis-feature-effects

ArcGIS 要素效果

将此技能用于对图层应用视觉效果、要素过滤器、显示过滤器、聚焦区域和混合模式。

导入模式

直接 ESM 导入

import FeatureEffect from "@arcgis/core/layers/support/FeatureEffect.js";
import FeatureFilter from "@arcgis/core/layers/support/FeatureFilter.js";
import FocusArea from "@arcgis/core/effects/FocusArea.js";
import FocusAreas from "@arcgis/core/effects/FocusAreas.js";
import FocusAreaOutline from "@arcgis/core/effects/FocusAreaOutline.js";

CDN 动态导入

const [FeatureEffect, FeatureFilter, FocusArea] = await $arcgis.import([
  "@arcgis/core/layers/support/FeatureEffect.js",
  "@arcgis/core/layers/support/FeatureFilter.js",
  "@arcgis/core/effects/FocusArea.js",
]);

注： 以下示例使用自动转换。对于 CDN 用法，请将 import X from "path" 替换为 const X = await $arcgis.import("path")。

要素效果基础

要素效果根据过滤器将要素分为两组（包含／排除），然后分别对每组应用类似 CSS 的效果。

基本要素效果

layer.featureEffect = {
  filter: {
    where: "population > 100000",
  },
  includedEffect: "bloom(1.5, 0.5px, 0.2)",
  excludedEffect: "grayscale(100%) opacity(30%)",
};

对 LayerView 应用要素效果

const layerView = await view.whenLayerView(layer);

layerView.featureEffect = {
  filter: {
    where: "status = 'Active'",
  },
  excludedEffect: "grayscale(100%) opacity(50%)",
};

依比例尺变化的效果

layerView.featureEffect = {
  filter: {
    where: "party_switch = 'R' OR party_switch = 'D'",
  },
  includedEffect: [
    { scale: 36978595, value: "drop-shadow(3px, 3px, 4px)" },
    { scale: 18489297, value: "drop-shadow(2px, 2px, 3px)" },
    { scale: 4622324, value: "drop-shadow(1px, 1px, 2px)" },
  ],
};

效果类型参考

效果	语法	描述
opacity	opacity(50%)	透明度（0-100%）
grayscale	grayscale(100%)	移除颜色（0-100%）
blur	blur(5px)	高斯模糊
drop-shadow	drop-shadow(x, y, blur, color)	阴影效果
bloom	bloom(strength, radius, threshold)	发光效果
brightness	brightness(150%)	调整亮度
contrast	contrast(120%)	调整对比度
invert	invert(100%)	反转颜色
sepia	sepia(100%)	棕褐色调
saturate	saturate(200%)	色彩饱和度
hue-rotate	hue-rotate(180deg)	旋转色相

单项效果示例

不透明度

layer.featureEffect = {
  filter: { where: "type = 'primary'" },
  excludedEffect: "opacity(25%)",
};

灰度

layer.featureEffect = {
  filter: { where: "category = 'important'" },
  excludedEffect: "grayscale(100%)",
};

模糊

layer.featureEffect = {
  filter: { where: "highlighted = 1" },
  excludedEffect: "blur(5px)",
};

投影

layer.featureEffect = {
  filter: { where: "selected = 1" },
  includedEffect: "drop-shadow(3px, 3px, 4px, #000000)",
};

光晕（发光）

layer.featureEffect = {
  filter: { where: "active = 1" },
  includedEffect: "bloom(1.5, 0.5px, 0.2)",
};

亮度和对比度

layer.featureEffect = {
  filter: { where: "status = 'highlight'" },
  includedEffect: "brightness(150%) contrast(120%)",
  excludedEffect: "brightness(50%)",
};

组合多个效果

layer.featureEffect = {
  filter: { where: "status = 'active'" },
  includedEffect: "drop-shadow(2px, 2px, 3px) brightness(120%)",
  excludedEffect: "grayscale(100%) opacity(30%) blur(2px)",
};

过滤器类型

属性过滤器

layer.featureEffect = {
  filter: {
    where: "population > 50000 AND state = 'CA'",
  },
  excludedEffect: "grayscale(100%) opacity(30%)",
};

基于几何图形的过滤器

const layerView = await view.whenLayerView(layer);

layerView.featureEffect = {
  filter: {
    geometry: polygon,
    spatialRelationship: "intersects",
  },
  excludedEffect: "grayscale(100%) opacity(30%)",
};

基于距离的过滤器

layerView.featureEffect = {
  filter: {
    geometry: point,
    spatialRelationship: "intersects",
    distance: 1000,
    units: "meters",
  },
  excludedEffect: "opacity(20%)",
};

ObjectID 过滤器

layerView.featureEffect = {
  filter: {
    objectIds: [1, 5, 10, 42],
  },
  includedEffect: "drop-shadow(3px, 3px, 4px)",
  excludedEffect: "grayscale(100%) opacity(40%)",
};

基于时间的过滤器

layer.featureEffect = {
  filter: {
    timeExtent: {
      start: new Date("2020-01-01"),
      end: new Date("2020-12-31"),
    },
  },
  excludedEffect: "opacity(20%)",
};

空间关系

关系	描述
intersects	与几何图形相交的要素
contains	包含该几何图形的要素
within	位于该几何图形内的要素
crosses	与该几何图形交叉的要素
overlaps	与该几何图形重叠的要素
touches	与该几何图形接触的要素
disjoint	与该几何图形不相交的要素
envelope-intersects	包络线相交（速度更快）

聚焦区域（3D SceneView）

聚焦区域可在 3D SceneView 中突出显示特定多边形区域，同时调暗区域以外的所有内容。适用于在 3D 场景中强调关注区域。

创建聚焦区域

import FocusArea from "@arcgis/core/effects/FocusArea.js";
import Collection from "@arcgis/core/core/Collection.js";

const focusArea = new FocusArea({
  title: "Area of Interest",
  id: "focus-1",
  enabled: true,
  outline: { color: [255, 128, 128, 0.55] },
  geometries: new Collection([polygon]),
});

添加到 SceneView

// Add focus area to the view
view.focusAreas.areas.add(focusArea);

// Set visual style: "bright" or "dark"
view.focusAreas.style = "bright";

切换聚焦区域

// Disable without removing
focusArea.enabled = false;

// Re-enable with different style
focusArea.enabled = true;
view.focusAreas.style = "dark";

// Remove entirely
view.focusAreas.areas.remove(focusArea);

FocusArea 属性

属性	类型	描述
title	string	聚焦区域的标题
id	string	唯一标识符（省略时自动生成）
enabled	boolean	是否显示（默认值：true）
geometries	Collection<Polygon>	定义聚焦范围的多边形几何图形
outline	FocusAreaOutline	轮廓样式：{ color }

图层效果（非要素）

对整个图层（而非单个要素）应用类似 CSS 的效果。

// Apply effect to the whole layer
layer.effect = "bloom(1.5, 0.5px, 0.2)";

// Multiple effects
layer.effect = "drop-shadow(3px, 3px, 4px) brightness(120%)";

// Remove effect
layer.effect = null;

混合模式

混合模式用于控制图层与其下方图层的混合方式。

layer.blendMode = "multiply"; // Default is "normal"

混合模式类别

类别	模式
变暗	multiply、darken、color-burn
变亮	screen、lighten、color-dodge
对比	overlay、soft-light、hard-light
分量	hue、saturation、luminosity、color
合成	destination-in、destination-out、destination-over、source-in
反转	difference、exclusion、minus
其他	normal、average、vivid-light、reflect

常见混合模式组合

// Darken: show dark features on light basemap
layer.blendMode = "multiply";

// Lighten: show light features on dark basemap
layer.blendMode = "screen";

// Masking: clip layers using another layer shape
maskLayer.blendMode = "destination-in";

显示过滤器

显示过滤器会完全隐藏要素（由于不会渲染要素，因此性能优于效果）。

简单显示过滤器

layer.displayFilterInfo = {
  where: "population > 10000",
};

比例尺依赖型显示过滤器

const layer = new FeatureLayer({
  url: "https://services.arcgis.com/.../FeatureServer/0",
  displayFilterInfo: {
    mode: "scale",
    filters: [
      {
        title: "Major rivers",
        minScale: 0,
        maxScale: 36_978_595,
        where: "streamOrder >= 8",
      },
      {
        title: "Large rivers",
        minScale: 36_978_595,
        maxScale: 18_489_297,
        where: "streamOrder >= 7",
      },
      {
        title: "All rivers",
        minScale: 4_622_324,
        maxScale: 0,
      },
    ],
  },
});

检查活动显示过滤器

const layerView = await view.whenLayerView(layer);
const activeFilter = layerView.effectiveDisplayFilter?.title;

将显示过滤器与要素效果结合使用

// Display filter hides deleted features entirely (performance)
layer.displayFilterInfo = {
  where: "status != 'deleted'",
};

// Feature effect styles remaining features
layer.featureEffect = {
  filter: { where: "status = 'active'" },
  excludedEffect: "opacity(50%)",
};

交互式要素效果

点击时应用效果

view.on("click", async (event) => {
  const response = await view.hitTest(event);
  const graphic = response.results[0]?.graphic;

  if (graphic) {
    const oid = graphic.attributes.OBJECTID;
    layerView.featureEffect = {
      filter: {
        objectIds: [oid],
      },
      includedEffect: "drop-shadow(3px, 3px, 4px)",
      excludedEffect: "grayscale(100%) opacity(40%)",
    };
  }
});

使用滑块调整效果

slider.on("thumb-drag", (event) => {
  const value = event.value;
  layer.featureEffect = {
    filter: { where: `value > ${value}` },
    excludedEffect: `opacity(${100 - value}%)`,
  };
});

清除要素效果

layer.featureEffect = null;
// or
layerView.featureEffect = null;

使用直方图的效果

import histogram from "@arcgis/core/smartMapping/statistics/histogram.js";

const histogramResult = await histogram({
  layer: layer,
  field: "population",
  numBins: 30,
});

const slider = new HistogramRangeSlider({
  bins: histogramResult.bins,
  min: histogramResult.minValue,
  max: histogramResult.maxValue,
  values: [histogramResult.minValue, histogramResult.maxValue],
});

slider.on("thumb-drag", () => {
  const [min, max] = slider.values;
  layerView.featureEffect = {
    filter: {
      where: `population >= ${min} AND population <= ${max}`,
    },
    excludedEffect: "grayscale(100%) opacity(30%)",
  };
});

参考示例

• featureeffect-geometry - 基于几何的要素效果，包含空间关系
• featureeffect-drop-shadow - 比例尺依赖型投影效果
• featureeffect-layers-histogram - 带直方图控件的要素效果
• featureeffect-multiple-effects - 组合多种视觉效果
• effect-blur-shadow - 图层的模糊和阴影效果
• intro-effect-layer - 图层效果简介
• display-filter - 比例尺依赖型显示过滤
• focus-area - 3D SceneView 中的焦点区域
• highlight-features-by-geometry - 使用几何图形高亮显示要素
• blendmode-darkening - 混合模式变暗效果
• blendmode-grouplayer - 组图层上的混合模式
• blendmode-multiple-layers - 跨多个图层使用混合模式

常见问题

1. 图层与 LayerView：对 layer 应用要素效果会影响所有视图；对 layerView 应用则只影响该特定视图。

   // Affects all views
   layer.featureEffect = { ... };
   
   // Affects only this view
   const layerView = await view.whenLayerView(layer);
   layerView.featureEffect = { ... };
   

2. 性能：对大量要素应用复杂效果（模糊、泛光）会影响渲染性能。请先使用显示过滤器减少要素数量。

3. 效果顺序：组合多个效果时，会按照字符串中列出的顺序应用。

4. 显示过滤器与要素效果：使用 displayFilterInfo 完全隐藏要素（性能更佳）。使用 featureEffect 以不同方式设置包含集和排除集的样式。

5. 时间范围过滤器：基于时间的过滤器要求图层已配置时间信息。若未配置，过滤器会被静默忽略。

6. 仅 LayerView 支持空间过滤器：基于几何图形的过滤器（geometry、distance）仅适用于 layerView.featureEffect，不适用于 layer.featureEffect。

7. 泛光参数：bloom(strength, radius, threshold) —— threshold（0-1）控制开始发光的亮度级别。值越高，泛光越弱。

8. 效果字符串语法：效果之间以空格分隔，而非逗号。语法错误会被静默忽略。

   // Anti-pattern: comma-separated effects
   excludedEffect: "grayscale(100%), opacity(30%)";
   
   // Correct: space-separated effects
   excludedEffect: "grayscale(100%) opacity(30%)";
   

9. 焦点区域需要 Polygon 几何图形：FocusArea.geometries 仅支持 Polygon 几何图形，不支持点和折线。

10. 比例尺依赖型效果：使用比例尺依赖型效果的数组格式时，至少提供两个停止点，以便在不同比例尺之间平滑插值。

相关技能

• arcgis-visualization - 渲染器和符号
• arcgis-smart-mapping - 使用直方图自动生成渲染器
• arcgis-interaction - 用户交互和命中测试
• arcgis-layers - 图层类型和配置
• arcgis-core-maps - 地图和视图设置