@getodk/web-forms

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

ODK Web Forms

原始使用文档
文档目录11 节
  1. Feature matrix
  2. Usage
  3. Plugin
  4. Props ( OdkWebFormsProps )
  5. Events ( OdkWebFormEmits )
  6. What if I don't use Vue?
  7. Development
  8. Project Structure
  9. Styling Overview
  10. Icons
  11. Translations

@getodk/web-forms

This package is a Vue component library that uses @getodk/xforms-engine to render ODK XForms. These forms are generally authored by end users in Excel using the XLSForm standard. Learn more on the ODK website and the ODK Web Form project's main README.

Feature matrix

This section is auto generated. Please update feature-matrix.json and then run npm run feature-matrix from the repository's root to update it.

Question types (basic functionality)
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜ 91%

Feature Progress
text✅
integer✅
decimal✅
note✅
select_one✅
select_multiple✅
select_*_from_file✅
repeat✅
group✅
geopoint✅
geotrace✅
geoshape✅
start-geopoint✅
range✅
image✅
barcode
audio✅
background-audio
video✅
file✅
date✅
time✅
datetime✅
rank✅
csv-external✅
acknowledge✅
start✅
end✅
today✅
deviceid✅
username✅
phonenumber✅
email✅
audit
Appearances
🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜ 56%

Feature Progress
numbers✅
multiline✅
url
ex:
thousands-sep✅
bearing
vertical
no-ticks
picker
rating✅
new
new-front
draw✅
annotate✅
signature✅
no-calendar
month-year✅
year✅
ethiopian
coptic
islamic
bikram-sambat
myanmar
persian
placement-map✅
maps✅
hide-input
minimal✅
search / autocomplete✅
quick✅
columns-pack✅
columns✅
columns-n✅
no-buttons✅
image-map
likert✅
map✅
field-list✅
label✅
list-nolabel✅
list✅
table-list✅
counter
hidden-answer
printer
masked✅
Parameters
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 66%

Feature Progress
randomize✅
seed✅
value✅
label✅
rows✅
geopoint capture-accuracy,
warning-accuracy, allow-mock-accuracy
✅
range start, end, step✅
image max-pixels✅
audio quality
Audit: location-priority,
location-min-interval, location-max-age,
track-changes, track-changes-reasons,
identify-user
geotrace/shape incremental=true
range labels, placeholder
Form logic
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 100%

Feature Progress
calculate✅
relevant✅
required✅
required message✅
custom constraint✅
constraint message✅
read only✅
dynamic defaults (including trigger
column)
✅
choice filter✅
default✅
repeat_count✅
create or update Entities✅
Descriptions and annotations
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜ 75%

Feature Progress
label✅
hint✅
guidance hint
form translations✅
form translations with ref to other
field
✅
Markdown✅
Inline HTML✅
image✅
big-image
audio✅
video✅
autoplay
Theme and layouts
🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜⬜ 50%

Feature Progress
grid
pages✅
logo
application translations✅
theme color
preview form✅
send instance✅
view instance
edit instance✅
table of contents
XPath
🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩⬜ 98%

Feature Progress
operators✅
predicates✅
axes✅
string(* arg)✅
concat(string arg*|node-set arg*)✅
join(string separator, node-set nodes*)✅
substr(string value, number start,
number end?)
✅
substring-before(string, string)✅
substring-after(string, string)✅
translate(string, string, string)✅
string-length(string arg)✅
normalize-space(string arg?)✅
contains(string haystack, string needle)✅
starts-with(string haystack, string
needle)
✅
ends-with(string haystack, string
needle)
✅
uuid(number?)✅
digest(string src, string algorithm,
string encoding?)
✅
pulldata(string instance_id, string
desired_element, string query_element,
string query)
✅
if(boolean condition, _ then, _ else)✅
coalesce(string arg1, string arg2)✅
once(string calc)✅
true()✅
false()✅
boolean(* arg)✅
boolean-from-string(string arg)✅
not(boolean arg)✅
regex(string value, string expression)✅
checklist(number min, number max, string
v*)
✅
weighted-checklist(number min, number
max, [string v, string w]*)
✅
number(* arg)✅
random()✅
int(number arg)✅
sum(node-set arg)✅
max(node-set arg*)✅
min(node-set arg*)✅
round(number arg, number decimals?)✅
pow(number value, number power)✅
log(number arg)✅
log10(number arg)✅
abs(number arg)✅
sin(number arg)✅
cos(number arg)✅
tan(number arg)✅
asin(number arg)✅
acos(number arg)✅
atan(number arg)✅
atan2(number arg, number arg)✅
sqrt(number arg)✅
exp(number arg)✅
exp10(number arg)✅
pi()✅
count(node-set arg)✅
count-non-empty(node-set arg)✅
position(node arg?)✅
instance(string id)✅
current()✅
randomize(node-set arg, number seed)✅
today()✅
now()✅
format-date(date value, string format)✅
format-date-time(dateTime value, string
format)
✅
date(* value)✅
decimal-date-time(dateTime value)✅
decimal-time(time value)✅
selected(string list, string value)✅
selected-at(string list, number index)✅
count-selected(node node)✅
jr:choice-name(node node, string value)✅
jr:itext(string id)✅
indexed-repeat(node-set arg, node-set
repeat1, number index1, [node-set
repeatN, number indexN]{0,2})
✅
area(node-set ns|geoshape gs)✅
distance(node-set ns|geoshape
gs|geotrace gt|(geopoint|string)
arg*)
✅
geofence(geopoint p, geoshape gs)✅
base64-decode(base64Binary input)✅
intersects(geoshape gs|geotrace gt)
Misc
🟩🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜⬜⬜ 44%

Feature Progress
last saved instance✅
defaults from query parameters✅
multi-form app-like experience
prevent multiple submissions✅
configure end of form experience
save as draft
offline entities
MBtiles / offline map layers
submission encryption✅

Usage

To use this library in a Vue.js application:

  1. Import @getodk/web-forms as a dependency in the application
  2. Install the exported plugin by adding app.use(WebFormsPlugin) in entry component (usually App.vue)
  3. Add the exported component anywhere in the application:
<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"
/>

Plugin

The plugin is there to initialize PrimeVue, currently it exposes no options. In the future, configuration options may be added to the plugin.

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

Props (OdkWebFormsProps)

The <OdkWebForm> component accepts the following props:

  • formXml (string, required): The XML of the ODK XForm to be rendered.
  • fetchFormAttachment (FetchFormAttachment, required): Function to fetch form attachments.
  • missingResourceBehavior (MissingResourceBehavior, optional): Defines behavior when resources are missing.
  • submissionMaxSize (number, optional): Maximum size for chunked submissions. Required when subscribing to submitChunked event.
  • attachmentMaxSize (number, optional, defaults to 100MB): Maximum size for submission attachments in bytes.
  • editInstance (EditInstanceOptions, optional): Options to resolve and load instance and attachment resources for editing.
  • preloadProperties (PreloadProperties, optional): Properties to make available for binding in the form using jr:preload.
  • deviceId (string, optional): If provided is available for binding into the form using preload attributes. Ignored if preloadProperties.deviceID is given.
  • instanceDefaults (InstanceDefaults, optional): Default values to set in the form as a map of xpath reference to string value.
  • lastSavedXml (string, optional): The XML to parse and bind to the last-saved virtual instance.

Events (OdkWebFormEmits)

The component emits the following events:

  • languageSelected: Emitted when the component changes the language that buttons and messages are displayed in. It is emitted when the form is loaded (defaulting to 'en'), and any time the user selects an option from the language selector.
    • Payload: ([language: string])
  • loaded: Emitted when the form is loaded and displayed to the user
  • submit: Emitted when the user presses the "Send" button on a valid form
    • Payload: ([submissionPayload: MonolithicInstancePayload, callback: HostSubmissionResultCallback])
  • submitChunked: Emitted for chunked submissions when the form is valid
    • Payload: ([submissionPayload: ChunkedInstancePayload, callback: HostSubmissionResultCallback])
    • Note: Requires submissionMaxSize prop to be set

What if I don't use Vue?

We will eventually publish a framework-agnostic custom element.

Development

To run in development, run this command at the monorepo root:

npm run dev -w=packages/web-forms

Individual test environments, and their corresponding watch modes, also have separate commands which can be found in package.json.

Project Structure

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

Styling Overview

This project uses a combination of PrimeFlex and PrimeVue for consistent styling, alongside specific font rules for the ODK Website's Web Forms Preview.

  • PrimeFlex: A CSS utility library used for layout-related properties such as positioning (e.g., flexbox, grid), responsive breakpoints, font-size and font-weight adjustments.
  • PrimeVue: A UI component library that defines the visual design of components, including shapes (e.g., borders, rounded corners) and color schemes.

Theming with CSS Variables

We use CSS variables for theming with two prefixes:

  • --p- Prefix: Variables prefixed with --p- (e.g., --p-primary-50) come from PrimeVue and control its component styles (e.g., colors, borders). These are part of PrimeVue’s theming system.
  • --odk- Prefix: Variables prefixed with --odk- (e.g., --odk-font-family) are custom to this project and manage styles outside PrimeVue or PrimeFlex, such as application-specific typography.

Z-Index Layering System

This package uses a centralized z-index layering system to manage UI stacking order, defined in src/assets/styles/style.scss. The ODK variables (e.g., --odk-z-index-error-banner) ensure elements like floating error messages, form controls, and overlays stack correctly without overlap.

  • Key layers:

    • --odk-z-index-base (background)
    • --odk-z-index-form-content (inputs, buttons)
    • --odk-z-index-form-floating (highlights, tooltips)
    • --odk-z-index-error-banner (floating errors)
    • --odk-z-index-overlay (modals)
    • --odk-z-index-topmost (loaders, notifications)
  • Usage: Apply with z-index: var(--odk-z-index-error-banner); on positioned elements (e.g., position: absolute).

Fonts

Form elements use font-family: Roboto, sans-serif; for accessibility and a clean, readable appearance.

Material Design

This package uses the Material Design system for the UI, though not strictly. The idea is to closely match the design to that of ODK Collect.

Icons

The IconSVG component renders Material Design Icons (MDI) with customizable size and style variants. It uses the @mdi/js library for icon data and supports a predefined set of icons.

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

To add a new icon:

  • Import the icon from @mdi/js in the IconSVG component.
  • Add the icon to the iconMap object with its corresponding name.
  • Use the icon by passing its name to the name prop.

Material Icons are available under the Apache License Version 2.0. Copy of the license can be found at ./src/assets/fonts/LICENSE-2.0.txt

Translations

Translations are managed on Transifex. Translators can contribute at: https://app.transifex.com/getodk/web_forms

For developers, see TRANSLATIONS.md for details on how UI strings are managed and how to add or update translations.

Pulling and pushing translations

Use the npm scripts in this package to sync with Transifex. From the repository root:

  • Pull translations from Transifex into locales/:
    npm run transifex:pull -w @getodk/web-forms
    
  • Push the English source strings (locales/strings_en.json) to 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 Web Forms

如何安装 @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 和提交记录判断。