arcgis-arcade

用途

本技能用于编写 Arcade 表达式，服务于 ArcGIS Maps SDK for JavaScript 中的弹出窗口（popups）、渲染器（renderers）、标注（labels）和字段计算（calculations）。适用于数据驱动样式、自定义标注等场景。

主要能力

Arcade 是 ArcGIS 的表达式语言，用于：动态弹出窗口内容、数据驱动渲染、自定义标注、字段计算、表单验证。

技能覆盖以下内容板块：

导入模式：直接 ESM 导入（import * as arcade from "@arcgis/core/arcade.js";）与 CDN 动态导入（const arcade = await $arcgis.import("@arcgis/core/arcade.js");）。
基本语法：变量声明、计算、返回值。
在 PopupTemplate 中使用（expressionInfos、简单与复杂表达式示例）。
在渲染器中使用（值表达式 valueExpression、视觉变量 visualVariables）。
在标注中使用（labelingInfo、labelExpressionInfo、where 条件）。
常用函数：数学函数、文本函数、日期函数、几何函数、条件函数（IIf、When、Decode）、数组函数。
要素访问：$feature、FeatureSet、Filter、Sum、按关系名获取相关记录、全局变量（$map、$view、$datastore）。
以编程方式执行 Arcade（createArcadeExecutor、profile 定义、executeAsync）。
在 HTML 中以 script 标签存放表达式文本。
Arcade 表达式配置文件（profile）及其暴露的全局变量与用途。
参考示例（popuptemplate-arcade、popuptemplate-arcade-expression-content、visualization-arcade、arcade-execute-chart）。
常见陷阱与相关技能。

使用方式

按场景选择对应 profile 编写表达式，将表达式放入相应的配置对象中，例如 PopupTemplate 的 expressionInfos、渲染器的 valueExpression 或 visualVariables、图层的 labelingInfo。表达式语法以 $feature 访问当前要素字段，通过 return 返回结果。也可导入 @arcgis/core/arcade.js，使用 createArcadeExecutor 编译表达式后调用 executeAsync 执行。

Arcade 表达式配置文件（profile）与全局变量对应关系如下：

Profile	全局变量	用途
popup	$feature, $layer, $map, $datastore	弹出窗口内容
visualization	$feature, $view	渲染器、视觉变量
labeling	$feature, $view	标注表达式
field-calculate	$feature, $layer	字段计算
form-calculation	$feature, $layer, $originalFeature	表单计算表达式
constraint	$feature, $layer, $originalFeature	表单验证
alias	$feature, $layer	聚合弹出窗口别名

常用函数示例（节选）：Round、Floor、Ceil、Abs、Sqrt、Pow、Min、Max、Sum、Mean；Upper、Lower、Trim、Left、Right、Mid、Find、Replace、Split、Concatenate；Now、Today、Year、Month、Day、DateDiff、Text；Area、Length、Centroid、Buffer、Intersects、Contains；IIf、When、Decode；Count、First、Last、IndexOf、Includes、Push、Reverse、Sort、Slice。

以编程方式执行时的 profile 定义示例：

const profile = {
  variables: [
    {
      name: "$feature",
      type: "feature",
    },
  ],
};

const executor = await arcade.createArcadeExecutor(
  "Round($feature.value * 100, 2)",
  profile,
);

const result = await executor.executeAsync({
  $feature: graphic,
});

注意：v5.0 中 ExecuteContext.lruCache 已弃用，改用 ExecuteContext.cache。

适用场景

需要在弹出窗口中呈现计算值或格式化文本；需要按属性值进行数据驱动着色、大小或不透明度映射；需要根据人口等字段生成简化或格式化标注；需要进行字段计算与表单计算/验证；需要在图表中执行 Arcade 表达式。

限制与注意事项

空值处理：算术运算前应使用 IsEmpty($feature.field) 检查空值，与 null 相除或相加结果为 null。
类型转换：混合类型时使用 Number() 或 Text() 显式转换。
大小写：Arcade 函数名大小写不敏感，但字段名必须与源数据完全一致。
性能：渲染器和标注中的复杂表达式会按要素、按帧计算，大数据集下应保持简单。
调试：可使用 Console() 函数，输出显示在浏览器开发者控制台。
FeatureSet 查询：FeatureSet() 与 Filter() 会执行服务器端查询，图层要素较多时在弹出窗口表达式中可能变慢。

相关技能：arcgis-popup-templates（弹出窗口模板配置）、arcgis-visualization（渲染器与符号配置）、arcgis-smart-mapping（数据驱动可视化）、arcgis-coding-components（<arcgis-arcade-editor> 组件）。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项