Bootstrap Table API 中文版(翻译文档)
看网上有中文版的,但有些就是字面直接译过来了,而且有的就没有翻译,那就打算自己再翻译一遍,每一条会尽最大可能结合尽可能多资料翻译,如果发现译的内容比英文多,是添加了更详细的说明,表的名称,属性,类型,默认值不翻译,例如:"class"、"id"等不翻译。有错请提出,会及时改正,谢谢。
推荐教程:bootstrap教程
1、“名称”可以写在$('#table').bootstrapTable({});的大括号中,可以定义一些想要的值,如:
$("#realTime_Table").bootstrapTable({ search: true, pagination: false, pageSize: 15, pageList: [5, 10, 15, 20], showColumns: true, showRefresh: false, showToggle: true, locale: "zh-CN", striped: true });
2、“属性”放在声明表内,如:
<!--例子应该很好看懂Table options和Column options 所放的位置不同,随便写的,主要为了懂得如何用--!> <table id="realTime_Table" data-click-to-select="true" class="table table-bordered" data-page-size="20"> <thead> <tr > <th data-sortable="true" data-field="realTimeDate">日期</th> <th data-sortable="true" data-field="newPlayerNum">新增用户</th> <th data-sortable="true" data-field="activePlayerNum">活跃用户</th> </tr> </thead> <tbody> </tbody> </table>
3、如果名称和属性功能类似,则任意一个地方就够了,不用重复定义,有的属性写在js里比名称写在声明表中更为简单,or vice verse(有的属性必须要写,对应的名称只是表示是否启用那个属性)
表的各项(Table options )
定义在 jQuery.fn.bootstrapTable.defaults 文件内
名称 | 属性 | 类型 | 默认值 | 作用描述 |
---|---|---|---|---|
- | data-toggle | String | table | 只要引入 jquery、bootstrap 、bootstrap-table的包,不用在js里面定义就可以使用 默认有写data-toggle="table",data-toggle应该知道吧,常用的有"tooltip、popover等等",这边就不说了 |
classes | data-classes | String | table table-hover | 表的class属性,如果没有自己定义,则默认有边框,并且当鼠标悬浮在那一行,背景会变为浅灰色. |
sortClass | data-sort-class | String | undefined | 声明表格td的class名,代表此列元素的class名将被排序 |
height | data-height | Number | undefined | 表格的高度 |
undefinedText | data-undefined-text | String | - | 当不写任何内容默认显示'-' |
striped | data-striped | Boolean | false | 默认false,当设为true,则每行表格的背景会显示灰白相间 |
sortName | data-sort-name | String | undefined | 定义哪一列的值会被排序,写data-field的自定义名,没定义默认都不排列,同下面的sortOrder结合使用,没写的话列默认递增(asc) |
sortOrder | data-sort-order | String | asc | 同上面的结合使用,默认递增(asc),也可设为递减(desc) |
sortStable | data-sort-stable | Boolean | false | (别看错了,是sortStable,sortable在下面)默认false,设为true,则和sort部分一样,区别是:在排序过程中,如果存在相等的元素,则原来的顺序不会改变。原文还有一句:(如果你把此属性设为了true)我们将为此行添加'_position'属性 |
iconsPrefix | data-icons-prefix | String | glyphicon | 定义字体库 ('Glyphicon' or 'fa' for FontAwesome),使用"fa"时需引用 FontAwesome,并且配合 icons 属性实现效果 Glyphicon 集成于Bootstrap可免费使用 |
iconSize | data-icon-size | String | undefined | 定义的图标大小: - undefined =>默认表示默认的按钮尺寸(btn) - xs =>超小按钮的尺寸(btn-xs) - sm =>小按钮的尺寸(btn-sm) - lg =>大按钮的尺寸(btn-lg) |
buttonsClass | data-buttons-class | String | default | 按钮的类,默认为default。 - 可选的有:primary、danger、warning等等 - 写了之后会自动转换为btn-primary(蓝色)、btn-danger(红色)、btn-warning(黄色)等格式,所以前面不要再加"btn-",默认为btn-default(白色) - 参考菜鸟教程:Bootstrap 按钮 |
icons | data-icons | Object | {
paginationSwitchDown: 'glyphicon-collapse-down icon-chevron-down', paginationSwitchUp: 'glyphicon-collapse-up icon-chevron-up', refresh: 'glyphicon-refresh icon-refresh', toggle: 'glyphicon-list-alt icon-list-alt', columns: 'glyphicon-th icon-th', detailOpen: 'glyphicon-plus icon-plus', detailClose: 'glyphicon-minus icon-minus' } | 定义在工具栏、分页、详细视图中使用的图标 - 没办法解释,请参考菜鸟教程的图标:Bootstrap 字体图标 |
columns | - | Array | [] | 默认空数组,在JS里面定义,field即data-field,title就是每列表头名等等。 - 请参考:查Bootstrap-table的Usage |
data | - | Array | [] | 被加载的数据。 - 也就是从服务器获取的数据,通过"."运算符获取,例如"data.date/data.anything",后面是服务器发来的字段名 |
dataField | data-data-field | String | rows | - 名称写自己定义的每列的字段名,也就是key,通过key才能给某行的某列赋value。 - 原文:获取每行数据json内的key - 例如:{"name":"zz","age":20},name和age就是key,如果这是从服务端请求的json,那可能和每列定义的字段不同,但都是唯一的 |
ajax | data-ajax | Function | undefined | - ajax方法,和jQuery的ajax方法类似 |
method | data-method | String | get | 向服务器请求远程数据的方式,默认为'get',可选'post' |
url | data-url | String | undefined | 向服务器请求的url。 - 例如:server + "get_app_player"和server + 'get_channel_list',两者都是向server(server是自己定义的,例如"http://kanshakan.nichousha.com/")请求数据,只是接口不同,一个是请求该游戏玩家信息,一个是请求渠道信息 下面看看原文: - 向远程站点请求数据的URL - 请记住,如果服务端分页选项使用了自定义的,那么请求的服务器响应格式是不同的,参考下面两个数据格式: Without server-side pagination(没有启用服务端分页 - data1.json) With server-side pagination(启用服务端分页 - data2.json) |
cache | data-cache | Boolean | true | 默认缓存ajax请求,设为false则禁用缓存 |
contentType | data-content-type | String | application/json | 请求数据的contentType(内容类型),用于定义文件的类型,决定接收方以什么形式读取这个文件。 - 默认application/json,用来告诉接收端从服务器发来的消息是序列化后的json字符串 |
dataType | data-data-type | String | json | 期望从服务器获取的数据的类型,默认为json格式字符串 |
ajaxOptions | data-ajax-options | Object | {} | 向服务器请求ajax时的附加项,默认无附加 - 参考 jQuery.ajax() |
queryParams | data-query-params | Function | function(params){ return params;} | 当请求数据时,你可以通过修改queryParams向服务器发送其余的参数。 - queryParamsType="limit",它的参数包括:limit,offset,search,sort,order Else - params包括:pageSize,pageNumber,searchText,sortName,sortOrder - 当return false,请求则终止 |
queryParamsType | data-query-params-type | String | limit | 默认"limit",设置该属性用来发送符合RESTful格式的参数 |
responseHandler | data-response-handler | Function | function(res){ return res;} | 在加载服务器发送来的数据之前,处理数据的格式,参数res表示the response data(获取的数据) |
pagination | data-pagination | Boolean | false | 默认为false,表格的底部工具栏不会显示分页条(pagination toolbar),可以设为true来显示 |
paginationLoop | data-pagination-loop | Boolean | true | 默认true,分页条无限循环 |
onlyInfoPagination | data-only-info-pagination | Boolean | false | 前提:pagination设为true,启用了分页功能。 - 默认false,设为true显示总记录数 |
sidePagination | data-side-pagination | String | client | 设置在哪进行分页,默认"client",可选"server",如果设置 "server",则必须设置url或者重写ajax方法 - 请记住,如果服务端分页选项使用了自定义的,那么请求的服务器响应格式是不同的,参考下面两个数据格式: Without server-side pagination(没有启用服务端分页) With server-side pagination(启用服务端分页) |
pageNumber | data-page-number | Number | 1 | 前提:pagination设为true,启用了分页功能。 - 默认第1页,用于设置初始的页数 |
pageSize | data-page-size | Number | 10 | 前提:pagination设为true,启用了分页功能。 - 默认每页显示10条记录,用于设置每页初始显示的条数 |
pageList | data-page-list | Array | [10, 25, 50, 100] | 前提:pagination设为true,启用了分页功能。 - 默认为[10, 25, 50, 100],即可以选择"每页显示10/25/50/100条记录",用于设置选择每页显示的条数 |
selectItemName | data-select-item-name | String | btSelectItem | radio(单选按钮)或checkbox(复选框)的字段名 |
smartDisplay | data-smart-display | Boolean | true | 默认为true,会机智地(<_<)根据情况显示分页(pagination)或卡片视图(card view) |
escape | data-escape | Boolean | false | 跳过插入HTML中的字符串,替换掉特殊字符(后面符号没有逗号):&,<,>,",`,' |
search | data-search | Boolean | false | 默认false不显示表格右上方搜索框 ,可设为true,在搜索框内只要输入内容即开始搜索 |
searchOnEnterKey | data-search-on-enter-key | Boolean | false | 默认false不启用,设为true启用,比功能是与上面相比,在搜索框内输入内容并且按下回车键才开始搜索 |
strictSearch | data-strict-search | Boolean | false | 设为true,开启精确搜索 |
searchText | data-search-text | String | "" | 前提:search设为true,启用了搜索功能。 - 搜索框初始显示的内容,默认空字符串 |
searchTimeOut | data-search-time-out | Number | 500 | 前提:search设为true,启用了搜索功能。 - 设置搜索文件的超时时间(原文:Set timeout for search fire,不知道是写错了还是我知识面太窄,"search fire"是什么意思,官方API错了?给我整蒙逼了) |
trimOnSearch | data-trim-on-search | Boolean | true | 默认true,自动忽略空格 |
showHeader | data-show-header | Boolean | true | 默认为true显示表头,设为false隐藏 |
showFooter | data-show-footer | Boolean | false | 默认为false隐藏表尾,设为true显示 |
showColumns | data-show-columns | Boolean | false | 默认为false隐藏某列下拉菜单,设为true显示 |
showRefresh | data-show-refresh | Boolean | false | 默认为false隐藏刷新按钮,设为true显示 |
showToggle | data-show-toggle | Boolean | false | 默认为false隐藏视图切换按钮,设为true显示 |
showPaginationSwitch | data-show-pagination-switch | Boolean | false | 默认为false隐藏每页数据条数选择,设为true显示 |
minimumCountColumns | data-minimum-count-columns | Number | 1 | 每列的下拉菜单最小数 |
idField | data-id-field | String | undefined | 表明哪个是字段是标识字段 |
uniqueId | data-unique-id | String | undefined | 表明每行唯 一的标识符 |
cardView | data-card-view | Boolean | false | 默认false,设为true显示card view(卡片视图) |
detailView | data-card-view | Boolean | false | 默认false,设为true显示detail view(细节视图) |
detailFormatter | data-detail-formatter | Function | function(index, row, element){ return '';} | 前提:detailView设为true,启用了显示detail view。 - 用于格式化细节视图 - 返回一个字符串,通过第三个参数element直接添加到细节视图的cell(某一格)中,其中,element为目标cell的jQuery element |
searchAlign | data-search-align | String | right | 搜索框的位置,默认right(最右),可选left |
buttonsAlign | data-buttons-align | String | right | 工具栏按钮的位置,默认right(最右),可选left |
toolbarAlign | data-toolbar-align | String | left | 自定义工具栏的位置,默认right(最右),可选left |
paginationVAlign | data-pagination-v-align | String | bottom | 分页条垂直方向的位置,默认bottom(底部),可选top、both(顶部和底部均有分页条) |
paginationHAlign | data-pagination-h-align | String | right | 分页条水平方向的位置,默认right(最右),可选left |
paginationDetailHAlign | data-pagination-detail-h-align | String | left | 如果解译的话太长,举个例子,paginationDetail就是“显示第 1 到第 8 条记录,总共 15 条记录 每页显示 8 条记录”,默认left(最左),可选right |
paginationPreText | data-pagination-pre-text | String | ‹ | 还是举例子,如果你内容太多,底部最右边会显示:"‹ 1 2 3 4 5 ›"来选择页数,默认就是最左边那个符号,下同 |
paginationNextText | data-pagination-next-text | String | › | 参考上面一条 |
clickToSelect | data-click-to-select | Boolean | false | 默认false不响应,设为true则当点击此行的某处时,会自动选中此行的checkbox(复选框)或radiobox(单选按钮) |
singleSelect | data-single-select | Boolean | false | 默认false,设为true则允许复选框仅选择一行 |
toolbar | data-toolbar | String | Node | undefined | jQuery的选择器,例如:#toolbar,.toolbar,或者是DOM 结点 |
checkboxHeader | data-checkbox-header | Boolean | true | 如果你有声明复选框,默认显示表头行的全选复选框,设为false隐藏(就是表格第一行的不显示,从第二行往后都显示) |
maintainSelected | data-maintain-selected | Boolean | false | 设为true则保持被选的那一行的状态 |
sortable | data-sortable | Boolean | true | 默认true,设为false禁用所有的行排列(也就是每列表头不会显示排序的按钮,这个需要在th声明data-sortable="true",写在js中只是启不启用) |
slientSort | data-silent-sort | Boolean | true | 前提:sidePagination设为server(服务端) - 默认true,设为false则静默排序数据 |
rowStyle | data-row-style | Function | {} | 改变某行的格式,需要两个参数:
- row:此行的数据 - index:此行的索引 支持classes和css,用法如下: function rowStyle(row, index){ return { classes: 'text-nowrap another-class', css: {"color": "blue", "font-size": "50px"} }; } |
rowAttributes | data-row-attributes | Function | {} | 改变某行的属性,需要两个参数: - row:此行的数据 - index:此行的索引 支持所有自定义的属性。 |
customSearch | data-custom-search | Function | $.noop | 自定义搜索功能(用来代替自带的搜索功能),需要一个参数: - text:想要搜索的内容 用法如下: function customSearch(text){ //必须使用'this.data'对数据进行过滤(filter the data,感觉这个词也不用译),不要使用'this.options.data' } |
customSort | data-custom-sort | Function | $.noop | 自定义排序功能(用来代替自带的排序功能),需要两个参数(可以参考前面): - sortName:需要排序的那列 - sortOrder:排序方式 用法:和上面一样,不用担心,注释也一模一样 |
locale | data-locale | String | undefined | 本地化(动词)。 本地化的文件必须被预加载,允许fallback(简单来说就是如果要使用的文件不可用,就可以用别的替代它,例如球场替补,没替补,如果有人受伤了,比赛不就废了),如果加载,将按如下顺序: - 首先尝试加载的是指定的"本地化"文件 - 然后是'_'(下划线)写成'-'(破折号),并且区域代码被大写的 - 然后是短区域代码(例如:用'fr'代替'fr-CA') - 最后使用的是剩下的本地化文件(当没有文件可加载则使用默认的) 如果剩余的undefined,或者是空字符,则使用最后一次使用的那个文件(当没有本地化文件可被加载,则使用自带的'en_US') |
footerStyle | data-footer-style | Function | {} | 改变footer格式,需要两个参数:
- row:此行的数据 - index:此行的索引 支持classes和css,用法如下: function rowStyle(value,row, index){ return { css: { "font-weight": "bold" } }; } |
列的各项(Column options )
定义在 jQuery.fn.bootstrapTable.columnDefaults 文件内
名称 | 属性 | 类型 | 默认值 | 作用描述 | |
---|---|---|---|---|---|
radio | data-radio | Boolean | false | 默认false不显示radio(单选按钮),设为true则显示,radio宽度是固定的 | |
checkbox | data-checkbox | Boolean | false | 默认false不显示checkbox(复选框),设为true则显示,checkbox的每列宽度已固定 | |
field | data-field | String | undefined | 是每列的字段名,不是表头所显示的名字,通过这个字段名可以给其赋值,相当于key,表内唯一 | |
title | data-title | String | undefined | 这个是表头所显示的名字,不唯一,如果你喜欢,可以把所有表头都设为相同的名字 | |
titleTooltip | data-title-tooltip | String | undefined | 当悬浮在某控件上,出现提示 - 参考 Bootstrap 提示工具(Tooltip)插件 | |
class | class/data-class | String | undefined | 没什么好说的,就是class | |
rowspan | rowspan/data-rowspan | Number | undefined | 每格所占的行数 | |
colspan | colspan/data-colspan | Number | undefined | 每格所占的列数 | |
align | data-align | String | undefined | 每格内数据的对齐方式,有:left(靠左)、right(靠右)、center(居中) | |
halign | data-halign | String | undefined | table header(表头)的对齐方式,有:left(靠左)、right(靠右)、center(居中) | |
falign | data-falign | String | undefined | table footer(表脚,就这样译,任性,其实随便译啦,知道就好)的对齐方式,有:left(靠左)、right(靠右)、center(居中) | |
valign | data-valign | String | undefined | 每格数据的对齐方式,有:top(靠上)、middle(居中)、bottom(靠下) | |
width | data-width | Number(单位:px或%) | undefined | 每列的宽度。 - 如果没有自定义宽度,那么宽度会根据内容的宽度自适应。 - 如果表是左适应(left responsive)或者设置的宽度小于内容的宽度,那么,宽度还是会自适应(可以在class或其他的属性中使用 min-width 或 max-width)。 - 你也可以使用"%"作为单位,这样的话,bootstapTable将按百分比划分,如果你想使用"pixels(像素值)",你可以只写数字(只要不加"%",单位默认"px",不嫌麻烦,或者想更清晰,你也可以加上"px") | |
sortable | data-sortable | Boolean | false | 默认false就默认显示,设为true则会被排序 | |
order | data-order | String | asc | 默认的排序方式为"asc(升序)",也可以设为"desc(降序)"。 - 与上面的结合使用,不然都不让排序了,你还考虑什么升降。 | |
visible | data-visible | Boolean | true | 默认为true显示该列,设为false则隐藏该列。 - 还是很有用的,例如隐藏自定义index列,按某属性排序后会变乱,你可以读取某行的index来进行赋值 | |
cardVisible | data-card-visible | Boolean | true | 默认为true显示该列,设为false则隐藏。 | |
switchable | data-switchable | Boolean | true | 默认为true显示该列,设为false则禁用列项目的选项卡。 | |
clickToSelect | data-click-to-select | Boolean | true | 默认true不响应,设为false则当点击此行的某处时,不会自动选中此行的checkbox(复选框)或radiobox(单选按钮) | |
formatter | data-formatter | Function | undefined | 需要此列的对象。 某格的数据转换函数,需要三个参数: -value: field(字段名) -row:行的数据 -index:行的(索引)index | |
footerFormatter | data-footer-formatter | Function | undefined | 需要此列的对象。 某格的数据转换函数,需要一个参数: -data: 所有行数据的数组 函数需要返回(return)footer某格内所要显示的字符串的格式,还要包括内容 | |
events | data-events | Object | undefined | 当某格使用formatter函数时,事件监听会响应,需要四个参数: -event:jQuery事件(参考Events)。 - value:字段名 - row:行数据 - index:此行的index 举个例子: | var operateEvents = {'click .like': function (e, value, row, index) {}}; |
sorter | data-sorter | Function | undefined | 自定义的排序函数,实现本地排序,需要两个参数: - a:第一个字段名 - b:第二个字段名 | |
sortName | data-sort-name | String | undefined | 除了表头默认的sort-name或列的字段名,还可以使用自定义的sort-name 对特殊情况说明: - 一个列显示的内容或许是"html"代码,如:abc,但是被排列的是html代码中的内容(content):abc | |
cellStyle | data-cell-style | Function | undefined | 对某格中显示样式(style)进行改变,需要三个函数: - value:字段名 - row:行数据 - index:此行的index - field:行的字段名 支持classes和css,用法如下: function cellStyle(value, row, index, field) { return { classes: 'text-nowrap another-class', css: {"color": "blue", "font-size": "50px"} }; } | |
searchable | data-searchable | Boolean | true | 默认true,表示此列数据可被查询 | |
searchFormatter | data-search-formatter | Boolean | true | 默认true,可使用格式化的数据查询 | |
escape | data-escape | Boolean | false | 跳过插入HTML中的字符串,替换掉特殊字符(后面符号没有逗号):&,<,>,",`,' |
事件(Events)
定义事件的格式: $(’#table’).bootstrapTable({ onEventName: function (arg1, arg2, …) { // … } }); $(’#table’).on(‘event-name.bs.table’, function (e, arg1, arg2, …) { // … });
事件名 | 定义在jQuery中的事件名 | 参数 | 作用描述 |
---|---|---|---|
onAll | all.bs.table | name, args | 当所有触发器被触发时都执行此函数,就是所有的事件都会触发该事件,参数包括: - name:事件名 - args:事件的数据 |
onClickRow | click-row.bs.table | row, $element, field | 当单击此行的任意一处,就会触发该事件,所需参数如下(只是按原文译过来的,在bootstraptable的js中不需要这些参数,因为单击该行就会获得一个row,row中包括此行所有数据,只要通过此行某列的字段名即可取出): - row:哪一行(从0开始) - $element:该行(tr) - field:当点击该行,你想获取此行哪一格的数据,field就是此列字段名 |
onDblClickRow | dbl-click-row.bs.table | row, $element, field | 和上面差不多,当双击(666)此行的任意一处,就会触发该事件,所需参数如下(只是按原文译过来的,在bootstraptable的js中不需要这些参数,因为双击该行就会获得一个row,row中包括此行所有数据,只要通过此行某列的字段名即可取出): - row:哪一行(从0开始) - $element:该行(tr) - field:当点击该行,你想获取此行哪一格的数据,field就是此列字段名 |
onClickCell | click-cell.bs.table | field, value, row, $element | 当单击某一格,就会触发该事件,所需参数如下: - field:此格所在列的字段名 - value:此格的数据 - $element:此行的此列,就是此格(td) |
onDblClickCell | dbl-click-cell.bs.table | field, value, row, $element | 当双击某一格,就会触发该事件,所需参数如下: - field:此格所在列的字段名 - value:此格的数据 - $element:此行的此列,就是此格(td) |
onSort | sort.bs.table | name, order | 当对某列进行排序时触发该事件,所需参数如下: - name:所排序的列的字段名 - order:所排的顺序 |
onCheck | check.bs.table | row, $element | 当选择(check)此行时触发,所需的参数如下: - row:所选择的行的字段名 - $element:此行的DOM元素 |
onUncheck | uncheck.bs.table | row, $element | 当取消选择(uncheck)此行时触发,所需的参数如下: - row:所取消选择的行的字段名 - $element:此行的DOM元素 |
onCheckAll | check-all.bs.table | rows | 当全选行时触发,所需的参数如下: - rows:最近(newly)所选择的行的字段名的数组 |
onUncheckAll | uncheck-all.bs.table | rows | 当取消全选行时触发,所需的参数如下: - rows:之前或上次(previously)所选择的行的字段名的数组 |
onCheckSome | check-some.bs.table | rows | 当选择(check)某些行(多行,rows)时触发,所需的参数如下: - rows:之前或上次(previously)所选择的行的字段名的数组 |
onUncheckSome | uncheck-some.bs.table | rows | 当取消选择(uncheck)某些行(多行,rows)时触发,所需的参数如下: - rows:之前或上次(previously)所选择的行的字段名的数组 |
onLoadSuccess | load-success.bs.table | data | 当所有数据被加载时触发 |
onLoadError | load-error.bs.table | status, res | 当加载某些数据出现错误时触发 |
onColumnSwitch | column-switch.bs.table | field, checked | 当某列改变是否可见的状态时触发 |
onColumnSearch | column-search.bs.table | field, text | 当某列被查询时触发 |
onPageChange | page-change.bs.table | number, size | 当改变此页所显示的数据条数或改变页码时触发 |
onSearch |