w2ui使用指南

简介:

1. w2ui是一套前端UI框架, 基本上是通过json进行自动渲染的, 界面UI比较简洁朴素, 适合后台管理;

2. 包含功能(或插件)有: 布局, 表格, 工具栏, 侧边栏, Tab切换, 弹出层(提醒,对话框等), 表单, 数据校验等, 依赖jquery

3. 这些插件可以自由组合, 比如先定义一个左右的布局页面, 然后左边填充侧边栏插件, 右边填充表格插件

语言本地化

引入w2ui的js以后, 在其下边改写其语言配置(如下); 也可以将下边的代码单独放一个js文件中, 然后引入, 方便复用

//引入w2ui.js以后添加下边代码
w2utils.settings.dateFormat = "yyyy-mm-dd";
w2utils.settings.date_display = "yyyy年mm月dd日";
w2utils.settings.shortmonths = ["1月", "2月", "3月", "4月", "5月", "6月", "7月", "8月", "9月", "10月", "11月", "12月"];
w2utils.settings.fullmonths = ["1月", "2月", "3月", "4月", "5月", "6月", "7月", "8月", "9月", "10月", "11月", "12月"];
w2utils.settings.shortdays = ["一", "二", "三", "四", "五", "六","日"];
w2utils.settings.fulldays = ["星期一", "星期二", "星期三", "星期四", "星期五", "星期六","星期日"]
w2utils.settings.phrases = {
    'Reload data in the list': '重新加载数据',
    'Show/hide columns': '显示/隐藏 列',
    'All Fields':'所有字段, 按回车搜索',
    'Add New' : '添加记录',
    'Add new record':'',
    'Delete' : '删除记录',
    'Cancel' : '取消',
    'Save' : '保存',
    'Save changed records' : '',
    'Delete selected records':'',
    'Are you sure you want to delete NN records?': '是否确定要删除这 NN 条记录?',
    'Your remote data source record count has changed, reloading from the first record.': '数据已变更, 需要重新加载',
    'Refreshing...':'加载中...',
    'Returned data is not in valid JSON format.':'返回了无法解析的数据.',
    'Search':'搜索',
    'Reset':'重置',
    'Open Search Fields':'选择搜索字段',
    'Attach files by dragging and dropping or Click to Select' : '拖拽或点击选择要上传的文件',
    "Not an integer" : "不是一个整数(int)",
    "Not a float" : "不是一个浮点数(float)",
    "Not in money format" : "不是货币格式",
    "Not a hex number" : "不是一个十六进制数",
    "Not alpha-numeric" : "不是字母或数字",
    "Not a valid email" : "不是一个有效的Email地址",
    "is" : "是(等于)",
};

布局 (layout)

1. 配置中的type是内部指定的, 不能自定义. 比如一个左-中的布局, 中间那块的type值是main,而不能自定义

let pstyle = 'border: 1px solid #dfdfdf;';
let layout = {
    name: 'layout',
    padding: 4,
    panels: [
        { type: 'left', size: 150, maxSize:300, style: pstyle, content: 'aaaaa' },
        { type: 'main', minSize:550, style: '', content: 'bbbbb' }, //left,main,right 是有固定意思的, 不能自定义
    ]
};

$('#layout').w2layout(layout); //在dom中渲染此布局

 2. 在左侧渲染一个目录

w2ui.layout.html('left', $().w2sidebar(config));

3. 目前使用来看(v1.5), 一个页面显示多个组件的时候, 需要有先有布局, 直接渲染多个组件样式会乱 

4. 每个panel比如main块都包含几个默认的子模块, 从上到下依次是

子模块	类名	相关方法,属性	备注
标题栏(title)	w2ui-panel-title	属性:panels.title	留空则隐藏
标签栏(tabs)	w2ui-panel-tabs	属性:panels.tabs 方法: hideTabs(); showTabs(); toggleTabs();	默认隐藏, 1.建议将属性先定义出来, 留空, 后续再动态控制内容以及是否显示; 2.他不像toolbar有个assignToolbar添加的方法 3.初始化后, 可以通过 w2ui.layout名_main(top/left/...)_tabs访问
工具栏(toolbar)	w2ui-panel-toolbar	属性: panels.toolbar 方法: assignToolbar(); hideToolbar(); showToolbar();	默认隐藏
内容(content)	w2ui-panel-content	属性: panels.content	默认显示

表格(Grid)

1. 表格中的records中recid是必须要有的, 但是可以不显示

2. 从服务端加载records, 可以在js端更改json数据的格式以符合w2ui的要求, 下边是表格的部分配置:

let config = {
        name: 'grid1',
        url: 'url/to/get/json',
        selectType : 'cell', //点击选择一个cell, 默认为一次选择一行, 这个选择会影响delete时请求参数的结构
        show: {
            toolbar: true,
            footer: true
        },
        textSearch:'contains', //搜索时的匹配规则
        columns: [
            { field: 'recid', caption: '序号', size: '3%' },
            { field: 'code', caption: '编码', size: '10%' },
            { field: 'product_name', caption: '产品', size: '10%' }
        ],
        onLoad: function (event) {
            console.log(event);
            
            //增加必须的recid字段
            let response = JSON.parse(event.xhr.responseText);
            for(let i=0; i<response.length; i++) {
                response[i].recid = i + 1;
            }

            //重新组装json, 以符合w2ui的要求, 注意更改xhr.responseJSON 
            event.xhr.responseJSON = {
                status:'success',
                total:response.length,
                records:response
            };
        }
    }

3. 渲染grid的两种方法

3.1 渲染到指定dom中:

$('#xxxx').w2grid(config);

3.2 返回内容, 但不渲染, 然后把内容放到布局的某个地方

//将表格渲染到布局(layout)的main部分
w2ui.layout.html('main', $().w2grid(config)); //注意其中的$(), 没有指定dom

//将表格渲染到某个dom中
$().w2grid(config); //config中指定了表格的name值为grid1, 在下边用到
$('#selected-tab').w2render('grid1'); //这种写法可以自动清除掉dom中原有的w2ui插件内容

4. 工具栏

4.1 表格自带的工具栏按钮

//简化的表格配置json
let config = {
        name: 'grid',
        url: {
            get: '',
            remove: '',
            save: ''
        },
        show: {
            toolbar: true,
            footer: true,
            toolbarAdd: true,
            toolbarDelete: true,
            toolbarSave: true,
            toolbarEdit: true
        },
        
        ...

        onAdd: function (event) {
            w2alert('add');
        },
        onEdit: function (event) {
            w2alert('edit');
        },
        onDelete: function (event) {
            //删除记录时会有多次回调, 服务端返回后, 才有xhr这个变量
            if (event.xhr) {
                event.xhr.responseJSON = JSON.parse(event.xhr.responseText);
            }
        },
        onSave: function (event) {
            if (event.xhr) {
                event.xhr.responseJSON = JSON.parse(event.xhr.responseText);
            }
        },
        onLoad: function (event) {
            //列表数据动态加载
            if (event.type === 'load') { //如果url是对象的话, 这里要加上type的判断
                let response = JSON.parse(event.xhr.responseText);
                for(let i=0; i<response.length; i++) {
                    response[i].recid = response[i].id;
                }
                event.xhr.responseJSON = {
                    status:'success',
                    total:response.length,
                    records:response
                };
            }
        },
}

4.2 通过配置toolbar属性来自定义工具栏按钮 

let config = {
    name: 'grid',
    ...
    toolbar: {
         items:[
             {type:'button', id:'add', text:'添加记录'},
             {type:'button', id:'del', text:'删除记录'},
         ],
         onClick: function (event){
             console.log(event);
             switch (event.target) {
                 case 'add':

                     break;
                 case 'del':

                     break;
                 default:
                     break;
             }
         }
     },
    ...
}

5. 本地搜素

有的时候希望从服务端加载数据, 但是搜素的时候只在本地搜素, 可以利用onSearch事件, 临时更改url的值, 达到这个效果 (本地搜索的默认匹配规则是左匹配, 可以通过添加配置改为"包含"匹配: textSearch:'contains')

    onSearch: function (event) {
            if (event.phase === 'before') {
                this.url = false; //本地搜素, 不请求服务端
            }
            event.onComplete = function () {
                this.url = url; //恢复URL的原始值
            }
        },

6. 枚举值渲染

服务端返回的数据, 有的是数值, 需要将其映射为汉字显示, 可以使用 grid.columns中的render回调进行转换:

columns: [
            { field: 'name', text: '活动名称', size: '10%', sortable: true },
            { field: 'discount_type', text: '优惠类型', size: '10%', sortable: true, render: function (record){return mapValue(record, 'discount_type')} },
        ],

注意: 这种方法渲染出来的数据, 本地搜素时, 会搜不到这些字段; 如果希望搜到, 就需要在onLoad事件中将服务端返回的数据映射成汉字.

侧边栏(sidebar)

1. 样例(注意img属性, icon属性, 官网例子中的icon属性是依赖font-awsome的, 但一些img值是图片的base64编码写在css文件中的,比如下边 icon-folder, icon-page)

//sideber配置: (expanded:true, 意思是默认展开此菜单)
    let sidebar = {
        name: 'sidebar',
        img: null,
        nodes: [
            { id: 'level-1', text: 'aaaa', img: 'icon-folder', expanded: true,
                nodes: [
                    { id: 'aaaa_add', text: '添加', img: 'icon-page' },
                    { id: 'aaaa_list', text: '列表', img: 'icon-page' },
                ]
            },
            { id: 'level-2', text: 'bbbb', img: 'icon-folder', expanded: true,
                nodes: [
                    { id: 'bbbb_add', text: '添加', img: 'icon-page' },
                    { id: 'bbbb_list', text: '列表', img: 'icon-page' },
                ]
            }
        ],
        onClick: function (event) {
            menuClick(event.target); //target就是nodes.id的值
        }
    };

//渲染sidebar
$('#aaa').w2sidebar(sidebar)

2. 渲染出来后, 要双击父级菜单才可以实现打开与折叠

事件

1. 对于提示无效的json的问题, 需要在事件回调中修改服务端返回的json的数据结构, 以符合w2ui的要求

// grid中获取远程数据后的onLoad
    onLoad: function (event) {
            let response = JSON.parse(event.xhr.responseText);
            for(let i=0; i<response.length; i++) {
                response[i].recid = i + 1; //补上必要的recid
            }
            event.xhr.responseJSON = {
                status:'success',
                total:response.length,
                records:response
            };
        }

//form中提交表单后的onSave
onSave:function (event) {
    event.xhr.responseJSON = event.data; //json对象, 里边有status等字段
}

继续探索中...