@getodk/web-forms

中文文档
1.1.1发布于 2026/09/29Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 2906

ODK 网络表格

中文使用文档
文档目录11 节
  1. 特性矩阵
  2. 使用量
  3. 插件
  4. 道具( E) OdkWebFormsProps (中文(简体) )
  5. 活动 OdkWebFormEmits (中文(简体) )
  6. 如果我不用Vue怎么办?
  7. 发展
  8. 项目结构
  9. 样式概览
  10. 图标
  11. 翻译

@ getodk/ 网络窗体

此软件包是一个使用 Vue 组件库 @getodk/xforms-engine 将提交 ODK X 表格。这些表格通常由 Excel 的最终用户使用 XLS 格式 标准。 学多点 在ODK网站上 和ODK网络表格项目 主读取器。 。 。 .

特性矩阵

此区域是自动生成的 。 请更新 feature-matrix.json 然后运行 npm run feature-matrix 从寄存器的根来更新它.

问题类型(基本功能)
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜ 91 %

特性 进展
文本✅
整数✅
小数✅
说明✅
选择一✅
选择倍数( m)✅
从文件选中 {}✅
重复✅
组✅
地理点✅
地谱✅
地貌✅
起始点✅
范围✅
图像✅
条码
音频✅
背景音频
视频✅
文件✅
日期✅
时间✅
约会时间✅
军衔✅
csv - 外部✅
确认✅
开始✅
结束✅
{\fn华文楷体\fs16\1che0e0e0}今天✅
设备✅
用户名✅
电话号码✅
电子邮件✅
审计
外观
* 56%

特性 进展
数字✅
多线✅
url 密码
实例:
千兹普✅
显示
垂直
无
拾取器
评级✅
新设
新前页
绘图✅
注释✅
签名✅
无日历
月数✅
年份✅
美国
暗号
伊斯兰
比克拉姆桑巴特语name
阿曼玛
波斯语name
安置图✅
地图✅
隐藏输入
最小✅
搜索/ 自动完成✅
快点✅
列装✅
栏✅
栏n✅
无按钮✅
图像映射
喜欢✅
地图✅
字段列表✅
标签✅
列表- 无标签✅
列表✅
表格列表✅
计数器
隐藏回答
打印机
蒙上面具✅
参数
* 66%

特性 进展
随机✅
种子✅
价值✅
标签✅
行数✅
地点捕捉精确度,
警告精确度,允许- mock- 精确度
✅
区域开始、结束、步骤✅
图像最大像素✅
音频质量
审计:地点优先事项,
位置- min- interval, 位置- 最大年龄,
改变轨道 改变轨道的理由,
识别用户
地轨/形状增量=真
区域标签、占位符
形式逻辑
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100%

特性 进展
计算✅
相关✅
所需经费✅
需要的消息✅
自定义约束✅
约束信息✅
只读✅
动态默认(包括触发)
栏)
✅
选择过滤器✅
默认✅
重复计数✅
创建或更新实体✅
说明和说明
——75%

特性 进展
标签✅
提示✅
指导提示
窗体翻译✅
表格翻译和参考其它
字段
✅
标记✅
内置 HTML✅
图像✅
大图像
音频✅
视频✅
自动播放
主题和布局
🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜⬜ 50%

特性 进展
网格
页次✅
标志
应用程序翻译✅
主题颜色
预览窗体✅
发送实例✅
视图实例
编辑实例✅
目录
十进制
* 98%

特性 进展
运算符✅
前提✅
轴✅
字符串(* arg)✅
concat( 字符串 arg- node- set arg*)✅
加入( 字符串分隔符, 节点设置节点 *)✅
子字符串( 字符串值, 开始数字, ),
数字端?)
✅
子字符串前( 字符串, 字符串)✅
子字符串后( 字符串, 字符串)✅
翻译( 字符串、 字符串、 字符串)✅
字符串长度( 字符串参数)✅
正态空间( 字符串 ) ✅
包含( 字符串干草克, 字符串针头)✅
启动( 字符串干草ack, 字符串)
针头)
✅
端与( 字符串干草ack, 字符串)
针头)
✅
uuid( 数字 ) ✅
文摘(字符串、字符串算法,
字符串编码? )
✅
拉数据( 字符串实例 id, 字符串)
想要的元素, 字符串查询 元素,
字符串查询)
✅
如果( 布尔条件, 然后, 其它)✅
conesce( 字符串 arg1, 字符串 arg2)✅
一次( 字符串计算)✅
真( )✅
虚 ()✅
布尔(* arg)✅
布尔从字符串( 字符串)✅
不是(布尔参数)✅
regex( 字符串值, 字符串表达式)✅
清单( 分数、 最大数、 字符串)
页:1
✅
加权核对列表( 分数, 分数)
最大值, [字符串v, 字符串w] *)
✅
编号(* 参数)✅
随机( )✅
int( 数值)✅
和( 节点设置参数)✅
最大值( 节点设置参数 *)✅
分钟( 节点设置 arg *)✅
圆( 数字 arg, 小数 ?)✅
pow( 数字值, 数字功率)✅
日志( 数字 )✅
log10( 数值 )✅
abs( 数 )✅
辛( 数)✅
cos( 数 )✅
棕色( 数值 )✅
ain( 数值)✅
acos( 个数 )✅
atan( 数 )✅
aan2( 数值为 arg, 数字为 arg)✅
sqrt( 个数 )✅
exp( 数字 )✅
exp10( 数值)✅
pi () (中文(简体) )✅
计数( 节点设置参数)✅
计数非空( 节点设置 arg)✅
位置( 节点参数 ?)✅
实例(字符串 id)✅
当前( )✅
随机化( 节点设置参数, 编号种子)✅
今天( )✅
现在( )✅
格式- 日期( 日期值, 字符串格式)✅
格式- 日期- 时间( 时间值, 字符串)
格式)
✅
日期(* 数值)✅
小数- 日期- 时间( 时间值)✅
小数时间(时间值)✅
选中( 字符串列表, 字符串值)✅
所选( 字符串列表, 数字索引)✅
计数所选(节点)✅
jr: 选择名称( 节点, 字符串值)✅
jr: itext( 字符串 id)✅
已索引重排( 节点设置 arg, 节点设置)
重复 1, 数字索引1, [节点设置]
重复 N, 数字索引N]{0, 2})
✅
区域(节点设置 ns|geoshape gs)✅
相距( 节点设置 ns|geoshape)
gs|geotrace gt| (gopoint| string) (gopoint|ting) (gopoint| string) (gs|geotrace gt| (gopoint| string)) (gs|geotrace gt| (gopoint| string) ) (gs|gt| (gopoint| string) ) (gs| ) (geotrace ) (gs| ) (geotrace ) (geotrace gt| ) (geotrace ) (gt| )
参数*
✅
地缘(地点p,地貌克)✅
base64-decode (base64 基准输入)✅
相交点( geoshape gs|geotrace gt)
杂项
* 44%

特性 进展
上次保存实例✅
从查询参数默认值✅
多形式类似应用程序的经验
防止多次提交✅
配置窗体体验的结束
保存为草稿
离线实体
MBtiles / 离线映射层
提交加密✅

使用量

要在 Vue.js 应用程序中使用此库 :

  1. 导入 @getodk/web-forms 作为申请中的依附关系
  2. 通过添加安装导出插件 app.use(WebFormsPlugin) 输入组件(通常是 App.vue)
  3. 在应用程序的任意位置添加导出组件 :
<OdkWebForm
    :form-xml="formXml"
    :fetch-form-attachment="fetchAttachment"
    :missing-resource-behavior="missingBehavior"
    :submission-max-size="5242880"  <!-- 5MB -->
    :edit-instance="editOptions"
    :preload-properties="preloadProperties"
    :instance-defaults="instanceDefaults"
    :device-id="abc123"
    :last-saved-xml="lastSavedXml"
    @submit="handleSubmit"
    @submit-chunked="handleChunkedSubmit"
/>

插件

插件是用来初始化PrimeVue的,目前它不会暴露任何选项. 将来,配置选项可能会被添加到插件中.

import { WebFormsPlugin } from '@getodk/web-forms';
app.use(WebFormsPlugin);

道具( E)OdkWebFormsProps(中文(简体) )

这个 <OdkWebForm> 组件接受下列道具:

  • formXml (单位:千美元)string: ODK XForm 的 XML 将制取.
  • fetchFormAttachment (单位:千美元)FetchFormAttachment: 获取窗体附件的函数.
  • missingResourceBehavior (单位:千美元)MissingResourceBehavior,可选: 定义资源缺失时的行为 .
  • submissionMaxSize (单位:千美元)number:块状提交的最大尺寸。 签署时要求 submitChunked 活动.
  • attachmentMaxSize (单位:千美元)number,可选,默认为100MB): 以字节表示的提交附件的最大大小 .
  • editInstance (单位:千美元)EditInstanceOptions,可选):用于编辑的解决并加载实例和附件资源的选项.
  • preloadProperties (单位:千美元)PreloadProperties,可选: 使用 jr: preload 来装入表单的属性.
  • deviceId (单位:千美元)string,可选: 如果提供,可用预装属性装入表格。 如果 preloadProperties.deviceID 给出.
  • instanceDefaults (单位:千美元)InstanceDefaults,可选: 要设置在表单中的默认值为 xpath 引用字符串值的映射 .
  • lastSavedXml (单位:千美元)string,可选: 解析和绑定到最后保存的虚拟实例的 XML .

活动OdkWebFormEmits(中文(简体) )

该组件发布下列事件:

  • languageSelected: 当组件更改按键和信件中显示的语言时, 发送。 它在表单被加载( 默认为 “ en ” ) 时被放出, 用户随时从语言选择器中选择一个选项 .
    • 有效载荷:([语言:字符串])
  • loaded: 当窗体被装入并显示给用户时发出
  • submit: 用户在有效表格上按下“发送”按钮时发送
    • 有效载荷:([提交页载:单石式InstancePay载荷,回调:HostSubmissionResultCallback])
  • submitChunked: 当表格有效时, 被批量提交
    • 有效载荷:([提交费载:ChunkedInstancePayload,回调:HostSubmissionResultCallback])
    • 注:要求 submissionMaxSize 待设道具

如果我不用Vue怎么办?

我们最终将公布一个框架不可知的定制要素.

发展

要在开发中运行, 在单列波根运行此命令 :

npm run dev -w=packages/web-forms

单个测试环境及其相应的监视模式也有单独的指令,可以在 package.json。 。 。 .

项目结构

web-forms/
├── public/                   # Static assets (e.g., favicon.ico)
├── src/
│   ├── assets/
│   │   ├── images/           # Web Forms images
│   │   ├── styles/           # Web Forms styles
│   ├── components/           # UI components
│   │   ├── form-elements/    # Form elements or controllers (question types, hints, labels, inputs)
│   │   ├── form-layout/      # Form layout and rendering (e.g., form panel, groups, repeats, form error classes)
│   │   ├── common/           # Reusable smaller components (e.g., icon, image, checkbox components)
│   ├── lib/                  # Utilities
│   ├── index.ts
│   ├── web-forms-plugin.ts   # Vue plugin
├── tests/                    # Unit tests
├── e2e/                      # E2e tests
├── package.json
├── vite.config.ts
├── playwright.config.ts

样式概览

这个项目使用组合 缩写 财务报告和审定财务报表 首选项 用于一致的样式,与ODK网站网页表格预览的特定字体规则并列.

  • 缩写:用于定位(如:flexbox,网格)等与布局相关的属性,应答断点,字体大小和字体重量调整的 CSS 工具库.
  • 首选项:一个UI组件库,它定义了组件的外观设计,包括形状(例如边框,圆角)和颜色方案.

带有 CSS 变量的主题

我们使用 CSS 变量进行前缀:

  • --p- 前缀: 前缀的变量 --p- (例如, --p-primary-50)来自PrimeVue并控制其组件样式(如颜色,边框等). 这些是PrimeVue的一部分 主题系统。 。 。 .
  • --odk- 前缀: 前缀的变量 --odk- (例如, --odk-font-family)是本工程的自定义,管理PrimeVue或PrimeFlex以外的样式,如应用程序专用打字.

Z- Index 分层系统

此软件包使用集中式 z-index 管理 UI 堆放顺序的分层系统,定义于 src/assets/styles/style.scss。ODK变量(例如:, --odk-z-index-error-banner)确保诸如浮动错误消息,窗体控件等元素,并正确叠叠而无重叠.

  • 密钥层数字 :

    • --odk-z-index-base (背景情况)
    • --odk-z-index-form-content (输入,按钮)
    • --odk-z-index-form-floating (高亮,工具提示)
    • --odk-z-index-error-banner (浮动错误)
    • --odk-z-index-overlay (模式)
    • --odk-z-index-topmost (装载机,通知)
  • 使用量: 应用 z-index: var(--odk-z-index-error-banner); 关于定位要素(例如:, position: absolute) (中文(简体) ).

字体

使用的形式元素 font-family: Roboto, sans-serif; 以无障碍和清洁,可读的外观.

材料设计

本套件为UI使用材料设计系统,虽然不严格. 想法是将设计与 ODK 收藏。 。 。 .

图标

这个 IconSVG 组件使材料设计图标具有自定义大小和样式变体。 它使用 @mdi/js 用于图标数据的库,并支持一套预定义的图标.

<IconSVG name="mdiCamera" size="md" variant="primary" />

要添加新图标 :

  • 导入图标 @mdi/js 输入 IconSVG 组件.
  • 将图标添加到 iconMap 对象及其相应的名称.
  • 通过将图标的名称传递到 name 道具 (英语).

材料图标在Apache许可证2.0版本下提供. 许可证副本可在 ./src/assets/fonts/LICENSE-2.0.txt

翻译

翻译在Transifex上管理. 笔译员可以提供下列服务: https://app.transifex.com/getodk/web forms (中文(简体) )

对于开发者,参见 翻译:md 关于如何管理 UI 字符串以及如何添加或更新翻译的详细信息.

调出和推动翻译

使用此包中的 npm 脚本与 Transifex 同步 。 从寄存器根 :

  • 从Transifex调取翻译到 locales/数字 :
    npm run transifex:pull -w @getodk/web-forms
    
  • 按下英语源字符串( P)locales/strings_en.json() 至 Transifex:
    npm run transifex:push -w @getodk/web-forms
    

版本与发布记录

@getodk/web-forms 共发布 36 个版本,首次发布于 2024/05/23;过去 12 个月发布了 16 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.1.1latest2026/09/291 个月前
1.1.02026/09/112 个月前
1.0.32026/08/212 个月前
1.0.22026/08/113 个月前
1.0.12026/07/313 个月前
1.0.02026/07/044 个月前

关于 @getodk/web-forms 的常见问题

@getodk/web-forms 是什么?

ODK 网络表格

如何安装 @getodk/web-forms?

在项目目录运行 npm install @getodk/web-forms,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vue(^3.5.29)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getodk/web-forms 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getodk/web-forms 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@getodk/web-forms 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^24.20.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@getodk/web-forms 可以商用吗?

@getodk/web-forms 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@getodk/web-forms 的下载量有多少?

根据 npm 官方下载统计,@getodk/web-forms 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,906 次,日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getodk/web-forms 还在维护吗?

最新版本 1.1.1 发布于 2026/09/29(1 个月前);至今共发布 36 个版本,其中过去 12 个月发布了 16 个;首次发布于 2024/05/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。