@zdwh/vue-json-schema-form

表单从来没有这么简单，通过一份 json-schema，你就拥有了一套交互完整，校验完善的表单。

USAGE

npm i @zdwh/vue-json-schema-form -S

然后

import JsonSchemaForm from '@zdwh/vue-json-schema-form'
import JsonSchemaFormThemeElement from '@zdwh/vue-json-schema-form/dist/theme-element/index.common.js'

vue.use(JsonSchemaForm)
vue.use(JsonSchemaFormThemeElement)

<JsonSchemaForm :schema="schema" v-model="value" :formProps="...props pass to form" :plugins="plugins" locale="" />

theme 是必须的，真正的表单组件都是由 theme 提供的，将 theme 拆分出来的目的很明显，未来对于不同的使用场景，可以无缝迁移，同时可以在移动端使用。

props

schema

json schema 对象

v-model

绑定结果值

formProps

传递给表单组件的props，这里面的值根据表单的最终实现来定，比如theme-element的formProps可以是任意 element-ui 中的 form 组件的props

plugins

插件

uiSchema

具体参考下面的vjsf

locale

默认zh中文，支持值参考ajv-i18n

ajvInstanceOptions

参考ajv options

vjsf

vjsf是我们用来在 json schema 基础上帮助我们更好得渲染表单的工具参数，我们可以通过在每个 schema 节点上带上来传递：

const schema = {
  type: 'string',
  vjsf: {
    component: 'your-custom-component',
    additionProps: {
      ...props, // 对于表单组件你想传递的其他参数
    },
    title: '名称',
    description: '描述',
    withFormItem: true, // 对于自定义组件，是否使用formItem，默认为true
  },
}

如果你不想把这些属性放在schema上面，那么你可以通过给JsonSchemaForm传递uiSchema参数来进行定制，只要保持uiSchema的结构和schema一致就行比如：

const schema = {
  type: 'object',
  properties: {
    name: {
      type: string,
    },
    pets: {
      type: 'array',
      items: {
        type: 'string',
      },
    },
  },
}

const uiSchema = {
  title: '我和我的宠物',
  properties: {
    name: {
      title: '我的名字',
      component: 'input',
    },
    pets: {
      title: '我的宠物们',
      items: {
        title: '名字',
      },
    },
  },
}

custom event

如果你有自定义组件，并且你的自定义组件想要跟JsonSchemaForm的 owner 进行沟通，你的组件可以inject: ['fireEvent']，然后通过this.fireEvent(name, data)来向外触发一个事件，在 owner 处，我们可以进行监听：

<json-schema-form @youEventName="yourHandler" />

propertiesOrder

对象 key 的排序，尤其在有dependencies的时候非常有用，在声明 schema 的时候，在type为object的 schema 中可以增加propertiesOrder属性，他的值是一个数组，properties里面的变量会根据这里声明的顺序进行渲染，没有出现在这个数组里面的变量名则放在最后面

插件

插件能够帮助我们非常方便地扩展功能，目前支持情况如下：

[x] customFormat
[x] customKeywords

如何创建一个自定义 format 插件

接口定义如下：

interface AjvFormat {
  name: string
  definition: FormatValidator | FormatDefinition
}

interface CustomFormat extends AjvFormat {
  component: String // jsf-text-input || your-custom-component
}

interface JsonSchemFormPlugin {
  customFormats: CustomFormat[]
}

比如我们增加一个图片上传的插件，这个组件返回的结果最终的图片链接，我们需要校验的自然也是这个链接，所以我们的 format 定义如下：

const format = {
  name: 'image',
  definition: /reg-to-valid-image-url/,
}

对于这个 format 我们需要使用特定的组件来进行渲染，毕竟他要实现上传图片并返回图片路径的功能，这并不是标准的 json schema 功能，并且上传的操作是业务相关操作直接写死在 vjsf 库内肯定不合适。

这时候我们可以创建一个ImageUploader组件，并且注册到 vue 上，这时候我们的插件就成型了：

const plugin = {
  customFormats: [
    {
      name: 'image',
      definition: /reg-to-valid-image-url/,
      component: 'image-uploader',
    },
  ],
}

在我们定义如下 schema 之后：

{
  type: 'string',
  format: 'image'
}

我们的表单就是如下：

<image-uploader v-model="value" />

快速替换 format 使用的组件

默认的 format 组件映射关系如下：

export const stringFormatComponentMap: StringMap = {
  default: 'jsf-text-input',
  color: 'jsf-color-picker',
  date: 'jsf-date-picker',
  'date-time': 'jsf-date-time-picker',
  time: 'jsf-time-picker',
}

export const numberFormatComponentMap: StringMap = {
  default: 'jsf-number-input',
  date: 'jsf-date-picker',
  'date-time': 'jsf-date-time-picker',
  time: 'jsf-time-picker',
}

我们可以通过formatMaps来定义 format 默认使用的组件，比如：

const formats = {
  string: {
    date: 'jsf-my-date-picker'
  }
}

<JsonSchemaForm :formatMaps="formats" />

之后字符串类型的日期format就会使用jsf-my-date-picker作为表单组件

重要：该方式建议只对 json schema 默认支持的 format 使用，对于你自定义的 format，你仍然需要使用插件的方式，因为你需要制定该 format 的校验方式。

如何自定义关键字插件

接口如下：

interface CustomKeyword {
  name: string
  definition: KeywordDefinition
  transformSchema?: (originSchema: Schema) => Schema
}

关于自定义 Ajv 关键字，请看Ajv 文档，此处的definition就是这个作用，而name则是你的关键字的名字。

自定义关键字和customFormats最大的区别是，我们不需要指定组件（毕竟我们不可能到每个类型里面判断关键字该怎么渲染）。在这里我们通过transformSchema来转换 schema，也就是我们真正渲染的 schema 是通过transformSchema转换的结果，这个方法会收到原始的 schema，你需要返回一个新的 schema，注意：不要 originSchema 上做改动

表单渲染会根据你返回的新的 schema 来进行。

示例

const plugin: JsonSchemFormPlugin = {
  customKeywords: [
    {
      name: 'test',
      definition: {
        // validate(schema: any, data: any) {
        //   return typeof data === 'object' && data.x === 1
        // },
        macro(schema: any) {
          return {
            ...schema,
            type: 'object',
            properties: {
              x: {
                type: 'number',
                minimum: 5,
              },
            },
          }
        },
        errors: true,
      },
      transformSchema(schema: any) {
        return {
          ...schema,
          type: 'object',
          properties: {
            x: {
              type: 'number',
              vjsf: {
                title: '测试数字',
              },
            },
          },
        }
      },
    },
  ],
}

在使用关键字的时候，我们只需要：

const schema = {
  test: true,
}

实际等于的效果如下：

const schema = {
  type: 'object',
  properties: {
    x: {
      type: 'number',
      vjsf: {
        title: '测试数字',
      },
    },
  },
}

我们建议通过macro来声明该关键字的校验，因为这能够完全契合 vjsf 的错误显示。如果你通过validation来进行校验，最终校验结果只针对于当前路径，而并不会有针对 transform 之后的 schema 的校验，可能就需要你自行显示错误信息了。

校验

你可以通过给JsonSchemaForm组件指定一个ref，然后通过ref.doValidate()来进行校验，会返回{ errors, valid }，其中errors是错误信息的对象。组件会把错误信息显示到每个表单项，你可以根据自己的需求以另外的方式提醒错误。

TODO:

[ ] 输入时对每个表单项独立进行校验

错误信息

我们通过ajv-errors来提供错误信息的定制，在你的每一项 schema 里面你可以：

const schema = {
  type: 'string',
  pattern: '/^abc$/',
  errorMessage: {
    pattern: '请填写正确的内容',
  },
}

如果你不写errorMessage，那么在用户输入的内容不匹配正则的时候，显示的错误信息是：应当匹配模式 "/^abc&/"，这对于非技术人员显然不够友好，在增加了errorMessage之后，对于关键字pattern的错误信息就会显示你指定的错误信息。

Note：你可以对每个关键字设定错误信息

errorMessage: {
  pattern: '请填写正确的内容',
  maxLength: '最长不超过xxx',
  //...others
}

主题

主题就是一组规范命名的组件，这一组组件都注册到全局 vue 上之后，vjsf 渲染表单就会使用这些组件，组件列表：

{
  JsfColorPicker: '颜色选择器' // 非必须，会回滚到text-input
  JsfDatePicker: '日期选择'
  JsfDateTimePicker: '日期时间选择'
  JsfDateTimeRangePicker: '日期时间区间选择'
  JsfForm: '表单组件'
  JsfFormItem: '表单项组件'
  JsfNumberInput: '数字输入'
  JsfSelection: '下拉选择'
  JsfSwitch: 'boolean开关'
  JsfTextInput: '字符串输入'
  JsfTimePicker: '时间选择'
  JsfSingleTypeArrayWrapper: '单类型数组区块控制器'
  JsfAlert: '提示框'
}

你要实现一个主题则需要实现这些组件并逐一注册到vue

使用默认主题

vjsf 的默认主题现在打包在一起，需要通过：

import JsonSchemaFormThemeElement from '@zdwh/vue-json-schema-form/dist/theme-element/index.common.js'
import JsonSchemaFormThemeElement from '@zdwh/vue-json-schema-form/dist/theme-element/index.css'

来引入。

在自定义组件的时候，你需要给你的表单组件套上FormItem来进行布局和错误显示：

<FormItem v-bind="formItemProps">
  <YourContent>
</FormItem>

import { FormItem, CommonBase } from '@zdwh/vue-json-schema-form/dist/theme-element/index.common.js'

export default class YourComponent extends CommonBase

为了方便获取formItemProps，我们提供了CommonBase作为你的组件可继承的基类

当然如果你只需要一个 mixin，你可以import { FormItemPropsMixin } from '@zdwh/vue-json-schema-form/dist/theme-element/index.common.js'

帮助方法

import { ThemeBaseClass, ThemeBaseMixin } from '@zdwh/vue-json-schema-form'

如果你用class开发可以继承前者，或者你可以使用后面的 mixin

表单依赖

demo

export default {
  name: '依赖关系',
  schema: {
    type: 'object',
    properties: {
      selected: {
        type: 'number',
        title: '是否选中',
        enum: [1, 2, 3],
      },
    },
    dependencies: {
      selected: {
        oneOf: [
          {
            properties: {
              selected: {
                // const: 1,

                const: 1,
              },
              name1: {
                type: 'string',
                title: '名字1',
              },
            },
            required: ['name1'],
          },
          {
            properties: {
              selected: {
                const: 2,
              },
              name2: {
                type: 'string',
                title: '名字2',
              },
            },
            required: ['name2'],
          },
          {
            properties: {
              selected: {
                const: 3,
              },
              name3: {
                type: 'string',
                title: '名字3',
              },
            },
            required: ['name3'],
          },
        ],
      },
    },
  },
}

解释

通过dependencies声明依赖关系，dependencies的key是依赖选项，比如在这里selected是依赖项，在selected有值的情况下才会展示和执行他包含的内容。

selected的值是一个oneOf则对应我们对于selected不同的结果会现实其中某个结果，比如在这里如果：

selected是1，则我们必须填写name1
selected是2，则我们必须填写name2
selected是3，则我们必须填写name3

注意这里我们在每一项中都声明了一个selected，他的类型是const也就是固定值，以此我们来强制区分不同的结果，符合selected为1的结果必定不会符合其他的选项，就完全符合oneOf的逻辑。

@zdwh/vue-json-schema-form

@zdwh/vue-json-schema-form

USAGE

props

schema

v-model

formProps

plugins

uiSchema

locale

ajvInstanceOptions

vjsf

custom event

propertiesOrder

插件

如何创建一个自定义 format 插件

快速替换 format 使用的组件

如何自定义关键字插件

示例

校验

错误信息

主题

使用默认主题

帮助方法

表单依赖

demo

解释

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@zdwh/vue-json-schema-form

@zdwh/vue-json-schema-form

USAGE

props

schema

v-model

formProps

plugins

uiSchema

locale

ajvInstanceOptions

vjsf

custom event

propertiesOrder

插件

如何创建一个自定义 format 插件

快速替换 format 使用的组件

如何自定义关键字插件

示例

校验

错误信息

主题

使用默认主题

帮助方法

表单依赖

demo

解释

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads