# @getodk/web-forms 中文文档

规范地址：https://npmcn.com/package/%40getodk/web-forms/

版本：1\.1\.1
npm 元数据更新时间：2026-09-28T16:33:16.467Z
中文译文更新时间：2026-11-16T06:40:33.454Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40getodk/web-forms
原文对照：https://npmcn.com/package/%40getodk/web-forms/?lang=original
项目主页：https://getodk.org/
源码仓库：https://github.com/getodk/central-frontend

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6 MB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.20\.0
- 运行依赖：9 个
- peer 依赖：vue ^3\.5\.29
- 首次发布：2024-05-22T21:09:13.741Z
- 最新版本发布：2026-09-28T16:33:16.132Z
- 近 30 天下载量：2906（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 16 个）

## 中文简介

ODK 网络表格

## 安装

```sh
npm install @getodk/web-forms
```

也可以使用：`pnpm add @getodk/web-forms`、`yarn add @getodk/web-forms`、`bun add @getodk/web-forms`

## README

# @ getodk/ 网络窗体

此软件包是一个使用 Vue 组件库 [`@getodk/xforms-engine`](https://npmcn.com/package/%40getodk/xforms-engine/) 将提交 [ODK X 表格](https://getodk.github.io/xforms-spec/)。这些表格通常由 Excel 的最终用户使用 [XLS 格式](https://docs.getodk.org/xlsform/) 标准。 学多点 [在ODK网站上](https://getodk.org/) 和ODK网络表格项目 [主读取器](https://github.com/getodk/web-forms)。 。 。 .

## 特性矩阵

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

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

  

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

##### 外观  
\* 56%

  

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

##### 参数  
\* 66%

  

| 特性  | 进展 |
| --- | :-: |
| 随机 | ✅ |
| 种子 | ✅ |
| 价值 | ✅ |
| 标签 | ✅ |
| 行数 | ✅ |
| 地点捕捉精确度,  
警告精确度,允许- mock- 精确度 | ✅ |
| 区域开始、结束、步骤 | ✅ |
| [图像最大像素](https://github.com/getodk/web-forms/issues/397) | ✅ |
| 音频质量 |  |
| 审计:地点优先事项,  
位置- min- interval, 位置- 最大年龄,  
改变轨道 改变轨道的理由,  
识别用户 |  |
| [地轨/形状增量=真](https://github.com/getodk/web-forms/issues/562) |  |
| 区域标签、占位符 |  |

##### 形式逻辑  
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100%

  

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

##### 说明和说明  
——75%

  

| 特性  | 进展 |
| --- | :-: |
| 标签 | ✅ |
| 提示 | ✅ |
| [指导提示](https://github.com/getodk/web-forms/issues/53) |  |
| 窗体翻译 | ✅ |
| 表格翻译和参考其它  
字段 | ✅ |
| 标记 | ✅ |
| 内置 HTML | ✅ |
| [图像](https://github.com/getodk/web-forms/issues/30) | ✅ |
| 大图像 |  |
| [音频](https://github.com/getodk/web-forms/issues/30) | ✅ |
| [视频](https://github.com/getodk/web-forms/issues/30) | ✅ |
| 自动播放 |  |

##### 主题和布局  
🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜⬜ 50%

  

| 特性  | 进展 |
| --- | :-: |
| [网格](https://github.com/getodk/web-forms/issues/16) |  |
| [页次](https://github.com/getodk/web-forms/issues/254) | ✅ |
| [标志](https://github.com/getodk/web-forms/issues/353) |  |
| [应用程序翻译](https://github.com/getodk/web-forms/issues/332) | ✅ |
| [主题颜色](https://github.com/getodk/web-forms/issues/43) |  |
| 预览窗体 | ✅ |
| 发送实例 | ✅ |
| 视图实例 |  |
| 编辑实例 | ✅ |
| 目录 |  |

##### 十进制  
\* 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)](https://github.com/getodk/web-forms/issues/572) |  |

##### 杂项  
\* 44%

  

| 特性  | 进展 |
| --- | :-: |
| [上次保存实例](https://github.com/getodk/web-forms/issues/306) | ✅ |
| [从查询参数默认值](https://github.com/getodk/web-forms/issues/464) | ✅ |
| 多形式类似应用程序的经验 |  |
| [防止多次提交](https://github.com/getodk/web-forms/issues/461) | ✅ |
| 配置窗体体验的结束 |  |
| 保存为草稿 |  |
| 离线实体 |  |
| MBtiles / 离线映射层 |  |
| [提交加密](https://github.com/getodk/web-forms/issues/448) | ✅ |

## 使用量

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

1.  导入 `@getodk/web-forms` 作为申请中的依附关系
2.  通过添加安装导出插件 `app.use(WebFormsPlugin)` 输入组件(通常是 App.vue)
3.  在应用程序的任意位置添加导出组件 :

```html
<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的,目前它不会暴露任何选项. 将来,配置选项可能会被添加到插件中.

```js
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怎么办?

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

## 发展

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

```sh
npm run dev -w=packages/web-forms
```

单个测试环境及其相应的监视模式也有单独的指令,可以在 [`package.json`](https://npmcn.com/package/%40getodk/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
```

### 样式概览

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

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

#### 带有 CSS 变量的主题

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

-   `--p-` 前缀: 前缀的变量 `--p-` (例如, `--p-primary-50`)来自PrimeVue并控制其组件样式(如颜色,边框等). 这些是PrimeVue的一部分 [主题系统](https://primevue.org/theming/styled/)。 。 。 .
-   `--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 收藏](https://docs.getodk.org/collect-intro/)。 。 。 .

### 图标

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

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

要添加新图标 :

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

材料图标在Apache许可证2.0版本下提供. 许可证副本可在 [`./src/assets/fonts/LICENSE-2.0.txt`](https://npmcn.com/package/%40getodk/web-forms/src/assets/fonts/LICENSE-2.0.txt)

### 翻译

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

对于开发者,参见 [翻译:md](https://npmcn.com/package/%40getodk/web-forms/TRANSLATIONS.md) 关于如何管理 UI 字符串以及如何添加或更新翻译的详细信息.

#### 调出和推动翻译

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

-   从Transifex调取翻译到 `locales/`数字 :
    
    ```sh
    npm run transifex:pull -w @getodk/web-forms
    ```
    
-   按下英语源字符串( P)`locales/strings_en.json`() 至 Transifex:
    
    ```sh
    npm run transifex:push -w @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 和提交记录判断。

