Back to Details

arcgis-arcade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ArcGIS Arcade Expressions

ArcGIS Arcade 表达式

Use this skill for writing Arcade expressions for popups, renderers, labels, and calculations.
本技能适用于编写用于弹窗、渲染器、标签和计算场景的Arcade表达式。

Arcade Basics

Arcade 基础

Arcade is an expression language for ArcGIS. It's used for:
  • Dynamic popup content
  • Data-driven rendering
  • Custom labels
  • Field calculations
  • Form validation
Arcade是ArcGIS的一种表达式语言，可用于：
  • 动态弹窗内容
  • 数据驱动渲染
  • 自定义标签
  • 字段计算
  • 表单验证

Basic Syntax

基础语法

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

// Calculations
var density = population / area;

// Return result
return Round(density, 2);
arcade
// Variables
var population = $feature.population;
var area = $feature.area_sqkm;

// Calculations
var density = population / area;

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

Arcade in PopupTemplates

在PopupTemplates中使用Arcade

Expression Infos

表达式信息

javascript
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²"
};
javascript
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²"
};

Complex Expressions

复杂表达式

javascript
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"
      }]
    }
  ]
};
javascript
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 in Renderers

在渲染器中使用Arcade

Value Expression

值表达式

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

Visual Variable Expression

视觉变量表达式

javascript
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 }
    ]
  }]
};
javascript
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 in Labels

在标签中使用Arcade

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

Common Arcade Functions

常用Arcade函数

Math Functions

数学函数

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

Text Functions

文本函数

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

Date Functions

日期函数

arcade
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
arcade
Now()                                    // 当前日期/时间
Today()                                  // 当前日期
Year($feature.date_field)               // 提取年份
Month($feature.date_field)              // 提取月份（1-12）
Day($feature.date_field)                // 提取日期
DateDiff(Now(), $feature.date, "days")  // 两个日期的天数差
Text($feature.date, "MMMM D, YYYY")     // 日期格式化

Geometry Functions

几何函数

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

Conditional Functions

条件函数

arcade
// 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"
)
arcade
// IIf（内联条件）
IIf($feature.value > 100, "High", "Low")

// When（多条件判断）
When(
  $feature.type == "A", "Type A",
  $feature.type == "B", "Type B",
  "Other"
)

// Decode（值匹配）
Decode($feature.code,
  1, "One",
  2, "Two",
  3, "Three",
  "Unknown"
)

Array Functions

数组函数

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

Feature Access

要素访问

arcade
// 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
// 当前要素
$feature.fieldName

// 图层中所有要素（用于聚合计算）
var allFeatures = FeatureSet($layer);
var filtered = Filter(allFeatures, "type = 'A'");
var total = Sum(filtered, "value");

// 关联记录
var related = FeatureSetByRelationshipName($feature, "relationshipName");

// 全局变量
$map                     // 地图引用
$view                    // 视图引用
$datastore               // 数据存储引用

Execute Arcade Programmatically

以编程方式执行Arcade

javascript
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);
javascript
import * as arcade from "@arcgis/core/arcade.js";

// 创建配置文件
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
});

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

Arcade in HTML (Script Tags)

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

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

TypeScript Usage

TypeScript 用法

Arcade expression configurations use autocasting. For TypeScript safety, use 
as const
:
typescript
// Use 'as const' for expression-based visualizations
layer.renderer = {
  type: "simple",
  symbol: { type: "simple-marker" },
  visualVariables: [{
    type: "size",
    valueExpression: "$feature.population / $feature.area",
    stops: [
      { value: 50, size: 4 },
      { value: 500, size: 20 }
    ]
  }]
} as const;
Tip: See arcgis-core-maps skill for detailed guidance on autocasting vs explicit classes.
Arcade表达式配置支持自动类型转换。为了TypeScript类型安全，可使用
as const
：
typescript
// 对基于表达式的可视化使用'as const'
layer.renderer = {
  type: "simple",
  symbol: { type: "simple-marker" },
  visualVariables: [{
    type: "size",
    valueExpression: "$feature.population / $feature.area",
    stops: [
      { value: 50, size: 4 },
      { value: 500, size: 20 }
    ]
  }]
} as const;
提示： 有关自动类型转换与显式类的详细说明，请查看arcgis-core-maps 技能。

Reference Samples

参考示例

  • popuptemplate-arcade
    - Arcade expressions in PopupTemplates
  • popuptemplate-arcade-expression-content
    - Arcade expression content in popups
  • popuptemplate-arcade
    - PopupTemplates中的Arcade表达式
  • popuptemplate-arcade-expression-content
    - 弹窗中的Arcade表达式内容

Common Pitfalls

常见陷阱

  1. Null values: Check for nulls with 
    IsEmpty($feature.field)
  2. Type coercion: Use 
    Number()
    or 
    Text()
    for explicit conversion
  3. Case sensitivity: Arcade is case-insensitive for functions but field names match exactly
  4. Performance: Complex expressions in renderers can slow performance
  5. Debugging: Use 
    Console()
    function to debug expressions
  1. 空值问题：使用
    IsEmpty($feature.field)
    检查空值
  2. 类型转换：使用
    Number()
    或
    Text()
    进行显式类型转换
  3. 大小写敏感性：Arcade函数不区分大小写，但字段名需完全匹配
  4. 性能问题：渲染器中的复杂表达式可能会降低性能
  5. 调试：使用
    Console()
    函数调试表达式