Form

An enhanced native <form> supporting validation and submission of inner fields according to rules.

The data source is each field's value attribute (controlled mode). Fields validated by the form are oas-input / oas-textarea / oas-select / oas-auto-complete / oas-cascader / oas-tree-select / oas-input-number / oas-checkbox / oas-radio with a name (group containers are not involved). oas-input / oas-textarea / oas-input-number do not automatically write back to the value attribute while typing — listen to oas-input / oas-change events in script to sync; oas-select / oas-cascader / oas-tree-select write back by themselves on selection.

Feature Demo

The feature demo area only demonstrates field collection and submission, without validation rules.

Basic Usage

Collect & submit

Submit

Example

Without rules, submission performs no validation and dispatches oas-submit directly, with detail.values carrying the collected results of all fields with a name.

Mixed Controls

Mixed controls

Submit

Example

Validation

The validation area demonstrates rules-declared validation rules and failure feedback.

Validation rules: { required, message, minLength, maxLength, pattern }. On failure, the field is marked aria-invalid (red-bordered input), an error message is shown in red below the field, and oas-validate-fail is dispatched.

Required & Format Validation

Required & format validation

Submit

Example

Length Validation

minLength validation

Submit

Example

Disabled Fields Skip Validation

Disabled fields are not validated

Submit

Example

Submit & Validation-fail Events

submit / validate-fail

Submit

Example

Grid Form Layout

With layout="grid", the form element becomes a 24-column grid and oas-form-item spans columns via span (default 24 = full row); gap controls grid spacing, label-align positions the label (left / right / top, default top), and label-width sets the label column width for left/right. On validation failure, error messages are collected into the oas-form-item error slot (role="alert").

Two-Column Grid with Validation

Two-column grid layout

Submit

Example

label-align & label-width

Switch label-align

Example

Controlled syncing and event listeners (wired in one <script> block):

API

oas-form

Attribute	Description	Type	Default
gap	Grid spacing in grid mode (token value, e.g. var(--oas-space-4))	string	0
label-align	Label alignment: left / right / top (default top in grid mode)	string	top
label-width	Label column width when label-align is left/right	—	—
layout	Layout mode: vertical (default, stacked) / grid (24-column grid); non-enum values fall back to vertical	string	vertical
rules	Validation rules JSON: { 字段名: [{ required, message, minLength, maxLength, pattern }] }	Rules | string	{}

Event	Description
oas-submit	Validation passed, detail: { values }
oas-validate-fail	Validation failed, detail: { errors, values }

Name	Description
default	—

oas-form-item

Attribute	Description	Type	Default
label	Label text (no label row when omitted)	string	—
name	Field name (validation association)	—	—
required	Required asterisk (visual only; validation is still driven by form rules)	boolean	—
span	Columns spanned in the 24-column grid (only when form layout="grid"; non-integer in 1-24 → 24)	string	24

Name	Description
default	Field control

On validation failure, failed fields are marked aria-invalid; error messages can be retrieved via form.getErrors(). For fields wrapped in oas-form-item, the error text is collected into the form-item's error slot (role="alert").