bsFormBuilder

一个基于 Bootstrap (v4.x) + JQuery 的、拖拽的表单构建工具。

演示

演示站点：http://bsformbuilder.jpress.cn
推荐一个代码格式化工具：http://www.codeformat.cn

特点

1、基于 Bootstrap (v4.x) + JQuery，简单易用
2、拖动的 html 组件，支持通过 Json 自定义扩展
3、组件的属性面板，支持通过 Json 自定义扩展
4、支持导出 html 和 json，然后自己通过 json 来构建 UI 页面
5、支持导入 json 到 bsFormBuilder，用来进行二次编辑
6、丰富的 API，方便二次开发和扩展
7、支持 “模板” 功能，可以选择已有模板进行二次开发
8、内置轻量的 html 渲染引擎，速度极快，极好用~~

快速使用

<div id="builder"></div>
<script>
    $('#builder').bsFormBuilder({...});
</script>

在使用前，需要导入 bootstrap 和 jquery 的相关文件。

<link href="path/bootstrap.min.css" rel="stylesheet">
<link href="path/bootstrap-icons.css" rel="stylesheet">

<script src="path/jquery.min.js"></script>
<script src="path/bootstrap.bundle.min.js"></script>

<!-- 导入 bs-form-builder 依赖-->
<link href="path/bs-form-builder.min.css" rel="stylesheet">
<script src="path/bs-form-builder.min.all.js"></script>

开发文档

1、初始化

通过 $('#builder').bsFormBuilder({options...}); 进行初始化，bsFormBuilder 方法可以传入 options 配置，options 内容如下：

{
  //模式: "view" 预览模式, "builder" 构建工具模式，默认值为 builder
  mode: "builder", 
  templateEngine: null, //支持自定义模板渲染引擎，默认使用 fasty
  bsFormContainerSelector: ".bsFormContainer", // 设计容器
  bsFormContainerFilterSelector: ".bsFormFilter", // 设计容器里，不允许拖动的组件 class
  bsFormContainerSortableGroup: "shared", // 配置主容器里的 group 名称
  bsFormContainerPlaceHolderSelector: ".bsFormContainer-placeholder", // 设计容器里的提示内容
  bsFormPropsSelector: ".bsFormProps", // 面板内容
  bsFormPropsTitleSelector: ".bsFormPropsTitle", // 面板标题
  bsFormPropsFilter:null, // 属性过滤器，用于对特殊的组件进行属性过滤
  bsFormPropsItemAppended:null, //监听 props html 内容被追加，可以通其设置 propsPanel 里的表单内容或者事件
  customBuilderStructure: false, // 自定义容器面板
  onDataChange:null, //监听数据更新（更新之前）
  onDataChanged:null, //监听数据更新（更新之后）
  renderEmptyDrags: null,//当左边的拖动按钮分类找不到任何组件时，调用该方法
  useComponents:[], //使用哪些组件
  unUseComponents:[], //排除哪些组件（不使用哪些组件）
  customRender:null, //支持自定义渲染方法，或者服务端渲染
  optionsDatasources: null, // 定义数据源      
  //初始化数据
  datas:[],
  //操作按钮列表      
  actionButtons:[],
  //操作按钮模板
  actionButtonTemplate:'',     
  //组件扩展配置，配置的内容可以覆盖掉系统的配置
  components: {},
  //每个组件的默认属性
  defaultProps: [],
  //属性渲染的 html 模板配置
  propTemplates: {},
  //初始化回调方法
  onInit: function(bsFormBuilder){},
}

2、方法调用

1、通过 $('#builder').bsFormBuilder('methodName',arguments...); 方法调用。
2、或者可以通过 $('#builder').bsFormBuilder().data('bsFormBuilder') 来获取 bsFormBuilder 实例，然后直接调用其方法。

bsFormBuilder 支持的方法如下：

init：初始化，bsFormBuilder 自动调用
render(data, withActive)：通过 data 数据，来渲染出一个 html 内容
renderDefault(data)：系统内置的默认渲染方法，当 component 未定义自己的 render 方法的时候，使用该方法进行渲染。
deepCopy(target, withNewElementIdAndId)：深度拷贝工具类
createComponentData(component)：通过 component 来创建 data 数据
genRandomId()：生成一个随机的 id
makeFormItemActive(elementId)：设置选择状态
deleteFormItem(elementId)：删除一个 formItem
copyFormItem(elementId)：复制一个 formItem
getDataByElementId(elementId)：通过一个节点 id 获取 data 数据
removeDataByElementId(elementId)：通过节点 id 移除 data 数据
getParentArrayByElementId(elementId)：通过节点 id 获取其所在的数组
refreshDataIndex($parentElement)：刷新 data 的 index 属性
refreshPropsPanel()：渲染（刷新）属性面板
renderPropTemplate(prop, data, template)：渲染属性模板
exportToJson()：导出 json 数据
exportToHtml()：导出 html 数据
getDatas()：获取 datas 数据，并可以对其进行修改
addDataToRoot(data)：添加一个 data 到根节点
addDatasToRoot(array)：添加一个 data 数组到根节点
addDataToContainer(data, containerElementId, index)：添加一个 data 到一个子container
addDatasToContainer(array, containerElementId, index)：添加一个 data 数组到一个子container
updateDataAttr(data, attr, value)：更新一个 data 的属性，并同步到 html 显示
refreshDataElement(data)：刷新 data 数据到 html
isViewMode()：是否是视图模式
isBuilderMode()：是否是构建模式（构建工具）
clear()：清空设计的所有内容，然后可以重新设计
destroy()：销毁整个组件

3、组件扩展

在 bsFormBuilder 中，组件是通过一个 json 内容来定义的，一个完整的组件的 json 内容如下：

{
    "name": "输入框",
    "tag": "input",
    "drag": {
            "title": "输入框",
            "type": "base",
            "index": 100,
            "icon": "bi bi-terminal"
         },
    "template": '<div class="bsFormItem">' +
                '  <div class="form-group clearfix">' +
                '    <div class="form-label-left">' +
                '      <label for="label">{{label}}</label>' +
                '    </div>' +
                '    <div class="flex-auto">' +
                '      <input type="text" class="form-control" id="{{id}}"' +
                '        placeholder="{{placeholder}} value="{{value}}" />' +
                '    </div>' +
                '  </div>' +
                '</div>',
}

组件属性描述

name：组件名称
tag: 组件 tag，全局唯一，若用户定义的组件 tag 与系统一样，则会覆盖系统的组件定义。
drag：右侧显示的内容
props：组件支持的属性配置
propsfilter：系统属性过滤配置，若为配置则显示系统存在的 props 定义
withOptions：该属性是否带有 options 配置
defaultOptions：options 的默认配置值
optionsTypes：options 支持的类型，目前系统内置两种类型：自定义(custom) 和数据源(datasource)
optionsTitle：options 属性面板的标题
template：模板，可以是一个 string 字符串，也可以是一个返回一个 string 的 function(component, data)。
onAdd：当组件被添加到 html 的时候回调，或者被拖动的时候，注意：当组件从一个子容器被拖动到另一个子容器，也会调用此方法。
onPropChange：当属性被修改的时候，回调。

注意：默认情况下，无需配置 onAdd、onPropChange 方法。除非您已经了解的其作用。

props 属性描述

bsFormBuilder 已经内置了 4 个属性：tag、id、name、label，任何组件都包含有这 4 个属性（除非定义了 propsfilter），然而，一个复杂的组件除了这 4 个属性以外，还应该有其他的属性，比如 textarea 应该有行数 rows。

所以，textarea 组件的定义如下：

{
    "name": "多行输入框",
    "tag": "textarea",
    "props": [
        {
            name: "rows",
            type: "number",
            label: "行数",
            placeholder: "请输入行数...",
            defaultValue: 3,
            disabled: false,
            required: true,
        }
    ],
     "template":"...."   
}

template 语法：

输出：{{attr}}
for循环：{{~ for(let item of array)}} -{{item.name}}- {{~end}}
if循环：{{~ if( x === "string")}} -{{x}}- {{~end}}
if-elseif-else循环：{{~ if( x === "string")}} - {{~elseif(x === "other")} - {{~else}} - {{~end}}

template 内置变量：

$builder : bsFormBuilder 实例
$component：component 实例
$data：当前 component 的数据
$children：html 数组，若当前是一个容器，那么该容器下的 html 内容。

props 描述 props 是一个组件的属性配置，系统内置了 4 个属性，我们可以通过这个来定义组件自己的属性。

例如，textarea 需要定义行号属性，因此，需要添加如下的配置：

{
    name: "rows",
    type: "input",
    label: "行数",
    placeholder: "请输入行数...",
    defaultValue: 5,
    disabled: false,
    required: true,
}

textarea 定义了名称为 rows 的属性，template 必须通过 {{rows}} 来接收该属性的设置：

<textarea rows="{{rows}}">{{value}}</textarea>

prop 属性描述

name: 属性名称
type: 属性渲染类型，支持有：input/select/number/switch/checkbox/radio/none，可以扩展其他属性类型，或者复写这些属性的默认行为。
label: 属性在面板里的label
placeholder: 属性里 placeholder 内容
defaultValue: 属性的默认值
disabled: 属性面板里是否启用
required: 属性面板里是否必填

4、属性扩展

理论上，属性面板支持 input、select、number、switch、checkbox、radio 这 6 种属性类型，已经够用了，不过 bsFormBuilder 依然支持通过在初始化的时候，通过初始化函数来扩展自己的属性面板设置类型。

属性扩展如下：

var options = {
    propTemplates: {
        otherType:function (){
            return '<div> </div>'
        }
    },
    defaultProps:[
        {
            name: "属性名称",
            type: "otherType",
            label: "属性label",
            placeholder: "请输入行数..."
        }
    ]
}
$('#builder').bsFormBuilder(options)

或者

var options = {
    propTemplates: {
        otherType:function (){
            return '<div> </div>'
        }
    },
    components:{
        component1 :{
            "name": "自定义组件1",
            "tag": "component1",
            "props": [
                {
                    name: "属性名称1",
                    type: "otherType",
                    label: "属性名称1",
                }
            ],
            "template":"...."
        },
        component2 :{
            "name": "自定义组件2",
            "tag": "component2",
            "props": [
                {
                    name: "属性名称2",
                    type: "otherType",
                    label: "属性名称2",
                }
            ],
            "template":"...."
        }
    }
}
$('#builder').bsFormBuilder(options)

Options 数据源

在很多场景下，一些组件（比如复选框、下拉菜单等）的内容不是写死的，也不是自定义的，而是来之某个 API 接口，或者说来源于某个 "数据源"。此时，我们要做一下配置：

1、在初始化 bsFormBuilder 的时候，定义好数据源列表，例如：

var options = {
    optionsDatasources:[
                {
                    text: "数据源1", value: "ds1", 
                    options: [
                        {text: "aaa1", value: "value"}
                    ]
                },
                {
                    text: "数据源2", value: 'ds2', 
                    options: [
                        {text: "bbb1", value: "value1"},
                        {text: "bbb2", value: "value2"}
                    ]
                },
                {
                    text: "数据源3", value: "ds3", 
                    options: function (){
                        return ["..."]
                    }
                },
                {
                    text: "数据源4", value: "ds4", 
                    options: "http://www.***.com/***.json"
                }
          ]
}

$('#builder').bsFormBuilder(options);

数据结构说明：

1、optionsDatasources 里有多个数据源，可以配置为 array、function、url (String类型)
2、数据源有 3 个字段： text / value / options
3、每个数据源通过 options 字段来定义数据集合
4、数据（option）是由 value 和 text 组成的

PS:

1、optionsDatasources 可以配置为一个 url 地址(要求返回 json，json 内容必须有 datasources 字段来描述数据源数据)。

2、数据源里的 options 字段，可以是一个数据集合，也可以是一个 function，或者一个 url 地址 (要求返回 json，json 内容必须有 options 字段来描述数据)。

当配置 optionsDatasources 字段后，属性面板会多出一个 "选项类型" 的下拉菜单，用户让用户选择自定义选项，还是使用数据源。

二次开发

1、下载代码

git clone https://gitee.com/fuhai/bsFormBuilder.git

2、安装依赖

npm install

PS：在安装依赖的过程中，可能会出现网络错误，请配置好网络环境，或者多安装几次...

3、构建编译生成 dist 文件

npm run build

商业级定制

联系微信：wx198819880
预算要求：1w 以上

案例：

yangfuhai/bsFormBuilder