![NPM downloads](https://camo.githubusercontent.com/7be731911dbc0d9b7aabd633b63e751cba2ae77d96475e03a620b68c1d13842c/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f646d2f7578636f72652d7461626c652e737667)
![Sauce Test Status](https://camo.githubusercontent.com/d77504f027d634bd2ecf89f2ad17f96875335f56f74ec73347143ffacfaeb474/68747470733a2f2f73617563656c6162732e636f6d2f62726f777365722d6d61747269782f7578636f72652d7461626c652e737667)
Table UI Component based on React. working for many modes such as sub table, tree table and inline editing table.
$ git clone https://github.com/uxcore/uxcore-table
$ cd uxcore-table
$ npm install
$ npm start
- getData(): 返回表格的数据,并作校验。
- addEmptyRow(): 添加一个空的新行。
- addEmptyRowFromTop(): 从顶部添加一个空的新行。
- addRow(rowData): 以指定数据添加一个新行。
- addRowFromTop(rowData): 以指定数据从顶部添加一个新行。
- delRow(rowData): 删除一个新行。
- editRow(rowData): 使指定的行切换到编辑模式。
- editAllRow(): 使所有行切换到编辑模式。
- viewRow(rowData): 使指定的行切换到查看模式。
- viewAllRow(): 使所有行切换到查看模式。
- saveRow(rowData): 保存行的数据(同时切换至查看模式)。
- saveAllRow(): 保存所有行的数据(同时切换至查看模式)。
- resetRow(rowData): 重置行到数据(若保存过,则为保存过后的数据)。
- resetAllRow(): 重置所有行的数据(若保存过,则为保存过后的数据)。
- resetAndViewAllRow(): 重置所有行数据(若保存过,则为保存过后的数据)并切换至查看模式。
- fetchData(from): 使表格重新请求一次数据。
- @param from {string} {optional}: 这个参数会传入到 beforeFetch 的回调中。
Name |
Type |
Require |
Default |
Since Ver. |
Note |
options.component |
React Element |
yes |
input |
1.12.8 |
被包裹的组件,需要提供 value 和 onChange,或相同功能的 API |
options.valuePropName |
string |
No |
value |
1.12.8 |
与 value 对应的 prop 名字 |
options.changePropName |
string |
No |
onChange |
1.12.8 |
与 onChange 对应的 prop 名字 |
options.processValue |
func |
No |
- |
1.12.8 |
针对 value(editKey 对应字段)的处理函数 |
options.processText |
func |
No |
- |
1.12.8 |
针对 text (dataKey 对应字段) 的处理函数 |
- toggleSubComp(rowData): 使指定的行显示或隐藏二级组件(subComp)。
- moveRowUp(rowData): 使指定的行向上移动一行
- moveRowDown(rowData): 使指定的行向下移动一行
Name |
Type |
Require |
Default |
Since Ver. |
Note |
jsxcolumns |
array |
required |
null |
- |
表格列配置项,具体见这里 |
width |
number |
optional |
1000 |
- |
表格的宽度 |
height |
number |
optional |
100% |
- |
表格的高度 |
showColumnPicker |
boolean |
optional |
true |
- |
是否显示列筛选按钮 |
showPager |
boolean |
optional |
true |
- |
是否显示分页 |
showPagerTotal |
boolean |
optional |
false |
1.3.17 |
是否显示分页的总数部分 |
showPagerSizeChanger |
boolean |
optional |
true |
1.6.9 |
是否可以改变分页的pageSize |
isMiniPager |
boolean |
optional |
false |
1.6.9 |
分页是否是mini的 |
showHeader |
boolean |
optional |
true |
- |
是否显示表格头部 |
showHeaderBorder |
boolean |
optional |
false |
1.3.6 |
是否显示头部列之间的分割线 |
showMask |
boolean |
optional |
true |
- |
是否在 loading 的时候显示蒙层 |
showSearch |
boolean |
optional |
false |
- |
是否显示内置的搜索栏 |
doubleClickToEdit |
boolean |
optional |
true |
- |
是否开启双击编辑 |
fetchDataOnMount |
boolean |
optional |
true |
1.3.18 |
是否在组件 Mount 时立刻获取一次数据 |
rowSelector |
string |
optional |
复选 |
1.3.20 |
行选择是复选还是单选,支持 checkboxSelector 和 radioSelector |
locale |
string |
optional |
zh-cn |
1.3.17 |
国家化,目前支持 zh-cn/en-us |
emptyText |
string or element |
optional |
"暂无数据" |
- |
当没有数据时 Table 展示的文案 |
searchBarPlaceholder |
string |
optional |
"搜索表格内容" |
1.3.0 |
searchBar 的占位符 |
loadingText |
string |
optional |
"loading" |
1.4.4 |
加载数据时的文案 |
headerHeight |
number |
optional |
40 |
- |
表格头部的高度 |
pageSize |
number |
optional |
10 |
- |
每页显示多少条数据 |
pagerSizeOptions |
array |
optional |
[10,20,30,40] |
- |
显示的可选 pageSize |
queryKeys |
array |
optional |
[] |
- |
有哪些数据会传递给 subComp |
jsxdata |
object |
optional |
- |
- |
在远端数据还没有返回时用作默认数据 |
fetchUrl |
string |
optional |
"" |
- |
表格的数据源 |
fetchParams |
object |
optional |
- |
- |
表格在请求数据时,会额外附带的参数,具有最高的优先级 |
fetchWithCredentials |
bool |
optional |
- |
7.8.0 |
同 NattyFetch 配置 |
actionBar |
object/array |
optional |
null |
- |
表格内置的操作条配置,详细见此 |
beforeFetch |
function(data, from) |
optional |
noop |
- |
两个参数,data 表示表格请求数据时即将发送的参数,from 表示这次请求数据的行为从哪里产生,内置的有 search (搜索栏),order (排序) & pagination (分页),该函数需要返回值,返回值为真正请求所携带的参数。 |
processData |
function(data) |
optional |
noop |
- |
有时源返回的数据格式,并不符合 Table 的要求,可以通过此函数进行调整,参数 data 是返回数据中 content 字段的 value,该函数需要返回值,返回值为符合 content 字段 value 的数据结构。 |
onFetchError |
function(result) |
optional |
noop |
1.3.7 |
在返回数据中 success 不是 true 的情况下触发,返回所有请求得到的数据 |
onSearch |
function(searchTxt) |
optional |
noop |
1.6.1 |
未配置 fetchUrl 的情况下触发,传回搜索的关键词 |
onOrder |
function(column, orderType) |
optional |
noop |
1.6.1 |
未配置 fetchUrl 的情况下触发,传回排序的列和排序方式 |
onPagerChange |
function(current, pageSize) |
optional |
noop |
1.6.1 |
未配置 fetchUrl 的情况下触发,传回要到达的分页和每页条数 |
onColumnPick |
function(columns) |
optional |
noop |
7.6.0 |
勾选自定义列时触发,参数为勾选后的 columns |
addRowClassName |
function(rowData) |
optional |
noop |
- |
用于为特定的某几行添加特殊的 class,用于样式定制 |
rowSelection |
object |
optional |
noop |
- |
选中复选框时触发的回调,rowSelection 是由回调函数组成的对象,包括 onSelect 和 onSelectAll,例子见此 |
rowGroupKey |
string |
optional |
|
8.2.0 |
用于行分组,可选值为 columns 设置中 dataKey,使用对应的列内容做行分组 |
Name |
Type |
Require |
Since Ver. |
Default |
Note |
SubComp |
React Element |
optional |
- |
- |
传入二级组件,已废弃,请使用 renderSubComp, 自 1.7.0 版本后不再保证此部分功能的完整性。 |
renderSubComp |
function(rowData) |
optional |
1.3.15 |
- |
传入二级组件,该函数需要返回值,返回 false,表示不渲染二级,返回 jsx,则渲染该 jsx |
toggleSubCompOnRowClick |
boolean |
optional |
8.5.0 |
false |
在点击行的时候,展开和收起折叠面板,操作列不受影响。其他区域如果不想触发需要自行 stopPropagation |
Name |
Type |
Require |
Since Ver. |
Default |
Note |
renderModel |
string |
optional |
- |
'' |
使用 tree 模式时,此项为 'tree' |
levels |
number |
optional |
- |
0 |
tree 模式默认展开的级数 |
Name |
Type |
Require |
Since Ver. |
Default |
Note |
onChange |
function(data) |
optional |
- |
noop |
有表格编辑行为触发,参数的数据格式为 {data: 表格的所有数据, changedData: 变动行的数据, dataKey: xxx, editKey: xxx, pass: 正在编辑的域是否通过校验} |
getSavedData |
boolean |
optional |
- |
true |
onChange 中的数据是否是保存之后的数据(通过了 saveRow() 的数据) |
页底(Footer)
页底是固定在表格底部的一个特殊行,可用于统计合计等场景。
Name |
Type |
Require |
Since Ver. |
Default |
Note |
showFooter |
boolean |
optional |
8.4.0 |
true |
在配置了 footer 参数后,是否显示页底 |
showRowGroupFooter |
boolean |
optional |
8.4.0 |
false |
是否显示行分组中的 footer |
footer |
function({data, column, rowGroupData, from}) |
optional |
8.4.0 |
- |
页底渲染函数,data 为表格数据(一个数组),column 为当前列配置,rowGroupData 和 from 在 showRowGroupFooter 为 true 时生效,分别返回当前行分组的所有数据,和一个标志位 'rowGroup' |
Key Name |
Type |
Since Ver. |
Require |
Note |
dataKey |
string |
- |
required |
表格的数据中用于查看模式展示的字段 |
editKey |
string |
- |
optional |
表格的数据中用于编辑模式的字段,如对于 select 来说,此项应为选项里的 key |
align |
string |
- |
optional |
文字居中方式,默认 'left' |
title |
string/func |
- |
required |
列头标题,可以是个函数,根据返回值进行渲染 |
width |
number |
- |
required |
列宽,支持 100px, 100, '30%'(7.7.0 之后支持) |
hidden |
boolean |
- |
optional |
是否隐藏,默认为 false |
ordered |
boolean |
- |
optional |
是否显示内置的排序,默认为 false |
type |
string |
- |
optional |
包含 'money', 'card', 'cnmobile', 'checkboxSelector', 'action', 'radio', 'text', 'select' 和 'custom' |
actions |
array |
- |
optional |
当 type 是 action 的时候会用到,用于定义具体有哪些操作,格式见下方说明 |
collapseNum |
number |
1.9.4 |
optional |
当 type 是 action 的时候会用到,默认 3,指定超过多少个 action 时折叠 |
actionType |
string |
1.9.4 |
optional |
当 type 是 action 的时候会用到,默认 link,枚举值:link/button |
customField |
React Element |
- |
optional |
当 type 是 custom 的时候会用到,用于传入自定义的 Field,用于行内编辑 |
render |
function |
- |
optional |
在查看模式下,用户定制渲染的方式,返回一个 jsx 格式 |
fixed |
boolean |
- |
optional |
是否固定在左侧,固定列不可以和折叠展开面板混合使用 |
rightFixed |
boolean |
1.14.0 |
optional |
是否固定在右侧,固定列不可以和折叠展开面板混合使用 |
delimiter |
string |
- |
optional |
在 type 是 'money', 'card', 'cnmobile' 的时候会用到,用于传入格式化的分隔符 |
disable |
boolean |
- |
optional |
在 type 为 checkboxSelector 时使用,是否禁用 checkbox,优先级高于 isDisable |
isDisable |
function(rowData) |
1.3.1 |
optional |
在 tpye 为 checkboxSelector 时使用,为一个回调函数,用于根据 rowData 去判断是否禁用该行的 checkbox |
canEdit |
function(rowData) |
1.3.3 |
optional |
在 type 为可编辑表格的类别时使用,为一个回调函数,用于根据 rowData 去判断该行该列是否可以编辑 |
config |
object |
1.5.0 |
optional |
在 type 为 text/select/radio 时使用,传入对应的配置项,配置项与对应的组件(uxcore-selelct2)相同 |
renderChildren |
function |
1.5.0 |
- |
在 type 为 select/radio 时使用,通过返回 jsx 传入选项。 |
let columns = [
{ dataKey: 'check', type: 'checkbox', isDisable: function(rowData) {return /city/.test(rowData.city)}}, // 定制 checkbox 列,dataKey 对应的应是一个 bool 值,表明是否被选中。
{ dataKey: 'country', title:'国家', width: 200,ordered:true},
{ dataKey: 'action1', title:'操作1', width:100, type:"action",actions: [
{
title: '编辑',
callback: (rowData) => {
me.refs.grid.editRow(rowData);
},
mode: Constants.MODE.VIEW
},
{
title: '保存',
callback: (rowData) => {
me.refs.grid.saveRow(rowData);
},
mode: Constants.MODE.EDIT
}
]},
{ dataKey: 'action', title:'链接', width:100, render: function(cellData,rowData) {
return <div><a href="#">{rowData.email}</a></div>
}}
]
列配置项的例子2(带列群组, since ver. 1.3.0)
let columns = [
{ dataKey: 'check', type: 'checkbox', disable: false}, // custom checkbox column, dataKey can be anyone, true means checked.
{
group: "国家",
columns: [
{ dataKey: 'country', title:'国家', width: 200,ordered:true},
{ dataKey: 'country2', title:'国家2', width: 200,ordered:true},
]
}
]
let rowSelection = {
onSelect: function(record, selected, selectedRows) {
console.log(record, selected, selectedRows);
},
onSelectAll: function(record, data) {
console.log(record, data);
},
isDisabled: function(rowData) {
return false;
}
};
{
"content":{
"data":[
{
"id":'1'
"grade":"grade1",
"email":"email1",
"firstName":"firstName1",
"lastName":"lastName1",
"birthDate":"birthDate1",
"country":"country1",
"city":"city1"
}
...
],
"currentPage":1,
"totalCount":30
},
"success": true,
"errorCode": "",
"errorMsg": ""
}
上面的数据格式是 ajax 返回的数据格式要求,如果你通过 jsxdata 传值,只需要 content 里面的内容。
{
"data":[
{
"id":'1'
"grade":"grade1",
"email":"email1",
"firstName":"firstName1",
"lastName":"lastName1",
"birthDate":"birthDate1",
"country":"country1",
"city":"city1"
}
...
],
"currentPage":1,
"totalCount":30
}
// actionBar 支持传入一个对象
actionBar: {
"新增行": () => { // 点击回调
me.refs.grid.addEmptyRow();
},
"编辑所有行": () => {
me.refs.grid.editAllRow();
}
}
// 或者定制能力更加强大的数组
actionBar: [
{
title: '新增行', // 显示名称
callback: () => { // 点击回调
me.refs.grid.addEmptyRow();
},
render: (title) => { // 定制渲染
return <Button>{title}</Button>
}
},
{
title: "编辑所有行",
callback: () => {
me.refs.grid.editAllRow();
}
},
{
title: "保存所有行",
callback: () => {
me.refs.grid.saveAllRow();
}
}
]
actions: [
{
title: '编辑', // 操作名称
callback: (rowData) => { // 操作回调
me.refs.grid.editRow(rowData);
},
mode: Constants.MODE.VIEW // 非必要参数,只在何种模式下显示
},
{
title: '保存',
callback: (rowData) => {
me.refs.grid.saveRow(rowData);
},
mode: Constants.MODE.EDIT,
render: (title, rowData) => { // 定制渲染
return title + '1'
}
}
]
正常情况下,Table 中每个单元格按照一行缩略的方式展示,根据业务需要,有时可能需要展示多行,对此,Table 通过 prop addRowClassName
配合专属类名 multiline
来实现。示例如下:
addRowClassName: function(rowData) {
return 'multiline';
}
需要注意:当配置为 multiline 时,用户需自己处理上下间距的问题,处理的方式应为在 multiline 或其他专属类名作用域下进行设置,避免影响其他非 multiline 设置的行。当 多行 和 固定列 同时开启 时,表格需要经过比较大量的计算去调整固定列中行的高度,对 性能 产生一定的影响。