开源软件名称：

开源软件地址：

开源软件介绍：

这是什么

这是一款可以赋予输入框更实用的表格选择器的能力, 就是这么简单

效果预览

兼容性

理论上兼容所有人类浏览器, 包括但不限于国产套壳浏览器及浏览器内置的极速模式. 谷歌/火狐浏览器, 可能在苹果设备上会有少许差异, 这个暂时无解. 因为本人穷, 买不起苹果! 也不喜欢苹果! 谢谢! 如果是 Mac 端遇到"兼容性"问题, 请自行 fork 一份代码解决后私信我. 代码合适的话会合并过来.

如何使用

1. 下载代码, 通常你可以在项目的 releases 页面找到压缩包.
2. 将下载好的代码解压到你项目中扩展所在目录, 如: libs/layui_exts
3. 率先正确引入 layui, 这是必须的
4. 使用 layui 提供的 layui.config 和 layui.extend 配置和注册扩展.
5. 使用 layui.use 来引用和初始化扩展
6. 开始使用

目录结构

如果你是通过直接拉取本仓库的完整代码来"离线阅读"扩展. 那么可以了解下基本的目录格式.

example --- 示例目录libs --- 扩展目录   libs/layui --- Layui 框架目录   libs/layui_exts --- 扩展目录index.html --- 文档入口(基于docsify)

学习路线

1. 直接看示例页面, 通常该页面位于 example 目录下, 示例页面大概率包含了你想要的效果

2. 学习一些 API, 你可以在本页面阅读或访问本项目的 Gitee Page 地址.

快速上手

引入 layui

首先, 你需要引入 layui, 代码类似于这样

<!-- 引入layui --><script src="../libs/layui/layui.js"></script><link rel="stylesheet" href="../libs/layui/css/layui.css" />

配置扩展

你不需要单独引入扩展的 js 和 css 文件, layui 已经帮你简化了这些操作, 你可以使用类似于如下的代码来引入和注册扩展!

<!-- 配置扩展 --><script>    // 配置扩展路径    layui.config({        base: "../libs/layui_exts/",    });    // 注册扩展    layui.extend({        tableSelected: "tableSelected/index",    });</script>

使用扩展

同样的, 你可以使用 layui 提供的 layui.use 方法来引入扩展, 如果你在 配置扩展 环节没有问题, 那么当你走到这一步的时候, 就等于已经成功了!

layui.use(["tableSelected"], function () {    // 引用扩展    var tableSelected = layui.tableSelected;    // 使用扩展的渲染函数初始化    tableSelected.render();});

学习更多

准备好了吗? 如果示例文件内的内容不能满足你的野心, 那么可以试试学习更多的 API, 看是否能满足你的需求, 如果不能, 你可以自行修改源代码或把你的诉求告诉作者并等待作者更新!

API

render

• 渲染效果
• 参数:
  • elem -- DOM 选择器
  • opt -- 配置项

配置项

v1.0.2.20211011 新增

searchContent

• 默认搜索框内容
• 默认: 没有默认值~

autoSearch

• 是否自动搜索一次
• 配套上面属性使用

showSearchInput

• 是否显示搜索框?
• 默认: true

headerPosition

• 头部位置, 默认 top
• 可设置为: bottom
• 配套 showSearchInput 使用更加刺激!

基础配置

width

• 弹层宽度控制
• 数值或字符串
• 默认: 100%
• 暂不支持调整弹层高度, 如果调整弹层高度, 可适当在 tableConfig 下配置表格高度解决

position

• 弹层的位置
• 字符串
• 默认: down
• 可配置为: up,down

autoRender

• 自动渲染
• 布尔值
• 默认: false
• 开启后选择直接回显,而不是点击提交按钮

autoReset

• 自动重置
• 布尔值
• 默认: true
• 开启后当输入框内容被清空会恢复默认状态

value

• 默认选中的值
• 字符串
• 配合: rowKey 使用
• 等价于 input 直接 value 属性的值

limit

• 选择上线
• 数值
• 默认: 0
• 具体规则:
  • 当 limit=0 表示多选无上限
  • 当 limit=1 表示单选(radio)
  • 当 limit>1 比如 limit=2 表示多选且最多可以选 2 个(checkbox)

searchField

• 表格内执行搜索的键
• 默认: keyword

分隔符

delimiter

• 分隔符

• 对象

• 确认在不同场景下的分隔符

• 可配置值:

  • native

    • 原始输入框的分隔符
    • 字符串
    • 默认: ,

  • render

    • 渲染的输入框分隔符
    • 字符串
    • 默认: ,

高级配置

doubleData

• 双倍快乐
• 布尔值
• 默认: true
• 该选项的作用是让显示的值和录入的值不一样,即一个用于显示,一个用于数据录入
• 配合 rowKey,echoKey 使用
• 配合 event.formatRowKey 事件使用

rowKey

• 行数据唯一标识
• 字符串
• 默认: id

echoKey

• 回显值
• 字符串
• 默认: name

tableAttr

• 表格的属性
• 对象
• 参考资料: https://www.layui.com/doc/element/table.html#default
• 可配置项:
  • layEven
    • 隔行背景
    • 布尔值
    • 默认: true
  • laySkin
    • 风格
    • 无默认值
  • laySize
    • 尺寸
    • 无默认值

searchForm

• 弹层内表单配置

• 对象

• 可配置项:

  • inputValue

    • 输入框默认值
    • 字符串

  • inputPlaceholder

    • 输入框提示信息
    • 字符串
    • 默认: 在列表内搜索

  • submitText

    • 搜索按钮文本
    • 字符串
    • 默认: 搜索

submitText

• 提交按钮配置
• 这个是指弹层头部右侧的确认按钮
• 可配置项:
  • zero
    • 未选中任何数据文本
    • 默认: 请选择
  • notzero
    • 选中了一些行显示的文本
    • 默认: 已选择%s个
    • 其中 %s 会被替换成实际的值
  • radio
    • 单选框选中任意一行的文本
    • 默认: 确认

tableConfig

• 表格的配置
• 除了 id,elem,done 三个被保留, 其他全部可直接使用官方的设置
• 参考资料: https://www.layui.com/doc/modules/table.html

事件托管

事件位于 event 下, 它看上去长得像这样

layui.use(["tableSelected"], function () {    var tableSelected = layui.tableSelected;    tableSelected.render(".checkbox_auto", {        event: {            beforeCreate: function () {},            created: function () {},            beforeMount: function () {},            mounted: function () {},            beforeUpdate: function () {},            updated: function () {},            formatRowKey: function () {},            tableDone: function () {},            change: function () {},            checked: function () {},            submit: function () {},            search: function () {},            checkbox: function () {},            radio: function () {},        },    });});

生命周期

古人云, 取其精华去其糟粕, Vue 大法好! 因此, 你同样可以看到和 Vue 生命周期一样的机制在扩展中的表达

beforeCreate

• 插件准备开始运行

created

• 虚拟 DOM 创建完毕, 还未塞到页面上

beforeMount

• 虚拟 DOM 组装完毕, 但是嘿! 虚晃一枪, 还是没有塞到页面上! 还是个虚拟的 DOM

mounted

• 这回是真的 DOM 了, 已经塞到页面了, 返回各种扩展创建的 DOM 供你进一步的操作
• 传递参数: dom

beforeUpdate

• 当单选框或复选框被选中, 扩展逻辑处理之前
• 传输参数: data 相关数据的集合

updated

• 当单选框或复选框被选中, 扩展逻辑处理之后
• 传输参数: data 相关数据的集合

预处理事件

formatRowKey

• 对行数据进行翻译
• 传递参数: data, 其中包含
  • value
    • 当前选中的值
  • next
    • 传递函数
    • 将处理好的数据传递给扩展

知道你们没理解, 我来个简单的说明吧! 其实你们看示例就知道这个是干嘛的了..

场景举例

比如你现在在一个输入框选择用户, 你希望输入框内显示的是 玩家昵称(name) 但是录入的数据是 玩家ID(id), 这就分别对应着 echoKey(回显键名) 和 rowKey(行唯一标识)

很多场景下都分页的, 比如你客户一共 1W 人, 你不可能不分页直接一次性 1W 条数据全出来. 比如一页数据是 100条, 但是由于你存的是 id, 但你显示的是昵称.

这时候问题就来了, 比如选的用户有一个用户正好不是第一页的数据, 比如是第 101 条数据, 那么这时候, 由于扩展本身没有"下一页"的数据,

必然没办法吧 101 条记录的 id 转移成 name, 这个事件就是做这个用的. 传递 id, 让后端查出来给你就行了. 简单粗暴. 查完了 next 塞回去给扩展即可.

监听事件

tableDone

• 当 layui 的表格创建完毕触发, layui 本身 done 给你啥数据我这里就给你啥数据
• 传递参数: res layui本身 table done 给你返回什么这里就返回什么

change

• 和 updated 理论上没任何区别, 只是语义化一点
• 传递参数: data 数据合集

checked

• 和 updated 理论上没任何区别, 只是语义化一点
• 传递参数: data 数据合集

submit

• 点击提交按钮的时候触发
• 传递参数: data 数据合集

search

• 点击搜索按钮的时候触发
• 传递参数: data 数据合集

checkbox

• 仅 checkbox 触发, 返回选中行
• 传递参数: data 选中行数据集合

radio

• 仅 radio 触发, 返回选中行
• 传递参数: data 当前选中行