@tongfun/tf-widget 0.1.30 → 0.1.31

package/README.md

@@ -1,5 +1,13 @@
 # TF-Widget
-## 版本更新记录
+
+## 目录
+ - [版本更新说明](#1-版本更新记录)
+ - [使用文档](#2-组件使用文档)
+    - [tinput](#21-tinput组件)
+    - [FormBody](#22-formbody单据体组件)
+    - [FormBodyItem](#23-formbodyitem-组件)
+
+## 1 版本更新记录
 
 ## 🍎 0.1.30
 
@@ -85,5 +93,269 @@
 ⭐ 1.组件库初始化
 
 
-## 使用文档
+## 2 组件使用文档
+
+### **2.1 tinput组件**
+
+此组件包含除了基础资料外的常见基本组件，提供统一的样式，和统一入口，基本配置</br>
+组件默认在el-form表单中使用，也可以在表单之外使用
+
+#### (1)基本使用
+
+```html
+  <el-form :model='form'>
+      <!-- 文本输入框 -->
+      <Tinput v-model="form.test" title="输入框" type="input" />
+      <!-- 文本输入框 input可以省略 -->
+      <Tinput v-model="form.test" title="输入框" />
+		
+	
+      <!-- 文本域输入 -->
+      <Tinput v-model="form.test2" title="文本" type="text" />
+      <!-- 可以通过rows指定文本域的行数,默认3行 -->
+      <Tinput v-model="form.test2" title="文本" type="text" :rows='5' />
+
+
+      <!-- 日期和日期时间输入 -->
+      <Tinput v-model="form.test3" title="日期" type="date" />
+      <Tinput v-model="form.test4" title="日期时间" type="datetime" />
+
+      <!-- 数字输入 数字输入必须保障双向绑定到的属性值是undefined -->
+      <Tinput v-model="form.test5" title="整数" type="integer" />
+      <Tinput v-model="form.test6" title="小数" type="decimal" :percision='4' />
+
+      <!-- 选择框 绑定的对象必须{name:null,id:null} 格式-->
+      <!-- enumType是获取选项的参数 可查看租户管理枚举配置中获取 -->
+      <Tinput v-model="form.test7" title="下拉选择框" type="select" enumType='UP_DOWN'/>
+
+      <!--基础资料展示字段  用于创建人，创建时间等永远不会被更改的字段，可以节省性能和内存-->
+      <Tinput v-model="form.test8" title="基础资料展示字段" type="basicDisplay" />
+       <!--使用老版本的通用crud的基础资料，需要提供表名称-->
+      <Tinput v-model="form.test9" title="通用的基础资料" type="basicData" :table-config="{enum:tableEnum,name:'b_basic_brand'}"/>
+       <!--定制的基础资料 -->
+      <Tinput  title="定制的基础资料" type="basicCus" >
+         <BasicData v-model="form.test10" type='employy' @dataConfirm="handleEmployyConfirm"/>	
+      </Tinput>
+      <!--新的通用列表组成的基础资料组件 target是接口的地址 的一部分，后端用于区分不同表单的依据 -->
+      <Tinput title="新版通用基础资料" v-model="form.test8" type="basic" target="/stock/material"></Tinput>
+      <!-- 附件上传 -->
+      <Tinput v-model="form.test11"  label-width="0" type="file" :file-list="fileList"/>
+  </el-form>
+```
+
+```javascript
+// in vue template file
+data(){
+	return {
+		  // 以下仅仅是解释，对应类型的数据是什么样子，实际开发中也可以不在form中添加对应的属性,tinput 控件会根据绑定的属性自动创建
+          // 为了代码的可维护性，在form加入明确的字段是明智的选择
+			form:{
+				test:null,
+				test2:null,
+				test3:null,
+				test4:null,
+				// 数字类型的值初始值必须是undefined
+				test5:undefined,
+				test6:undefined,
+				// 下拉框和基础资料的初始值必须是以下的对象格式
+				test7:{name:null,id:null},
+				test8:{name:null,id:null},
+				test9:{name:null,id:null},
+				test10:{name:null,id:null},
+				/**
+				 * 附件类型需要是数组格式
+				 * v-model：向后端传递的参数
+				 * fileList：上传附件的列表
+				*/
+				test11:[],
+			},
+			// 实际开发中只需要添加一饿空对象即可
+			form:{},
+			// 附件的文件列表
+			fileList:[],
+			// 存储tableID的地方
+			tableEnum:{
+				'b_basic_brand':null
+			}
+	}
+}
+```
+
+#### (2)在表单中加入校验
+
+使用方式element一致，对于基础资料和下拉选择框的校验和平时稍有不同
+
+```html
+
+<el-form model="form" :rules="formRules">
+  <Tinput v-model="form.test" title="输入框" prop="test" type="input"/>
+  <Tinput v-model="form.test2" title="文本" prop="test2" type="text"/>
+  <Tinput v-model="form.test3" title="日期" type="date"/>
+  <Tinput v-model="form.test4" title="日期时间" type="datetime"/>
+  <Tinput v-model="form.test5" title="整数" type="integer"/>
+  <Tinput v-model="form.test6" title="小数" type="decimal"/>
+</el-form>    
+```
+
+todo:添加校验细节
+
+#### (3)其他属性
+
+not-form: 不在表单中使用，仅仅是使用控件，忽略prop title等属性
+
+entity: 在单据体中使用，添加该属性后，效果也与not-form相同，此外样式上也没有底部边框
+
+disabled: 关闭
+
+placeholder : 提示信息
+
+label-width:  就是label-width，感觉没什么卵用，默认150px
+
+#### (4) 其他说明
+
+鉴于基础资料多个租户下不能兼容存在，基础资料的处理没有加入到input组件中
+
+但是有basicDisplay类型仅仅用于展示基础资料类型
+
+
+
+### **2.2 FormBody单据体组件**
+
+#### 全属性案例
+```html
+    <FormBody
+      ref="formBodyRef"
+      height="40vh"
+      :data="data"
+      :calculations="calculations"
+      :before-add-row="beforeAddRow"
+      :after-add-row="afterAddRow"
+    >
+      <FormBodyItem
+        title="所在省"
+        field="province"
+        type="basic"
+        target="/basic/province"
+        :before-input="beforeProvinceInput"
+        :after-basic-selected="afterProvinceSelected"
+      />
+      <FormBodyItem
+        title="邮政编码"
+        field="code"
+        disabled
+      />
+      <FormBodyItem
+        title="所在市"
+        field="city"
+        type="basic"
+        target="/basic/city"
+        :limitation="[{key:'inProvince',value:'province',type:'field'}]"
+      />
+      <!-- precision默认值是2 -->
+      <FormBodyItem title="数量" field="number" type="decimal" :percision="4" />
+      <FormBodyItem title="单价" field="price" type="decimal" :percision="2" />
+      <FormBodyItem title="总额" field="amount" type="decimal" :percision="2" />
+      <FormBodyItem title="是否启用" field="isActive" type="select" enum-type='YES_OR_NO'/>
+      <!-- 默认类型就是input，可以省略 -->
+      <FormBodyItem title="姓名" field="name" type="input" />
+      <FormBodyItem title="出生日期" field="birthDate" type="date" />
+      <FormBodyItem title="审核时间" field="auditTime" type="datetime" />
+
+      <!--      // 极端的情况下，可以放弃封装，直接使用ux-table-column，获取最大的灵活性-->
+      <ux-table-column title="说明" field="example">
+        <template v-slot:edit="scope">
+          {{ scope.row.xx }}
+        </template>
+        <template v-slot="scop">
+          {{ scop.row.yy }}
+        </template>
+      </ux-table-column>
+
+      <!-- 插槽 -->
+      <template v-slot:buttons="{currentRow}">
+        <el-button @click="dialogVisible = true">使用说明</el-button>
+        <!--        这个弹窗可以不放在插槽中，如果需要访问scope中的数据，也可以通过函数的参数来传递-->
+        <el-dialog :visible.sync="dialogVisible">
+          <div class="dialog-content">
+            <span>大概率，这个地方可能还会要一些数据的</span>
+            <p>
+              注意:因为在template模版中，js的编译没有使用转译，所以不能使用可选链(?.)高级语法
+              而且当前作用域的空指针报错，会直接导致子组件不渲染
+              在访问插槽作用域属性时，要考虑空指针问题，建议使用如下方式避免
+            </p>
+            <span>{{ currentRow && currentRow.material }}</span>
+          </div>
+        </el-dialog>
+      </template>
+    </Formbody>
+```
+```javascript
+export default {
+  data(){
+    return {
+      caculations:{
+        amount:'#{number} * #{price}'
+      }
+      
+    }
+  },
+  methods:{
+    beforePrivinceInput(done){
+      if(some condition){
+        done()
+      }
+    },
+    afterPrinvceSelected(row,selected){
+      row.code = selected.code
+    }
+
+  }
+}
+
+```
+
+#### props 
+ - **data:Array** 编辑的列表数据，编辑的目标数据
+ - **disalbeButtons:Array['add','del']** 不需要显示的按钮,和关闭的功能耦合了
+ - **height** 列表的高度，支持vh 和px，其中px作为单位的时候可以省略
+ - **calculations** 列表行字段之间的计算关联 数学表达式
+ - **before-add-row：function(row)** 添加数据行（点击单据体新增按钮）之前执行
+ - **after-add-row(row)** 添加数据行之后执行
+
+#### methods 
+  - **getFormateData(filter)** : 输出格式化之后的数据 <br>
+  参数是可选的函数类型，参数是row，其实就是Array.filter中的参数形式，函数的返回值为true的结果，将会被输出到结果中<br>
+  默认的过滤行为是：一行中所有的字段的值，都是false等价的值，那么将不会输出
+  - **calculate(row)** 针对某一行，重新进行列之间的数学表达式计算
+  - **calculateRow(rows)** 批量进行计算
+
+### **2.3 FormBodyItem** 组件
+
+#### props
+  - 列属性
+    - **title:string** 可编辑列表的列标题，
+    - **field:string** 数据模型的字段
+    - **width:string** 列的默认宽度 
+    - **readOnly:boolean** 不可编辑列
+  - 控件属性 （主要是tiput 属性的再封装）
+    - **type:string**  编辑状态下的输入控件类型，具体参考tinput<br>
+          强烈不建议在单据体中使用text文本域
+    - **disable:boolean** tinput 属性，禁用
+    - **placeholder:string** tinput 属性，占位符内容 
+    - **target:string** 言午的基础资料控件，发送请求必须的参数 
+    - **limitations:Array** 言午的基础资料属性，限定基础资料的查询范围 
+    - **afterBaiscSelected:Function(currentRow,selected)** 基础资料单选或者多选之后要执行的动作 <br>
+        使用场景:<br>
+        当基础资料选择单行或者多行后,,会自动填充并替换下面的行<br>
+        这个过程中，被新添加的行（也包括被修改的行）,因为业务需求，可能会根据选中的基础资料，调用一些接口，来获取行中另外一些字段的数据<br>  
+        可以将这个业务行为通过函数来确定
+        fucntion(selectedRows)<br>
+      这个钩子函数可以是异步的，建议 属性携带的业务，放到同步中，但是需要访问接口查询的数据放到异步中
+    - **beforeInput:Function** 编辑状态下输入前要进行的钩子，但是目前只有言午的基础资料控件提供了实现，basic，其他的控件不生效
+    - **enumType:string** 枚举类型的获取枚举值的接口参数
+    - **percision** 小数保留的位数
+#### event 
+  - change => function(row,value) 值发生改变
+
+#### methods