Формулы

Вы можете использовать формулы для создания более сложных форм в ArcGIS Survey123.

На предыдущие вопросы всегда следует ссылаться в формулах в формате ${field_name}.

Операторы

В Survey123 поддерживаются следующие операторы 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 поддерживаются следующие функции:

Функция	Описание
площадь(вопрос)	Возвращает площадь полигона в квадратных метрах для вопросов о геоформе. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: area(${geoshape})
boolean(question, expression, or value)	Возвращает true, если введенное значение не null. Лучше использовать boolean-from-string(). Внимание: Эта функция будет всегда возвращать true в веб-приложении Survey123. Для альтернативных вариантов см. Пустые значения. Пример: boolean(${question_one})
boolean-from-string()	Возвращает true, если введенное значение 'true' или '1'. В противном случае возвращается 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 Studio или Survey123 Mobile. При работе в полевом приложении Survey123, эта функция может быть расположены внутри или снаружи повтора. Если эта функция используется в веб-приложении Survey123, она должна быть расположена снаружи повтора. Значение количества, расположенное снаружи повтора, может учитываться в вычислении внутри повтора. Пример: 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})
Расстояние(вопрос)	Возвращает длину полилинии в метрах для вопросов о геотрассировке. Возвращает длину в метрах периметра полигона для вопросов о геотрассировке. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: distance(${geotrace})
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)	Если условие оценивается как истина, возвращается a, иначе возвращается b. Более подробную информацию см. в разделе Условные выражения. Пример: if(selected(${question_one}, 'yes'), 'yes', 'no')
индексированный повтор(вопрос, повтор, индексный номер)	Возвращает значение из определенного вопроса в записи повтора. Для получения дополнительных сведений см. раздел Повторы. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Отсекает дробную часть десятичного числа, возвращая целое число. Примечание: Если эта функция пустая, будет возвращено NaN, и вопрос останется пустым. Пример: int(${question_one})
join(separator, question)	Объединяет все ответы на данный вопрос, разделив их указанным разделителем. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. При работе в полевом приложении Survey123, эта функция может быть расположены внутри или снаружи повтора. Если эта функция используется в веб-приложении Survey123, она должна быть расположена снаружи повтора. Значение связи, расположенное снаружи повтора, может учитываться в вычислении внутри повтора. Пример: 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, ...)	Возвращает максимальное значение в заданном диапазоне, или для одного вопроса в повторах. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: max(${question_one}, ${question_two})
min(value1, value2, ...)	Возвращает минимальное значение в заданном диапазоне, или для одного вопроса в повторах. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: min(${question_one}, ${question_two})
not(expression)	Возвращает булево значение ложь, если выражение вернуло истину, и возвращает булево значение истина, если выражение вернуло ложь. Пример: not(selected(., 'yes'))
now()	Возвращает текущее время для экземпляра. Эта функция используется в вопросах типа Время и ДатаВремя. Работает так же, как выражение today() iв вопросах типа Дата. Пример: now()
number(question, expression, or value)	Конвертирует последовательность цифр в числовое значение. Примечание: Если эта функция пустая, будет возвращено NaN, и вопрос останется пустым. Пример: number(${question_one})
once()	Если для вопроса уже есть значение, возвращается имеющееся значение. Эта функция применяется при использовании random() или uuid() в повторяющемся вопросе, для того чтобы убедиться, что значение не меняется при переходе по повторяющимся записям в форме. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: once(uuid())
position(..)	Возвращает индекс текущей записи в повторе. Для получения дополнительных сведений см. раздел Повторы. Пример: position(..)
pulldata()	Возвращает значение из внешнего файла CSV. Подробнее см. Получение значения из CSV. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. Пример: 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(вопрос, значение)	Проверяет, выбран ли ответ. Эта функция используется для вопросов 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)	Возвращает подстроку, начиная с заданного символа (начало) и заканчивая символом (конец -1, где наименьшим значением начала и конца является 0. Если начало является отрицательным, функция начинает отсчет с конца строки. Примеры: substr(${question_one}, 1, 2) substr(${question_one}, -5)
sum(repeat)	Возвращает сумму всех ответов на заданный вопрос в повторах. Более подробно см. Функции агрегации. Примечание: Эта функция не поддерживается в Survey123 Studio или Survey123 Mobile. При работе в полевом приложении Survey123, эта функция может быть расположены внутри или снаружи повтора. Если эта функция используется в веб-приложении Survey123, она должна быть расположена снаружи повтора. Значение суммы, расположенное снаружи повтора, может учитываться в вычислении внутри повтора. Пример: sum(${question})
today()	Возвращает сегодняшнюю дату, которая хранится внутри, как полдень по местному времени. Эта функция используется в вопросах типа Дата. Пример: today()
true()	True Пример: true()
uuid()	Возвращает случайную строку UUID. Пример: uuid()
version()	Возвращает версию опроса, указанную в настройках рабочего листа. Пример: version()

Следующие математические функции поддерживаются в Survey123:

Функция	Описание	Пример
acos(значение)	Возвращает арккосинус значения.	acos(${question_one})
asin(значение)	Возвращает арксинус значения.	asin(${question_one})
atan(значение)	Возвращает арктангенс значения.	atan(${question_one})
atan2(значение1, значение2)	Возвращает арктангенс деления значений.	atan2(${question_one}, ${question_two})
cos(значение)	Возвращает косинус значения как угол в радианах.	cos(${question_one})
sin(значение)	Возвращает синус значения как угол в радианах.	sin(${question_one})
tan(значение)	Возвращает тангенс значения как угол в радианах.	tan(${question_one})
exp(значение)	Возвращает значение натуральной экспоненты числа.	exp(${question_one})
exp10(значение)	Возвращает значение, равное 10 в заданной степени.	exp10(${question_one})
log(значение)	Возвращает значение натурального логарифма числа.	log(${question_one})
log10(значение)	Вычисляет логарифм по основанию 10 числа.	log10(${question_one})
pi()	Возвращает значение pi.	pi()
pow(значение, степень)	Возвращает значение в заданной степени.	pow(${question_one}, 3)
round(значение, знаки)	Возвращает округленное значение.	round(${question_one}, 5)
sqrt(значение)	Возвращает квадратный корень от числа.	sqrt(${question_one})

Ограничения

Добавление ограничения к вопросу ограничивает допустимые входные данные для ответа. Ограничение может включать определенный диапазон значений, комбинации букв и цифр, или общий шаблон совпадений. В вашей электронной таблице ограничивающее выражение вводится в поле ограничения, а информационный текст вводится в столбце constraint_message рабочего листа опроса. В ограничительном выражении входные данные вопроса всегда представлены периодом.

Например, можно использовать следующую формулу, чтобы ограничить входные данные для целочисленного поля только положительными числами:

.>= 0

Эта формула, примененная к полю date, не позволит пользователю ввести значение ранее сегодняшнего дня:

.>= today()

Вы также можете использовать вычисления в ограничениях. Эта формула выполняет расчет, чтобы позволить пользователю выбрать даты между текущим днем и 14 днями от текущего дня:

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

Подсказка:

Чтобы избежать непредвиденных ошибок, если формула содержит десятичные значения между -1 и 1, добавьте 0 впереди для всех значений. Если не добавить 0, то десятичные значения могут быть ошибочно приняты за символ операции (. или -.). Например, следующее выражение не будет выполнено:

.> .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, ограничивает входные данные строкового поля для соответствия формату адреса эл. почты:

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, ограничивает поле таким образом, чтобы оно принимало только ответы, соответствующие формату веб-адреса:

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 Developer Network. Список символов и их функций в регулярных выражениях можно найти в рабочем листе Справочник в шаблонах Survey123 или в Выражениях.

Вычисления

Значение вопроса можно вычислить, введя выражение в соответствующий столбец для вычислений. Вы можете применять вычисления к типам вопросов, в которых хранятся текст, числа, даты, время или местоположение.

Тип вопроса вычислить скрыт и в форме не отображается. Это означает, что он может использоваться для хранения значений, которые не должны отображаться в форме, но которые содержатся в векторном слое. Результаты вычисления могут использоваться для заполнения связанных выражений или выражений ограничений, путем ссылки на имя поля вычисляющего вопроса.

Например, вы можете создать вопрос типа вычислить и назвать его calc, а затем вставить следующее выражение в его столбец вычисления:

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

Используйте результат, чтобы задать отношение для следующего вопроса:

${calc} <= 100

Ответы на вопросы типа дата могут быть использованы в вычислениях. Следующее вычисление определит количество лет между введенной датой и текущим днем, оно идеально подходит для вычисления возраста человека:

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

Иногда вам требуется только часть значения или сокращенная версия полного ответа. Функция substr() возвращает часть строки, начинающуюся с указанного начала и простирающуюся до (но не включая) окончания. Если окончание не указано, подстрока продолжается до конца строки. В этом примере функция substr() возвращает символы с 10 по 14 (включительно):

substr(${previous_question}, 10, 15)

Если начало является отрицательным, substr() начнет отсчет с конца строки, вместо начала. Этот пример возвращает последние 5 символов строки:

substr(${previous_question}, -5)

Вы можете использовать параметр calculationMode для управления вычислениями в форме. Для получения дополнительной информации см. раздел Режим вычислений.

Вы также можете использовать столбец calculation для функций агрегирования в повторах. Для получения дополнительных сведений см. раздел Повторы.

При использовании вычислений придерживайтесь следующих рекомендаций:

• При использовании функции random() обдумайте возможность добавления постоянного значения, чтобы избежать получения нуля (0) в качестве результата, например, random()+0.5. Нулевое значение может привести к пустому ответу.
• Как и в случае ограничений, если ваша формула включает десятичные значения между -1 и 1, убедитесь, что вы добавили 0 впереди для всех значений, иначе точка перед десятичными значениями будет приводить к ошибкам.
• Тип данных результата вычисления зависит от типа данных каждого из элементов этого вычисления. Если вычисление выполняется для двух целочисленных значений, то результат вычисления будет целочисленным. Если вычисление включает тип строковых данных, вы можете столкнуться с тем, что оператор + выполняет соединение значений, вместо добавления значений. Чтобы избежать ошибочных результатов, используйте функцию number(), чтобы убедиться, что строковые значения в вычислении обрабатываются, как числовые. Например, вычисление для добавления question1 (целочисленного типа) к question2 (текстового типа) выглядит следующим образом: ${question1} + number(${question2}).

Подсказка:

Обязательным типом XLSForm для вопроса вычисления по умолчанию является string. Чтобы перезаписать это значение по умолчанию, введите требуемый тип (например, int или decimal) в столбце bind::type для вашего вопроса. Кроме того, вы можете использовать желаемый тип вопроса (например integer или decimal) и задать для этого вопроса оформление hidden.

Внимание:

Использование математических функций или операторов с текстовыми вопросами возвращает результат NaN в веб-приложении Survey123. Чтобы соединить текстовые вопросы, используйте функцию concat() вместо оператора +.

Сложные математические функции

Столбец calculation может также выполнять более сложные математические операции. В этом примере определяется площадь участка на основе его радиуса, используя функции pi и power:

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)

Форматирование даты

Вы можете использовать функцию format-date() в столбце calculation для форматирования значений даты и времени из вопросов типа "дата", "время" и "дата и время". Это бывает полезным, когда нужно показать части дат пользователям или сохранить их в строковом формате.

В этом примере значение содержит предыдущее время или вопрос dateTime возвращен в 24-часовом формате:

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

В функции format-date() используются следующие квалификаторы:

Квалификатор	Описание
%3	миллисекунды без нулей (000-999)
%a	Трехбуквенное краткое обозначение дня
%b	Аббревиатура имени месяца
%d	День месяца, без нулей
%e	День месяца
%h	Час (24 часа)
%H	Часы без нулей (24 часа)
%m	месяц, без нулей
%M	минуты без нулей
%n	Числовое значение месяца
%S	Секунды без нулей
%W	Номер недели (определяется по ISO 8601) Примечание: Квалификатор %W не может использоваться в функции format-date(), в которой вопрос типа «дата» использует вычисление. Этот квалификатор работает с вопросом типа «дата», который имеет значение по умолчанию. Квалификатор %W не поддерживается в веб-приложении.
%y	2 цифры года
%Y	4 цифры года

Примечание:

Вопросы dateTime не поддерживают временное разрешение меньше минуты. Чтобы зафиксировать временное разрешение с датами меньше одной минуты, рассмотрите возможность использования вопросов start и end.

Функция format-date() не поддерживается вопросами типа "время" в веб-приложении Survey123.

Пустые значения

При использовании ограничений и вычислений, ссылающихся на другие вопросы, необходимо предусмотреть тот случай, когда этот вопрос будет пустым (то есть не получит ответа). Пустые значения отображаются в следующем виде:

• NaN (не число) для целочисленных и десятичных вопросов. Это специальное значение, которое означает отсутствие корректного значения.
• '' (пустая строка) для текстовых вопросов. Типом данных по умолчанию для вопросов select_one, select_mulitple, rank и hidden также является текст. Когда вопросы типа select_one, select_multiple и hidden являются пустыми или в случае, если вопрос rank не был изменен пользователем, все они содержат пустую строку.

Поведение вычислений будет отличаться в зависимости от того, является ли значение числом или текстом.

В вопросах с целочисленными или десятичными ответами произойдет следующее:

• Любое математическое выражение со значением NaN не будет выполнено, и вопрос останется пустым.
• Функции min() и max() будут выполнены и проигнорируют все значения NaN.
• Значение NaN, если сравнивать его с любыми другими значением, может вернуть значение true только при вычислении, использующем сравнение значений is not equal. Значения всех остальных выражений будут ложными.

В текстовых вопросах произойдет следующее:

• Конкатенация текстовых вопросов будет завершена, даже если имеются пустые значения. Например, итогом concat("Hello" + ${firstName}, ", how are you?") будет "Hello , how are you?", если вопрос firstName пустой.
• Функции min() и max() будут выполнены и проигнорируют все пустые строки.
• Пустой текстовый ответ равнозначен другому пустому текстовому ответу и всегда меньше любого непустого текста.

Вы можете определить, является ли вопрос пустым, используя функцию string-length. Функцию string-length можно использовать для всех типов вопросов. Например, string-length(${Question1}) возвращает 0, если Question1 пустой.

Также вы можете определить, является ли вопрос select_one или select_multiple пустым, используя функцию count-selected. Например, count-selected(${question2}) возвращает 0, если для question2 не было сделано выборки.

Вопросы Select_multiple и rank

Примечание:

Вопросы типа "ранг" в настоящий момент поддерживаются только в полевом приложении Survey123 и веб-приложении Survey123.

Ответы на вопросы типа select_multiple и rank хранятся иначе, чем ответы на все другие типы вопросов. Каждый отмеченный ответ в вопросе select_multiple вводится в порядке выбора, а ответы разделяются запятыми. Например, выбор ответов 'A' и 'B' именно в таком порядке приведет к получению ответа 'A,B'. Вопрос rank также сохраняет ответы в виде списка значений, разделенных запятыми, - от самого высокого до самого низкого ранга на момент отправки.

Некоторые элементы XLSForm не работают с вопросами типа select_multiple и rank. Например, если вы вводите ответ 'A' в столбец relevant для вопроса, ссылающегося на вопрос select_multiple, и результатом опроса будет 'A,B', то результат не будет считаться значимым. В данном случае решением будет использование функции selected(), которая проверит, присутствуют ли любые из значений в списке.

Следующее выражение, если оно используется в столбце вопроса relevant, отображает вопрос, если пользователь выбрал 'A' в качестве одного из ответов на связанный вопрос типа select_multiple. Дополнительные ответы вопроса, имеющего тип select_multiple, не меняют это поведение.

selected(${previous_question}, 'A')

Получение значения из файла .csv

Примечание:

В этом разделе описывается функциональность, доступная только в Survey123 Connect и полевых приложениях Survey123. Эта функциональность недоступна в Survey123 Studio или Survey123 Mobile.

Используя функцию pulldata() в столбце вычисления вопроса, вы можете предварительно загрузить данные из файла .csv. Есть два способа включить файл .csv: вручную поместить его в папку media опроса или связать с файлом .csv.

Для функции pulldata() требуется указать указанные четыре параметра в следующем порядке:

• Имя файла .csv, который содержит список значений. Это имя не включает расширение файла .csv.
• Имя столбца в файле .csv, где содержится значение, которое вы хотите вернуть.
• Имя ключевого столбца в файле .csv, который вы будете использовать для поиска этого значения.
• Ключевое значение, которое нужно найти в ключевом поле.

Эти значения можно определить напрямую или с помощью переменных, определенных в другой части опроса. В следующем примере вычисление возвращает адрес электронной почты пользователя, имя которого выбрано в предыдущем вопросе, из файла .csv с названием info:

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

Та же функция pulldata() также работает со столбцом constraints, не позволяя пользователю отправить ответы, не находящиеся в файле .csv. В столбце constraints эта же формула не позволяет форме принять любые значения, не находящиеся в столбце name файла .csv.

При использовании функции pulldata() существуют некоторые ограничения. Имя ключевого поля имеет те же ограничения, что и столбец name в рабочем листе choices, что означает, что эти значения не могут содержать пробелы или символы, не являющиеся символами ASCII. Дополнительно, поскольку эти файлы являются файлами .csv, использование запятых в любом из этих полей приведет к некорректным результатам при использовании функции pulldata().

Если значения в файле .csv превышают 255 символов, потребуется ввести более высокое значение в столбец bind::esri:fieldLength для обоих вопросов, заполняемых содержанием файла .csv, и любых вопросов, которые используются в качестве входных данных для функции pulldata(). Если в файл .csv входят значения, превышающие максимальную длину одного из этих полей, ответ на опрос будет невозможно отправить и будет показана ошибка Code 1000.

Примечание:

Функция pulldata() не может использоваться для подстановки значений вопросов select_multiple.

При использовании функции pulldata() имена столбцов .csv не могут быть пустыми и не могут содержать пробелы, дефисы или другие специальные символы.

Рекомендуется кодировать файл .csv, используя кодировку UTF-8. Если вы используете 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. Например, чтобы получить свойство City из объекта address, используйте "address.City".

В следующем примере результат операции обратного геокодирования возвращается как JSON в текстовом вопросе с названием json_response:

Ответ от локатора похож на пример ниже:

{
    "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") используется для получения свойства City из объекта address в следующем примере:

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

Широта и долгота получаются из объекта location следующим образом:

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

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

Примечание:

Период используется для доступа к отдельным свойствам родительского объекта. Если период также является частью свойства, он должен быть заключен в квадратные скобки [ ]. Например, чтобы получить свойство City.Population из объекта address, использовалось бы выражение 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
        }
    ]
}

В приведенном выше примере следующее выражение возвращает оценку 0.67421875 для первого объекта массива classes:

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 возвращают одно значение из векторного объекта, а не весь ответ на запрос.

Примечание:

Операция getRecord не может быть использована для извлечения полилинейных или полигональных объектов в Survey123 Studio или Survey123 Mobile.

У 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})

Затем атрибут ZONE извлекается из ответа на запрос с помощью функции pulldata("@json"). Кроме того, вы можете использовать операцию getValueAt в вычислении pulldata("@layer"), чтобы получить атрибут 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

Извлечение местоположения из списка

Примечание:

В этом разделе описывается функциональность, доступная только в Survey123 Connect и полевых приложениях Survey123. Эта функциональность недоступна в Survey123 Studio или Survey123 Mobile.

Вы можете позволить пользователям извлечь местоположение из векторного слоя на основе их выбора из списка вариантов в вопросе типа "выбрать один". Выбранный вариант представляется в виде текста, а соответствующая ему геометрия — в качестве местоположения для ответа на опрос. Такой подход эквивалентен вопросу список местоположений в веб-дизайнере Survey123.

Чтобы создать список местоположений, добавьте вопрос типа "выбрать один" с поиском и автозаполнением следующим образом:

• Оформление поиска заполняет список значениями из векторного слоя. Для получения дополнительной информации о настройке выражения search() см. раздел Создание динамического списка вариантов выбора с использованием параметров поиска.
• Оформление автозаполнения отображает значения в ниспадающем списке, что полезно, когда из векторного слоя возвращается очень длинный список.

В вопросе геоточка, геоформа или геотрассировка добавьте выражение pulldata("@layer") для получения геометрии для объекта, выбранного из списка.

В приведенном примере респонденты выбирают счетчик воды из вопроса select_one под названием meter_id. Геометрия счетчика воды извлекается из векторного слоя "Water meter" и сохраняется в вопросе геоточки: