1 Star 0 Fork 27

touchx / TinySelect

forked from 小李 / TinySelect 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
MIT

TinySelect

TinySelect 是一个以灵活为目标的WEB下拉组件。旨在通过灵活的接口和用法,适应各种不同的场景

  • 单选/多选
  • 支持直接从select元素渲染
  • 提供过滤框以通过关键字简单过滤数据
  • 编程显示/隐藏下拉框
  • 编程过滤数据,可以是关键字或函数
  • 支持selectunselectready事件
  • 支持设置初始值
  • 支持后加载数据/重新加载数据
  • 编程设置下拉组件只读属性
  • 丰富的初始化选项,并且可以通过选项设置样式
  • 提供多种渲染器的自定义支持,如:下拉项,header,footer和选中结果
  • 可以设置部分数据的显示模板
  • 支持数据项的异步渲染
  • 支持多种显示模式:下拉(dropdown, 默认)、列表(list)、弹出(popup)
  • 支持多种数据项布局:列表(list, 默认)、网格(grid)、表格(table)
  • 支持键盘操作移动与选择项

快速上手

dist目录复制到你的项目中,然后在页面上添加引用

<link rel="stylesheet" type="text/css" href="dist/tinyselect.css" />
<script type="text/javascript" src="dist/tinyselect.js" />

HTML结构

<div id="tinyselectcontext"></div>

<select id="tinyselectcontext">
    <optgroup label="1-2">
        <option>1</option>
        <option value="2"></option>
    </optgroup>
    <optgroup label="3-5">
        <option value="3">3</option>
        <option value="4">4</option>
        <option value="伍"></option>
    </optgroup>
    <option value="6">6</option>
    <option value="7">7</option>
    <option value="8">8</option>
    <option value="9">9</option>
</select>

数据

var data = [{
    "id": 0,
    "text": "一月"
    }, {
        "id": 1,
        "text": "二月"
    }, {
        "id": 2,
        "text": "三月"
    }, {
        "id": 3,
        "text": "四月"
    }, {
        "id": 4,
        "text": "五月"
    }, {
        "id": 5,
        "text": "六月"
    }, {
        "id": 6,
        "text": "七月"
    }, {
        "id": 7,
        "text": "八月"
    }, {
        "id": 8,
        "text": "九月"
    }, {
        "id": 9,
        "text": "十月"
    }, {
        "id": 10,
        "text": "十一月"
    }, {
        "id": 11,
        "text": "十二月"
}];

最简单的用法

单选

var ts = tinyselect('#tinyselectcontext', data);

多选

var ts = tinyselect('#tinyselectcontext', data, true);

注:参数 true仅在第二个参数为数据数组时有效。

通过select元素创建TinySelect

通过select元素创建TinySelect实例时,传入配置需要注意以下问题:

  • 支持读取select的以下属性:
    • readonly 生成只读实例
    • disabled 生成只读实例
    • multiple 生成多选实例
  • 尽量在配置中通过设置contextcss属性和style属性来控制select占位元素的样式,如:
     {
          context:{
              css: '自定义的样式类名称',
              style: '自定义样式'
          }
     }
    在设置了这些样式时,占位元素的所有样式都靠自定义,TinySelect不会自动生成任何样式。 否则将应用select元素的样式,此时至少需要设置select元素的宽度和高度, 当然要是再设置个border那就更好了。
  • 支持optgroup分组

加点选项的用法

var ts = tinyselect('#tinyselectcontext', {
    css: 'custom-select-style',
    style:{
        width: 400
    },
    item:{
        data: data,
        render: function(data, index){
            return (index + 1) + ':' + data.text;
        }
    }
});

这里指定了自定义的样式类custom-select-style,这个类会被附加到下拉组件的顶层容器上,可以通过.tinyselect-container.custom-select-style这样的方式来重写样式。

更多用法,请看示例

选项

创建下拉组件的默认选项。这里列出了所有可用的项,这些项会被附加到TinySelect上面,可以通过修改tinyselect.defaults 来改变这些默认配置,如: tinyselect.defaults.result.multi = true 这样的写法会让页面内之后创建的下拉组件都默认启用多选模式。

{
    // 组件是否是只读的
    readonly: false,
    // 显示模式,可以设置的值为: dropdown(默认下拉模式), list(列表模式), popup(弹出模式)
    mode: 'dropdown',
    // 是否支持键盘操作,默认为 true
    keyboard: true,
    // 附加的样式类名称
    css: NULL,
    // 下拉框容器的样式
    style: {
        // 这个行高是必须的,覆盖这些样式时,需要注意,
        // 其值需要是可以转换成整数的类型,因为下拉的项会使用这个作为默认的行高
        // 例外的情况:设置了项的行高(即下面的 item.line-height)
        lineHeight: '28px'
    },
    // 下拉框的头部
    header: {
        // 头部渲染器,其this上下文就是其DOM对象,
        // 直接操作这个对象来改变头部
        // 这个是在执行完其初始化,添加到容器前调用的
        render: false,
        // 过滤框
        filter: {
            // 触发过滤的动作,可以设置为 change 或 enter(默认)。
            // 为change时,输入有变化时执行
            // 为enter时,按下回车时执行
            trigger: 'enter',
            // 此值表示在输入框经过指定时间后没有键盘输入时,触发过滤动作
            // 单位是毫秒,默认值为 618
            // 当 trigger 为change时有效
            // 设置这个是为了防止使用亚洲输入法时(比如:中文,日文等)时,文字输入中将字母上屏导致的事件触发
            delay: 618,
            // 过滤框的提示文字
            placeholder: '输入后按回车过滤',
            // 过滤时是否区分大小写,默认为 false
            matchCase: false,
            // 附加的样式类名称
            css: NULL,
            // 过滤框的样式
            style: {}
        },
        // 附加的样式类名称
        css: NULL,
        // 头部样式
        style: {}
    },
    // 下拉项容器
    box: {
        // 下拉列表没有数据时显示的文字
        empty: '没有数据',
        // 数据项的布局方式
        // 可设置的值有: list(列表布局,默认值), grid(网格布局), table(表格布局)
        layout: layout_list,
        // 附加的样式类名称
        css: NULL,
        // 下拉项容器的样式
        style: {}
    },
    // 数据项分组设置
    group: {
        // 分组值字段
        // 设置此值时才会分组
        valueField: false,
        // 分组文本字段,不设置时使用 valueField
        // 相同的 valueField 而 textField不同时,只会取第一个 textField的值
        textField: false,
        // 数据项不包含指定的 valueField字段时的分组名称
        unknown: '未分组',
        // 分组的渲染器
        render: false,
        // 附加的样式类名称
        css: NULL,
        // 下拉项容器的样式
        style: {}
    },
    // 下拉项
    item: {
        // 下拉项数据的数组,每一项需要对象结构的数据
        data: [],
        // 默认选中的项
        value: false,
        // 数据对象的值字段,在获取/设置值时,会使用这个字段
        valueField: 'id',
        // 数据对象的文本字段,下拉项的显示文字
        textField: 'text',
        // 可见项的数量,数据数量多余此值时出现滚动条
        visible: 5,
        // 下拉项的渲染器,使用返回值设置项的内容
        // render: function(itemdata, index, alldata){}  this 指向即将渲染的网页元素对象。
        // itemdata:这一项的数据 
        // index: 这一项数据的索引
        // alldata:下拉的所有数据
        // 设置为false 禁用渲染器
        render: false,
        // 是否在数据项比设定的 visible 多时使用异步渲染(true),
        // 在数据较多时建议设置为true,以避免大量的dom操作阻塞页面执行
        async: TRUE,
        // 附加的样式类名称
        css: NULL,
        // 每一个下拉项的样式
        style: {}
    },
    // 下拉底部DOM
    footer: {
        // 底部渲染器,其this上下文就是其DOM对象,
        // 直接操作这个对象来改变底部
        // 需要注意的是,底部分了“左”、“右”两个区域,以放置不同的东西
        // 这个是在执行完其初始化,添加到容器前调用的
        render: false,
        /**
         * 下拉项数量
         */
        totalTpl: '' + str_placeholder + '',
        /**
         * 选中的下拉项数据
         */
        selectedTpl: '选中' + str_placeholder + '项/',
        // 附加的样式类名称
        css: NULL,
        // 底部的样式
        style: {}
    },
    result: {
        // 是否启用多选模式
        multi: false,
        // 是否显示下拉指示器
        // false    始终不显示
        // true     始终显示
        // null     单选时显示  多选时不显示
        arrow: null, 
        // 当从select创建实例时,是否需要将TinySelect的选中值同步到select上,默认为 true
        sync: true,
        // 渲染选中结果的渲染器,可以通过这个来改变选中结果的渲染
        render: false,
        // 多选结果展示方式,可以设置为 0(显示选中的数量,默认值) 或者 1(显示 选中的项列表)
        // 这是一个预留配置项
        type: 0,
        // 附加的样式类名称
        css: NULL,
        // 多选结果的样式
        style: {}
    }
}

注:

  • 以上选项中所有的style项可以使用所有的css样式,名称中有连字符的时候可以写成font-size或者fontSize
  • 多选的结果框始终不会显示下拉指示器

键盘支持

通过选项option.keyboard 设置是否支持键盘操作,默认为true 当为true时,可以通过以下键操作组件:

  • 上方向键,项向上移动一位
  • 下方向键,项向下移动一位
  • Space 空格键,选中/取消选中当前项
  • Esc Esc键,关闭组件

显示模式选项

目前组件提供了三种显示模式:

  • dropdown 下拉模式(默认) 示例
  • list 列表模式,此模式没有选择结果框 示例
  • popup 弹出模式,这项会弹出框的方式显示数据项,在弹出框后面,有一个mask层 示例

数据项布局选项

布局是指数据项的排列方式,通过参数option.box.layout来设置,可以设置为

布局gridtable不同之处在于:

  • grid是所有项以网格方式显示,每一行显示的项的数量与每项占用的宽度相关,如果要控制每一行显示项的数量,那么请设置项的宽度和下拉框的宽度
  • table的一行显示的是一项数据的多个字段

不同的布局基本上都是通过不同的样式来实现的。

接口

TinySelect 提供了一组易用的操作接口。这些接口除了取值类的,其它都返回了下拉组件的实例,也就是说非取值类的接口可以进行链式调用。

show(callback: Function) : TinySelect

显示下拉组件。

callback 下拉组件显示后的回调函数。这个回调函数没有参数,其上下文this对象指向下拉组件的弹出框DOM对象。

hide(callback: Function) : TinySelect

隐藏下拉组件。

callback 下拉组件隐藏后的回调函数。这个回调函数没有参数,其上下文this对象指向下拉组件的弹出框DOM对象。

value(value: Any, trigger: Boolean) : TinySelect|Any

设置/获取下拉组件的选中值。当传了参数时是设置值;不传参数时,是获取值,此时若是单选则返回选中的值,多选则返回选中的值的数组。

value 第一个参数是要设置的值,单选时传入单个值,多选时传入值数组。

trigger 是否触发事件。true触发,false不触发。在设置值时,如果希望结果框中显示设置的值,这个参数需要传入true。默认为false

在初始化下拉组件后立即调用 .value() 设置值的时候,需要确保渲染已经完成,即事件ready已经被触发。

filter(keyOrFn: String|Function, toggle: Boolean) : Array

根据关键字或函数过滤数据项。返回所有命中项的数据组成的数组。

keyOrFn 关键字或过滤器函数。当传入字符串的时候,会在下拉项中查找匹配的文本,若有匹配则返回这项的数据;传入函数时,通过函数的返回值决定是否命中(返回true表示命中),这个函数的上下文this对象是某一个下拉项的DOM对象,并且有一个参数datadata是这个数据项的数据。

toggle 是否切换显示状态,即隐藏未命中项,显示命中项。默认为false

clear() : TinySelect

清除下拉组件的选中项。

load(data: Array) : TinySelect

加载数据,重新渲染下拉项,调用这个函数前的所有数据项都会在重新渲染前被清空。

data 组件会根据这个数据重新渲染所有的下拉项。

readonly(readonly: Boolean) : Boolean|TinySelect

设置/获取下拉组件的只读模式。当传了参数时是设置模式,不传参数时为获取模式。

readonlytrue时设置下拉组件只读,为false取消下拉组件的只读模式;不传时为获取当前是否是只读模式。

on(eventType: String, handler: Function) : TinySelect

绑定事件到下拉组件上。

eventType 事件类型名。,目前支持select,unselect,ready,传入其它值无效。

handler 事件的处理函数。详见下方 [事件][0] 部分

off(eventType: String, handler: Function) : TinySelect

从下拉组件上取消事件的绑定。参数同上面的on函数。需要注意的是,在调用off的时候,handler需要是函数引用,这个函数引用应该与调用on的时候是同一个引用,所以,调用on时使用了匿名函数,那么在这里无法解除绑定。

事件

TinySelect 目前提供了三个事件:select, unselect, ready

select: Function

下拉项被选中时触发的事件。上下文this指向下拉组件,处理函数有一个参数e,其结构如下:

{
    data: Object,
    index: Number,
    target: HtmlElement,
    type: String
}

,其中,data是下拉项的数据,index是下拉项的索引,target是下拉项的DOM元素,type是事件类型。

select: Function

下拉项被取消选中时触发的事件。参数与用法与select事件相同。

ready: Function

下拉组件的所有下拉项渲染完成后触发的事件,这个事件触发后表示下拉组件初始化已经完成,可以正常使用了。

在初始化下拉组件后立即调用 .value() 设置值的时候,需要确保渲染已经完成。

自定义样式

可以通过重写这些样式来实现不同的效果。 如果仅仅想要重设配色,那么可以直接通过修改src/colors.less文件,然后重新编译。这个文件里面提供了目前组件中的大部分颜色变量。

上下文元素

  • tinyselect-context 用来创建下拉组件的元素
  • tinyselect-context-result 存放选中结果的容器
  • tinyselect-result-item 选中结果项
  • tinyselect-result-item-text 选中结果项的文本
  • tinyselect-result-item-link 选中结果项的移除按钮
  • tinyselect-context-with-arrow 带有下拉指示器时候的样式
  • tinyselect-context-arrow 下拉指示器
  • tinyselect-readonly 下拉框处于只读模式的样式

弹出框mask层

仅在popup模式时存在

  • tinyselect-mask 弹出框的mask层,container的父级元素,默认以position: fixed撑满窗口

弹出框

  • tinyselect-container 下拉框最顶级容器
  • tinyselect-empty 没有数据项时顶级容器的样式
  • tinyselect-mode-dropdown 下拉组件作为下拉框显示时的样式(默认)
  • tinyselect-mode-list 下拉组件作为列表显示时的样式
  • tinyselect-mode-popup 下拉组件作为弹出框显示时的样式

头部

  • tinyselect-header 下拉框头部元素,过滤框就是放这里面的
  • tinyselect-filter 下拉框的过滤输入框

底部

  • tinyselect-footer 下拉框底部元素
  • tinyselect-footer-left 底部左侧容器
  • tinyselect-footer-right 底部右侧容器
  • tinyselect-count-total 底部右侧显示下拉项数量
  • tinyselect-count-selected 底部右侧显示下拉项选中的数量

下拉项

  • tinyselect-box 下拉项的容器
  • tinyselect-box-layout-list 下拉项列表布局
  • tinyselect-box-layout-grid 下拉项网格布局
  • tinyselect-box-layout-table 下拉项表格布局
  • tinyselect-scroll-proxy 列表项滚动的代理元素
  • tinyselect-item 下拉项
  • tinyselect-item-selected 下拉项选中状态
  • tinyselect-item-before 下拉项文字前的元素
  • tinyselect-item-text 下拉项文字元素
  • tinyselect-item-after 下拉项文字后的元素
  • tinyselect-group-content 分组项的容器,同一组的项会被放到一起
The MIT License (MIT) Copyright (c) 2017 hyjiacan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

简介

灵活的WEB下拉组件 展开 收起
JavaScript
MIT
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
JavaScript
1
https://gitee.com/touchx_admin/TinySelect.git
git@gitee.com:touchx_admin/TinySelect.git
touchx_admin
TinySelect
TinySelect
master

搜索帮助