Survey123表单设计?XLSForm怎么写?
如果你正在搜索“Survey123表单设计?XLSForm怎么写?”，大概率是已经知道 Survey123 可以做外业调查，但卡在 XLSForm 表格到底怎么组织、字段怎么写、约束和跳题逻辑怎么配置。本文以 GIS 外业采集场景为例，讲清楚 Survey123 表单设计的基本结构、常用字段写法、常见错误和发布前检查方法。
引言：Survey123表单设计为什么离不开XLSForm
ArcGIS Survey123 是 Esri 生态中常用的移动端表单采集工具，适合做巡查、核查、资产登记、灾害调查、样点记录等 GIS 外业任务。它的核心不是“画一个表单界面”，而是通过 XLSForm 定义字段、控件、逻辑、校验规则和提交到图层的属性结构。
简单说，XLSForm 就是一个 Excel 表格规范。你在 Excel 中写好字段类型、字段名称、显示标签、是否必填、取值约束、选择项、跳题逻辑，Survey123 Connect 会把它转换成可发布的调查表单。
对于 GIS 用户来说，正确设计 XLSForm 的价值主要有三点：
- 让外业人员按统一规则采集数据，减少漏填和错填。
- 让提交结果直接进入 ArcGIS Online 或 Portal 要素图层，便于制图、分析和共享。
- 通过约束、默认值、计算字段和地理位置字段，提高数据质量。
背景：XLSForm文件通常由哪几个工作表组成
在 Survey123 Connect 中新建高级模板后，你会看到一个 Excel 文件。最常用的 XLSForm 工作表包括 survey、choices 和 settings。
| 工作表 | 作用 | GIS表单设计中的典型用途 |
|---|---|---|
| survey | 定义表单问题、字段、控件、逻辑和校验规则 | 巡查编号、设施类型、坐标点、照片、备注、检查结果 |
| choices | 定义单选、多选、下拉列表的选项 | 设施类型、道路等级、问题类型、处理状态 |
| settings | 定义表单标题、表单ID、提交图层等整体配置 | 调查名称、实例名称、发布服务名称 |
其中最重要的是 survey 工作表。很多 Survey123 表单设计问题，其实都是 survey 表中的 type、name、label、required、constraint、relevant 这些列没有写对。
原理：XLSForm怎么写才能变成可用的GIS采集表
XLSForm 的基本原理是：每一行代表表单中的一个问题或一个结构控制项，每一列代表这个问题的属性。Survey123 Connect 会读取这些配置，生成移动端和网页端可填写的调查表。
survey表的核心列
| 列名 | 含义 | 示例 |
|---|---|---|
| type | 问题类型或控件类型 | text、integer、select_one facility_type、geopoint |
| name | 字段名，通常会成为图层字段名 | facility_id、check_date、status |
| label | 用户在表单中看到的问题文字 | 设施编号、检查日期、是否存在破损 |
| required | 是否必填 | yes |
| constraint | 填写约束 | . >= 0 |
| relevant | 跳题显示条件 | ${is_damaged}='yes' |
choices表的核心列
如果你在 survey 表中使用了 select_one 或 select_multiple，就必须在 choices 表中定义选项。
| 列名 | 含义 | 示例 |
|---|---|---|
| list_name | 选项列表名称，需要和 type 中的列表名一致 | facility_type |
| name | 实际存储值 | road_lamp |
| label | 显示给调查员看的文字 | 路灯 |
这里要特别注意：name 是入库值，label 是显示值。后续在 ArcGIS Pro、Web Map、Dashboard 或 Python 中统计时，通常处理的是 name 存储值。
步骤：从零写一个Survey123表单设计示例
下面用“市政设施巡查”作为示例，演示 XLSForm 怎么写。这个表单包含设施编号、设施类型、位置、是否损坏、损坏类型、照片和备注。
步骤1：在Survey123 Connect中新建高级表单
- 打开 Survey123 Connect。
- 点击新建调查。
- 选择高级模板或从 XLSForm 创建。
- 输入调查名称，例如“市政设施巡查”。
- 打开生成的 Excel XLSForm 文件。
如果你只是用网页设计器拖拽控件，可以完成简单表单。但只要涉及跳题、计算、复杂约束、重复记录、外部选择列表，建议使用 Survey123 Connect 和 XLSForm。
步骤2：编写survey工作表
在 survey 工作表中，可以按下面的方式组织字段。
| type | name | label | required | constraint | relevant |
|---|---|---|---|---|---|
text |
facility_id |
设施编号 |
yes |
||
select_one facility_type |
facility_type |
设施类型 |
yes |
||
geopoint |
location |
采集位置 |
yes |
||
select_one yes_no |
is_damaged |
是否损坏 |
yes |
||
select_multiple damage_type |
damage_type |
损坏类型 |
${is_damaged}='yes' |
||
image |
photo |
现场照片 |
${is_damaged}='yes' |
||
text |
remark |
备注 |
这个 Survey123 表单设计示例里，geopoint 用于采集空间位置，最终会成为 GIS 要素的几何位置；image 用于采集附件；relevant 用于控制“是否损坏”为“是”时才显示损坏类型和照片。
步骤3：编写choices工作表
在 choices 工作表中，选项列表名称必须和 survey 表中的 select_one facility_type、select_one yes_no、select_multiple damage_type 对应。
| list_name | name | label |
|---|---|---|
facility_type |
road_lamp |
路灯 |
facility_type |
manhole_cover |
井盖 |
facility_type |
traffic_sign |
交通标志 |
yes_no |
yes |
是 |
yes_no |
no |
否 |
damage_type |
broken |
破损 |
damage_type |
missing |
缺失 |
damage_type |
tilted |
倾斜 |
建议选项的 name 使用英文、小写、下划线，不要使用空格和特殊字符。这样后续在 ArcGIS Pro 符号化、Arcade 表达式、Python 脚本或 Dashboard 统计时更稳定。
步骤4：配置settings工作表
settings 工作表用于配置调查整体信息。常用列包括 form_title、form_id、instance_name。
| form_title | form_id | instance_name |
|---|---|---|
市政设施巡查 |
municipal_facility_check |
${facility_id} |
instance_name 决定提交记录在 Survey123 收件箱、草稿或已发送列表中的显示名称。对于外业调查，建议使用编号、名称或日期组合，而不是空值。
步骤5：添加必填、约束和提示信息
一个可用的 XLSForm 不只是能填写，还要能减少错误。常见校验列包括 required、constraint、constraint_message 和 hint。
| type | name | label | required | constraint | constraint_message | hint |
|---|---|---|---|---|---|---|
integer |
risk_level |
风险等级 |
yes |
. >= 1 and . <= 5 |
风险等级必须填写1到5之间的整数 |
1最低，5最高 |
这里的点号 . 表示当前问题的填写值。约束条件不满足时，Survey123 会阻止提交并显示提示信息。
步骤6：使用relevant实现跳题逻辑
跳题逻辑是 Survey123 表单设计中最常用的功能之一。比如只有当“是否损坏”为“是”时，才显示“损坏类型”。
${is_damaged}='yes'这段写在 damage_type 和 photo 字段的 relevant 列中。注意这里判断的是 choices 表里的 name 值，而不是中文 label 值。
步骤7：在Survey123 Connect中预览和发布
- 保存 Excel 文件。
- 回到 Survey123 Connect，等待表单自动刷新。
- 如果出现红色错误提示，先修正 XLSForm 再继续。
- 在预览窗口逐项填写，检查控件、必填项、跳题逻辑和照片附件。
- 确认无误后点击发布。
- 发布后到 ArcGIS Online 或 Portal 检查生成的要素图层字段。
发布前一定要确认字段名。Survey123 表单一旦发布并产生数据，后续随意修改字段名或字段类型，可能导致数据结构不一致，甚至影响已有服务。
常见坑：Survey123表单设计和XLSForm怎么写最容易出错
1. name字段使用中文或特殊字符
name 最好使用英文、数字和下划线，并且不要以数字开头。虽然某些情况下中文字段名能被识别，但在服务发布、脚本处理、跨系统共享时更容易出问题。
2. choices表的list_name和survey表不一致
如果 survey 表中写的是 select_one facility_type，那么 choices 表中必须有 list_name 为 facility_type 的选项。大小写、空格、拼写不一致都会导致表单无法正常显示。
3. relevant判断写成中文label
很多新手会写成：
${is_damaged}='是'如果 choices 表中 name 是 yes，正确写法应该是：
${is_damaged}='yes'XLSForm 逻辑表达式判断的是实际存储值，不是界面显示文字。
4. select_multiple后续统计不方便
select_multiple 适合多选，但它会把多个选项存储在同一个字段中。后续如果要在 ArcGIS Pro、Dashboard 或 Python 中按单个类型精确统计，需要额外拆分或使用表达式处理。
如果业务上每类问题都需要独立统计，可以考虑改成多个 select_one yes_no 字段，或者在后续数据处理中拆分多选结果。
5. geopoint没有考虑定位精度
geopoint 能采集点位，但外业数据质量不仅取决于字段类型，还取决于设备定位精度、采集环境、是否手动偏移和底图参考。对于精度要求高的项目，应配合高精度 GNSS 设备，并记录精度字段。
6. 发布后频繁改字段结构
Survey123 表单发布后，字段结构会和托管要素图层绑定。后续可以增加一些字段，但删除字段、改字段类型、改字段名都要谨慎。正式采集前，建议先用测试调查完整跑一遍流程。
方法比较：网页设计器、Survey123 Connect和XLSForm怎么选
| 方法 | 适合场景 | 优点 | 限制 |
|---|---|---|---|
| Survey123网页设计器 | 简单问卷、基础属性采集 | 上手快，不需要写 XLSForm | 复杂逻辑、外部列表、重复记录等能力有限 |
| Survey123 Connect | 专业外业调查、GIS资产巡查、复杂表单 | 支持完整 XLSForm，逻辑控制能力强 | 需要理解字段、表达式和表单结构 |
| 直接维护XLSForm模板 | 多项目复用、标准化采集、批量表单设计 | 结构清晰，便于版本管理和复制修改 | 对命名规范和测试流程要求更高 |
如果只是做一次简单信息收集，可以先用网页设计器。如果是 GIS 项目中的正式外业采集，尤其涉及位置、照片、跳题、质量控制和后续空间分析，建议直接使用 Survey123 Connect 编写 XLSForm。
检查清单：发布Survey123表单前必须核对什么
- 字段名：
name是否为英文、数字、下划线组合，是否避免重复。 - 字段类型：
text、integer、decimal、date、geopoint是否符合业务含义。 - 选项列表：
select_one和select_multiple是否在 choices 表中有对应列表。 - 必填项：关键字段是否设置
required。 - 约束条件：数值范围、日期范围、文本格式是否有
constraint。 - 跳题逻辑：
relevant是否使用 choices 表中的name值判断。 - 空间字段：是否配置了
geopoint，是否需要记录定位精度。 - 附件字段：照片、签名、文件上传是否符合外业网络和存储要求。
- 预览测试：是否在 Survey123 Connect 中完整填写过至少3条测试记录。
- 图层检查：发布后是否在 ArcGIS Online 或 Portal 中检查字段、域值、附件和空间位置。
FAQ：Survey123表单设计?XLSForm怎么写常见问题
Survey123表单设计一定要写XLSForm吗？
不一定。简单表单可以用网页设计器完成。但如果你需要复杂跳题、计算字段、重复记录、外部选择列表、批量维护模板，XLSForm 更适合。
XLSForm里的type、name、label分别是什么意思？
type 决定控件和数据类型，name 是字段名或变量名，label 是用户在表单界面看到的问题文字。GIS 项目中最需要谨慎设计的是 name，因为它通常会影响发布后的要素图层字段。
Survey123的select_one和select_multiple有什么区别？
select_one 是单选，只能选择一个选项；select_multiple 是多选，可以选择多个选项。多选适合现场问题类型勾选，但后期统计会比单选复杂。
XLSForm跳题逻辑relevant怎么写？
常见写法是 ${字段名}='选项name值'。例如 ${is_damaged}='yes' 表示只有“是否损坏”的存储值为 yes 时，当前问题才显示。
Survey123采集的位置是什么坐标系？
Survey123 采集的空间位置会进入 ArcGIS 平台的要素图层，通常在 Web GIS 环境中以 WGS 84 或 Web Mercator 相关方式显示和服务化。实际项目中应关注发布图层、底图和后续分析环境的坐标系统一，避免和本地投影数据直接混用时产生偏移或面积长度计算误差。
发布后的Survey123表单还能修改吗？
可以修改部分内容，例如标签、提示、部分逻辑和新增字段。但字段名、字段类型、选择列表结构等涉及数据模型的内容要谨慎。正式项目建议先做测试版，确认无误后再发布生产版。
结论：先设计数据结构，再写Survey123 XLSForm
Survey123 表单设计的关键不是把问题堆进表格，而是先想清楚 GIS 数据最终要怎么入库、怎么制图、怎么统计、怎么质检。XLSForm 怎么写，本质上是在把业务调查流程转换成可执行的数据采集规则。
实操时可以按这个顺序推进：先确定字段和空间类型，再写 survey 表；需要选择项时补充 choices 表；最后配置 settings 并在 Survey123 Connect 中反复预览测试。只要字段命名规范、选择列表一致、跳题逻辑清楚、发布前检查完整，一个稳定可用的 Survey123 外业采集表单就能搭建起来。