公式

凭借 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_oneselect_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)

在重复中将所有问题连接到给定答案,由给定分隔符进行分隔。

注:

Survey123 外业应用程序中使用时,可将此函数置于重复的内部或外部。 如果要在 Survey123 web 应用程序中使用该函数,则必须将其放在重复的外部。 可以在重复内部的计算中引用来自重复外部的连接值。

join(',', ${question_in_repeat})

jr:choice-name(choice_name, 'question')

用于 select_one 问题。 它将返回与给定问题中的选项名称相关联的标注。 请注意,必须在引号内定义问题。

jr:choice-name(${select_one}, '${select_one}')

用于 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_oneselect_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 列输入所需的类型(例如 intdecimal)。 或者您可以使用所需的问题类型(例如 integerdecimal)并将此问题的外观更改为 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 问题不支持低于一分钟的时间分辨率。 要捕获日期时间低于一分钟的时间分辨率,请考虑使用 startend 问题。

空值

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

  • 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() 函数需要指定以下四个参数,依次为:

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

这些值可以直接定义,还可以通过在调查的其他位置定义的变量定义。 在以下示例中,计算从名为 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 形式返回:

具有 pulldata("@json") 计算的 XLSForm

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

{
    "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") 函数查询要素图层、要素表,或查询启用的地图服务。 可以执行属性查询或空间查询。 属性查询使用 getRecordgetValue 运算:

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

空间查询使用 getRecordAtgetValueAt 运算:

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

在空间查询中指定的位置必须为地理点问题。

getRecordgetRecordAt 运算将返回 JSON 要素对象,其中包含单一要素及其所有属性。 getValuegetValueAt 运算将返回要素对象的单一值,而不是整个查询响应。

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

参数描述
JSON property

getValuegetValueAt 运算的必需项。 要从查询响应中调用的值。

例如:

"attributes.COUNTRY"
"geometry"
location

getRecordAtgetValueAt 运算的必需项。 要在要素图层中查询的点位置。 这必须是一个地理点问题。

示例:

${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())

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

包含 pulldata("@layer") 计算的 XLSForm

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")。 例如,可以将约束应用于地理点问题,以防用户提交感兴趣区之外的位置。

包含 pulldata("@layer") 约束的 XLSForm

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") 查询,例如 distanceorderByFieldsresultOffset。 有关请求参数的详细信息,请参阅查询(要素服务/图层)pulldata("@layer") 函数仅支持返回要素对象的请求。

要在查询中包含这些参数,将其追加到 URL 中的问号后。 附加参数则由与号分隔。 在以下示例中,orderByFieldsresultOffset 参数追加到要素图层 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

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