Jiess文档

Appearance

页面布局 & 快捷构造 ​

本节讲基础库中的布局模块

基础介绍 ​

安装Jiess基础库时，通常会将area函数注入上下文对象，

javascript
import { h, reactive, withDirectives } from 'vue';
import { $entry } from '@jiess/plus';
// 导入vue3的环境对象，react同理
import JiessEnv from '@jiess/plus/vue3';
// 从基础库导入弹框相关的实例
import { $Area } from '@/.jiess';

const jiess = $entry(JiessEnv, 
// 静态注入到jiess实例中
{
	h,
	reactive,
	withDirectives
}, 
// 动态注入到组件上下文中
{
	area: $Area
});

构造area对象 ​

调用area方法可以得到实例对象area，该实例可以管理一块区域的布局与渲染

js
function setup() {
	const area = this.area(配置对象);
}

配置对象详解 ​

span

  • 类型 Array
  • 描述 定义区域中的每一个组件占据多少单位的宽度
  • 描述 区域的一行分为24份，默认每个组件占据8份，即一行3个组件

hasForm

  • 类型 Boolean
  • 描述 定义该区域是否包裹form组件

hasCard

  • 类型 Boolean
  • 描述 定义该区域是否包裹card组件

hasSpace

  • 类型 Boolean
  • 描述 定义该区域是否包裹space组件

formParam

  • 类型 Object
  • 描述 定义区域的form组件的参数

spaceParam

  • 类型 Object
  • 描述 定义区域的space组件的参数

initialValues

  • 类型 Object
  • 描述 初始化区域内表单的数据
  • 说明 Jiess内部会基于表单$name属性，从本数据源中取值

staticValues

  • 类型 Object
  • 描述 定义区域内的表单组件的数据源
  • 说明 直接将该对象作为数据源，不会根据$name属性过滤
  • 用途 如表单编辑，需携带Id，若表单中不用到该属性，则数据源中需提前放入

注：staticValues属性仅在element环境中生效

其余属性

其余属性，均作为card的属性，比如antd的card标题使用title，element的card标题使用header； 因为element的card支持header插槽，所以要结合vue2和vue3各自的插槽特性使用

vue2 element-ui中使用header插槽 ​

js
// 用法一：基础用法
const area = this.area({
	children: this.render({	slot:'header'	},'区域标题')
})

// 用法二：定义左右，$Between为基础库中的JiessBetween组件
import { $Between } from '@/.jiess';
const area = this.area({
	children: this.render({ slot: 'header' },
		this.render({
			is: $Between,
			left: '区域标题',
			right() {
				return this.render({ is: 'a' }, 'more')
			}
		})
	)
})

vue3 element-plus中使用header插槽 ​

js
// 用法一：基础用法
const area = this.area({
	$slots: {
		header(){
			return this.render({},'区域标题')
		}
	}
})

// 用法二：定义左右，$Between为基础库中的JiessBetween组件
import { $Between } from '@/.jiess';
const area = this.area({
	$slots: {
		header: () => this.render({
			is: $Between,
			left: '区域标题',
			right() {
				return this.render({ is: 'a' }, 'more')
			}
		})
	}
})

react antd中自定义右侧 ​

js
// jsx环境中
const area = this.area({
	title: '区域标题',
	// 直接使用Jsx语法
	extra: <a href="#">More</a>
})

// 通用写法
const area = this.area({
	title: '区域标题',
	// 将Jiess节点转化为react节点
	extra: this.render({ is:'a' },'more').getNative()
})

详解area ​

area实例中提供了常见组件的快捷构造方法，达到简化使用的效果

快速上手 ​

首先调用$area方法，传入配置，最终得到area实例

js
// 在setup配置函数中
function setup() {
	// 构造一块区域
	const area = this.area({
		// 一行放三个元素
		span: 8,
		// react中定义区域标题
		title: '用户注册',
		// vue中定义区域标题
		header: '用户注册',
		// 是否被Form嵌套，默认为true
		hasForm: true,
		// 是否被Card嵌套，默认为true
		hasCard: true,
		// 是否被Space嵌套，默认为true
		hasSapce: true,
		// space组件的参数
		spaceParam: {},
		// form组件的参数
		formParam: {}
		// 提供区域表单的初始数据
		initialValues: {},
		// vue环境中指定数据源
		staticValues: {},
		// 其余参数尽归card所有
		// ...
	});
}

然后，调用快捷方法Input构造一个输入框：

js
// $name：必要属性，用于初始化表单和收集表单数据
$Input({ $name: 'username' });

如上已经构建了一个输入框，简单的一行代码背后，包含了多层嵌套

js
$Input({
	// 表单label
	$label: '用户名',
	// 元素宽度
	$span: 8,
	// 初始值
	$defaultValue: 'admin',
	// 字段
	$name: 'username',
	// 必要字段
	$rules: ['required'],
	// 不需要SpaceItem包裹，默认为true
	$hasSpaceItem: true,
	// 不需要FormItem包裹，默认为true
	$hasFormItem: true,
	// spaceItem组件的参数
	$spaceItemParam: {},
	// formItem组件的参数
	$formItemParam: {},
	// 输入框的弟（输入框后）元素
	$formItemChilds:[],
	// 其余参数尽归组件所有，此处归Input输入框
	// ...
});

快捷构造也同样为扁平化的配置，组件需要什么属性，在配置对象种加入该属性即可

$name的作用

  • 控制表单的正常输入，否则无法输入内容
  • 初始化表单时的数据回显，需要唯一标识
  • 用户操作时的数据收集，需要唯一标识

加入渲染集合 ​

与基础配置渲染类似，元素须加入渲染集合中才可渲染

js
function setup() {
	// 构造一块区域
	const area = this.area();
	// 将渲染配置加入渲染集合中
	area.add(
		$Input({
			$name: 'username',
			size: 'small',
			placeholder: '请输入用户名'
		})
	)
  // 执行渲染
  const action = area.done();
}

使用area.add()，将元素加入渲染集合，再调用area.done()执行渲染

操作对象 action ​

执行渲染时会返回action对象，该对象用于操作当前area下的表单

  • 使用数据对象回显数据
js
// 执行渲染
const action = area.done();
setTimeout(()=>{
	// 模拟异步回显数据
  action.setFieldsValue({ ...异步数据 });
}, 1000)
  • 为指定的表单赋值
js
// 执行渲染
const action = area.done();
setTimeout(()=>{
	// 模拟异步赋值
  action.setFieldValue(字段, 值);
}, 1000)

Form和FormItem ​

接下来讲述Form和FormItem组件的能力，以及相互之间的配合

定义组件标题 ​

使用内置属性$label，定义组件的标题

js
$Input({
	$name: 'username',
	$label: '用户名',
	placeholder: '请输入用户名'
})

antd与element的FormItem均支持label；所以$label最终作为FormItem组件的属性

校验表单域数据 ​

对于表单的数据，通常需要校验，定义$rules可以快捷校验：

js
$Input({
	$name: 'username',
	$label: '用户名',
	$rules: ['required'],
	placeholder: '请输入用户名'
})

为满足多种校验条件，所以$rules属性需要定义为数组

上例中，输入框前会出现红色星号，会自动校验表单域必填

快捷校验一栏 ​

目前Jiess基础库内置的快捷校验有如下：

  • required：必填校验，表单域前会出现红色星号
  • requireArr：校验数据为数组，且长度大于0
  • [numMix,numMax]：验证表单内容长度是否在范围内
  • email：邮箱校验
  • phone：手机号码
js
$Input({
	$name: 'username',
	$label: '用户名',
	$rules: ['required', [6, 12]],
	placeholder: '请输入用户名'
})

上例中，同时校验必填，以及输入字符串的长度范围

自定义校验 ​

如果您需要自定义校验，您也可以传入自定义函数

js
$Input({
	$name: 'age',
	$label: '年龄',
	placeholder: '请输入年龄',
	$rules: ['required', (value, callback) => {
		value = parseInt(value);
		if (Number.isInteger(value)) {
			if (value < 18) {
				callback(new Error('年龄必须超过18岁'))
			} else {
				callback()
			}
		} else {
			callback(new Error('请输入数字'))
		}
	}]
})

上例中，同时校验必填，以及输入的是否为大于18岁的数字

页面布局 ​

页面布局，简单的说，就是控制一行放置元素的数量

定义区域内元素宽度 ​

区域内每一行分24份，span属性用于指定区域中元素占据宽度

js
// 指定区域内元素宽度12，即一行放两个元素
const area = this.area({ span: 12 });

span默认为8，即未指定时，一行放3个元素

定义区域内元素间隙 ​

指定gutter，用于指定元素间的间隙，默认间隙为8像素

js
// 在setup配置函数中
function setup() {
	const area = this.area({
		// 定义组件间隙为12
		gutter: 12,
		// 定义组件宽度为6
		span: 6
	})
}

上例中，一行放4个元素，元素间间隙为12像素

单独控制元素宽度 ​

有整体控制，就免不了有特殊；对于元素的宽度，可以使用$span来单独控制

js
// 引入基础库提供的快捷构造组件
import { $Input, $Select, $DatePicker } from "@/.jiess";

function setup() {
	// 示例为vue框架下的element-ui组件
	const area = this.area({
		// 定义组件间隙为12
		gutter: 12,
		// 定义组件宽度为6
		span: 6
	})

	area.add(
		$Input({
			$name: 'name',
			$label: '姓名',
			$rules: ['required'],
			placeholder: '请输入姓名',
		}),
		$Select({
			$name: 'sex',
			$label: '性别',
			$rules: ['required'],
			placeholder: '请选择性别',
			options: [
				{ text: '男', value: 1 },
				{ text: '女', value: 2 }
			]
		}),
		$DatePicker({
			$name: 'schoolTime',
			$label: '在校时间',
			$span: 12,
			type: 'daterange',
			$rules: ['required'],
			'range-separator': 'To',
			'end-placeholder': '毕业时间',
			'start-placeholder': '入学时间'
		})
	)
	// 执行渲染
	const area = area.done();
}

上例中，全局指定一行放四个元素，但在校时间是个时间范围选择器，咱们为它分配了12个单位， 另外两个元素的宽度不受影响，依然为6，所以上面三个元素整体占满一行

快捷构造 ​

Jiess基础库中基于UI进行了封装，提供了多个快捷构造方法

共有构造和独有构造

不同的UI间，存在较大差异；对于特殊的，甚至不存在的组件，只能单独在其对应环境中使用

共有构造 ​

列举element和antd间，共有的快捷构造方法

Input ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 空串
  • 说明 用于构造输入框
    • antd-ui 基于Input组件
    • element-ui 基于ElInput组件

Autocomplete ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 空串
  • 说明 用于构造自动补全输入框
    • antd-ui 基于AutoComplete组件
    • element-ui 基于ElAutocomplete组件

InputNumber ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 NaN
  • 说明 用于构造数字输入框
    • antd-ui 基于InputNumber组件
    • element-ui 基于ElInputNumber组件
    • 不能参与必填校验

DatePicker ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 null
  • 说明 用于构造时间选择器
    • antd-ui 基于DatePicker组件
    • element-ui 基于ElDatePicker组件

Switch ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 false
  • 说明 用于构造开关组件
    • antd-ui 基于Switch组件
    • element-ui 基于ElSwitch组件
    • 不能参与必填校验

Checkbox ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 false
  • 说明 用于构造复选框
    • antd-ui 基于Checkbox组件
    • element-ui 基于ElCheckbox组件
    • 不能参与布局
    • 不能定义label
    • 不能参与必填校验

CheckboxGroup ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 []
  • 说明 用于构造多选框组
    • antd-ui 基于Checkbox.Group组件
    • element-ui 基于ElCheckbox组件
    • 不能参与必填校验

Radio ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 false
  • 说明 用于构造单选框
    • antd-ui 基于Radio组件
    • element-ui 基于ElRadio组件
    • 不能参与布局
    • 不能定义label
    • 不能参与必填校验

RadioButton ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 false
  • 说明 用于构造按钮样式单选框
    • antd-ui 基于Radio.Button组件
    • element-ui 基于ElRadioButton组件
    • 不能参与布局
    • 不能定义label
    • 不能参与必填校验

RadioGroup ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 null
  • 说明 用于构造单选框组
    • antd-ui 基于Radio.Group组件
    • element-ui 基于ElRadioGroup组件

Cascader ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 []
  • 说明 用于构造级联选择器
    • antd-ui 基于Cascader组件
    • element-ui 基于ElCascader组件

Select ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 null
  • 说明 用于构造下拉框
    • antd-ui 基于Select组件
    • element-ui 基于ElSelect组件

下面的快捷构造为非表单类组件

Button ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造按钮
    • antd-ui 基于Button组件
    • element-ui 基于ElButton组件

Form ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造表单
    • antd-ui 基于Form组件
    • element-ui 基于ElForm组件

FormItem ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造表单域元素的包裹层
    • antd-ui 基于Form.Item组件
    • element-ui 基于ElFormItem组件

Row ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造行布局元素
    • antd-ui 基于Row组件
    • element-ui 基于ElRow组件

Col ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造行布局中的单个元素
    • antd-ui 基于Col组件
    • element-ui 基于ElCol组件

Option ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造下拉选项
    • antd-ui 基于Select.Option组件
    • element-ui 基于ElOption组件

OptionGroup ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 说明 用于构造下拉组
    • antd-ui 基于Select.OptGroup组件
    • element-ui 基于ElOptionGroup组件

由于不同UI组件设计会有所差异，所以其支持的属性，应参考对应UI的官方文档

antd-ui 独有 ​

列举在antd-ui环境中独有的快捷构造方法

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 空串
  • 说明 用于构造搜索框
    • antd-ui 基于Input.Search组件

Password ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 空串
  • 说明 用于构造密码框
    • antd-ui 基于Input.Password组件

TextArea ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 空串
  • 说明 用于构造文本域
    • antd-ui 基于Input.TextArea组件

RangePicker ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 null
  • 说明 用于构造范围选择器
    • antd-ui 基于RangePicker组件

element 独有 ​

列举在element环境中独有的快捷构造方法

ColorPicker ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 null
  • 说明 用于构造色彩选择器
    • element-ui 基于ElColorPicker组件

CheckboxButton ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 false
  • 说明 用于构造按钮样式多选框
    • element-ui 基于ElCheckboxButton组件
    • 不能参与布局
    • 不能定义label
    • 不能参与必填校验

CascaderPanel ​

  • 类型 Function
  • 参数 (param, ...children)
  • 返回 jsRender
  • 表单初始值 []
  • 说明 用于构造级联面板选择器
    • element-ui 基于ElCascader组件