表单

AutoForm并不是传统意义上的HTML表单，并没有<form>标签包裹，auto-form只是一个普通的WebComponent组件，用于收集数据到AutoStore中而已。

快速入门

创建一个AutoForm的基本方式如下：

提示

使用AutoForm不需要手动创建AutoStore实例，只需要定义状态数据并赋值给auto-form组件的state属性，AutoForm内部会自动创建AutoStore实例。

第 1 步: 定义状态数据

首先定义表单的状态数据。状态数据本质上是一个普通的JSON对象，最终会被收集到AutoForm内部自动创建的AutoStore实例中。

const state = {
    user: {
        username: 'NAME',
        password: 'PASSWORD',
    },
    order: {
        price: 100,
        count: 1,
        total: (order) => order.price * order.count,
    },
};

提示

状态数据可以任意复杂，包括嵌套对象和计算属性。

第 2 步: 声明字段

接下来，我们使用configurable函数来声明，状态树中的哪些字段中是可配置的。

import { configurable } from 'autostore';
const state = {
    user: {
        username: configurable('NAME'),
        password: configurable('PASSWORD'),
    },
    order: {
        price: configurable(100),
        count: configurable(1),
        total: (order) => order.price * order.count,
    },
};

在一个嵌套的对象树中，我们可以使用configurable函数来声明哪些字段是可配置的。在上面的例子中，我们声明了user.username、user.password、order.price、order.count四个字段是可配置的。

提示

configurable函数用于告诉AutoStore状态树中的哪些字段是可配置的，AutoStore会自动收集这些字段。 configurable函数还有一个别名schema。

第 3 步: 引入表单组件

接下来引入表单组件auto-form组件。

auto-form组件是一个标准的Web Component，所以你可以像使用其他Web Component一样使用它,包括在Vue/React等其他场景可。

在html中，你可以直接从CDN中引入：

html

<!-- 引入 AutoForm 样式: 黑暗模式 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@autostorejs/form/dist/themes/dark.css" />
<!-- 引入 AutoForm 样式: 默认亮模式 -->
<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@autostorejs/form/dist/themes/light.css"
/>
<!-- 引入 AutoForm 代码 -->
<script src="https://cdn.jsdelivr.net/npm/@autostorejs/form/dist/index.global.js"></script>
<!-- 引入 AutoStore 代码 -->
<script src="https://cdn.jsdelivr.net/npm/autostore/dist/index.global.js"></script>

也可以像普通代码一样，在你的ts/js文件中引入

import { configurable } from 'autostore';
import '@autostorejs/form/dist/themes/light.css';

// 只需要导入即可
import '@autostorejs/form';

import '@autostorejs/form'后就会自动注册auto-form组件以及所有内置的表单字段组件。

提示

auto-form组件是一个标准的Web Component，只需要import即可使用。

第 4 步: 创建表单

接下来，我们就可以使用auto-form组件来创建表单了。

在你的代码中创建auto-form组件，然后将第 1、2 步定义的状态数据赋值给state属性，AutoForm内部会自动创建AutoStore实例和ConfigManager，就可以创建一个表单了。

在html中，可以直接使用auto-form组件来创建表单：

html

<script>
    const { configurable } = AutoStoreSpaces;
    const form = document.querySelector('#login');
    // 将状态定义直接赋值给 state 属性（推荐方式）
    form.state = {
        user: {
            username: configurable('NAME', {
                icon: 'user', 
            }),
            password: configurable('PASSWORD'),
        },
        order: {
            price: configurable(100),
            count: configurable(1),
            total: (order) => order.price * order.count,
        },
    };
</script>

<auto-form id="login"></auto-form>

提示

在React/Vue中应用，可以将auto-form组件像普通的div标签一样使用。

第 5 步: 渲染效果

至此，一个简单的表单就渲染完成了，表单中包括了user.username、user.password、order.price、order.count四个字段。

渲染效果如下：

提示

修改表单数据后，AutoStore中的数据会同步更新，两者是双向绑定关系，即修改form.activeStore.state也会同步到表单中。

小结

可以看到，AutoForm完全不同于普通的表单解决方案，核心本质就是将数据收集到AutoStore中，然后通过auto-form组件来渲染表单。

注意

在上例中，我们可以看到渲染出的表单的外观、样式、label 等并不理想。实际场景中，一般需要进行更精细的控制，这就需要为configurable提供更多的控制参数，详见表单字段章节。

指南

绑定数据

auto-form组件推荐通过state属性传入状态定义对象，AutoForm内部会自动创建AutoStore实例和ConfigManager。 AutoStore实例本质上是一个经过proxy封装的JSON对象，会在读写对象时触发事件，为表单提供响应式支持。

html

<script>
    const { configurable } = AutoStoreSpaces;
    const form = document.querySelector('#login');
    form.state = { 
        // 表单状态数据
    };
</script>

<auto-form id="login"></auto-form>

state赋值后，可以在updateComplete之后通过activeStore属性访问内部创建的AutoStore实例：

html

<script>
    const form = document.querySelector('#login');
    form.updateComplete.then(() => {
        const store = form.activeStore; 
        store.watch(() => {
            console.log(store.state);
        });
    });
</script>

当state赋值后，就在AutoStore和AutoForm之间创建起双向同步关系，

当AutoStore中的数据发生变化时，AutoForm会自动更新表单数据。
当AutoForm中的数据发生变化时，AutoStore会自动更新AutoStore中的数据。

尺寸

AutoForm默认支持small、medium、large三种尺寸。可以控制表单的字体、间距等尺寸。

标题位置

AutoForm的字段标题支持

默认支持top、left两种标题位置,可以控制字段标题的显示位置。
当标题位置为left时，可以控制标题的宽度。

网格线

默认AutoForm不显示网格线，可以通过border参数控制：

none: 不显示网格线（默认）
outline: 仅显示表单外边框
grid: 显示字段网格分割线

浏览模式

允许切换到数据浏览模式，只查看表单数据。

紧凑模式

紧凑模式，可以控制表单字段的间距。

CSS::Part

auto-form是一个WebComponent组件，内部组件被渲染在一个shadow DOM中，无法在外部进行样式控制。

auto-form暴露了一些CSS::Part，允许通过进行样式控制。

例如，我们要控制字段label样式，可以通过::part(field-label)来进行样式控制。

css

auto-form::part(field-label) { color: red; }

AutoForm目前提供了以下CSS::Part：

名称	描述
field	字段
field-value	字段值
field-label	字段标题
field-help	字段帮助信息
field-error	字段错误信息

提示

CSS::Part是WebComponent规范中定义的，详见这里。
使用CSS::Part进行样式控制时也有一定的限制，在字段中有更丰富的样式控制，详见表单字段章节。

分组

AutoForm支持分组，可以只显示指定组的字段。

group参数可仅仅指定一个组，也可以指定多个组，多个组之间用,分隔。
group='' || group='*'表示显示所有组。

const form = document.querySelector('#login');
form.state = {
    user: {
        username: configurable('NAME', {
            label: '用户名',
            group: 'user', 
        }),
        password: configurable('PASSWORD', {
            label: '密码',
            group: 'user', 
        }),
    },
    order: {
        price: configurable(100, {
            label: '价格',
            group: 'price', 
        }),
        count: configurable(1, {
            label: '数量',
            group: 'price', 
        }),
        total: (order) => order.price * order.count,
    },
};

以上我们为配置字段指定了一个组名称，然后在渲染表单时，可以指定要渲染的组。

状态路径

可以通过path参数指定要显示某个路径下的字段。

const form = document.querySelector('#login');
form.state = {
    user: {
        username: configurable('NAME', {
            label: '用户名'
        }),
        password: configurable('PASSWORD', {
            label: '密码'
        }),
    },
    order: {
        price: configurable(100, {
            label: '价格'
        }),
        count: configurable(1, {
            label: '数量'
        }),
        total: (order) => order.price * order.count,
    },
};
<auto-form path="user"></auto-form> 
<auto-form path="order"></auto-form> 
<auto-form path="user,order"></auto-form>

字段排序

AutoForm可以通过order参数对字段进行排序，可以指定字段的顺序。按order参数值从小到大排列。

const form = document.querySelector('#login');
form.state = {
    user: {
        username: configurable('NAME', {
            label: '用户名',
            order: 2, 
        }),
        password: configurable('PASSWORD', {
            label: '密码',
            order: 1, 
        }),
    },
};

布局类型

默认情况下，表单对内部的字段采用inline-block布局，可以控制表单的布局类型。

layout参数支持以下值：

auto: 采用默认inline-block布局
row: 采用flex: row布局
col: 采用flex: column布局

高级字段

advanced参数用于标识这是一个高级选项字段，当advanced时才会显示字段。

const form = document.querySelector('#login');
form.state = {
    user: {
        username: configurable('NAME', {
            label: '用户名',
            advanced: true
        }),
        password: configurable('PASSWORD', {
            label: '密码'
        }),
    }
};
// 默认显示所有字段，包括advanced字段
<auto-form ></auto-form> 
// 显示所有字段，但不显示advanced字段
<auto-form advanced></auto-form>

提示

advanced参数用于当创建配置表单时，有时需要指定一些配置项是高级选项，仅在高级选项打开时才显示。

表单是否修改

当表单数据进行了更新后，会为表单增加一个dirty类，用于标识表单是否被修改过。

<auto-form class="dirty"></auto-form>

也可以通过读取form.dirty值来查看表单是否被修改过。

重置表单

可以通过reset方法重置表单到初始状态。

javascript

const form = document.querySelector('#login');
form.state = {...};

// 重置表单
form.reset();

提交表单

可以通过submit方法提交表单，该方法会触发回调，返回表单数据和错误信息：

javascript

form.submit((values, errors) => {
    if (errors) {
        console.log('表单校验失败', errors);
    } else {
        // values是一个对象，包含表单所有字段的值
        console.log('表单校验成功', values);
    }
});

提示

submit方法不会刷新页面，而是触发回调，让开发者自行处理表单数据。

表单 ​

快速入门 ​

第 1 步: 定义状态数据 ​

第 2 步: 声明字段 ​

第 3 步: 引入表单组件 ​

第 4 步: 创建表单 ​

第 5 步: 渲染效果 ​

小结 ​

指南 ​

绑定数据 ​

尺寸 ​

标题位置 ​

网格线 ​

浏览模式 ​

紧凑模式 ​

CSS::Part ​

分组 ​

状态路径 ​

字段排序 ​

布局类型 ​

高级字段 ​

表单是否修改 ​

重置表单 ​

提交表单 ​

表单

快速入门

第 1 步: 定义状态数据

第 2 步: 声明字段

第 3 步: 引入表单组件

第 4 步: 创建表单

第 5 步: 渲染效果

小结

指南

绑定数据

尺寸

标题位置

网格线

浏览模式

紧凑模式

CSS::Part

分组

状态路径

字段排序

布局类型

高级字段

表单是否修改

重置表单

提交表单