Es-el-plus NPM

es-el-plus

Introduce

This package is based on Element Plus and it privides:

Some components which base on the Element plus
A directive v-auth
A global attribute $api for HTTP request
A global attribute $hint for friendly tips
A global attribute $m with some functions

Using

1. Installation

npm install es-el-plus

2. In main.js

import {esElplus} from "es-el-plus"
app.use(esElplus,{
    baseUrl:"/api",  //axios.default.baseURL
    apiContext : require.context("@/api", false, /\.js$/), //http api
    apiResponseErrorInterceptor : function(err){
        //axios response error interceptor will be called when the response is failed;
    },
    apiRequestInterceptor: function(config){
        //axios request interceptor
    }
});

3. Main Components Using

3.1 es-form-loader

The form loading component is used to load forms according to the defined form attribute array. Developers only need to define the form attribute array to be displayed to complete the form loading.

Attributes

Attirbute	Description	default
labelWidth	The length of the label, for example `'120px'`。
model	Form Data Object
ui	Array,The UI definition of form
size	Used to control the size of components in the form，`large\|default\|small`	default

ui Supported types | type | Corresponding Element Plus | | ------------- | ---------------------------------------------- | | input | el-input | | date | el-date-picker | | datetime | el-date-picker | | switch | el-switch | | daterange | el-date-picker | | radio | el-radio-group | | checkbox | el-checkbox-group | | inputnumber | el-input-number | | inputmoney | | | select | el-select | | cascader | el-cascader | | upload | ks-upload | | rate | el-rate | | text | | | slot | slot |

Form Element Properties

Common Attributes | Attribute | Description | Default | |-----|------|-------| |beginRow|Whether to start a row for multi column layout|| |type|Form element type|input| |label|Label Text|| |model|Binding value|| |style|style，For example：{width:"120px"}|| |readonly|same as readonly in native element|false| |clearable|whether to show clear button|true| |placeholder|placeholder of element || |disabled|whether element is disabled|false| |rules|Validation rules||
Input | Attribute | Description | Default | |-----|------|-------| |password|whether to show toggleable password input|false| |multilines|Multi row or not|false| |maxlength|the max length|| |autosize|whether textarea has an adaptive height|true|
```
 {
    type: "input",
    label: "surname",
    model: "name",
    clearable: true,
    disabled:false,
    rules: [{ required: true, message: "Name cannot be empty" }],
    style:{
        width:'200px'
    }
}
```

Date|Datetime|Daterange | Attribute | Description | Default | |-----|------|-------| |disabledDate|a function determining if a date is disabled with that date as its parameter. Should return a Boolean||

{
    label: "Date Range",
    type: "daterange",
    model: "purchasePeriod",
    clearable: true,
    rules: [{ required: true, message: "Please select date range" }],
    disabledDate:function(time){
        return (
            time.getTime() < Date.now() - 8.64e7
        );
    }
},

Switch | Attribute | Description | Default | |-----|------|-------| |switch value when in on state|1| |inactiveValue|switch value when in off state|0|
```
{
    label:"Only see error",
    type:"switch",
    model:"onlyError",
}
```

Radio | Attribute | Description | Default | |-----|------|-------| |source|Object,datasource，format：{valueField:"id",labelField:"name",data:{id:'0', name:"Boy"},{id:'1',name:"Girl"}}，The object attribute of the data array is named valueField and the noun specified by labelField||

{
    label: "Gender",
    type: "radio",
    model: "gender",
    clearable: true,
    disabled:false,
    source:{
        valueField:"id",
        labelField:"name",
        data:[{
            id:'0',
            name:"Man"
        },
        {
            id:'1',
            name:"Woman"
        }]
    },
    rules: [{ required: true, message: "Please select gender" }],
    
}

Checkbox | Attribute | Description | Default | |-----|------|-------| |source|Object,datasource，format：{valueField:"id",labelField:"name",data:{id:'0', name:"Boy"},{id:'1',name:"Girl"}}，The object attribute of the data array is named valueField and the noun specified by labelField||
Inputnumber | Attribute | Description | Default | |-----|------|-------| |min|the minimum allowed value|| |max|the maximum allowed value|| |step|incremental step|1|
```
{
    label: "Count",
    type: "inputnumber",
    model: "count",
    clearable: true,
},
```
Select | Attribute | Description | Default | |-----|------|-------| |source|Object,datasource，format：{valueField:"id",labelField:"name",data:{id:'0', name:"Boy"},{id:'1',name:"Girl"}}，The object attribute of the data array is named valueField and the noun specified by labelField||
```
 {
    label: "Category",
    type: "select",
    model: "category",
    clearable: true,
    disabled:true,
    source: {
        valueField: "id",
        labelField: "label",
        data: [{id:0,label:"video"},
                {id:1,label:"audio"},
                ]
    }
},
```

Cascader | Attribute | Description | Default | |-----|------|-------| |options|data of the options, the key of value and label can be customize by Props.|| |props|Refer to the props attribute of el-casder||

{
    beginRow: true,
    label: "Area",
    type: "cascader",
    model: "combLocId",
    clearable: true,
    options:[],
    props:{
        checkStrictly: true,
    },
    style:{
        width:"350px"
    }
},

Upload | Attribute | Description | Default | |-----|------|-------| |url|URL address||
Rate
3.2 es-table-loader
According to the defined columns arrays of the tables,Table loader can Simplify table definition.
Attributes

Attirbute	Description	default
query-condition	查询条件，如果分页，需要包括三个参数：pageNo, pageSize, totalCount
data	表格数据
columns	表格列属性定义，参看下拉定义
privileges	权限代码数组
buttons	操作列按钮定义，参看下列定义
maxHeight	表格最大高度
height	表格高度
action-column-width	操作列宽度，当定义该属性，系统会提供名为buttons的slot
pageable	是否分页	false
highlight-current-row	是否高亮显示	false
multiSelect	是否多选	false
show-row-number	是否显示行号	false
row-mumber-title	行号列标题	序号
ref-name	Reference Name
row-class-name	function that returns custom class names for a row, or a string assigning class names for every row
span-columns	数组，合并列
show-summary	是否显示合计
summary-columns	数组，合计列
summary-text	合计标题
show-pop-card	是否显示弹出卡片，需要设置属性show-row-number，当鼠标移到行号时显示弹出卡片信息
pop-card-width	弹出卡片宽度
pop-card-column	弹出卡片显示列数

columns | Attirbute | Description | default | | ---------- | ------------------------------------------------- | ------- | | prop|字段名称对应列内容的字段名|| | label|显示的标题 || | width|对应列的宽度 || | headerAlign|表头对齐方式|center| | align|对齐方式 |center| | formatter|内容格式化函数，function(当前行字段值,当前行))|| | image|布尔值，显示为图片|false| | slot|slot，slot的名词为prop定义字段名称||
buttons | Attirbute | Description | default | | ---------- | ------------------------------------------------- | ------- | | type|button type ，refer to el-button|| | code|Permission code|| | event|Trigger Event Name|| | label|button label|| | dropdown|wether Drop down menu|false| | items|Array，Drop down menu item, see the following definition||
- items | Attirbute | Description | default | | ---------- | ------------------------------------------------- | ------- | | itemName|Menu Item Name|| | itemCode|Permission code|| | event|Trigger Event Name||

Events

 |Event|Description|Parameter|
 |---|---|---|
 |currentPageChanged|triggers when the current page changes||
 |currentRowChanged|triggers when current row changes|currentRow|
 |multiSelect|triggers where single select a row under multiple selection||selection|
 |select|triggers where single select a row|selection|
 |rowDoubleClick|triggers when double clicking a row|row|
 |rowClick|triggers when clicking a row|row|
 |Custom Events|Trigger event corresponding to buttons|index, row|

<template>
     <es-table-loader
                 pageable
                 :columns="ui.columns"
                 :data="tableData"
                 :query-condition="qryCondition"
                 @currentPageChanged="doQuery"
                 @currentRowChanged="doCurrentRowChanged"
                 :highlightCurrentRow="true"
                 @rowDoubleClick="doRowDoubleClick"
                 :show-row-number="true">
                 <template #subName="scope">
                     <span :class="{frozen:scope.row.isFrozen}">{{scope.row.subName}}</span>
                 </template>
                 <template #adminType="scope">
                     <span>{{$m.dictFormat(scope.row.adminType,"officialLevel","officialLevelId","officialLevel",$store.state.dicts)}}</span>
                 </template>
     </es-table-loader>
 </template>

 <script setup>
     import {ref,reactive,onMounted,getCurrentInstance,watch} from "vue"
     import ui from "./table.js"
 
     const {appContext: {config: {globalProperties: global}}} = getCurrentInstance();

     const emit = defineEmits(['update:visible','select','cancel'])

     const tableData = ref([]);

     const qryCondition = reactive({
         pageNo: 1,
         pageSize: 5,
         totalCount:0,
     });

    const doCurrentRowChanged = function(row){
        selectedSub = row;
    }

    const doSelect = function(){
        emit("select",selectedSub);
    }

    const doRowDoubleClick = function(row){
        emit("select",row);//
    }

    const doCancel = function(){
        emit("update:visible",false);
    }

    const doQuery = function(){
        global.$api.sub.query(qryCondition).then(
            (data)=>{
                tableData.value = data.result;
                qryCondition.totalCount = data.total;
            },
            (err)=>{
                global.$hint.error(err);
            }
        );
    }
</script>

table.js

export default { columns: { prop: "subNo", label: "SubNo", width: 150, }, { prop: "subName", label: "SubName", width: 400, slot:true }, { prop: "subType", label: "SubType", width: 100, slot: true }, { prop: "address", label: "Address", width: 300, }, }

#### 3.3 es-dialog
 Dialog
 - Attribute

     | Attirbute  | Description | default |
     | ---------- | ----------- | ------- |
     |title|title of Dialog||
     |visible|visibility of Dialog	||
     |width|width of Dialog||
     |ok|function，Callback function when OK button is clicked||
     |cancel|function，Callback function when CANCEL button is clicked||
     |close|function，Callback function when dialog is closed||
     |open|function，Callback function when dialog is opened||
     |destroy-on-close|Destroy elements in Dialog when closed|true|
     |cancel-button-visible|Whether to display the cancel button||
     |ok-button-visible|Whether to display the ok button||
     |cancel-button-title|The title of Cancel button||
     |ok-button-title|The title of Ok button||

     ``` vue
     <template>
         <es-dialog title="Dialog" v-model:visible="visible" :ok="doOK" :cancel="doClose">
         </es-dialog>
     </template>
     <script setup>
         const props = defineProps({
             visible: {
                 type: Boolean,
                 default: false,
             },
         });
         const doOK = function(){
             editForm.value.validate(()=>{
                 emit("success",data); 
             });
         }
         const doClose = function(){
             emit("update:visible",false);
         }
     </script>
     ```

#### 3.4 es-toolbar
 Toolbar
 - Attributes

     | Attirbute  | Description | default |
     | ---------- | ----------- | ------- |
     |justify-content|Button alignment in toolbar,&#91;start	&#124;end&#124;center&#93;|start|
     |end-right|Whether right aligned placeholders are provided|false|
 - slot
     | Name | Description|
     |---|---|
     |default|Left button slot|
     |end|Right button slot，Valid when the end-right is true|

     ``` vue
         <es-toolbar :end-right="true" >
             <el-button type="primary"
                     size="small"
                     @click="doNew">New</el-button>
             <el-button type="primary"
                     size="small"
                     @click="doDelete">Delete</el-button>
             <template #end>
                 <el-button :icon="Back" size="small" circle @click="doBack"/>
             </template>
         </es-toolbar>
     ```

#### 3.5 es-timer
 Timer
 - Attributes
     | Attirbute  | Description | default |
     | ---------- | ----------- | ------- |
     | interval| Time interval, ms|1000|
 - Events
     | Event| Description|
     | -------| --- |
     | task| Trigger function|
 ```
 <template>
     <div>
     <ks-timer @task="doTimer" :interval="3000"></ks-timer>
     </div>
 </template>

 <script setup>
     const doTimer = function(){
         console.log("timer");
     }
 </script>
 ```

### 4. Directives

#### v-auth

``` vue
<el-button type="primary"
         size="small"
         v-auth:[$store.getters.privileges]="$gl.au_wm_add"
         @click="doNewMask">New</el-button>

The directive argument is an array of permission codes. And the directive value is the permission code that is related to the DOM elements.

5. Global \$api

In main.js：

import {esElplus} from "es-el-plus"
app.use(kisElplus,{
    baseUrl:"/api",
    apiContext : require.context("@/api", false, /\.js$/)
});

Set axios baseURL with the options baseUrl
Using the function request.context to set the option apiContext. The first parameter is the directory of API js files. The API files will be delegated by the global \$api . The file name will be one of attributes of the object \$api.
The API js files should import http module(provides methods : get,post,delete,post,postFormData) from this package. And API function should be defined like:

    function(data){
        return http.post(url,data);  //return a promise
    }

e.g.

sec.js

import {http} from "es-el-plus"
export default {
    login(data){
        return http.post("/login",data);
    },
}

caller.js

    setup(props,context) {
        const {appContext: {config: {globalProperties: global}}} = getCurrentInstance();
        global.$api.sec.login({username:"aaa",password:"11111"}).then(
        (data) => {
            //success
        },
        (err)=>{
            //failed
        }  
    );
    }

6. Global \$hint

method	Parameters	description
confirm	param:{title,yesAction,noAction}	yesAction will be called while user click yes button and noAction will be called while click no button
alert	(msg,action)	action will be called while user click the ok button
delete	(yesAction,msg)	yesAction will be called while user click the ok button
success	(msg)	default "success"
error	(msg)	default "failed"
msg	(msg)

7. Global \$m

Method	Parameters	description
formatDate	(value)	Returns a formatted string like "yyyy-MM-dd"
formatDateTime	(value)	Returns a formatted string like "yyyy-MM-dd hh:mm:ss"
formatMoney
isEmpty	(object)	Check whether the given object is undefined or null or an empty string
isRef	(object)	Check whether the given object is undefined or null
isPromise	(object)	Check whether the given object is Promise
isFunction	(object)	Check whether the given object is Function
isObject	(object)	Check whether the given object is Object
isArray	(object)	Check whether the given object is Array