DigitalScholl/Learun.Framework.Ultimate V7/LearunApp-2.2.0/docs/component.md

# 力软框架移动端 · 移动端组件文档
组件放在 /components 目录下，目录结构如下：  
- **/components/learun-app** ：力软框架专用定制组件（依赖于力软 API，离开了框架无法独立运行）；
- **/components/learun-mpui** ：力软框架基础组件（输入框、表单、列表布局等）；
- **/components/其他** ：其他第三方组件。
  
由于不同平台存在差异，力软对不同平台实现了多套组件、多套样式，并使用条件编译进行切换。  
  
# 组件引入方式
先将组件放置于 /components 目录下，一般来说组件由一个或多个 .vue 文件，可能会包含一些 .js 文件；  
  
【方法一】全局注册，在 **/main.js** 中引入并注册：  
先引入组件：  
`import myComponent from '@/components/my-component/index.vue'`
再注册组件：  
`Vue.component('my-component', myComponent)`
  
使用这种方式，组件名必须是静态字符串，不能用变量，且必须带横杠，不要使用 `'myComponent'` 作为注册的名称，这是 uni-app 强制要求的。  
  
【方法二】单页面引入，在需要使用组件的页面：  
``` javascript
import myComponent from '@/components/xxx/xxx.vue'
export default {
  components: { myComponent }
  // …
}
```
  
【方法三，推荐】使用 uni-app 提供的 easycom 引入方式：  
[easycom](https://uniapp.dcloud.io/collocation/pages?id=easycom) 可以实现批量引入组件，支持自动查找、正则表达式等方式。  
在 **/pages.json** 中进行相关定义：  
``` json
{
  // pages.json 的其他项…
  
  "easycom": {
    "custom": {
      // 固定路径引入
      "l-scroll-list": "@/components/learun-app/scroll-list.vue",
      
      // 正则表达式批量匹配，键名中的括号捕获字符，值中的 $1 占位符表示第一组捕获到的值
      "l-(.*)": "@/components/learun-mpui/learun-ui-mp/$1.vue"
    }
  }
}
```
  
【注意】使用固定路径引入时，uni-app 会自上而下来匹配组件名，如果存在某个组件的名称完全包含另一个组件名称（例如，`l-customform` 和 `l-customform-table`）请将长的组件名放在前面，短的放在后面，避免 uni-app 把两个组件都识别为短的。  
使用这种方式，uni 会自动分析页面中用到的组件，并进行按需引入。开发者也可以在单个页面中直接引用组件，自行引用的组件优先级高于 easycom 引入的组件。  
力软框架使用此方式引入基础组件和扩展组件。  

# 力软扩展组件
这些组件依赖力软 API，专为实现力软框架中的需求而开发，离开框架后无法工作；路径： **/components/learun-app**。  



## `<l-customform>` 渲染表单
按给定的表单结构、数据值渲染出一张表单；框架中的工作流表单、自定义应用均是使用此组件渲染表单。  
工作流表单：自 /common/customform.js、/pages/nworkflow/workflow.js 中的相关方法生成 scheme、initFormValue、rel 等传入；
自定义应用：自 /pages/customapp/customapp.js 中的相关方法生成 scheme、initFormValue、rel 等传入。
  
参数：  
- `scheme`： （Array）表单的结构定义  
- `initFormValue`： （Objcet）表单的初始数据值  
- `editMode`： （Boolean）表单是否可编辑  
- `rel`： （Object）表单字段关系，用于处理级联组织结构选择器、日期区间计算等  

组件实例方法：  
- `setFormValue(val)`： 设置表单的数据值  
- `getFormValue()`： 获取表单的数据值
- `verifyValue()`： 对表单进行验证，返回一个包含所有错误的数组，数组为空则表示无错误

说明：  
`scheme` 中的每一项必须带有 `__valuePath__` 字段表示绑定到表单值的路径；可以带有 `__sourceData__` 字段表示数据源；可以带有 `__relationPath__` 字段表示从 `rel` 中获取依赖关系的路径，获取依赖关系后便可以实现组织结构选择器的级联、日期区间计算等关联计算。  
因为性能原因，该组件不提供 v-model 双向绑定，设置/获取表单值需要使用 `setFormValue()`/`getFormValue()` 两个组件实例方法来进行。  



## `<l-customform-table>` 渲染表单-子表格
用于 `<l-customform>`，实现其中的子表格渲染；开发者通常不会使用到该组件。  
  
参数：  
- `value`： （Array）子表格的数据值，可以使用 v-model 双向绑定  
- `item`： （Object）子表格的 scheme 项  
- `edit`： （Boolen）子表格可否编辑  

事件：  
- `input`： 实现 v-model 绑定数据值

说明：  
item 参数为子表格 scheme 项，自身需带有 `__defaultItem__` 字段表示表格项的默认值；带有 `fieldsData` 字段即表示子表格的 scheme；子表格 scheme 的每一项，需要 `__valuePath__` 字段表示绑定到表单值的路径；可以带有 `__sourceData__` 字段表示数据源。  



## `<l-scroll-list>` 滚动列表
滚动列表，带有下拉刷新、上拉加载更多的功能，适配多端。  
  
参数：  
- `refresherBackground`： （String）下拉刷新时露出区域的背景色，默认为 `'#f3f3f3'`  

插槽：  
- `default`： 请将列表内容放在本组件标签中

事件：  
- `pullDown`： 下拉刷新列表（需使用 `stopPullDown()` 停止下拉状态）
- `toBottom`： 滚动列表触底，触发上拉加载
- `scroll(h)`： 滚动列表滚动到某个高度

组件实例方法：  
- `scrollTo(h)`： 让列表滚动到某个高度  
- `stopPullDown()`： 停止下拉刷新  

说明：  
用于实现下拉刷新、上拉加载列表。  
在 H5 端，uni-app 模拟的下拉列表存在 bug，滚动速度快且特别容易触发下拉刷新，力软框架做了封装处理，只有列表距离顶部的高度接近 0 时才可下拉刷新。  



## `<l-customlist>` 表单列表容器
用于容纳表单列表项，适用于自定义应用、自定义表单的列表页。  

参数：  
- `showTips`： （Boolean）是否显示表尾 tips 文字，默认是 `false`
- `tips`： （String）表尾 tips 文字，默认为 `'已加载全部项目'`

插槽：  
- `default`： 请将列表通过 `v-for` 循环渲染在其中



## `<l-customlist-action>` 表单列表-操作区
表单项的操作区，即包含了「编辑」、「删除」、「查看」三个按钮的区域。「查看」按钮是始终显示的，其它两个按钮按需显示。  

参数：  
- `showDelete`： （Boolean）是否显示删除按钮，默认是 `false`
- `showEdit`： （Boolean）是否显示编辑按钮，默认是 `false`

事件：  
- `delete`： 点击了删除按钮
- `edit`： 点击了编辑按钮
- `view`： 点击了查看按钮



## `<l-customlist-add>` 表单列表-新增按钮
表单列表页面的新增按钮，固定显示在页面右下角。  

参数：  
- `icon`： （String）按钮的图标，默认为加号 `'add'`

事件：  
- `click`： 点击了该按钮



## `<l-customlist-banner>` 表单列表-表头提示栏
表单列表的表头提示栏，固定在页面顶部，一般用来提示页码等信息。  

参数：  
- `buttonShow`： （Boolean）是否在右侧显示一个按钮，一般用于打开筛选侧边栏，默认为 `true`
- `buttonIcon`： （String）按钮的类型，默认为 `'searchlist'`

插槽：  
- `default`： 请将表头要显示的内容放在本组件标签中

事件：  
- `buttonClick`： 表头右侧的按钮被点击



## `<l-customlist-sidepage-datefilter>` 表单列表-侧边栏-时间日期筛选器
放在表单列表页的侧边栏中，用于用户打开侧边栏进行日期筛选时使用。  

参数：  
- `value`： （Object）筛选的区间值，可以使用 v-model 双向绑定
- `title`： （String）筛选器的标题，默认为 `'按时间日期筛选：'`
- `ranges`： （Array）筛选器允许选择的时间日期区间，默认为 `['all', 'today', '7d', '1m', '3m', 'custom']`

事件：  
- `input`： 实现 v-model 绑定值
- `change`： 筛选区间值发生修改时触发

说明：  
区间值是一个数组，允许使用以下子项：`'all'` 表示所有，`'today'` 表示今天，`'7d'` 表示7天内，`'1m'` 表示1个月内，`'3m'` 表示3个月内，`'custom'` 表示允许用户自定。  
v-model 绑定的值，如果区间设置为「所有」，或者设置为自定义但是给出了错误的区间，那么该值为 `null`，否则其形如：`{ start: '', end: '' }`。  



## `<l-demo-description>` 组件说明
用于组件演示，介绍组件的功能和用法，点击后才会展开说明文字。  

参数：  
- `expand`： （Boolean）是否默认展开，默认为 `false`
- `tips`： （String）未展开状态的文字提示，默认为 `'显示说明'`

插槽：  
- `default`： 把描述文本放在本组件标签中



## `<l-layer-picker>` 弹层选择器
表单项中的弹层选择器组件，点击后跳转到弹层选择器页面，用户选择后返回。  
弹层选择页面位于 `/pages/common/select-layer.vue`。  

参数：  
- `value`： （String）选择器选择的值，该值直接显示在组件上
- `source`： （Array）数据源，可以通过数据字典或者数据源来加载
- `layerData`： （Array）弹层绑定到的字段的配置，详细要求见下文说明
- `title`： （String）标题文字
- `required`： （Boolean）是否在最左侧显示红色的星号，默认为 `false`
- `placeholder`： （String）数据值为空时的占位文字，默认为 `'点击以选择'`
- `readonly`： （Boolean）是否只读，默认为 `false`

事件：  
- `input`：用户点选某个弹层项后，会触发此事件，事件参数为用户选择的弹层项的值对象
- `change`：同上述 `input` 事件

说明：  
参数 `source` 的格式只需要为对象数组即可，无特殊要求；  
参数 `layerData` 的格式，有特殊约定：  
``` javascript
const layerData = [
  { name: '对应 source 中的哪个字段', label: '显示的标题文字', value: '绑定到表单中的哪个字段' },
  // ...
]
```
弹层选择器会根据 `layerData` 中所有 `name` 属性提取出 `source` 中相应的字段，并显示在弹层选择列表当中；  
字段 `label` 为每个弹层值的标题文字。  



## `<l-organize-picker>` 单位组织选择器
表单中的组织结构选择器，点击后跳转到组织结构选择页面，用户选择后返回。  
组织结构选择页面位于 `/pages/common/select-organize.vue`。  

参数：  
- `value`： （String）表单数据值，表示当前所选的组织结构的 id，可以使用 v-model 双向绑定
- `type`： （String）必填项，选择器的级别，可选 `'company'`/`'department'`/`'user'` 表示公司/部门/人员选择器
- `rootType`： （String）选择器根级的种类，配合 `rootId` 使用，控制选择器的可选范围，没有则无范围限制
- `rootId`： （String）选择器根级元素的 id，配合 `rootType` 使用，用于控制选择器的范围，没有则无范围限制
- `title`： （String）标题文字
- `required`： （Boolean）是否在最左侧显示红色的星号，默认为 `false`
- `placeholder`： （String）数据值为空时的占位文字
- `readonly`： （Boolean）是否只读，默认为 `false`

事件：  
- `input`：实现 v-model 绑定；用户点选某个单位组织项后，会触发此事件，事件参数为用户选择的组织结构对象的 id
- `change`：同上述 `input` 事件

说明：  
`rootType` 表示根级元素的类别， `rootId` 示根级元素的 id，这两个属性来确定根级元素；  
`rootType` 默认为当前 `type` 的更上一级，例如 `type='user'` 的情况下则 `rootType='department'`；  
存在一个唯一的全局顶级根元素，它的 `rootType` 为 `'company'`，它的 `rootId` 为 `'0'`，它默认不会显示在树形表中，如果没有设置根级元素，那么默认就是使用这个根级元素。  



## `<l-upload-file>` 文件上传下载
表单项中的文件上传下载组件，数据需要使用特定的格式，见下文说明。  
注意：上传文件时只能添加图片文件；小程序平台有文件格式限定，有文件大小限制，非图片、文档文件也无法保存到本地。  

不同的格式处理方式不同：  
图片：客户端添加的图片直接显示为 `<image>`，点击可以预览；服务器端的图片直接下载到本地，显示方式同。  
文档：在小程序端点击后会开始下载，下载完成会打开预览（钉钉小程序无法预览）；App 端点击会开始下载，下载完成会显示打开方式菜单；H5 直接使用浏览器下载；  
其他文件：小程序端点击后会提示无法下载；App 端和 H5 端同温度。  
  
  
参数：  
- `value`： （Array）当前文件列表，可使用 v-model 双向绑定，格式为 [{ path: '', size: 100, uid: 'xxx', type: 'png' }]，见下文说明
- `number`： （Number）允许添加的文件数量上限，默认为 `9`
- `readonly`： （Boolean）是否只读，默认为 `false`
- `title`： （String）标题文字
- `required`： （Boolean）是否在最左侧显示红色的星号，默认为 `false`

事件：  
- `input`：实现 v-model 绑定，文件列表修改，参数为新的文件列表
- `change`：同上述 `input` 事件
- `add`：添加文件时触发
- `del`：删除文件时触发

说明：  
组件会根据文件列表中的字段来判断显示方式：  
- `type`：表示文件格式，组件根据格式来显示文件，是图片格式则显示为 `<image>` 预览，是文档则显示为文档图标，否则显示为文件图标
- `path`：文件在本地的临时路径，图片文件会直接使用该字段作为 `<image>` 的 `src` 属性
- `uid`：文件的 id，使用该字段作为服务器下载文件的参数
- `size`：文件大小，单位为 Byte，小程序无法打开超过 50MB 的文件，会根据此字段进行判断
  
注意：刚添加的文件，没有 `uid` 和 `size` 字段，只有从服务器下载的文件才会有这些字段，因此可以通过这些字段判断哪些文件需要上传。  
文件不会自动上传，开发者通过 `v-model` 绑定的值获取文件临时路径，依次上传这些文件。  

 

## `<l-organize-tree>` 单位组织-树形表
单位组织结构的树形表，用于通讯录、组织结构选择器。  
本组件为递归组件，展示自身和子节点。  

参数：  
- `root`： （Object）组织结构根节点，默认为 `{ type: 'company', id: '0' }`，系统内置的根节点
- `button`： （Boolean）是否展示选择按钮，默认为 `false`
- `level`： （String）在哪一级节点上展示选择按钮，需要开启 `button`，默认为 `'user'`

事件：  
- `userClick(item)`：点击用户级别节点时触发事件
- `buttonClick(item)`： 点击选择按钮时触发事件，未开启显示按钮则不会触发此事件

说明：  
用做通讯录时，一般使用 `userClick` 事件；用做组织结构选择器时，一般使用 `buttonClick` 事件。  



## `<l-organize-single-item>` 单位组织-用户列表
用于平级显示用户信息，用于通讯录输入了搜索文字后，展示平级列表的用户子项。  

参数：  
- `item`： （Object）用户对象
- `button`： （Boolean）是否展示选择按钮，默认为 `false`

事件：  
- `buttonClick(item)`：点击选择按钮时触发的事件
- `click(item)`： 点击事件



## `<l-workflow-action>` 工作流操作区
显示工作流的操作区按钮。  

参数：  
- `currentNode`： （Object）当前节点信息（获取审核按钮列表、是否允许加签）
- `currentTask`： （Object）当前任务信息（获取打来自、是否可以加签）
- `type`： （String）当前页面类型，可选值：`'child'`、`'refer'`、`'view'`、`'create'`（仅系统表单）、`'again'`（仅系统表单）

事件：  
- `audit(auditItem)`：点击审批按钮时触发的事件，参数为审批按钮对象
- `action(type)`： 点击表单操作按钮时触发的事件，参数为操作类型字符串，可选值：`'urge'`/`'revoke'`/`'refer'`/`'draft'`/`'submit'` 分别表示催办/撤销/传阅/草稿提交/表单提交



## `<l-workflow-timeline>` 工作流时间线
显示工作流的时间线。  

参数：  
- `processList`： （Array）流程信息中的时间线
-