# @formschema/native 中文文档

规范地址：https://npmcn.com/package/%40formschema/native/

版本：2\.0\.0-beta\.7
npm 元数据更新时间：2022-04-05T11:54:44.518Z
中文译文更新时间：2026-11-15T09:13:03.320Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40formschema/native
原文对照：https://npmcn.com/package/%40formschema/native/?lang=original
项目主页：https://gitlab.com/formschema/native
源码仓库：https://gitlab.com/formschema/native

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

- 包体积（解压后）：1.2 MB，21 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2018-06-27T05:11:24.342Z
- 最新版本发布：2022-03-24T06:26:14.232Z
- 近 30 天下载量：6649（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

基于 JSON Schema 的 Vue 组件格式

## 安装

```sh
npm install @formschema/native
```

也可以使用：`pnpm add @formschema/native`、`yarn add @formschema/native`、`bun add @formschema/native`

## README

# FormSchema 土著

基于 JSON Schema 和 原生 HTML 的 Vue 组件格式

[![npm](https://img.shields.io/npm/v/@formschema/native.svg)](https://www.npmjs.com/package/@formschema/native) [![Build status](https://gitlab.com/formschema/native/badges/master/pipeline.svg)](https://gitlab.com/formschema/native/pipelines?ref=master) [![Test coverage](https://gitlab.com/formschema/native/badges/master/coverage.svg)](https://gitlab.com/formschema/native/-/jobs)

## 目录

-   [安装](https://npmcn.com/package/%40formschema/native/#readme-install)
-   [演示](https://npmcn.com/package/%40formschema/native/#readme-demo)
-   [使用量](https://npmcn.com/package/%40formschema/native/#readme-usage)
-   [特征](https://npmcn.com/package/%40formschema/native/#readme-features)
-   [支持的关键词](https://npmcn.com/package/%40formschema/native/#readme-supported-keywords)
-   [无关(被忽略)关键词](https://npmcn.com/package/%40formschema/native/#readme-irrelevant-ignored-keywords)
-   [窗体化学式 API](https://npmcn.com/package/%40formschema/native/#readme-formschema-api)
    -   [道具](https://npmcn.com/package/%40formschema/native/#readme-props)
    -   [活动](https://npmcn.com/package/%40formschema/native/#readme-events)
    -   [方法](https://npmcn.com/package/%40formschema/native/#readme-methods)
        -   [表单( )](https://npmcn.com/package/%40formschema/native/#readme-form)
-   [与 Async Schema 合作](https://npmcn.com/package/%40formschema/native/#readme-working-with-async-schema)
-   [使用 Vue 路由器工作](https://npmcn.com/package/%40formschema/native/#readme-working-with-vue-router)
-   [与 JSON Schema $ref 指针合作](https://npmcn.com/package/%40formschema/native/#readme-workind-with-json-schema-ref-pointers)
-   [数据验证](https://npmcn.com/package/%40formschema/native/#readme-data-validation)
    -   [原生 HTML5 验证](https://npmcn.com/package/%40formschema/native/#readme-native-html5-validation)
    -   [自定义验证 API](https://npmcn.com/package/%40formschema/native/#readme-custom-validation-api)
    -   [自定义 AJV 验证](https://npmcn.com/package/%40formschema/native/#readme-custom-validation-with-ajv)
    -   [禁用本地 HTML5 验证](https://npmcn.com/package/%40formschema/native/#readme-disable-native-html5-validation)
        -   [示例: 使用 `novalidate`](https://npmcn.com/package/%40formschema/native/#readme-example-disable-form-validation-using-novalidate)
        -   [使用大小写: 执行保存、 取消和提交](https://npmcn.com/package/%40formschema/native/#readme-usecase-implement-save-cancel-and-submit)
-   [标签翻译](https://npmcn.com/package/%40formschema/native/#readme-labels-translation)
-   [渲染窗体元素](https://npmcn.com/package/%40formschema/native/#readme-render-form-elements)
    -   [文本区域](https://npmcn.com/package/%40formschema/native/#readme-textarea)
    -   [文件输入](https://npmcn.com/package/%40formschema/native/#readme-file-input)
    -   [隐藏输入](https://npmcn.com/package/%40formschema/native/#readme-hidden-input)
    -   [密码输入](https://npmcn.com/package/%40formschema/native/#readme-password-input)
    -   [多个复选框](https://npmcn.com/package/%40formschema/native/#readme-multiple-checkbox)
    -   [分组电台](https://npmcn.com/package/%40formschema/native/#readme-grouped-radio)
    -   [选择输入](https://npmcn.com/package/%40formschema/native/#readme-select-input)
    -   [矩阵输入](https://npmcn.com/package/%40formschema/native/#readme-array-input)
    -   [Regex 输入](https://npmcn.com/package/%40formschema/native/#readme-regex-input)
    -   [字段集元素](https://npmcn.com/package/%40formschema/native/#readme-fieldset-element)
-   [自定义窗体元素](https://npmcn.com/package/%40formschema/native/#readme-custom-form-elements)
    -   [要点 API](https://npmcn.com/package/%40formschema/native/#readme-elements-api)
    -   [自定义元素示例](https://npmcn.com/package/%40formschema/native/#readme-custom-elements-example)
-   [描述界面](https://npmcn.com/package/%40formschema/native/#readme-descriptor-interface)
-   [使用大小写](https://npmcn.com/package/%40formschema/native/#readme-usecases)
    -   [分组字段](https://npmcn.com/package/%40formschema/native/#readme-grouping-fields)
-   [捐款](https://npmcn.com/package/%40formschema/native/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40formschema/native/#readme-license)

## 安装

```sh
npm install --save @formschema/native
```

## 演示

-   [带有元素UI的演示](https://gitlab.com/formschema/components/elementui)

![formschema-demo-elementui](https://gitlab.com/formschema/components/elementui/raw/master/screenshot.png "FormSchema Demo with ElementUI")

## 使用量

```html
<template>
  <FormSchema :schema="schema" v-model="model" @submit.prevent="submit">
    <button type="submit">Subscribe</button>
  </FormSchema>
</template>

<script>
  import FormSchema from '@formschema/native'
  import schema from './schema/newsletter-subscription.json'

  export default {
    data: () => ({
      schema: schema,
      model: {}
    }),
    methods: {
      submit (e) {
        // this.model contains the valid data according your JSON Schema.
        // You can submit your model to the server here
      }
    },
    components: { FormSchema }
  }
</script>
```

## 特征

-   [应用带布尔逻辑的子化学键](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.7)
-   [任何实例类型的验证关键字](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1)  
    表单Schema使用:
    -   HTML 输入 `text` 以图图 `type: 'string'`
    -   HTML 输入 `number` 以图图 `type: 'number' | 'integer'`
    -   HTML 输入 `hidden` 以图图 `type: 'null'`
    -   HTML 输入 `checkbox` 以图图 `type: 'boolean'`
-   [数字实例关键词(数量和整数)](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2)  
    FormSchema 解析关键词 `maximum`, (中文(简体) ), `minimum`, (中文(简体) ), `exclusiveMaximum` 财务报告和审定财务报表 `exclusiveMinimum` 生成 HTML 属性 `max` 财务报告和审定财务报表 `min`。 。 。 .
-   [字符串验证关键词](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.3)  
    FormSchema 解析关键词 `maxLength`, (中文(简体) ), `minLength`, (中文(简体) ), `pattern` 生成 HTML 属性 `maxlength`, (中文(简体) ), `minlength` 财务报告和审定财务报表 `pattern`。 。 。 .
-   [阵列的验证关键字](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4)
-   [用"格式"进行语义验证](https://json-schema.org/latest/json-schema-validation.html#rfc.section.7)  
    表单Schema使用:
    -   HTML 输入 `date` 以图图 `format: 'date'`
    -   HTML 输入 `datetime-local` 以图图 `format: 'date-time'`
    -   HTML 输入 `email` 以图图 `format: 'email' | 'idn-email'`
    -   HTML 输入 `time` 以图图 `format: 'time'`
    -   HTML 输入 `url` 以图图 `format: 'uri'`
-   [字符串编码非JSON数据](https://json-schema.org/latest/json-schema-validation.html#rfc.section.8)
-   [财产依赖和Schema依赖](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.7)
-   [Schema 重新使用“ 定义 ”](https://json-schema.org/latest/json-schema-validation.html#rfc.section.9) (见 [JSON Schema $ref 指针](https://npmcn.com/package/%40formschema/native/#readme-json-schema-ref-pointers)(中文(简体) )
-   [Schema 说明](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10)

## 支持的关键词

-   [类型](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.1) 只有支持的字符串值。 不支持矩阵类型定义 .
-   [语句](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.2) 用于提供多个选项输入
-   [上限](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.2), (中文(简体) ), [专有马克西姆](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.3), (中文(简体) ), [最低](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.4) 财务报告和审定财务报表 [最小](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.5) 用于制取数值字段
-   [倍数](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.1) 用于渲染输入属性 `step`
-   [最大长度](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.3.1), (中文(简体) ), [分钟](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.3.2), (中文(简体) ), [模式](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.3.3) 财务报告和审定财务报表 [针头](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.3) 用于渲染字符串字段
-   [项目](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.1), (中文(简体) ), [额外 项目](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.2), (中文(简体) ), [最大项目](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.3), (中文(简体) ), [分钟项目](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.4) 财务报告和审定财务报表 [唯一项目](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.5) 用于渲染数组字段
-   [依赖关系](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.7) 用于执行 _财产依赖关系_ 财务报告和审定财务报表 _Schema 依赖关系_
-   [内容编码](https://json-schema.org/latest/json-schema-validation.html#rfc.section.8.3)
-   [内容介质Type](https://json-schema.org/latest/json-schema-validation.html#rfc.section.8.4)  
    -   何时 `contentMediaType` 等于 `text/*`, HTML 元素 `<textarea/>` 用于渲染
    -   何时 `contentMediaType` 不等同于 `text/*`, HTML 元素 `<input/>` 有属性 `{ type: file, accept: contentMediaType }` 用于渲染
-   [标题](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) 用于渲染输入标签
-   [说明](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) 用于提供输入描述
-   [默认](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10.2) 用于定义默认输入值
-   [仅读](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10.3) 用于将字段作为只读输入

## 无关(被忽略)关键词

由于FormSchema只是一个表单生成器,一些JSON Schema验证关键字 无关 :

-   [包含](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.6)
-   [最大收益](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.1)
-   [收益](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.2)
-   [特性](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.5)
-   [额外收益](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.6)
-   [属性名称](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.8)
-   [没有](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.7.4)
-   [只写](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10.3)
-   [实例](https://json-schema.org/latest/json-schema-validation.html#rfc.section.10.4)

## 窗体化学式 API

### 道具

| 名称 | 类型 | 说明 | 默认 |
| --- | --- | --- | --- |
| `schema` _所需经费_ | `Object` | 输入 JSON Schema 对象 . |  |
| `v-model` | `any` | 使用此指令来创建带有组件的双向数据绑定. 它会自动选择正确的方法来根据输入类型更新元素. | `undefined` |
| `id` | `String` | 元素界面的id属性代表了窗体的标识符,反映了id全局属性. | `Random unique ID` |
| `name` | `String` | 所出形式之名. 它必须是文件表格中独一无二的. | `undefined` |
| `bracketed-object-input-name` | `Boolean` | 设定为 `true` (default),复选框输入和嵌入对象输入将 \* 自动在名字结尾处加入括号(例如. `name="grouped-checkbox-fields[]"`) (中文(简体) ). 设置此属性为 `false`,禁用此行为. | `true` |
| `search` | `Boolean` | 使用此道具启用 `search` 用于查找网页、网站或网站收藏的网页的一栏. | `false` |
| `disabled` | `Boolean` | 说明形式元素是否被禁用. | `false` |
| `components` | `ComponentsLib` | 使用此道具覆盖带有自定义组件的默认本地 HTML 元素 . | `GLOBAL.Elements` |
| `descriptor` | [`DescriptorInstance`](https://npmcn.com/package/%40formschema/native/#readme-descriptor-interface) | UI Schema 描述器用于渲染. | `{}` |
| `validator` | `Function` | 用于在发送数据前验证数据的验证器功能 `input` 活动.  
**语法**  
`function validator(field: GenericField): Promise<boolean>`  
**参数**  
-   `field: GenericField` 请求验证的字段
-   `field.id: string` 输入 ID 属性值
-   `field.name: string` 输入名称属性值
-   `field.value: any` 校验输入值
-   `field.schema: JsonSchema` 输入的 JSON Schema 对象
-   `field.required: boolean` 布尔表示是否强制字段
-   `field.hasChildren: boolean` 布尔表示字段是否有孩子
-   `field.initialValue: any` 初始输入值
-   `field.messages: Message[]` 校验输入值

**返回值**  
回来的承诺 `true` 如果验证成功 `false` 否则  
 | `null` |

### 活动

| 名称 | 说明 |
| --- | --- |
| `input` | 当元素值被改变时同步被点燃.  
**参数**  
-   **`value: any`**

 |

### 方法

#### 表单( )

获取 HTML 窗体对象引用 .

**示例**

```html
<template>
  <FormSchema ref="formSchema" :schema="schema"/>
</template>

<script>
  import FormSchema from '@formschema/native'

  export default {
    components: { FormSchema },
    data: () => ({
      schema: { type: 'string' }
    }),
    mounted() {
      console.log(this.$refs.formSchema.form())
    }
  };
</script>
```

**语法**

```typescript
form(): HTMLFormElement | VNode | undefined
```

**返回值**

一个 `HTMLFormElement` 对象或一个 `VNode` 描述窗体元素的对象 对象,或 `undefined` 用于输入 JSON 计划对象.

## 与 Async Schema 合作

```html
<template>
  <FormSchema :schema="schema"/>
</template>

<script>
  import axios from 'axios'
  import FormSchema from '@formschema/native'

  export default {
    components: { FormSchema },
    data: () => ({
      schema: {}
    }),
    created() {
      axios.get('/api/schema/subscription.json').then(({ data: schema }) => {
        this.schema = schema
      });
    }
  };
</script>
```

## 使用 Vue 路由器工作

装入同步计划 `beforeRouterEnter` 钩:

```html
<template>
  <FormSchema :schema="schema"/>
</template>

<script>
  import axios from 'axios'
  import FormSchema from '@formschema/native'

  export default {
    components: { FormSchema },
    data: () => ({
      schema: {}
    }),
    beforeRouterEnter(from, to, next) {
      axios.get('/api/schema/subscription.json')
        .then(({ data: schema }) => next((vm) => vm.setSchema(schema)))
        .catch(next);
    },
    methods: {
      setSchema(schema) {
        this.schema = schema;
      }
    }
  };
</script>
```

## 与 JSON Schema $ref 指针合作

用 JSON Schema 装入 `$ref` 指针,您需要安装额外的 解决这些困难的依赖性:

```js
import $RefParser from 'json-schema-ref-parser';
import FormSchema from '@formschema/native';
import schemaWithPointers from './schema/with-pointers.json';

export default {
  components: { FormSchema },
  data: () => ({
    schema: {}
  }),
  created () {
    $RefParser.dereference(schemaWithPointers)
      .then((schema) => {
        // `schema` is the resolved schema that contains your entire JSON
        // Schema, including referenced files, combined into a single object
        this.schema = schema;
      });
  }
}
```

见 [json-schema-ref-parser 文档页面](https://www.npmjs.com/package/json-schema-ref-parser) 更多细节.

## 与 `allOf` 关键词

装入 JSON Schema 包含 `allOf` 关键字,需要安装 额外扶养 [json - schema - 综合起来](https://www.npmjs.com/package/json-schema-merge-allof) 帮助FormSchema正常工作:

```js
import mergeAllOf from 'json-schema-merge-allof';
import FormSchema from '@formschema/native';
import schemaWithAllof from './schema/with-allof.json';

export default {
  components: { FormSchema },
  data: () => ({
    schema: mergeAllOf(schemaWithAllof)
  })
}
```

见 [json-sema-commerce- all of 文档页面](https://www.npmjs.com/package/json-schema-merge-allof) 更多细节.

## 数据验证

### 原生 HTML5 验证

默认情况下, FormSchema 通过应用验证使用基本的 HTML5 验证 属性。 这已经足够简单的计划了 但你需要 如果您想要验证复杂的方案, 请指定 JSON Schema 验证器 .

### 自定义验证 API

对于自定义验证,您需要提供 [验证函数道具](https://npmcn.com/package/%40formschema/native/#readme-props)。 。 。 .

Bellow 自定义验证 API :

```ts
type MessageInfo = 0;
type MessageSuccess = 1;
type MessageWarining = 2;
type MessageError = 3;
type MessageType = MessageInfo | MessageSuccess | MessageWarining | MessageError;

interface Message {
  type?: MessageType;
  text: string;
}

interface GenericField<TModel = any> {
  readonly id: string;
  readonly key: string;
  readonly name: string;
  readonly isRoot: boolean;
  readonly schema: JsonSchema;
  readonly required: boolean;
  readonly hasChildren: boolean;
  readonly initialValue: TModel;
  readonly value: TModel;
  readonly messages: Required<Message>[];
  clear(): void; // clear field
  reset(): void; // reset initial field value
  addMessage(message: string, type: MessageType = MessageError): void;
  clearMessages(recursive: boolean = false): void;
}
```

### 自定义 AJV 验证

贝洛是受欢迎的榜样 [阿联酋](https://www.npmjs.com/package/ajv) 验证符 :

```html
<template>
  <FormSchema v-model="model" v-bind="{ schema, validator }" @submit.prevent="onSubmit">
    <button type="submit">Submit</button>
  </FormSchema>
</template>

<script>
  import Ajv from 'ajv';
  import FormSchema from '@formschema/native';

  export default {
    data: () => ({
      schema: {
        type: 'object',
        properties: {
          username: {
            type: 'string',
            minLength: 5
          },
          password: {
            type: 'string',
            minLength: 6
          }
        },
        required: ['username', 'password']
      },
      model: {},
      ajv: new Ajv({ allErrors: true })
    }),
    computed: {
      validate() {
        return this.ajv.compile(this.schema);
      }
    },
    methods: {
      onSubmit({ field }) {
        if (field && this.validator(field)) {
          // validation success, submit code here
        }
      },
      validator(field) {
        // Clear all messages
        field.clearMessages(true);

        if (!this.validate(field.value)) {
          this.validate.errors.forEach(({ dataPath, message }) => {
            const errorField = field.hasChildren
              ? field.getField(dataPath) || field
              : field;

            /**
             * Add a message to `errorField`.
             * The first argument is the message string
             * and the second one the message type:
             *    0 - Message Info
             *    1 - Message Success
             *    2 - Message Warning
             *    3 - Message Error
             */
            errorField.addMessage(message, 3);
          });

          // Return `false` to cancel the `input` event
          return Promise.resolve(false);
        }

        // Return `true` to trigger the `input` event
        return Promise.resolve(true);
      }
    },
    components: { FormSchema }
  };
</script>
```

### 禁用本地 HTML5 验证

由于FormSchema使用本地 HTML 窗体元素, 属性 `novalidate` 财务报告和审定财务报表 `formvalidate` 可用于按 [W3C 规格](https://dev.w3.org/html5/spec-LC/association-of-controls-and-forms.html#attr-fs-novalidate)数字 :

> 如果存在,它们表示表格在下列情况下不予验证: 提交.  
> 这个 **无效状态** 如果元素是 [提交按钮](https://dev.w3.org/html5/spec-LC/forms.html#concept-submit-button) 和元素的 `formnovalidate` 属性是存在的,或者如果元素是 [窗体所有者](https://dev.w3.org/html5/spec-LC/association-of-controls-and-forms.html#form-owner)是因为 `novalidate` 属性存在,以及 `false` 否则.

#### 示例: 使用 `novalidate`

```html
<template>
  <FormSchema v-model="model" :schema="schema" novalidate>
    <button type="submit">Submit</button>
  </FormSchema>
</template>
```

#### 使用大小写: 执行保存、 取消和提交

禁用窗体验证限制在执行时可能有用 _保存_ 窗体的特性 :

-   用户应该能够保存进度,尽管他们还没有完全输入表格中的数据
-   用户应当能够取消已保存的窗体数据
-   用户应能够提交经验证的表格数据

```html
<template>
  <FormSchema v-model="model" :schema="schema" action="/api/blog/post" method="post">
    <input type="submit" name="submit" value="Submit">
    <input type="submit" formnovalidate name="save" value="Save">
    <input type="submit" formnovalidate name="cancel" value="Cancel">
  </FormSchema>
</template>
```

## 标签翻译

翻译标签而不更改 JSON Schema 文件的简单方法是 使用描述符.

举个例子 [第一十八号](https://kazupon.github.io/vue-i18n)数字 :

```html
<template>
  <FormSchema v-model="model" :schema="schema" :descriptor="descriptor"/>
</template>

<script>
  import FormSchema from '@formschema/native';

  export default {
    data: () => ({
      schema: {
        type: 'object',
        properties: {
          firstname: {
            type: 'string'
          },
          lastname: {
            type: 'string'
          }
        }
      },
      model: {}
    }),
    computed: {
      descriptor() {
        properties: {
          firstname: {
            label: this.$t('firstname.label'),
            helper: this.$t('firstname.helper')
          },
          lastname: {
            label: this.$t('lastname.label'),
            helper: this.$t('lastname.helper')
          }
        }
      }
    },
    // `i18n` option, setup locale info for component
    // see https://kazupon.github.io/vue-i18n/guide/component.html
    i18n: {
      messages: {
        en: {
          firstname: {
            label: 'First Name',
            helper: 'Your First Name'
          },
          lastname: {
            label: 'Last Name',
            helper: 'Your Last Name'
          }
        },
        fr: {
          firstname: {
            label: 'Prénom',
            helper: 'Votre prénom'
          },
          lastname: {
            label: 'Nom',
            helper: 'Votre nom'
          }
        }
      }
    },
    components: { FormSchema }
  };
</script>
```

## 渲染窗体元素

### 文本区域

添加一个 `text/*` 媒体键入字符串计划以制取文本区域元素.

**实例 schema.json**

```json
{
  "type": "string",
  "contentMediaType": "text/plain"
}
```

您也可以使用描述符来强制 Render 使用文本区域 元素 :

**示例描述符.json**

```json
{
  "kind": "textarea"
}
```

### 文件输入

使用媒体类型的字符串计划,而不是从头开始 `text/*` 作为输入文件元素自动渲染.

**实例 schema.json**

```json
{
  "type": "string",
  "contentMediaType": "image/png"
}
```

> 有一个列表 [IANA正式登记的MIME类型](http://www.iana.org/assignments/media-types/media-types.xhtml), (中文(简体) ), 但所支持的一组类型将是应用程序和操作系统 依赖。 Mozilla开发者网络也维护一个 [对网络重要的 MIME 类型列表](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)。 。 。 .

### 隐藏输入

带有描述符的图案 `hidden` 作为隐藏输入元素.

**实例 schema.json**

```json
{
  "type": "string"
}
```

**示例描述符.json**

```json
{
  "kind": "hidden"
}
```

### 密码输入

带有描述器的字符串计划 `password` 用于提供输入 密码元素.

**实例 schema.json**

```json
{
  "type": "string"
}
```

**示例描述符.json**

```json
{
  "kind": "password"
}
```

### 多个复选框

要定义多个复选框,请使用 [JSON Schema 关键词 `enum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.23) 财务报告和审定财务报表 [唯一项目](https://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4.5)数字 :

**实例 schema.json**

```json
{
  "type": "array",
  "uniqueItems": true,
  "enum": {
    "type": "string",
    "enum": [
      "daily",
      "promotion"
    ]
  }
}
```

**示例描述符.json**

```json
{
  "items": {
    "daily": {
      "label": "Receive daily updates"
    },
    "promotion": {
      "label": "Receive promotion emails"
    }
  }
}
```

### 分组电台

组合无线电元件,请使用 [JSON Schema 关键词 `enum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.23) 带有 `enum` 描述符 :

**实例 schema.json**

```json
{
  "type": "string",
  "enum": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday",
    "saturday",
    "sunday"
  ]
}
```

**示例描述符.json**

```json
{
  "kind": "enum",
  "items": {
    "monday": { "label": "Monday" },
    "tuesday": { "label": "Tuesday" },
    "wednesday": { "label": "Wednesday" },
    "thursday": { "label": "Thursday" },
    "friday": { "label": "Friday" },
    "saturday": { "label": "Saturday" },
    "sunday": { "label": "Sunday" }
  }
}
```

### 选择输入

组合 HTML 选择元素,使用 [JSON Schema 关键词 `enum`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.23) 带有 `list` 描述符 :

**实例 schema.json**

```json
{
  "type": "string",
  "enum": [
    "monday",
    "tuesday",
    "wednesday",
    "thruday",
    "friday",
    "saturday",
    "sunday"
  ]
}
```

**示例描述符.json**

```json
{
  "kind": "list",
  "items": {
    "monday": { "label": "Monday" },
    "tuesday": { "label": "Tuesday" },
    "wednesday": { "label": "Wednesday" },
    "thursday": { "label": "Thursday" },
    "friday": { "label": "Friday" },
    "saturday": { "label": "Saturday" },
    "sunday": { "label": "Sunday" }
  }
}
```

### 矩阵输入

制作 [阵列字段](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4),定义您的计划,如:

**实例 schema.json**

```json
{
  "type": "array",
  "items": {
    "type": "string"
  }
}
```

`FormSchema` 将添加一个按钮以添加更多输入,从而提供文本输入.

### Regex 输入

制作 [正则输入](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.3.3), (中文(简体) ), 定义您的计划如下:

**实例 schema.json**

```json
{
  "type": "string",
  "pattern": "[a-e]+"
}
```

### 字段集元素

表单Schema 使用 a `<fieldset>` 元素到对象 JSON Schema 的组输入:

**实例 schema.json**

```json
{
  "type": "object",
  "properties": {
    "firstname": {
      "type": "string"
    },
    "lastname": {
      "type": "string"
    }
  },
  "required": ["firstname"]
}
```

使用描述符设置标签和助手 。 也可以改变顺序 用于渲染的属性 :

**示例描述符.json**

```json
{
  "properties": {
    "firstname": {
      "label": "First Name",
      "helper": "Your first name"
    },
    "lastname": {
      "label": "Last Name",
      "helper": "Your last name"
    }
  },
  "order": ["lastname", "firstname"]
}
```

## 自定义窗体元素

### 要点 API

```ts
type SchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
type ScalarKind = 'string' | 'password' | 'number' | 'integer' | 'null' | 'boolean' | 'hidden' | 'textarea' | 'image' | 'file' | 'radio' | 'checkbox';
type ItemKind = 'enum' | 'list';
type FieldKind = SchemaType | ScalarKind | ItemKind;
type ComponentsType = 'form' | 'message' | 'button' | 'helper' | FieldKind;
type Component = string | VueComponent | VueAsyncComponent;

interface IComponents {
  set(kind: ComponentsType, component: Component): void;
  get(kind: ComponentsType, fallbackComponent?: Component): Component;
}
```

### 自定义元素示例

要定义自定义元素, 您需要使用 `NativeComponents` 类和 `components` 道具 :

```js
// MyCustomComponents.js

// First, import the base class Components from `@formschema/native` package
import { NativeComponents } from '@formschema/native';

// Then declare your custom components as functional components
import { InputElement } from '@/components/InputElement';
import { StateElement } from '@/components/StateElement';
import { ArrayElement } from '@/components/ArrayElement';
import { FieldsetElement } from '@/components/FieldsetElement';
import { ListElement } from '@/components/ListElement';
import { TextareaElement } from '@/components/TextareaElement';
import { MessageElement } from '@/components/Message';

// Finaly, extend the NativeComponents class and define override it
export class MyCustomComponents extends NativeComponents {
  constructor() {
    super();

    this.set('array', ArrayElement);
    this.set('boolean', StateElement);
    this.set('string', InputElement);
    this.set('password', InputElement);
    this.set('file', InputElement);
    this.set('image', InputElement);
    this.set('radio', StateElement);
    this.set('checkbox', StateElement);
    this.set('enum', FieldsetElement);
    this.set('number', InputElement);
    this.set('integer', InputElement);
    this.set('object', FieldsetElement);
    this.set('list', ListElement);
    this.set('textarea', TextareaElement);
    this.set('message', MessageElement);
  }
}
```

> 见文件 [原生组件.ts](https://gitlab.com/formschema/native/blob/master/src/lib/NativeComponents.ts) 举个例子.

```html
<template>
  <FormSchema v-model="model" :schema="schema" :components="components"/>
</template>

<script>
  import FormSchema from '@formschema/native'
  import { MyCustomComponents } from './MyCustomComponents'

  export default {
    data: () => ({
      schema: { /* ... */ },
      components: new MyCustomComponents(),
      model: {}
    }),
    components: { FormSchema }
  }
</script>
```

### Vue 元件示例

-   资料来源: [元素/虚拟元件.js](https://gitlab.com/formschema/native/blob/master/elements/VueMaterial.js)

```html
<template>
  <FormSchema v-model="model" :schema="schema" :components="components"/>
</template>

<script>
  import FormSchema, { NativeComponents } from '@formschema/native'
  import createComponents from '@formschema/native/elements/VueMaterial'

  export default {
    data: () => ({
      schema: { /* ... */ },
      components: createComponents(NativeComponents),
      model: {}
    }),
    components: { FormSchema }
  }
</script>
```

## 描述界面

```ts
type SchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
type ParserKind = SchemaType | 'enum' | 'list' | 'textarea' | 'image' | 'file' | 'password';
type ScalarKind = 'string' | 'password' | 'number' | 'integer' | 'null' | 'boolean' | 'hidden' | 'textarea' | 'image' | 'file' | 'radio' | 'checkbox';
type ItemKind = 'enum' | 'list';
type FieldKind = SchemaType | ScalarKind | ItemKind;
type ComponentsType = 'form' | 'message' | 'button' | 'helper' | FieldKind;
type Component = string | VueComponent | AsyncVueComponent;

type SetDescriptor = EnumDescriptor | ArrayDescriptor | ObjectDescriptor;
type Descriptor = ScalarDescriptor | SetDescriptor | ListDescriptor;
type DescriptorConstructor = (field: Field) => Descriptor;
type DescriptorInstance = Descriptor | DescriptorConstructor;

interface DescriptorDefinition<TKind extends FieldKind = FieldKind> {
  kind?: TKind;
  label?: string;
  helper?: string;
  visible?: boolean; // by default true. If false, component will be ignored on rendering
  component?: Component;
  attrs?: {
    [attr: string]: unknown;
  };
  props?: {
    [prop: string]: unknown;
  };
}

/**
 * Describe scalar types like: string, password, number, integer,
 * boolean, null, hidden field, textarea element, image and file
 * inputs, radio and checkbox elements
 */
interface ScalarDescriptor extends DescriptorDefinition<ScalarKind> {
}

/**
 * Use to describe grouped object properties
 */
interface ObjectGroupDescriptor extends DescriptorDefinition {
  properties: string[];
}

/**
 * Describe JSON Schema with type `object`
 */
interface ObjectDescriptor extends DescriptorDefinition {
  layout?: Component; // default: 'fieldset'
  properties?: {
    [schemaProperty: string]: DescriptorInstance;
  };
  order?: string[];
  groups?: {
    [groupId: string]: ObjectGroupDescriptor;
  };
}

/**
 * Describe JSON Schema with key `enum`
 */
interface ItemsDescriptor<TKind extends ItemKind> extends DescriptorDefinition<TKind> {
  items?: {
    [itemValue: string]: ScalarDescriptor;
  };
}

/**
 * Describe HTML Radio Elements
 */
interface EnumDescriptor extends ItemsDescriptor<'enum'> {
  layout?: Component; // default: 'fieldset'
}

/**
 * Describe HTML Select Element
 */
interface ListDescriptor extends ItemsDescriptor<'list'> {
}

/**
 * Describe buttons for array schema
 */
interface ButtonDescriptor<T extends string, A extends Function> extends Partial<ActionButton<A>> {
  type: T;
  label: string;
  tooltip?: string;
  visible?: boolean;
  component?: Component;
}

type ActionPushTrigger = () => void;

type PushButtonDescriptor = ButtonDescriptor<'push', ActionPushTrigger>;
type MoveUpButtonDescriptor = ButtonDescriptor<'moveUp', ActionPushTrigger>;
type MoveDownButtonDescriptor = ButtonDescriptor<'moveDown', ActionPushTrigger>;
type DeleteButtonDescriptor = ButtonDescriptor<'delete', ActionPushTrigger>;
type UnknownButtonDescriptor = ButtonDescriptor<string, ActionPushTrigger>;

type ArrayItemButton = MoveUpButtonDescriptor
  | MoveDownButtonDescriptor
  | DeleteButtonDescriptor
  | UnknownButtonDescriptor;

/**
 * Describe JSON Schema with type `array`
 */
interface ArrayDescriptor extends DescriptorDefinition {
  layout?: Component; // default: 'fieldset'
  items?: DescriptorInstance[] | DescriptorInstance;
  pushButton: PushButtonDescriptor | null;
  buttons: ArrayItemButton[];
}
```

## 使用大小写

### 分组字段

FormSchema可以通过组合来帮助您组织您的形式字段. 请检查 [对象描述器定义](https://npmcn.com/package/%40formschema/native/#readme-descriptor-interface)。 。 。 .

**实例 schema.json**

```json
{
  "type": "object",
  "properties": {
    "lastname": {
      "type": "string"
    },
    "firstname": {
      "type": "string"
    },
    "city": {
      "type": "string"
    }
  }
}
```

**示例描述符.json**

```json
{
  "groups": {
    "name": {
      "label": "Your name",
      "properties": ["firstname", "lastname"]
    },
    "location": {
      "label": "Your location",
      "properties": ["city"]
    }
  }
}
```

不分组的结果

```html
<form id="id-form">
  <fieldset id="id-form-field">
    <div data-fs-kind="string" data-fs-type="text" data-fs-field="lastname"><label for="id-form-field-lastname"></label>
      <div data-fs-input="text"><input id="id-form-field-lastname" type="text" name="lastname"></div>
    </div>
    <div data-fs-kind="string" data-fs-type="text" data-fs-field="firstname"><label for="id-form-field-firstname"></label>
      <div data-fs-input="text"><input id="id-form-field-firstname" type="text" name="firstname"></div>
    </div>
    <div data-fs-kind="string" data-fs-type="text" data-fs-field="city"><label for="id-form-field-city"></label>
      <div data-fs-input="text"><input id="id-form-field-city" type="text" name="city"></div>
    </div>
  </fieldset>
</form>
```
组合的结果

```html
<form id="id-form">
  <fieldset id="id-form-field">
    <div data-fs-group="name">
      <div data-fs-group-label="name">Your name</div>
      <div data-fs-group-nodes="2">
        <div data-fs-kind="string" data-fs-type="text" data-fs-field="firstname"><label for="id-form-field-firstname"></label>
          <div data-fs-input="text"><input id="id-form-field-firstname" type="text" name="firstname"></div>
        </div>
        <div data-fs-kind="string" data-fs-type="text" data-fs-field="lastname"><label for="id-form-field-lastname"></label>
          <div data-fs-input="text"><input id="id-form-field-lastname" type="text" name="lastname"></div>
        </div>
      </div>
    </div>
    <div data-fs-group="location">
      <div data-fs-group-label="location">Your location</div>
      <div data-fs-group-nodes="1">
        <div data-fs-kind="string" data-fs-type="text" data-fs-field="city"><label for="id-form-field-city"></label>
          <div data-fs-input="text"><input id="id-form-field-city" type="text" name="city"></div>
        </div>
      </div>
    </div>
  </fieldset>
</form>
```

## 捐款

请看 [贡献指南](https://gitlab.com/formschema/native/blob/master/CONTRIBUTING.md)。 。 。 .

## 许可证

根据麻省理工学院的许可。 见 [自由主义](https://gitlab.com/formschema/native/blob/master/LICENSE) 以备详细文件.

## 常见问题

### @formschema/native 是什么？

基于 JSON Schema 的 Vue 组件格式

### 如何安装 @formschema/native？

在项目目录运行 npm install @formschema/native，或使用 pnpm add / yarn add / bun add。

### @formschema/native 支持 TypeScript 吗？

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

### @formschema/native 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @formschema/native 可以商用吗？

@formschema/native 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @formschema/native 的下载量有多少？

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

### @formschema/native 还在维护吗？

最新版本 2\.0\.0-beta\.7 发布于 2022/03/24（4 年前）；至今共发布 9 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/06/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。