Arcade入门：Text与逻辑函数实战，解决GIS地图标注与条件显示

1. 项目概述：为什么从Arcade的Text和逻辑函数开始？

如果你正在接触ArcGIS平台，尤其是ArcGIS Pro、ArcGIS Online或者ArcGIS Enterprise中的地图样式、标注、弹出窗口或者属性规则，那你大概率已经听说过Arcade。它不是街机游戏，而是Esri专门为地理空间数据处理设计的一种轻量级脚本语言。很多朋友刚接触时，会觉得它有点像JavaScript，但又有很多独特的函数和语法，专门用来处理地图上的要素（Feature）和它们的属性。

那么，为什么这个系列的第一篇要从Text函数和逻辑函数讲起呢？从我十多年的GIS项目经验来看，这恰恰是新手最容易上手、也最能立刻看到效果的两个领域。几乎你做的第一件事，就是想把数据“说人话”——把一堆数字代码转换成可读的文本显示在地图上，比如把“1”显示为“住宅区”，或者把“20240101”显示为“2024年1月1日”。这就是Text函数的用武之地。而当你需要根据条件来决定显示什么、怎么显示，或者计算什么值时，逻辑函数就登场了。比如，你想在地图上高亮显示所有面积大于1000平方米且状态为“在建”的地块，这个“且”和“大于”的判断，就是逻辑函数的范畴。

最近在社区里看到不少朋友遇到一个报错：“逻辑 and (&&)和 or (||)运算符的操作数必须可转换为标量逻辑值。请使用 any 或 all 函数将操作数简化为标量逻辑值。” 这个错误信息听起来有点拗口，但其实它直指Arcade逻辑运算的一个核心特点，也是新手最容易踩的坑。我们会在后面的逻辑函数部分，结合这个热词，把它彻底讲透。

所以，这篇内容的目标很明确：让你能独立使用Arcade的Text函数和逻辑函数，解决地图表达中最常见的“文本格式化”和“条件判断”问题，并避开那些典型的错误。无论你是GIS分析师、地图制图师，还是开发者，这些基础都是构建更复杂表达式的基石。

2. Arcade表达式基础与环境准备

在深入函数之前，我们得先搞清楚Arcade表达式写在哪里、怎么运行。这就像你要做饭，得先找到厨房和灶具。

2.1 Arcade的应用场景：它在哪里生效？

Arcade不是一个独立的编程环境，它的脚本（我们称之为“表达式”）是嵌入在ArcGIS平台的各个功能模块中执行的。主要应用场景有四个：

1. 标注（Labeling）：这是最常用的场景。你可以写一个Arcade表达式，动态决定每个要素上显示什么文本。比如，一个地块的标注可能是“[地块编号] - [面积]平方米”。
2. 弹出窗口（Pop-ups）：当用户点击地图上的要素时，弹出的信息窗口内容可以用Arcade来丰富和格式化，比直接显示原始字段美观得多。
3. 可视化（Symbology）：你可以用Arcade表达式来驱动地图的显示样式。例如，用一个返回数字的表达式来定义颜色渐变，或者用一个返回文本的表达式来匹配不同的符号。
4. 属性规则（Attribute Rules）：在数据编辑时进行自动计算或约束验证。比如，自动计算多边形要素的周长，或者在用户输入非法值时弹出警告。

对于初学者，我强烈建议从标注开始练习。因为标注的反馈是最直观、最即时的——写完表达式，地图上立刻就能看到变化，非常有利于学习和调试。

2.2 编写与调试你的第一个表达式

我们以在ArcGIS Pro中为图层设置标注为例。

1. 打开标注设置：在内容列表（Contents）中右键点击你的图层，选择“标注（Labeling）”，然后点击“标注（Label）”按钮下拉菜单中的“表达式（Expression）...”。
2. 进入表达式构建器：这会打开表达式构建器窗口。窗口上方是表达式编辑区，下方是预览窗口，会显示当前选中要素的表达式计算结果。
3. 理解上下文：在编辑区的右侧，你会看到“字段（Fields）”和“函数（Functions）”两个选项卡。“字段”里列出了当前图层的所有属性字段，你可以直接双击将其插入表达式。“函数”则按类别列出了所有可用的Arcade函数，包括我们今天要讲的Text和逻辑函数。

这里有个非常重要的实操心得：一定要善用“预览（Preview）”功能。在编辑表达式时，下方预览区会实时（或在你点击“验证”后）显示结果。你可以通过点击地图选择不同的要素，来查看你的表达式在不同要素上的计算结果是否符合预期。这是调试Arcade表达式最有效的手段，没有之一。

注意：Arcade表达式是大小写敏感的。$feature.OBJECTID和$feature.objectid指向的是不同的东西（通常字段名是大写的），写错了就会报“未找到变量”的错误。刚开始时，最稳妥的方法是从右侧的字段列表里双击插入，而不是自己手动输入。

3. Text函数详解：让数据“说人话”

Text函数，顾名思义，就是处理文本字符串的函数。在地图表达中，我们很少会直接把原始的、冰冷的字段值扔给用户看。Text函数能帮你进行格式化、拼接、提取和转换。

3.1 字符串拼接与格式化：Concatenate与Text函数

这是最基础也是最常用的操作：把多个字段或文本组合成一句通顺的话。

• Concatenate(value1, value2, ...): 将多个值连接成一个字符串。它接受数字、文本、日期等各种类型，在连接时会自动将它们转换为文本。

  // 示例：将姓名和年龄拼接 Concatenate($feature.NAME, " 的年龄是 ", $feature.AGE, " 岁。") // 如果NAME字段值为“张三”，AGE为30，则结果为：“张三 的年龄是 30 岁。”

  不过，在实际使用中，我更喜欢用更简洁的加号（+）来进行拼接，这在Arcade里是允许的，而且更符合编程习惯：

  $feature.NAME + " 的年龄是 " + $feature.AGE + " 岁。"

  效果完全一样，但写起来更顺手。

• Text(value, format): 这是一个功能强大的格式化函数，尤其适用于数字和日期。

  • 格式化数字：比如控制小数位数、添加千位分隔符、显示为百分比。

    // 假设 $feature.AREA 字段值为 1234567.8912 Text($feature.AREA, “#,###.##”) // 结果：“1,234,567.89” Text($feature.AREA, “#.##%”) // 先将数字乘以100，然后加百分号，结果：“123456789.12%”（通常需要先除以100） Text($feature.AREA / 10000, “#.## 公顷”) // 结果：“123.46 公顷”

    #代表数字占位符，,是千位分隔符，.是小数点。“#,###.##”这个格式符的意思是：整数部分使用千位分隔符，保留两位小数。
  • 格式化日期：这是Text函数的杀手级应用。GIS数据里的日期字段常常是“20240101”这样的数字或者时间戳，直接显示非常不友好。

    // 假设 $feature.SURVEY_DATE 是一个日期型字段 Text($feature.SURVEY_DATE, “YYYY年MM月DD日”) // 结果：“2024年01月15日” Text($feature.SURVEY_DATE, “MMM D, YYYY”) // 结果：“Jan 15, 2024”（英文月份缩写）

    常用的日期格式符：YYYY-四位年份，MM-两位月份，DD-两位日期，HH-24小时制小时，mm-分钟。

避坑技巧：当你用Text函数格式化一个可能为null（空值）的字段时，整个表达式可能会返回null，导致标注不显示。一个稳健的做法是先用IsEmpty()函数判断：

var myDate = $feature.SURVEY_DATE; if (IsEmpty(myDate)) { return “日期未记录”; } else { return Text(myDate, “YYYY-MM-DD”); }

3.2 字符串操作：截取、查找与替换

有时你需要加工文本，比如只显示地址的前一部分，或者替换掉某些字符。

• Left(text, count)/Right(text, count)/Mid(text, start, count): 截取子字符串。
  • Left(“Arcade函数”, 3)返回 “Arc”。
  • Mid(“北京市海淀区中关村”, 3, 2)返回 “海淀”。（这里注意，Arcade中字符串的起始位置是0，所以“海”是第3个字符，取2个字符）。
• Find(text, search_text): 查找子串的位置，返回索引（从0开始），如果没找到则返回-1。

  Find(“北京市海淀区”, “海淀”) // 返回 3 Find(“北京市海淀区”, “上海”) // 返回 -1

• Replace(text, old_text, new_text): 替换文本。

  Replace(“面积：100㎡”, “㎡”, “平方米”) // 返回 “面积：100平方米”

• Lower(text)/Upper(text): 转换为小写/大写。这在做不区分大小写的比较时很有用。

  Lower($feature.TYPE) == “residential” // 无论TYPE字段是“Residential”还是“RESIDENTIAL”，都会转为小写后比较。

一个综合示例：我们有一个“地址”字段，格式是“省-市-区-详细地址”，我们只想显示“市-区”部分。

var fullAddress = $feature.ADDRESS; // 假设值为 “广东省-深圳市-南山区-科技园科苑路” var firstDash = Find(fullAddress, “-”); // 找到第一个“-”的位置，是2 var secondDash = Find(fullAddress, “-”, firstDash + 1); // 从第一个“-”之后开始找第二个“-”，是5 var thirdDash = Find(fullAddress, “-”, secondDash + 1); // 找第三个“-”，是8 if (firstDash >=0 && secondDash > firstDash) { // 截取第一个“-”和第三个“-”之间的部分（不包含“-”本身） return Mid(fullAddress, firstDash + 1, thirdDash - firstDash - 1); } else { return fullAddress; // 如果格式不对，返回原地址 } // 返回结果：“深圳市-南山区”

这个例子结合了Find和Mid函数，并考虑了边界情况。在实际工作中，数据往往不那么规整，所以增加if判断是个好习惯。

4. 逻辑函数与条件判断：让地图“智能”起来

逻辑函数是表达式的“大脑”，它让地图能够根据数据的不同情况做出不同的响应。核心就是if-else语句和逻辑运算符。

4.1 逻辑运算符：&&,||,!与常见陷阱

这三个运算符和大多数编程语言一样：

• &&(逻辑与)：两边条件都为真时，结果才为真。
• ||(逻辑或)：两边条件有一个为真时，结果就为真。
• !(逻辑非)：对条件取反。

看起来很简单，但陷阱就藏在细节里。让我们回到开篇提到的那个热词错误：

“逻辑 and (&&)和 or (||)运算符的操作数必须可转换为标量逻辑值。请使用 any 或 all 函数将操作数简化为标量逻辑值。”

这个错误究竟是什么意思？在Arcade中，当你对数组（Array）或集合进行逻辑比较时，不能直接使用&&或||。比如，你有一个字段Categories，它的值可能是一个数组[“A”, “B”, “C”]。你想判断这个数组里是否包含“A”，你可能会错误地写成：

// 错误写法！这将引发上述错误。 $feature.Categories == “A” && $feature.Status == “Active”

这里的问题在于，$feature.Categories == “A”这个比较，如果Categories是数组，它返回的不是一个简单的true或false，而可能是一个布尔值数组[true, false, false]。&&运算符不知道如何处理这个数组。

正确的解决方案：使用Any或All函数。

• Any(iterable, value)：检查数组（或字典等可迭代对象）中是否至少有一个元素满足条件（等于某个值，或符合某个判断）。返回true或false。
• All(iterable, value)：检查数组（或字典等可迭代对象）中是否所有元素都满足条件。返回true或false。

所以，上面的例子应该改写为：

// 正确写法：判断数组Categories中是否包含“A” Any($feature.Categories, “A”) && $feature.Status == “Active”

Any($feature.Categories, “A”)会遍历数组，只要发现有一个元素等于“A”，就立即返回true；否则返回false。这样，它就变成了一个&&可以处理的“标量逻辑值”。

另一个常见场景：判断数值是否在某个范围内。这需要组合使用&&。

// 判断面积在100到500之间（包含边界） var area = $feature.AREA; if (area >= 100 && area <= 500) { return “中等面积”; } // 判断状态为“已完成”或“已审核” if ($feature.Status == “Completed” || $feature.Status == “Reviewed”) { return “可归档”; }

4.2 条件判断函数：IIf,Decode,When

除了标准的if-else语句，Arcade提供了几个更简洁的内置函数来处理条件逻辑。

• IIf(condition, true_value, false_value): 如果条件为真，返回第二个参数；否则返回第三个参数。它是“Inline If”的缩写，非常适合简单的二选一。

  // 用IIf替代if-else var label = IIf($feature.POPULATION > 1000000, “大城市”, “一般城市”); // 等价于： var label; if ($feature.POPULATION > 1000000) { label = “大城市”; } else { label = “一般城市”; }

• Decode(value, case1, result1, case2, result2, ..., default_result): 类似于编程中的switch-case语句，根据一个值匹配多种情况。它比一连串的else if更清晰。

  // 根据用地类型代码返回中文名称 Decode($feature.LANDUSE_CODE, “R”, “居住用地”, “C”, “商业用地”, “M”, “工业用地”, “G”, “绿地与广场用地”, “未知用地类型” // 默认值 )

• When(expr1, result1, expr2, result2, ..., default_result): 这是功能最强大的条件函数。它依次判断多个表达式（expr1,expr2...），返回第一个为真的表达式所对应的结果。它允许每个条件都是独立的逻辑表达式，而Decode只是比较值是否相等。

  // 根据人口和面积综合判断城市等级 When( $feature.POPULATION > 5000000 && $feature.AREA > 1000, “特大城市”, $feature.POPULATION > 1000000, “大城市”, $feature.POPULATION > 500000, “中等城市”, “小城市” // 默认值 )

  When函数会按顺序判断：先看是否满足“人口>500万且面积>1000”，不满足再看是否“人口>100万”，以此类推。这里有个关键点：条件的顺序很重要！如果把“人口>100万”放在第一行，那么所有人口超过100万的要素（包括那些超过500万的）都会被匹配为“大城市”，后面的条件就不再判断了。

选择建议：对于简单的真假判断，用IIf；对于基于一个值的多路精确匹配，用Decode；对于需要复杂逻辑判断的多分支情况，用When。When是最通用、最强大的。

5. 实战演练：构建一个完整的智能标注表达式

现在，我们把Text函数和逻辑函数组合起来，解决一个真实场景的问题。

场景：我们有一个“建设项目”图层，包含以下字段：

• PROJ_NAME(文本)：项目名称
• STATUS(文本)：状态，值可能是 “Planned”（计划中）、“InProgress”（进行中）、“Completed”（已完成）、“OnHold”（已暂停）
• BUDGET(数字)：预算（万元）
• START_DATE(日期)：开始日期
• AREA(数字)：占地面积（平方米）

需求：我们需要一个标注，能直观反映项目状态和关键信息。具体要求：

1. 项目名称始终显示。
2. 状态用中文和颜色符号表示（例如：🔵进行中）。
3. 如果预算超过1000万元，在名称后加一个“💰”符号。
4. 显示格式化的开始日期和占地面积（转换为公顷，保留两位小数）。

表达式设计与实现：

// 1. 定义变量，避免重复计算和访问字段，提高可读性和性能 var projName = $feature.PROJ_NAME; var status = $feature.STATUS; var budget = $feature.BUDGET; var startDate = $feature.START_DATE; var area = $feature.AREA; // 2. 处理状态显示：使用Decode函数进行映射，并添加Emoji（注意：标注表达式本身支持Unicode Emoji） var statusDisplay = Decode( Upper(status), // 将状态转为大写，避免大小写不一致问题 “PLANNED”, “🟡计划中”, “INPROGRESS”, “🔵进行中”, “COMPLETED”, “🟢已完成”, “ONHOLD”, “⚪️已暂停”, “❓状态未知” // 默认值，处理异常数据 ); // 3. 判断是否高预算项目 var budgetFlag = IIf(budget > 1000, “ 💰”, “”); // 如果预算>1000，则budgetFlag为“ 💰”，否则为空字符串 // 4. 格式化日期和面积 var dateDisplay = “”; var areaDisplay = “”; if (!IsEmpty(startDate)) { // 检查日期是否为空 dateDisplay = “ | 始于：” + Text(startDate, “YYYY-MM-DD”); } if (!IsEmpty(area) && area > 0) { // 检查面积是否为空且大于0 var areaInHectares = Round(area / 10000, 2); // 转换为公顷，四舍五入保留两位小数 areaDisplay = “ | 占地：” + Text(areaInHectares, “#.##”) + “公顷”; } // 5. 拼接最终标注字符串 var finalLabel = projName + budgetFlag + “\n” + statusDisplay + dateDisplay + areaDisplay; // 6. 返回结果 return finalLabel;

表达式解析与技巧：

1. 变量定义：开头将字段值赋给局部变量是很好的习惯。它让后面的代码更简洁（不用每次都写$feature.XXX），更重要的是，在某些复杂的表达式或循环中，这能轻微提升性能，因为字段值只需查找一次。
2. 状态映射：使用Decode函数将英文状态码映射为带Emoji的中文，清晰直观。用Upper()函数包裹status，确保了比较时不区分大小写，增强了代码的健壮性。
3. 条件标志：budgetFlag使用了IIf函数，简洁地生成了一个条件文本。这里用空字符串作为false_value，实现了“有则加，无则不加”的效果。
4. 空值处理：在格式化日期和面积前，都用IsEmpty()和附加条件进行了检查。这是至关重要的错误预防措施。如果不检查，当遇到null值或非法值（如面积为0或负数）时，Text函数可能返回null或错误，导致整个标注不显示。
5. 单位换算与格式化：面积除以10000得到公顷，并用Round函数控制精度，最后用Text函数格式化数字，避免显示过多小数位。
6. 字符串拼接与换行：使用+进行拼接，“\n”表示换行，使得标注信息分层显示，更加清晰。

最终，一个预算1200万元、正在进行中、占地50000平方米的项目，标注可能显示为：

阳光新城项目 💰 🔵进行中 | 始于：2024-03-01 | 占地：5.00公顷

6. 进阶技巧与性能考量

当你掌握了基础，开始编写更复杂的表达式时，就需要关注一些进阶技巧和性能问题。

6.1 使用When与IIf处理多级分类

对于更复杂的分类逻辑，When函数是主力。例如，根据人口密度和GDP对城市进行综合分级：

var density = $feature.POPULATION / $feature.AREA; // 人/平方公里 var gdp = $feature.GDP; // 亿元 return When( density > 1000 && gdp > 500, “一线城市”, density > 500 && gdp > 200, “二线城市”, density > 200 && gdp > 50, “三线城市”, “其他城市” );

注意条件的顺序和逻辑的严谨性，确保每个要素都能被正确归类，且没有重叠或遗漏。

6.2 避免在表达式内进行复杂循环与递归

Arcade表达式是为每个要素独立执行的。虽然它支持for循环，但如果你对一个拥有成千上万要素的图层，在标注表达式中使用循环遍历另一个大型图层，性能会急剧下降，甚至导致客户端无响应。

黄金法则：尽量让表达式的逻辑只依赖于当前要素（$feature）的属性或一些全局常量。如果需要进行跨要素的复杂空间分析或统计（例如，计算每个要素周围10公里内同类要素的数量），这通常不是标注表达式的任务，而应该考虑使用“连接”工具预先计算好一个统计字段，或者使用Arcade的FeatureSet函数时格外小心并设置空间过滤。

6.3 调试与错误排查实战记录

即使再小心，错误也难免。Arcade表达式构建器通常会有基本的错误提示（如语法错误）。但逻辑错误需要自己排查。

1. 使用Console函数输出日志：在ArcGIS Pro的表达式构建器中，你可以使用Console(信息)函数。执行后，信息会输出到Pro的“Python”窗格旁边的“Arcade”窗格中。这对于查看中间变量值非常有用。

   var testValue = $feature.AREA; Console(“面积原始值：” + testValue); testValue = testValue / 10000; Console(“转换为公顷后：” + testValue); return Text(testValue, “#.##”);

2. 简化与分段测试：如果表达式很长很复杂，先注释掉一部分，确保核心部分能运行。然后逐步取消注释，添加功能，定位出错的位置。
3. 关注数据类型：很多错误源于类型不匹配。确保你比较的是同类型数据（如数字和数字比，文本和文本比）。使用TypeOf()函数可以查看变量的类型。

   Console(“STATUS字段类型是：” + TypeOf($feature.STATUS));

4. 处理空值和除零错误：这是最常见的运行时错误。在任何数学运算（特别是除法）和函数调用前，养成检查空值和有效性的习惯。

   var ratio = 0; if (!IsEmpty($feature.A) && !IsEmpty($feature.B) && $feature.B != 0) { ratio = $feature.A / $feature.B; } return ratio;

7. 常见问题速查与避坑指南

根据我和社区里很多同行的经验，下面这些问题是新手（甚至有时是老手）最容易遇到的：

问题现象	可能原因	解决方案
标注什么都不显示，或者弹出窗口内容为空。	1. 表达式存在语法错误，根本未执行。 2. 表达式返回了null或undefined值。 3. 字段名拼写错误或大小写不对。	1. 检查表达式构建器是否有红色错误提示。 2. 检查表达式所有分支是否都有返回值。使用IIf或When时确保有默认值。 3. 对可能为空的字段用IsEmpty()判断，并提供备用值。 4. 从字段列表双击插入字段名，避免手动输入。
标注显示为 “NaN”, “Infinity” 或 “0”。	进行了非法的数学运算，如除以零、对非数字进行算术运算。	在除法运算前判断分母是否为0。确保参与运算的变量是数字类型，可用Number()函数强制转换。
逻辑判断 (&&, `	`) 报错：“操作数必须可转换为标量逻辑值”。
Decode或When函数没有返回预期的默认值。	1. 条件值（case）与字段值不完全匹配（如大小写、空格）。 2. 在When中，前面的条件意外包含了后面的情况。	1. 使用Upper()或Lower()统一大小写，使用Trim()去除空格后再比较。 2. 检查When函数的条件顺序和逻辑，确保它们是互斥且全面的。
日期显示为奇怪的数字（如 “44930”）。	直接输出了日期字段，没有用Text()函数格式化。	使用Text($feature.DATE_FIELD, “YYYY-MM-DD”)等格式进行格式化。
性能极慢，地图操作卡顿。	表达式过于复杂，可能包含了对大型FeatureSet的未过滤查询或循环。	优化表达式逻辑，避免在每要素计算中进行全表扫描。考虑将复杂计算提前到字段计算器或属性规则中完成，标注表达式仅做简单引用。

最后，再分享一个我个人的深刻体会：写好Arcade表达式的关键，不在于记住所有函数，而在于清晰的逻辑思维和对数据的深刻理解。在动手写代码之前，先用自然语言把你想实现的条件和输出描述清楚。比如，“如果项目状态是进行中且预算超千万，就用红色粗体显示名称并加感叹号；否则正常显示”。把这个描述翻译成When、IIf和字符串拼接，就水到渠成了。多利用表达式构建器的预览功能，边写边看，小步快跑，是最高效的学习方式。