arcgis-arcade

ArcGIS Arcade 表达式

在编写用于弹出窗口、渲染器、标注和计算的 Arcade 表达式时，请使用此技能。

导入模式

直接 ESM 导入

import * as arcade from "@arcgis/core/arcade.js";

动态导入（CDN）

const arcade = await $arcgis.import("@arcgis/core/arcade.js");

Arcade 基础知识

Arcade 是 ArcGIS 的表达式语言，用于：

• 动态弹出窗口内容
• 数据驱动渲染
• 自定义标注
• 字段计算
• 表单验证

基本语法

// Variables
var population = $feature.population;
var area = $feature.area_sqkm;

// Calculations
var density = population / area;

// Return result
return Round(density, 2);

在 PopupTemplates 中使用 Arcade

表达式信息

const popupTemplate = {
  title: "{name}",
  expressionInfos: [
    {
      name: "population-density",
      title: "Population Density",
      expression: "Round($feature.population / $feature.area_sqkm, 2)",
    },
    {
      name: "formatted-date",
      title: "Formatted Date",
      expression: "Text($feature.created_date, 'MMMM D, YYYY')",
    },
  ],
  content: "Density: {expression/population-density} people/km²",
};

复杂表达式

const popupTemplate = {
  title: "{name}",
  expressionInfos: [
    {
      name: "predominant-category",
      title: "Predominant Category",
      expression: `
      var fields = [
        { value: $feature.category_a, alias: "Category A" },
        { value: $feature.category_b, alias: "Category B" },
        { value: $feature.category_c, alias: "Category C" }
      ];

      var maxValue = -Infinity;
      var maxCategory = "";

      for (var i in fields) {
        if (fields[i].value > maxValue) {
          maxValue = fields[i].value;
          maxCategory = fields[i].alias;
        }
      }

      return maxCategory;
    `,
    },
  ],
  content: [
    {
      type: "text",
      text: "The predominant category is: {expression/predominant-category}",
    },
    {
      type: "fields",
      fieldInfos: [
        {
          fieldName: "expression/predominant-category",
        },
      ],
    },
  ],
};

在渲染器中使用 Arcade

值表达式

const renderer = {
  type: "unique-value",
  valueExpression: `
    var labor = $feature.labor_force;
    var notLabor = $feature.not_in_labor_force;

    if (labor > notLabor) {
      return "In labor force";
    } else {
      return "Not in labor force";
    }
  `,
  valueExpressionTitle: "Labor Force Status",
  uniqueValueInfos: [
    {
      value: "In labor force",
      symbol: { type: "simple-fill", color: "blue" },
    },
    {
      value: "Not in labor force",
      symbol: { type: "simple-fill", color: "orange" },
    },
  ],
};

视觉变量表达式

const renderer = {
  type: "simple",
  symbol: { type: "simple-marker", color: "red" },
  visualVariables: [
    {
      type: "size",
      valueExpression: "Sqrt($feature.population) * 0.1",
      valueExpressionTitle: "Population (scaled)",
      stops: [
        { value: 10, size: 4 },
        { value: 100, size: 40 },
      ],
    },
    {
      type: "opacity",
      valueExpression: "($feature.value / $feature.max_value) * 100",
      valueExpressionTitle: "Percentage of max",
      stops: [
        { value: 20, opacity: 0.2 },
        { value: 80, opacity: 1 },
      ],
    },
  ],
};

在标注中使用 Arcade

layer.labelingInfo = [
  {
    symbol: {
      type: "text",
      color: "black",
      font: { size: 10 },
    },
    labelExpressionInfo: {
      expression: `
      var name = $feature.name;
      var pop = $feature.population;

      if (pop > 1000000) {
        return name + " (" + Round(pop/1000000, 1) + "M)";
      } else if (pop > 1000) {
        return name + " (" + Round(pop/1000, 0) + "K)";
      }
      return name;
    `,
    },
    where: "population > 50000",
  },
];

常用 Arcade 函数

数学函数

Round(3.14159, 2)        // 3.14
Floor(3.9)               // 3
Ceil(3.1)                // 4
Abs(-5)                  // 5
Sqrt(16)                 // 4
Pow(2, 3)                // 8
Min(1, 2, 3)             // 1
Max(1, 2, 3)             // 3
Sum([1, 2, 3])           // 6
Mean([1, 2, 3])          // 2

文本函数

Upper("hello")           // "HELLO"
Lower("HELLO")           // "hello"
Trim("  hello  ")        // "hello"
Left("hello", 2)         // "he"
Right("hello", 2)        // "lo"
Mid("hello", 2, 2)       // "ll"
Find("l", "hello")       // 2
Replace("hello", "l", "L") // "heLLo"
Split("a,b,c", ",")      // ["a", "b", "c"]
Concatenate(["a", "b"])  // "ab"

日期函数

Now()                                    // Current date/time
Today()                                  // Current date
Year($feature.date_field)               // Extract year
Month($feature.date_field)              // Extract month (1-12)
Day($feature.date_field)                // Extract day
DateDiff(Now(), $feature.date, "days")  // Days between dates
Text($feature.date, "MMMM D, YYYY")     // Format date

几何函数

Area($feature, "square-kilometers")
Length($feature, "kilometers")
Centroid($feature)
Buffer($feature, 100, "meters")
Intersects($feature, $otherFeature)
Contains($feature, $point)

条件函数

// IIf (inline if)
IIf($feature.value > 100, "High", "Low")

// When (multiple conditions)
When(
  $feature.type == "A", "Type A",
  $feature.type == "B", "Type B",
  "Other"
)

// Decode (value matching)
Decode($feature.code,
  1, "One",
  2, "Two",
  3, "Three",
  "Unknown"
)

数组函数

var arr = [1, 2, 3, 4, 5];

Count(arr)               // 5
First(arr)               // 1
Last(arr)                // 5
IndexOf(arr, 3)          // 2
Includes(arr, 3)         // true
Push(arr, 6)             // [1, 2, 3, 4, 5, 6]
Reverse(arr)             // [5, 4, 3, 2, 1]
Sort(arr)                // [1, 2, 3, 4, 5]
Slice(arr, 1, 3)         // [2, 3]

要素访问

// Current feature
$feature.fieldName

// All features in layer (for aggregation)
var allFeatures = FeatureSet($layer);
var filtered = Filter(allFeatures, "type = 'A'");
var total = Sum(filtered, "value");

// Related records
var related = FeatureSetByRelationshipName($feature, "relationshipName");

// Global variables
$map                     // Reference to map
$view                    // Reference to view
$datastore               // Reference to data store

以编程方式执行 Arcade

import * as arcade from "@arcgis/core/arcade.js";

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

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

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

console.log("Result:", result);

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

在 HTML 中使用 Arcade（脚本标签）

<script type="text/plain" id="my-expression">
  var total = $feature.value_a + $feature.value_b;
  var percentage = Round((total / $feature.max_value) * 100, 1);
  return percentage + "%";
</script>

<script type="module">
  const expression = document.getElementById("my-expression").text;

  const popupTemplate = {
    expressionInfos: [
      {
        name: "my-calc",
        expression: expression,
      },
    ],
    content: "Value: {expression/my-calc}",
  };
</script>

Arcade 表达式配置文件

不同的 Arcade 配置文件会公开不同的全局变量和函数：

配置文件	全局变量	用途
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	聚类弹出窗口别名

参考示例

• popuptemplate-arcade - PopupTemplates 中的 Arcade 表达式
• popuptemplate-arcade-expression-content - 弹出窗口中的 Arcade 表达式内容
• visualization-arcade - Arcade 驱动的可视化
• arcade-execute-chart - 使用图表执行 Arcade

常见问题

1. 空值：执行算术运算前，请务必使用 IsEmpty($feature.field) 检查空值。除以空值或将空值与其他值相加都会产生空值。

   // Anti-pattern: no null check
   return $feature.population / $feature.area;
   

   // Correct: check for null
   if (IsEmpty($feature.area) || $feature.area == 0) {
     return "N/A";
   }
   return Round($feature.population / $feature.area, 2);
   

2. 类型强制转换：混合使用不同类型时，请使用 Number() 或 Text() 进行显式转换。

3. 区分大小写：Arcade 函数名称不区分大小写，但字段名称必须与源数据完全一致。

4. 性能：渲染器和标注中的复杂表达式会针对每个要素、每一帧进行计算。处理大型数据集时，请保持表达式简洁。

5. 调试：使用 Console() 函数调试表达式。输出会显示在浏览器的开发者控制台中。

6. FeatureSet 查询：FeatureSet() 和 Filter() 会执行服务器端查询。如果图层包含许多要素，在弹出窗口表达式中使用这些函数可能会较慢。

相关技能

• 有关弹出窗口模板配置，请参阅 arcgis-popup-templates
• 有关渲染器和符号配置，请参阅 arcgis-visualization
• 有关数据驱动可视化，请参阅 arcgis-smart-mapping
• 有关 <arcgis-arcade-editor> 组件，请参阅 arcgis-coding-components