这是什么

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

效果预览

兼容性

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

如何使用

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

目录结构

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

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

学习路线

直接看示例页面, 通常该页面位于 example 目录下, 示例页面大概率包含了你想要的效果
学习一些 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 当前选中行

fengyun / table Selected .gitee-modal { width: 500px !important; }