组件共有性质

任一表单组件都具有提示、录入、展示和校验等功能，相应的，它们会具有某些相同的API与使用方式。我们会在本篇文章中统一介绍表单组件的共有性质，而不是在各个组件中分散的重复叙述。所以在具体使用某个具体组件之前，请先仔细阅读本篇文章，以达到一通百通、提升各自效率的目的。

使用方式

日常情形是将组件用Item包裹置于Form中（node=组件名），通过录入与展示数据实现页面功能逻辑。

PCPhonePad

HTMLJAVASCRIPTCSS

<page>
    <form>
        <item
            label="输入的标签"
            node="input"
            name="a"
        />
        <item
            label="日期的标签"
            node="date-picker"
            name="b"
        />
    </form>
</page>

export default XPage({

});

组件与Item的结合，使其既保留了原有功能（API）又具有提示、布局、关联和校验等功能，详细可以查看 Item 文档。

PCPhonePad

HTMLJAVASCRIPTCSS

<form>
    <item
        required
        label="必填标识"
        node="input"
        name="a"
        placeholder="此为必填项"
    />
    <item
        label="布局设置"
        node="input"
        name="b"
        colspan="{{6}}"
        placeholder="占一整行"
    />
    <item
        label="提示信息"
        node="input"
        name="c"
        tips="这里是提示信息"
    />
    <item
        label="添加校验"
        node="input"
        name="d"
        validators="{{(v) => (v.length > 5 && '最长不能多于 5')}}"
        placeholder="不能超过5个字"
        bindvalidated="() => '这里触发校验事件'"
    />
</form>

export default XPage({

});

通用属性

name

在独立使用组件时，可以忽略该属性。在Form容器中，该属性是各种联动关系的key。除纯展示的文字节点（node=text）外，该属性都是必要的。在一个容器Form/Item中，不允许存在重复的name值。

value

组件的值，同时也是设定组件值的一种方式（另一种通过Form的setData方法）。不同组件会有不同格式要求的value。这种要求是严格的全等于，比如1不是'1'也不是true。具体请查看各个组件。

changed

组件值被用户修改后触发的事件。事件的第一个参数是值，第二个是值的相关信息。

为了减少不必要的事件触发和循环触发，我们严格区分了用户触发行为与开发者触发行为。该changed事件只在用户触发行为中被触发。用户触发行为：通过鼠标或键盘修改了组件的值、点击了表单的重置按钮或组件的清除按钮。开发者触发行为：通过value与setData设置组件的值。该行为依旧会触发Item的校验功能。

其它

type - 组件的不同类型（维度），比如DatePicker有week、mouth、year和daterange等不同维度。 data - 传入组件的数据（多为展示性数据），比如传入[{label, value}]给Select用于渲染出选项。 disabled - 禁止用户操作此组件。 placeholder - 占位提示信息。 clearable - 是否允许清除。 ajax / action / loaded - 请查看远程交互小节。

PCPhonePad

HTMLJAVASCRIPTCSS

<page>
    <actions>
        <button
            text="设置表单的值"
            bindclick="setData()"
        />
        <button
            text="删除表单的值"
            bindclick="clearData()"
        />
    </actions>
    <form
        x="form"
        bind-clear="args => console('clear', args)"
        bind-confirm="args => console('confirm', args)">
        <item
            disabled
            label="禁用事项"
            node="input"
            name="input"
            value="向兵长献出心脏"
            bind-changed="args => console('input changed', args)"
        />
        <item
            label="夏日水果"
            node="select"
            name="select"
            placeholder="选择你喜欢的水果"
            data="{[
          {label: '西瓜', value: 1},
          {label: '是西瓜', value: 2},
          {label: '还是西瓜', value: 3}
        ]}"
            bind-changed="args => console('select changed', args)"
        />
        <item
            label="月份维度"
            node="date-picker"
            name="month"
            type="month"
            bind-changed="args => console('month changed', args)"
        />
    </form>
</page>

export default XPage({
    console(type, args) {
        console.log(type, args);
    },

    setData() {
        this.getComponent('form').setData({
            input: '向兵长献出心脏',
            select: 2,
            month: Date.now()
        });
    },

    clearData() {
        this.getComponent('form').clear();
    }
});

远程交互

为简化大数据量展示、搜索与上传等远程操作，以及统一数据格式和交互等，我们内置了请求配置接口ajax。接口ajax在上传组件Upload中为action接口，用法相同，语义上前者是获取后者为传递。接口ajax完整的格式为{url:String, params:Object, initData:Array}。也可以直接是字符串，此时等同url。

PCPhonePad

HTMLJAVASCRIPTCSS

<page>
    <form>
        <item node="select" placeholder="远程获取" name="a"
              ajax="{{ajax}}"></item>
    </form>
</page>

export default XPage({
    data: {
        ajax: {url: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/select/options', params: {id: 1}}
    }
});

极限展示

展示类组件Select和Cascader能够承载的数目有限，超过限制会导致页面卡顿甚至直接崩溃。以下是组件的实际测试数据（在公司电脑的环境下）： Select - 单选 - 10000 条后明显卡顿，建议控制在 500 条以内，大于此值建议改成远程搜索。 Select - 多选 - 3000 条后明显卡顿，建议控制在 300 条以内，大于此值建议改成远程搜索。 Cascader - 单选 - 50 50 100 条（CPU无法再过高计算）后无卡顿，建议控制每级展示数目不高于 300 条。 Cascader - 多选 - 50 50 100 条（CPU无法再过高计算）后无卡顿，建议控制每级展示数目不高于 200 条。

大部分系统的实际使用者，他们的电脑配置十分原始，必要时可以用网速替代电脑的低运速。

请求格式

所有与后端交互的内置行为，它们的请求方式、请求配置、关键字段和返回数据格式等都是固定的、不可配置的。

获取数据的组件Select、Cascader与AutoComplete的行为如下：请求方式 - Get；搜索的关键字为 - keywords；请求响应的整体格式 - {code, msg, data}，code='0000'意味着成功；请求响应的数据格式 - {data: []} 或 {data: result: []}，[]代表组件需要的数据，兼容两种方式；数据格式 - 不同组件间有些许差异，请查看各个组件的说明。基本是[{label, value}]这种形式。

传递数据的组件Upload的行为：请求方式 - Post，使用FormData包裹；文件的关键字为 - file；请求响应的整体格式 - 与获取数据的组件相同；请求响应的数据格式 - {data: ''} 或 {data: result: ''}，''代表组件需要的数据，兼容两种方式；数据格式 - 链接（字符串）。

具体请在实际项目中使用与体验。

错误处理

当请求出错时，组件会自动优先展示后端提供的错误提示{msg}。实际应用中，{msg}可能满足不了需求，或面对错误还需要执行跳转（如权限）等行为。接口loaded便是用来处理这种场景。它会在数据请求完成后（无论成功与否）被调用，其参数是完整的响应数据。

PCPhonePad

HTMLJAVASCRIPTCSS

<page>
    <form>
        <item node="select" placeholder="远程获取" name="a"
              ajax="{{ajax}}" loaded="{{ (args) => '做一些自定义事情' }}"></item>
    </form>
</page>

export default XPage({
    data: {
        ajax: {url: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/select/options', params: {id: 1}}
    }
});

数据回显

具有远程获取数据能力的组件，在数据回显时，都会遇到值与选项不匹配的情况。

举个例子，在使用Select配置远程搜索时；搜索四川，显示出四川的省级市，选中成都后保存数据到后端。保存的数据为成都（value）；刷新页面，Select的值是成都（value），但没有成都（label），这时显示出错。

接口ajax中的initData配置便是用来解决这个问题的。在设置Select的value时，同时设置initData值，此时initData相当接口data。注意：该initData只在第一次数据请求之前可用。第一次数据请求完成后，无论请求结果如何，都会被弃用。

PCPhonePad

HTMLJAVASCRIPTCSS

<page>
    <form>
        <item node="select" placeholder="请选择" name="a"
              ajax="{{ajax}}"></item>
    </form>
</page>

export default XPage({
    data: {
        ajax: {
            url: '//testapi-nodedmallos.dmall.com/cabinx/pcapi/select/options',
            params: {id: 1},
            initData: [{value: 1, label: '选中的值'}]
        }
    }
});

组件共有性质

使用方式​

通用属性​

name​

value​

changed​

其它​

远程交互​

极限展示​

请求格式​

错误处理​

数据回显​

使用方式

通用属性

name

value

changed

其它

远程交互

极限展示

请求格式

错误处理

数据回显