公式—ArcGIS Survey123

凭借 ArcGIS Survey123，可使用公式创建智能表单。

在格式为 ${field_name} 的公式中，必须始终引用先前的问题。

运算符

Survey123 支持以下运算符：


运算符	描述	示例
。	当前答案	.=1
+	加	${question_one} + 4
-	减	${question_one} - 4
*	乘	${question_one} * 4
div	除	${question_one} div 4
=	相等	${price}=9.80
!=	不等于	${price}!=9.80
<	小于	${price}<9.80
<=	小于或等于	${price}<=9.80
>	大于	${price}>9.80
>=	大于或等于	${price}>=9.80
and	和	${price}>9.00 and ${price}<9.90
mod	模(除法余数)	${question_one} mod ${question_two}
or	或	${price}=9.80 or ${price}=9.70

函数

Survey123 支持以下函数：


函数	描述	示例
boolean(question, expression, or value)	如果提供的值不为空，则返回 true。否则，建议使用 boolean-from-string()。警告：在 Survey123 web 应用程序中，此功能将始终返回 true。有关替代方案，请参阅空值。	boolean(${question_one})
boolean-from-string()	如果提供的字符串为“true”或“1”，则返回 true。否则，将返回 false。	boolean-from-string(${question_one})
coalesce(value1, value2)	返回第一个非空值。此函数仅支持两个值。	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	返回字符串值的串联。	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	如果给定字符串包含子字符串，则返回 true。	contains(${question_one}, 'red')
count(repeat)	返回给定的跨重复项问题答案的数量。有关详细信息，请参阅聚合函数。注：在 Survey123 外业应用程序中使用时，可将此函数置于重复的内部或外部。如果要在 Survey123 web 应用程序中使用该函数，则必须将其放在重复的外部。可以在重复内部的计算中引用来自重复外部的计数值。	count(${question})
count-selected(question)	返回针对 select_one 和 select_multiple 问题选择的答案的数量。此函数还使用多行外观返回有关图像、音频和文件问题的附加文件数。	count-selected(${question_one})
date(question, expression, or value)	将数值或字符串转换为日期对象，不保留时间。	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	将数值或字符串转换为日期对象。	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	将日期对象转换为十进制日期时间值。	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	将时间对象转换为数字，该数字表示设备时区中的小数日。	decimal-time(${time_question})
ends-with(string, substring)	如果给定字符串以子字符串结尾，则返回 true。	ends-with(${question_one}, 'hand.')
false()	False	false()
format-date()	使现有的日期或时间值适合定义的格式。	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	如果条件评估为 true，将返回 a；否则，将返回 b。	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
已构建索引的重复（问题、重复、索引号）	返回重复记录中特定问题的值。有关详细信息，请参阅重复。	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	转换为整数。转换取决于数据类型。注：如果此函数为空，则其将返回 NaN，并且问题将会留空。	int(${question_one})
join(separator, question)	在重复中将所有问题连接到给定答案，由给定分隔符进行分隔。	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	用于 select_one 问题。它将返回与给定问题中的选项名称相关联的标注。请注意，必须在引号内定义问题。	jr:choice-name(${select_one}, '${select_one}')
jr:choice-name(choice_name, 'question')	用于 select_multiple 问题。它将返回与给定问题中的选项名称相关联的标注。必须使用 selected-at() 函数来提取单个答案的标注。请注意，必须在引号内定义问题。	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	返回给定范围内的最大值，或跨重复项的单个问题。	max(${question_one}, ${question_two})
min(value1, value2, ...)	返回给定范围内的最小值，或跨重复项的单个问题。	min(${question_one}, ${question_two})
not(expression)	如果表达式返回 true，则返回 false 值；如果表达式返回 false，则返回 true 值。	not(selected(., 'yes'))
now()	返回此时此刻的时间戳。此函数用于时间和 dateTime 问题。它在日期问题中与 today() 的行为相同。	now()
number(question, expression, or value)	转换为数字。转换取决于数据类型。注：如果此函数为空，则其将返回 NaN，并且问题将会留空。	number(${question_one})
once()	如果问题已有值，则返回现有值。浏览表单中的重复记录时，在重复问题中使用 random() 或 uuid() 以确保该值没有更改时，此函数是非常有用的。	once(uuid())
position(..)	返回重复中的当前记录的索引。有关详细信息，请参阅重复。	position(..)
pulldata()	从外部 CSV 文件返回一个值。有关详细信息，请参阅从 CSV 中检索值。	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	从图像中的 EXIF 元数据返回一个值。有关详细信息，请参阅提取图像元数据。	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	从地理点问题返回一个值。有关详细信息，请参阅提取地理点值。	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	在表单中运行 JavaScript 函数并返回结果。有关详细信息，请参阅调查表单中的 JavaScript 函数。	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	从 JSON 对象返回一个值。有关详细信息，请参阅从 JSON 中检索值。	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	查询 ArcGIS 要素图层、要素表或查询启用的地图服务并返回结果。有关详细信息，请参阅查询要素图层。	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	返回有关设备或登录用户的信息。有关详细信息，请参阅设备和用户属性。	pulldata("@property", 'username')
random()	返回 0 （含）至 1 （不含）之间的一个随机值。	random()
regex()	将正则表达式应用于问题的输入。如果模式匹配，则返回 true。有关详细信息，请参阅正则表达式。	regex(., '^\d{5}$')
selected(question, value)	检查是否选择了答案。此函数用于 select_one 和 select_multiple 问题。	selected(${question_one}, 'a')
selected-at(question, number)	用于 select_multiple 问题。它将返回给定编号的所选选项的名称（从零开始计数）；例如，“2”将返回第三个所选选项。	selected-at(${question_one}, 2)
starts-with(string, substring)	如果给定字符串以子字符串开头，则返回 true。	starts-with(${question_one}, 'The')
string(question, expression, or value)	转换为字符串。转换取决于数据类型。	string(${question_one})
string-length(question, expression, or value)	返回非空字符串的长度。	string-length(${question_one})
substr(question, start, end)	返回始于指定 start 的子字符串，并扩展至索引 end -1 上的字符，其中 start 和 end 从 0 开始。	substr(${question_one}, 1, 2)
sum(repeat)	返回给定的跨重复项问题的所有答案的总和。有关详细信息，请参阅聚合函数。注：在 Survey123 外业应用程序中使用时，可将此函数置于重复的内部或外部。如果要在 Survey123 web 应用程序中使用该函数，则必须将其放在重复的外部。可以在重复内部的计算中引用来自重复外部的总和值。	sum(${question})
today()	返回今天的日期，内部存储为当地正午。此函数用于日期问题。	today()
true()	True	true()
uuid()	返回随机 UUID 字符串。	uuid()
version()	返回设置工作表中定义的调查版本。	version()

Survey123 支持以下数学函数：


函数	描述	示例
acos(value)	返回值的反余弦。	acos(${question_one})
asin(value)	返回值的反正弦。	asin(${question_one})
atan(value)	返回值的反正切。	atan(${question_one})
atan2(value1, value2)	返回多个值的商的反正切。	atan2(${question_one}, ${question_two})
cos(value)	以角度形式返回值的余弦，以弧度为单位。	cos(${question_one})
sin(value)	以角度形式返回值的正弦，以弧度为单位。	sin(${question_one})
tan(value)	以角度形式返回值的正切，单位为弧度。	tan(${question_one})
exp(value)	返回某个值的自然指数。	exp(${question_one})
exp10(value)	返回 10 的指定次幂。	exp10(${question_one})
log(value)	返回某个值的自然对数。	log(${question_one})
log10(value)	返回以 10 为底，某个值的对数。	log10(${question_one})
pi()	返回 pi。	pi()
pow(value, power)	返回某个值的指定次幂。	pow(${question_one}, 3)
round(value, places)	返回四舍五入的值。	round(${question_one}, 5)
sqrt(value)	返回某个值的平方根。	sqrt(${question_one})

约束

向调查问题中添加约束会限制答案接受的输入。限制内容包括数字的指定范围、字母和数字组合或常规模式匹配。在电子表格中，约束表达式已输入约束字段，并且信息文本已输入调查工作表的 constraint_message 列。在约束表达式中，问题的输入始终由句点表示。

例如，可使用以下公式将整数字段的输入限制为仅正数：

.>= 0

将此公式应用于 date 字段时，可以防止用户输入早于今天的值：

.>= today()

您还可以在约束中使用计算。此公式用于执行计算，以仅允许用户选择介于今天与从今天开始计算第 14 天之间的日期。

(.>= today()) and (.<=(today() + (1000 * 60 * 60 * 24 * 14)))

提示：

如果公式包括介于 -1 与 1 之间的小数值，为了避免意外错误，请在值中包括前导零。如果不包括前导零，则小数会被误认为是运算符 .（或 -.）。例如，以下表达式将无效：

.> .25 and .< 24.25

以下表达式将按预期运行：

.> 0.25 and .< 24.25

正则表达式

正则表达式是用于匹配字符串中的模式的字符序列。在 Survey123 中，如果模式匹配，则表达式将返回 true；否则，如果模式不匹配，则表达式将返回 false。

您能够以各种方式使用正则表达式进行模式匹配，以限制对给定格式的有效答案，或者确保格式中包含特定内容。本示例要求对此问题的答案中应包括 road 一词：

regex(., 'road')

这些示例开始位置使用的句点用于将表达式应用于当前字段。在其位置添加另一个字段的名称会将正则表达式应用于该字段，这非常适用于相关表达式。逗号作为字段定义与表达式之间的分隔符。

该正则表达式确保答案完全匹配 road 一词，在该词之前或之后不会存在其他内容：

regex(., '^road$')

正则表达式是将问题输入限定为标准格式的理想选择。本示例仅接受美国五位邮政编码的输入：

regex(., '^\d{5}$')

本示例将响应与当前印尼车牌的格式相匹配，如下图所示：

regex(., '^[A-Z]{1,2}\d{4}[A-Z]{2,3}$')

不太严密的标准化格式可能需要非常复杂的正则表达式。 Survey123 web 应用程序使用的正则表达式会限制字符串字段的输入，以匹配电子邮件地址的格式。

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$')

上述表达式的此类修改将限制输入以匹配电子邮件地址的格式，同时接受非英文字符：

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\u0400-\uffff\-0-9]+\.)+[a-zA-Z\u0400-\uffff]{2,}))$')

本示例也使用了 Survey123 web 应用程序中的正则表达式，以将字段限制为仅接受匹配 web 地址格式的响应：

regex(., '^((https?|ftps?)\://|)(((?:(?:[\da-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.)+(?:[a-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.?)|localhost)(\:\d+)?(/(?:[^?#\s/]+/)*(?:[^?#\s/]+(?:\?[^?#\s/]*)?(?:#[A-Za-z][\w.:-]*)?)?)?')

有关正则表达式的详细信息，请参阅 Mozilla 开发者网络文档。有关正则表达式中的字符及其功能的列表，请参阅 Survey123 模板中的参考工作表或参阅快速参考。

计算

计算会在问题的 calculation 列中执行。计算通常与问题的计算类型相关联，但是，还可以将其应用于整数、小数、文本和 select_one 问题。通过引用计算问题的字段名称，可以使用计算的结果填充相关或约束表达式。

计算问题类型将被隐藏，不显示在表单中。这意味着计算问题类型可用于保存无需显示在表单中，但应包括在要素图层中的值。

例如，您可以创建计算类型问题，并将其命名为 calc，然后将以下表达式插入其 calculation 列中：

${question_1} + ${question_2} + ${question_3}

使用结果为下一个问题设置相关性：

${calc} <= 100

计算可与 date 字段中的答案配合使用。此计算用于估计所输入日期与今天之间的年数，非常适用于计算人员年龄：

int((today() - ${birth_date}) div (1000 * 24 * 60 * 60 * 365.25))

有时，您仅需要值的一部分或完整答案的截断版本。 substr 运算符可仅返回字符串的一部分（由该运算符之后的数字定义）。第一个字符用于确定选择的起点，而第二个值用于确定长度（如果不存在第二个值，则会继续执行运算，直到字符串结尾为止）。在本例中，除了包含 10 至 15 个字符的字符串之外，substr 运算符将会移除其余的所有字符串。

substr(${previous_question}, 10, 15)

如果第一个数字为负数，substr 将会从字符串的终点而非起点开始计数。本例仅返回答案的最后五个字符：

substr(${previous_question}, -5)

您可以使用 calculationMode 参数控制什么时候执行表单中的计算。有关详细信息，请参阅计算模式。

您也可以将 calculation 列用于重复中的聚合函数。有关详细信息，请参阅重复。

使用计算时，请遵循以下最佳做法：

使用 random() 时，需要考虑添加常量，以避免得到零 (0) 结果，例如，random()+0.5。值为 0 时，答案可能为空。
与约束类似，由于将小数点放在第一位会导致错误，因此，请确保公式中介于 -1 与 1 之间的所有小数值均具有前导 0。
计算结果的数据类型取决于计算的每个元素的数据类型。如果对两个整数执行计算，则计算结果为整数。如果计算包括字符串数据类型，则会发现系统使用 + 运算符连接值，而非向值中添加值。为了避免得到意外结果，请使用 number() 函数，以确保将计算中的字符串值视为数字。例如，将 question1（整数类型）添加至 question2（文本类型）的计算为 ${question1} + number(${question2})。

提示：

计算问题的 XLSForm 默认绑定类型为 string。要覆盖此默认值，在问题的 bind::type 列输入所需的类型（例如 int 或 decimal）。或者您可以使用所需的问题类型（例如 integer 或 decimal）并将此问题的外观更改为 hidden。

警告：

在 Survey123 web 应用程序中，针对文本问题使用数学函数或运算符将返回结果 NaN。要串联文本问题，请使用 concat() 函数，而非 + 运算符。

复杂数学函数

calculation 列还可以处理更复杂的数学运算。在本例中，如果给出半径，则可以使用 pi 和幂函数确定图的面积：

pi() * pow(${plot_radius}, 2)

测量树高的常用方法是测量从观察点的水平视线到树顶部的角度，以及同一观察点到树底部的距离。如果到树顶部的角度以度为单位测量，则将使用以下计算将其转换为弧度：

${angle_to_top_degrees} * (pi() div 180)

现在，角度测量值以弧度为单位，可以通过以下计算确定树高（四舍五入到小数点后两位）：

round(((tan(${angle_to_top_radians}) * ${distance_to_tree}) + ${height_to_eyes}),2)

设置日期的格式

您可以在 calculation 字段中使用 format-date 函数来设置日期和时间值格式。如果要向用户显示部分日期或将日期保留为字符串，则该函数非常有用。

在此示例中，将以 24 小时时间格式返回上一时间或 dateTime 问题中包含的值：

format-date(${previous_time},'%H:%M')

可在 format-date 函数中使用的限定符如下所示：


限定符	描述
%3	使用 0 补充的毫秒刻度 (000-999)
%a	三个字母的短文本日期
%b	缩写月份名称
%d	使用 0 补充的日
%e	日期
%h	小时（24 小时时间）
%H	使用 0 补充的小时（24 小时时间）
%m	使用 0 补充的月份
%M	使用 0 补充的分钟
%n	数值月份
%S	使用 0 补充的秒
%W	周数注： %W 限定符不能用于日期问题中使用计算的 format-date 函数。该限定符适用于具有默认值的日期问题。
%y	2 位年份
%Y	4 位年份

注：

dateTime 问题不支持低于一分钟的时间分辨率。要捕获日期时间低于一分钟的时间分辨率，请考虑使用 start 和 end 问题。

空值

当使用引用其他问题的约束和计算时，考虑问题为空（即，没有答案）时所发生的情况。空值表示如下：

NaN（非数字），适用于整数和小数问题。此值为特殊值，表示不存在有效值。
''（空字符串），适用于文本问题。 select_one、select_mulitple、评级以及隐藏问题的默认数据类型同样为文本。当 select_one、select_multiple 和隐藏问题类型为空时，或者当用户未更改评级问题时，它们将包含一个空字符串。

计算的执行情况有所不同，具体取决于值为数字还是文本。

在整数或小数问题中，将会发生以下情况：

任何包含 NaN 值的数学表达式都无法完成，并且问题会留空。
而 min() 和 max() 函数能够完成并忽略任何 NaN 值。
在 is not equal 值比较计算中，与其他任何值比较的 NaN 值都仅为 true。所有其他表达式的结果均为 false。

在文本问题中，将会发生以下情况：

如果存在空值，文本问题的串联能够完成。例如，当问题 firstName 为空时，concat("Hello" + ${firstName}, ", how are you?") 的结果为 "Hello , how are you?"。
min() 和 max() 函数能够完成并忽略任何空字符串。
空文本答案等于其他空文本答案，并且始终小于任何非空文本答案。

您可以使用 string-length 函数确定问题是否为空。 string-length 函数可与所有问题类型配合使用。例如，如果 Question1 为空，则 string-length(${Question1}) 会返回 0。

您也可以使用 count-selected 函数确定 select_one 或 select_multiple 问题是否为空。例如，如果针对 question2 未做任何选择，则 count-selected(${question2}) 返回 0。

Select_multiple 和评级问题

对 select_multiple 和评级问题类型的响应的存储方式与所有其他问题类型均不相同。以所选顺序输入 select_multiple 问题中每个选中的答案，以逗号分隔。例如，以此顺序选择答案 “A”和“B”，答案将呈现为“A,B”。评级问题也可将其答案存储在逗号分隔的列表中，以在提交时按照从最高到最低等级的顺序进行排序。

某些 XLSForm 要素不适用于 select_multiple 和评级问题。例如，如果在问题（该问题引用 select_multiple 问题）的 relevant 列中输入答案“A”，则调查答案为“A,B”，该答案会被视为非相关答案。在这种情况下，解决方案是使用 selected() 函数确定是否有其中任一值显示在列表中。

如果用户已将“A”选择为所引用 select_multiple 问题的答案之一，则在问题的 relevant 列中使用下列表达式时，该表达式会显示该问题。 Select_multiple 问题中的其他答案不会改变此行为。

selected(${previous_question}, 'A')

从 .csv 文件中检索值

要从 .csv 文件预加载数据，您可以在问题的 calculation 列中使用 pulldata() 函数。包含 .csv 文件的方法有两种：将文件手动放置在测量的 media 文件夹中，或链接到 ArcGIS 中托管的 .csv 文件。

pulldata() 函数需要指定以下四个参数，依次为：

包含值的列表的 .csv 文件的名称。名称不包括 .csv 文件名后缀。
包含想要返回的值的 .csv 文件中的列的名称。
用于查找值的 .csv 文件中的键字段的名称。
要在键字段中查找的键值。

这些值可以直接定义，还可以通过在调查的其他位置定义的变量定义。在以下示例中，计算从名为 info 的 .csv 文件中返回在前一问题中提及的某人员的电子邮件地址：

pulldata('info', 'email', 'name', ${respondent_name})

相同的 pulldata() 函数还可用于 constraints 列，从而防止用户提交未包含在 .csv 文件中的答案。在 constraints 列中，此相同的公式可防止表单接受 .csv 文件的 name 列中不存在的所有值。

pulldata() 函数存在一些限制。键字段名称存在与 choices 工作表的 name 列相同的限制，这意味着这些值不能包含空格或非 ASCII 字符。此外，由于使用的文件为 .csv 文件，因此在任意字段中使用逗号会导致 pulldata() 函数生成错误结果。

如果您的 .csv 文件中的值超过 255 个字符，则对于您正在使用 .csv 内容填充的问题和正在用作 pulldata() 函数输入的任何问题，您必须在 bind::esri:fieldLength 列中输入一个更高的值。如果您的 .csv 文件包含的值大于其中一个字段的最大长度，则调查响应无法提交并会显示代码 1000 错误。

注：

pulldata() 函数不能用于填充 select_multiple 问题的值。

使用 pulldata() 函数时，.csv 列名称不能为空或包含空格、连字符或其他特殊字符。

建议使用 UTF-8 字符编码对 .csv 文件进行编码。如果您使用 Microsoft Excel 创建 .csv 文件，请将其另存为 CSV UTF-8。

从 JSON 中检索值

您可以使用 pulldata("@json") 函数从 JSON 对象中提取单个属性。此函数通常用于补充其他函数，例如 pulldata("@javascript") 和 pulldata("@layer")。该函数具有以下语法：

pulldata("@json", <question name>, "<JSON property>")

pulldata("@json") 的参数如下：

question name - 包含 JSON 对象的问题的名称，例如：${json_response}。
JSON property - 要从 JSON 中检索的属性。使用句点指定属性在 JSON 结构中的位置。例如，要从 address 对象中检索 City 属性，请使用 "address.City"。

在以下示例中，反向地理编码操作的结果在名为 json_response 的文本问题中以 JSON 形式返回：

返回来自定位器的类似于以下内容的响应：

{
    "address": {
        "Match_addr": "Eiffel Tower",
        "LongLabel": "Eiffel Tower, Paris, Île-de-France, FRA",
        "ShortLabel": "Eiffel Tower",
        "Addr_type": "POI",
        "Type": "Historical Monument",
        "PlaceName": "Eiffel Tower",
        "AddNum": "",
        "Address": "",
        "Block": "",
        "Sector": "",
        "Neighborhood": "Paris 07",
        "District": "Paris",
        "City": "Paris",
        "MetroArea": "",
        "Subregion": "Paris",
        "Region": "Île-de-France",
        "RegionAbbr": "",
        "Territory": "",
        "Postal": "",
        "PostalExt": "",
        "CntryName": "France",
        "CountryCode": "FRA"
    },
    "location": {
        "x": 2.294520000000034,
        "y": 48.85832000000005,
        "spatialReference": {
            "wkid": 4326,
            "latestWkid": 4326
        }
    }
}

pulldata("@json") 函数用于从 address 对象中检索 City 属性：

pulldata("@json", ${json_response}, "address.City")

从 location 对象中检索纬度和经度：

pulldata("@json", ${json_response}, "location.x")

pulldata("@json", ${json_response}, "location.y")

注：

句点用于访问父对象的各个属性。如果句点还是属性的一部分，则其必须包含在方括号 [ ] 中。例如，要从 address 对象中调用名为 City.Population 的属性，表达式将为 pulldata("@json", ${json_response}, "address.[City.Population]")。

通过在方括号内指定数组中的对象位置，可以访问对象数组中的对象。 JSON 数组的索引从零开始。下面是智能属性返回的 JSON 对象的示例。其中包含 classes 数组：

{
    "classNames": "person,bottle,keyboard",
    "classes": [
        {
            "name": "person",
            "score": 0.67421875,
            "xmin": 47,
            "ymin": 20,
            "xmax": 1086,
            "ymax": 262
        },
        {
            "name": "bottle",
            "score": 0.7625,
            "xmin": 237,
            "ymin": 469,
            "xmax": 552,
            "ymax": 639
        },
        {
            "name": "keyboard",
            "score": 0.55078125,
            "xmin": 28,
            "ymin": 49,
            "xmax": 1078,
            "ymax": 385
        }
    ]
}

对于上方示例，以下表达式返回 classes 数组中第一个对象的得分 0.67421875：

pulldata("@json", ${results}, "classes[0].score")

您可以使用 length 属性返回数组中的对象数。对于上方示例，以下表达式返回长度 3：

pulldata("@json", ${results}, "classes.length")

查询要素图层

您可以使用 pulldata("@layer") 函数查询要素图层、要素表，或查询启用的地图服务。可以执行属性查询或空间查询。属性查询使用 getRecord 或 getValue 运算：

pulldata("@layer", "getRecord", "<URL>", "<WHERE clause>")
pulldata("@layer", "getValue", "<JSON property>", "<URL>", "<WHERE clause>")

空间查询使用 getRecordAt 或 getValueAt 运算：

pulldata("@layer", "getRecordAt", "<URL>", <location>, "<WHERE clause>")
pulldata("@layer", "getValueAt", "<JSON property>", "<URL>", <location>, "<WHERE clause>")

getRecord 和 getRecordAt 运算将返回 JSON 要素对象，其中包含单一要素及其所有属性。 getValue 和 getValueAt 运算将返回要素对象的单一值，而不是整个查询响应。

pulldata("@layer") 的参数如下：


参数	描述
JSON property	getValue 和 getValueAt 运算的必需项。要从查询响应中调用的值。例如： `"attributes.COUNTRY" "geometry"`
location	getRecordAt 和 getValueAt 运算的必需项。要在要素图层中查询的点位置。这必须是一个地理点问题。示例： `${location}`
URL	必填项。要查询的要素图层或表的 URL。此参数接受其他请求参数。示例： `"https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"`
WHERE clause	可选。用于过滤要素图层或表的 WHERE 表达式。未提供 Where 子句时，将使用默认值 "1=1"。示例： `"COUNTRY='Canada'"`

提示：

pulldata("@layer") 函数将返回查询响应中的第一个记录。设计并测试您的查询，以确保获取所需的结果。可以使用 WHERE 子句和下述附加请求参数细化查询。

pulldata("@layer") 函数可以缓存查询响应，以便提高效率。要清除缓存并确保每次运行函数时都发出新的请求，请向 URL 添加一个 time=now 参数，例如 concat(${layer_url}, "?t=", now())。

以下示例用于查询世界时区的面要素图层并返回地理点所在的时区：

getRecordAt 运算用于按照以下语法调用与地理点相交的时区：

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

随后将使用 pulldata("@json") 函数从查询响应中提取 ZONE 属性。或者，可以在 pulldata("@layer") 计算中使用 getValueAt 运算直接调用 ZONE 属性，无需使用单独问题存储查询响应。请参阅以下示例：

pulldata("@layer", "getValueAt", "attributes.ZONE", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

可以在约束中使用 pulldata("@layer")。例如，可以将约束应用于地理点问题，以防用户提交感兴趣区之外的位置。

getRecordAt 运算将按照以下语法返回地理点所在的国家/地区的 JSON 要素对象：

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0", ${location}, "COUNTRY='Canada'")

将使用 pulldata("@json") 在文本问题中提取国家/地区名称。 ${country}='Canada' 约束随后将应用于地理点问题，以确保位置位于加拿大区域内。

请求参数

可以使用附加请求参数细化 pulldata("@layer") 查询，例如 distance、orderByFields 和 resultOffset。有关请求参数的详细信息，请参阅查询（要素服务/图层）。 pulldata("@layer") 函数仅支持返回要素对象的请求。

要在查询中包含这些参数，将其追加到 URL 中的问号后。附加参数则由与号分隔。在以下示例中，orderByFields 和 resultOffset 参数追加到要素图层 URL，以返回加利福尼亚州人口数排名第十的县的名称：

pulldata("@layer", "getValue", "attributes.NAME", "https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1?orderByFields=POPULATION DESC&resultOffset=9", "STATE_NAME = 'California'")

可以通过聚合查询使用 outStatistics 参数返回要素图层的统计数据。可以使用此参数计算的统计数据包括计数、总和、最小值、最大值、平均值、标准差或方差。

在以下示例中，将返回所选州中的县计数：

pulldata("@layer", "getValue", "attributes.TotalCount", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "count","onStatisticField": "objectId","outStatisticFieldName": "TotalCount"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

在以下示例中，将返回所选州中所有县的 POPULATION 字段的总和：

pulldata("@layer", "getValue", "attributes.TotalPopulation", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "sum","onStatisticField": "POPULATION","outStatisticFieldName": "TotalPopulation"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

注：

pulldata("@layer") 函数支持查询（要素服务/图层）中列出的所有请求参数，以下各项除外：

f
outFields
outSR
resultRecordCount
returnCountOnly
returnGeometry
returnIDsOnly
token

从列表中检索位置。

可以允许用户根据其在 select_one 问题选项列表中的选择从要素图层中检索位置。选项以文本形式提交，相应几何作为调查响应的位置提交。此方法相当于 Survey123 web 设计器中的位置列表问题。

要创建位置列表，请添加具有搜索和自动完成外观的 select_one 问题。搜索外观将使用来自要素图层的值填充列表。自动完成外观将在下拉列表中显示值，当从要素图层中返回的列表非常长时，此选项将非常有用。

配置 search() 表达式以从要素图层中检索值列表。在 geopoint、geoshape 或 geotrace 问题中，添加 pulldata("@layer") 表达式以检索从列表中选择的要素的几何。

在以下示例中，调查对象将从名为 meter_id 的 select_one 问题中选择一个水表。将从 Water Meters 要素图层中检索水表的几何并将其保存至 geopoint 问题：

包含 search() 和 pulldata("@layer") 表达式的 XLSForm

有关搜索外观的详细信息，请参阅搜索。

有关此主题的反馈?

运算符

函数

警告：

注：

注：

注：

注：

约束

提示：