表单

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

快速入门

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

第 1 步: 创建`AutoStore`实例

创建一个AutoStore实例，用于存储表单数据。AutoStore实例内部维护了一个经过Proxy代理的JSON对象，用于存储表单数据。

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

提示

可以创建任意复杂的AutoStore。

第 2 步: 声明字段

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

import { AutoStore, configurable } from 'autostore';
const store = new AutoStore({
    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 { AutoStore } 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组件，然后绑定store实例，就可以创建一个表单了。

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

html

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

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

提示

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

第 5 步: 渲染效果

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

渲染效果如下：

提示

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

小结

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

注意

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

指南

绑定数据

auto-form组件提供了bind方法，用于绑定AutoStore实例。 AutoStore实例本质上是一个经过proxy封装的JSON对象，会在读写对象进触发事件，为表单提供响应式支持。

html

<script>
    const { AutoStore, configurable } = AutoStoreSpaces;
    const store = new AutoStore({...});
    const form = document.querySelector('#login');
    form.bind(store); 
</script>

<auto-form id="login"></auto-form> // [!code ++]

当执行bind方法后，就在AutoStore和AutoForm之间创建起双向同步关系，

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

主题

AutoForm使用ThemePro用为主题方案，可以提供灵活实时的动态主题

tsx

<link href="https://cdn.jsdelivr.net/npm/@autostorejs/form/index.css" />
<link href="https://cdn.jsdelivr.net/npm/@autostorejs/form/themes/dark.css" />
<link href="https://cdn.jsdelivr.net/npm/@autostorejs/form/themes/red.css" />
<link href="https://cdn.jsdelivr.net/npm/@autostorejs/form/themes/blue.css" />

<auto-form></auto-frm>

提示

除了预设的light、dark、blue、red共四种颜色的主题外，还可以动态生成主题。详见ThemePro介绍。

尺寸

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

标题位置

AutoForm的字段标题支持

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

网格线

默认AutoForm会显示字段网格分割线，也可以控制不显示。

浏览模式

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

紧凑模式

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

CSS::Part

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

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

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

html

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 store = new AutoStore({
    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,
    },
});
const form = document.querySelector('#login');
form.bind(store);

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

状态路径

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

const store = new AutoStore({
    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 store = new AutoStore({
    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 store = new AutoStore({
    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方法重置表单。

表单 ​

快速入门 ​

第 1 步: 创建AutoStore实例 ​

第 2 步: 声明字段 ​

第 3 步: 引入表单组件 ​

第 4 步: 创建表单 ​

第 5 步: 渲染效果 ​

小结 ​

指南 ​

绑定数据 ​

主题 ​

尺寸 ​

标题位置 ​

网格线 ​

浏览模式 ​

紧凑模式 ​

CSS::Part ​

分组 ​

状态路径 ​

字段排序 ​

布局类型 ​

高级字段 ​

表单是否修改 ​

重置表单 ​

表单

快速入门

第 1 步: 创建`AutoStore`实例

第 2 步: 声明字段

第 3 步: 引入表单组件

第 4 步: 创建表单

第 5 步: 渲染效果

小结

指南

绑定数据

主题

尺寸

标题位置

网格线

浏览模式

紧凑模式

CSS::Part

分组

状态路径

字段排序

布局类型

高级字段

表单是否修改

重置表单