@activity-maker/linglong-setting-form v1.0.7

linglong-setting-form

用于快速创建玲珑系统配置表单的工具库。

简介

玲珑系统 的组件由 实际运行组件（index）、编辑预览组件（preview）和编辑配置组件（setting） 三部分组成。其中编辑配置组件的编写是枯燥无味的，因此就有了这个库，它可以通过固定的配置项，快速生成一个配置表单，节省开发的时间。

概念

• 控件：用户真正交互的组件本身，具备数据处理能力（接收输入、触发回调），如 Input、Select、Radio 等。

• 表单域：由 Form.Item + 控件 组合而成的组件，具备同 Form 交互的能力（通过 name 注册后，数据由 Form 统一管理），如

  <Form.Item label="演示" name="pr">
    <Input />
  </Form.Item>

安装

yarn add @xmly/linglong-setting-form --registry="http://xnpm.ximalay.com"
或
npm install @xmly/linglong-setting-form --registry="http://xnpm.ximalay.com"

也可以通过 script 标签进行引入，

<link
	rel="stylesheet"
	href="//s1.xmcdn.com/yx/linglong-setting-form/last/lib/umd/linglong-setting-form.css"
/>
<script src="//s1.xmcdn.com/yx/linglong-setting-form/last/lib/umd/linglong-setting-form.js"></script>

发布

需要在 node v10 环境编译，否则 build 编译会遇到问题

1. 更新版本号、changelog

   yarn release

2. 发布 xnpm

   yarn publish

3. 云效发布静态资源（主干模式），直接重新部署（一直到正式环境）就行：http://yunxiao.xmly.work/titan/appcenter/5126/overview

4. 替换掉 activity-maker-admin 里 public/index.html 引用此库的版本号

5. 替换掉 create-component-app/component-devtools 里 public/index.html 引用此库的版本号

使用

工具库对外暴露了 SettingForm 组件和 LingLongForm 组件，可以像这样引入它们：

import {
 SettingForm,
 LingLongForm,
 FormField,
} from '@xmly/linglong-setting-form';
import '@xmly/linglong-setting-form/lib/style.css';

完整示例

项目的 示例 提供了完整的使用示范。

SettingForm

工具包将内部的表单实现暴露出来，可以用来创造任何类型的表单。

const fields: FormField[] = [
  { type: 'Input', label: 'Input-inline', name: 'input-inline', llInline: true },
  { type: 'Input', label: 'Input', name: 'input'},
]

function Demo() {
  return (
    <SettingForm
      defaultData={{ 'input-inline': 123, input: 321 }}
      onDataChange={console.log}
      fields={fields}
    />
  );
}

LingLongForm

在 SettingForm 基础上进行封装，用来生成玲珑系统样式的，带有右侧 tab 标签样式的表单。

const fields: FormField[] = [
  { type: 'Input', label: 'Input-inline', name: 'input-inline', llInline: true },
  { type: 'Input', label: 'Input', name: 'input'},
]

const formTabs = [
  { tabTitle: '属性', fields: fields },
  { tabTitle: '行为', fields: fields },
];

function Demo() {
  return (
    <LingLongForm
      formTabs={formTabs}
      defaultData={{ 'input-inline': 123, input: 321 }}
      onDataChange={console.log}
    />
  );
}

ConditionalRender

为了处理常见的表单联动的场景，对 antd#Form.Item 的 dependencies 属性进行封装，已提升易用性。

组件属性：

• dependencies 被依赖表单项的数据
• when 判断是否进行渲染的函数，会将 dependencies 表单项的当前值以数组传入
• render 渲染函数，会将 dependencies 表单项的当前值以数组传入
• fallback 回退函数，默认返回 null，会将 dependencies 表单项的当前值以数组传入

SelfRenderControl

为了支持更加复杂的场景，工具库支持自定义表单控件，type 为 SelfRenderControl，通过向 field 配置传入 render 方法来实现自定义的渲染逻辑。

render 方法接收 value 和 onChange 两个固定属性，另外传递给 field 配置的 controlProps 也会传递给 render 方法。

你可以在 render 方法中使用外层的属性，但更加推荐的方式是将这些属性传给 controlProps，再从 render 的参数中获取，1. 这样控件的属性都在 controlProps 中，具有更好的一致性；2. 这样可以一目了然的知道控件所需的属性有哪些，在进行组件复用或者重构时会更容易一些。

关于自定义控件的写法可以参考 antd#自定义表单控件 和 项目示例

SelfRenderField

SelfRenderField 将表单域的控制权完全交给开发者，在 type 为 SelfRenderField 时，SettingFrom 会执行配置中传入的 render 方法，将 Field 配置中的属性传入，其他的工作就需要开发者自己来做了，比如怎么添加 Form.Item 实现数据注册，添加几个 Form.Item 才能满足需要等等。

配置项

defaultData?: any; onDataChange?: (val: any) => void; onImmediateChange?: (val: any) => void; form?: FormInstance; name?: string; fields?: FormField[]; component?: FormProps'component';

defaultData

表单的数据

onDataChange

表单域或表单值发生变化时的回调，传入表单的全量数据，由于 debounce 会延迟 200ms 触发

onImmediateChange

表单域或表单值发生变化时的回调，传入表单的全量数据，立即触发

form

antd 的 FormInstance，当你需要使用 form 的方法时，可以自己初始化一个，然后将生成的 form 传入 SettingForm。如：

const [form] = Form.useForm();

useEffect(() => {
	console.log(form.getFieldsValue());
}, []);

return <SettingForm form={form} {...props} />;

name

表单的命名空间，给定值的话，form 下的表单域都会组织在该命名空间下。

fields

表单域的数组

component

以什么标签渲染的 form 元素，传入 false 表示不渲染元素。

在 form 发生嵌套时，HTML 会提示异常，此时可以将被嵌套表单的 component 属性指定为 false

formTabs（LingLongForm 独有）

用于渲染玲珑系统样式的、带有右侧 tab 标签样式的表单

组件类型

渲染组件

工具库支持了 antd 内置如下控件

• Input
• InputNumber
• TextArea
• Slider
• Switch
• DatePicker
• TimePicker
• Select
• RadioGroup
• CheckboxGroup

另外内置了系统中常用的控件

• ColorPicker
• ImageUpload
• Background

为了方便使用，在这些控件的基础上封装了如下的表单域

• ImageUploadField
• BackgroundField
• ChildListField
• NofityField

为了满足多样的需求，工具库还支持自定义渲染控件和表单域

• SelfRenderControl
• SelfRenderField

功能组件

功能组件不承担组件渲染的任务，主要是做逻辑的控制，目前仅支持条件渲染功能

• ConditionalRender

关于 controlProps

由于控件都由 SettingForm 统一处理，控件需要的属性要传递给 controlProps 字段，如 readonly、disabled 等。

const filed: Field = {
	type: 'Input',
	label: '演示',
	name: 'pr',
	controlProps: {
		readonly: true,
		disabled: true,
	},
};