Survey123表单怎么设计?XLSForm语法是?

wowwwai GIS研习社 · 工具流程与项目排障

很多 GIS 项目都会遇到同一个问题：Survey123表单怎么设计?XLSForm语法是? 看起来只是做一个外业采集表，但一旦涉及必填项、下拉选项、级联选择、照片、定位、计算字段和条件显示，表单设计就会直接影响数据质量、外业效率和后期入库成本。

本文面向 ArcGIS Survey123 初学者、GIS 外业数据采集团队和需要维护调查表的 GIS 工程师，重点讲清楚 Survey123 表单设计思路，以及 XLSForm 语法中最常用、最容易出错的部分。你可以把它当作一份实用检查表，在正式发布调查之前逐项核对。

引言：Survey123 表单设计不要从“先加字段”开始

很多人第一次使用 Survey123 时，会直接打开 Survey123 Connect，然后在 Excel 里一行一行添加问题。这样可以快速做出表单，但后期很容易出现这些问题：

• 字段名不规范，导出到要素图层后难以维护。
• 下拉选项没有编码，统计时全是中文文本，难以做分类分析。
• 必填、约束、条件显示没有设置，外业人员容易漏填或误填。
• 坐标、照片、时间、人员信息没有统一规则，后期质检困难。
• 表单发布后才发现字段类型不合适，修改成本很高。

所以，Survey123表单设计的核心不是把纸质表格搬进手机，而是把“业务规则、空间位置、数据质量控制”一起设计进表单。XLSForm 语法就是实现这些规则的主要方式。

背景：Survey123 和 XLSForm 分别解决什么问题

ArcGIS Survey123 是 Esri 提供的表单式外业采集工具，适合做巡查、调查、核查、设施普查、灾害上报、公众报送等任务。它的结果通常会存储为 ArcGIS Online 或 ArcGIS Enterprise 中的托管要素图层。

XLSForm 是一种用电子表格描述调查表的标准格式。Survey123 Connect 使用 XLSForm 来定义表单结构。通常一个 Survey123 XLSForm 至少包含三个工作表：

工作表	作用	常见内容
survey	定义表单问题和逻辑	字段类型、字段名、标签、必填、约束、计算、显示条件
choices	定义选择题选项	单选、多选、级联选择的选项编码和显示文本
settings	定义表单整体设置	表单标题、实例名称、提交 URL、版本号

如果你只用 Survey123 Web Designer，可以完成简单表单。但如果要做级联下拉、复杂计算、动态默认值、重复组、隐藏字段、字段别名控制等，更推荐使用 Survey123 Connect 和 XLSForm。

原理：XLSForm 语法的核心是“类型、名称、标签、规则”

理解 XLSForm语法 不需要一开始背很多函数。先掌握 survey 表中最重要的几列即可：

列名	含义	示例
type	问题类型或控件类型	text、integer、select_one、geopoint、image
name	字段名，发布后通常对应图层字段	asset_id、damage_level、inspect_date
label	表单中显示给用户看的问题文本	设施编号、损坏等级、巡查日期
required	是否必填	yes
constraint	输入约束条件	. >= 0
relevant	条件显示	${has_damage} = ‘yes’
calculation	自动计算值	now()

在 XLSForm 中，${字段名} 表示引用另一个问题的答案，. 表示当前问题的输入值。理解这两个符号，就能读懂大部分 Survey123 表单逻辑。

步骤：如何设计一个实用的 Survey123 表单

步骤一：先确定采集目标和成果图层结构

在写 XLSForm 之前，先回答四个问题：

• 这个表单采集的是点、线、面，还是纯属性记录？
• 最终成果是用于制图展示、统计分析、巡查闭环，还是入库归档？
• 哪些字段必须填写，哪些字段可以自动计算？
• 哪些字段需要作为分类、筛选、专题图符号化的依据？

例如做“道路病害巡查”，至少需要位置、病害类型、严重程度、照片、发现时间、巡查人、备注等字段。如果后续要做统计，病害类型和严重程度就应该使用选择题，而不是自由文本。

步骤二：规划字段名，不要只看中文标签

Survey123 表单里的 label 可以写中文，但 name 建议使用英文、数字和下划线组合，并保持简短清晰。

不推荐	推荐	原因
道路病害类型	damage_type	中文字段名在跨系统处理时容易出现兼容问题
type	asset_type	避免过于通用，后期含义不清
是否有损坏?	has_damage	避免特殊字符，便于表达式引用

字段名一旦发布到要素图层，后期修改会比较麻烦。因此在 Survey123 表单设计阶段就要把字段命名当成数据建模来处理。

步骤三：在 survey 表中定义基础问题

下面是一个简化的道路病害巡查 XLSForm 示例：

type,name,label,required
start,start_time,开始时间,
end,end_time,结束时间,
geopoint,location,巡查位置,yes
text,road_name,道路名称,yes
select_one damage_type,damage_type,病害类型,yes
select_one damage_level,damage_level,严重程度,yes
image,photo,现场照片,yes
text,remark,备注,

其中 select_one damage_type 表示单选题，选项来自 choices 表中 list_name 为 damage_type 的记录。

步骤四：在 choices 表中设置选项编码

选择题不要只写显示文本，最好使用稳定的编码。这样导出数据后更适合统计、符号化和系统集成。

list_name,name,label
damage_type,pothole,坑槽
damage_type,crack,裂缝
damage_type,subsidence,沉陷
damage_level,low,轻微
damage_level,medium,中等
damage_level,high,严重

这里的 name 是实际存储值，label 是外业人员看到的文字。比如外业人员选择“裂缝”，图层中可以存储为 crack。这对后续接入 ArcGIS Pro、Python、PostGIS 或 WebGIS 系统都更友好。

步骤五：设置必填、约束和提示信息

Survey123 数据质量控制常用三列：required、constraint、constraint_message。

type,name,label,required,constraint,constraint_message
integer,width_cm,病害宽度厘米,yes,. > 0,宽度必须大于0
integer,length_cm,病害长度厘米,yes,. > 0,长度必须大于0
text,asset_id,设施编号,yes,string-length(.) >= 6,设施编号至少6位

约束的目的不是为难外业人员，而是在采集现场就拦截明显错误。比如宽度不能为负数，编号不能太短，日期不能晚于当前日期。

步骤六：使用 relevant 做条件显示

条件显示是 XLSForm 语法中最常用的功能之一。比如只有当“是否有损坏”为“是”时，才显示病害类型、严重程度和照片。

type,name,label,required,relevant
select_one yes_no,has_damage,是否有损坏,yes,
select_one damage_type,damage_type,病害类型,yes,${has_damage} = 'yes'
select_one damage_level,damage_level,严重程度,yes,${has_damage} = 'yes'
image,damage_photo,病害照片,yes,${has_damage} = 'yes'

这样可以减少无关字段干扰，让外业人员只填写当前场景需要的信息。注意：被隐藏的问题如果设置了必填，一般只有在显示时才会触发必填校验。

步骤七：使用 calculation 自动计算字段

自动计算字段适合存储时间、组合编号、面积等级、状态判断等信息。常见函数包括 now()、today()、concat()、pulldata() 等。

type,name,label,calculation
date,inspect_date,巡查日期,today()
text,record_code,记录编号,concat(${road_name}, '-', ${damage_type}, '-', format-date(now(), '%Y%m%d%H%M'))

如果计算字段不需要给外业人员查看，可以使用 hidden 类型保存后台字段：

type,name,label,calculation
hidden,submit_time,提交时间,now()

步骤八：使用 geopoint 获取空间位置

GIS 表单与普通问卷最大的区别是空间位置。常见位置字段类型是 geopoint：

type,name,label,required
geopoint,location,采集位置,yes

发布后，geopoint 通常会成为要素图层的几何字段。外业人员可以通过 GPS 获取当前位置，也可以在地图上手动调整点位。对于精度要求高的项目，需要在表单说明中明确采集规则，例如“站在设施正前方采点”或“采集病害中心点”。

步骤九：在 Survey123 Connect 中预览和发布

完成 XLSForm 后，建议按以下顺序检查：

1. 在 Survey123 Connect 中打开表单，确认没有语法错误。
2. 逐项预览问题顺序、标签、必填项和条件显示。
3. 模拟填写一条完整记录，检查计算字段是否正确。
4. 发布到测试环境，使用手机端实际采集一条数据。
5. 在 ArcGIS Online 或 ArcGIS Enterprise 中查看要素图层字段和附件。
6. 确认无误后再发布到正式外业团队。

常见坑：Survey123 XLSForm 最容易出错的地方

1. name 字段使用中文或特殊字符

中文标签没问题，但字段名建议使用英文小写和下划线。否则在导出、脚本处理、数据库同步、WebGIS 调用时可能增加兼容风险。

2. choices 表中的 list_name 和 survey 表不一致

如果 survey 表写的是 select_one damage_type，choices 表的 list_name 必须是 damage_type。多一个空格、大小写不一致或拼写错误，都会导致选项无法正常显示。

3. 条件表达式中引用了 label 而不是 name

表达式里要引用字段名和选项编码，不是显示文本。比如选项编码是 yes，标签是“是”，表达式应该写：

${has_damage} = 'yes'

不要写成：

${是否有损坏} = '是'

4. 先发布正式表单，后期再频繁改字段

Survey123 表单发布后会生成或关联要素图层。字段类型、字段名、选择题结构如果频繁变更，可能影响已有数据、报表模板和 Web 地图配置。正式发布前一定要留出测试阶段。

5. 多选题不适合所有统计场景

select_multiple 可以让用户选择多个选项，但其结果通常以分隔文本形式存储。对于需要严格分类统计、关联数据库或专题制图的场景，要提前评估是否改用重复组或多个布尔字段。

6. 照片字段没有控制数量和采集规范

照片是 Survey123 常用附件，但大量照片会增加同步压力和存储成本。建议在表单说明中明确照片角度、距离、是否需要近景和远景，并根据项目需要控制是否必填。

方法比较：Web Designer、Survey123 Connect 和其他采集方式怎么选

方式	适合场景	优点	限制
Survey123 Web Designer	简单问卷、快速发布	界面直观，上手快	复杂 XLSForm 逻辑支持有限
Survey123 Connect	专业外业调查、复杂表单	支持 XLSForm、条件显示、计算、级联选择、重复组	需要理解表格结构和表达式语法
Field Maps	地图驱动的设施编辑和巡检	适合直接在地图上查看和编辑要素	表单逻辑不如 Survey123 灵活
自研 WebGIS 表单	深度业务系统集成	可完全按业务定制	开发、维护和移动端适配成本高

如果你的任务以“问卷表单”为主，且需要严格控制填写逻辑，优先选择 Survey123 Connect。如果任务以“地图编辑和资产巡检”为主，Field Maps 可能更合适。如果需要接入复杂审批、权限、业务系统，再考虑自研 WebGIS 表单。

检查清单：发布 Survey123 表单前逐项核对

• 字段结构：字段名是否英文规范，字段类型是否符合后期分析需求。
• 空间位置：是否设置了 geopoint，采点规则是否清楚。
• 选择题：choices 表是否有稳定编码，是否避免只存中文自由文本。
• 必填项：关键字段是否设置 required，是否会影响隐藏字段逻辑。
• 约束条件：数值范围、日期范围、编号长度是否设置合理。
• 条件显示：relevant 表达式是否引用正确字段名和选项编码。
• 计算字段：calculation 是否能在预览和手机端正常运行。
• 照片附件：是否明确拍摄要求，是否评估同步流量和存储量。
• 测试数据：是否完成手机端真实采集测试，而不是只在电脑端预览。
• 后续使用：是否确认 ArcGIS Pro、Web 地图、仪表盘或脚本能正确读取字段。

FAQ：Survey123 表单设计常见问题

Survey123 表单一定要会 XLSForm 吗？

不一定。简单表单可以用 Survey123 Web Designer 完成。但如果你需要条件显示、自动计算、级联选择、复杂约束、隐藏字段或重复组，学习 XLSForm 语法会更高效，也更容易维护。

XLSForm 的 survey、choices、settings 哪个最重要？

三者都重要。survey 决定问题结构和逻辑，choices 决定选择题选项，settings 决定表单整体配置。初学者应先掌握 survey 和 choices，再逐步使用 settings 中的高级设置。

Survey123 表单设计时，字段名可以用中文吗？

技术上部分场景可以使用中文，但不推荐。更稳妥的做法是字段名用英文小写和下划线，中文写在 label 中。这样导出数据、写 ArcPy 或 Python 脚本、接入 PostGIS 和 WebGIS 时更方便。

select_one 和 select_multiple 有什么区别？

select_one 是单选，只能选择一个选项，适合病害类型、等级、状态等字段。select_multiple 是多选，适合多个现象同时存在的场景。但多选结果的统计和制图通常更复杂，使用前要考虑后期分析方式。

为什么 relevant 条件显示不生效？

常见原因有三个：字段名写错、选项编码写错、表达式中使用了中文标签而不是 name 值。建议先检查 survey 表中的字段名，再检查 choices 表中的选项编码，最后确认表达式是否类似 ${has_damage} = 'yes'。

Survey123 采集的照片存在哪里？

照片通常作为要素图层的附件存储在 ArcGIS Online 或 ArcGIS Enterprise 中。后期在 Web 地图、ArcGIS Pro、Dashboard 或数据导出时，需要注意附件是否一起导出或同步。

表单发布后还能修改 XLSForm 吗？

可以修改，但要谨慎。调整标签、提示文字、条件显示通常风险较低；修改字段名、字段类型、选项结构、重复组等可能影响已有数据和图层结构。正式项目建议先在测试表单中验证。

结论：好的 Survey123 表单等于一套数据质量规则

Survey123表单设计不是简单地把问题排进 Excel，而是把字段结构、外业流程、空间位置、质量控制和后期分析一起规划好。XLSForm 语法的价值就在于，它能把这些规则写成可执行的表单逻辑。

如果你刚开始学习，可以先掌握 type、name、label、required、constraint、relevant 和 calculation 这几类常用语法。等基础表单稳定后，再逐步使用级联选择、重复组、外部 CSV、动态默认值等高级能力。

对 GIS 项目来说，一个设计良好的 Survey123 表单，能在外业现场减少错误，在数据入库时减少清洗，在制图分析时提高一致性。这才是学习 XLSForm 语法最实际的意义。