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 强制要求的。

【方法二】单页面引入，在需要使用组件的页面：

import myComponent from '@/components/xxx/xxx.vue'
export default {
  components: { myComponent }
  // …
}

【方法三，推荐】使用 uni-app 提供的 easycom 引入方式：
easycom 可以实现批量引入组件，支持自动查找、正则表达式等方式。
在 /pages.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 的格式，有特殊约定：

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）流程信息中的时间线