uxcore-table

---

Table UI Component based on React. working for many modes such as sub table, tree table and inline editing table.

How to run

$ git clone https://github.com/uxcore/uxcore-table
$ cd uxcore-table
$ npm install
$ npm start

API

行内编辑用

• 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 的回调中。

创建一个 CellField

• createCellField(options)

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 对应字段) 的处理函数

树形表格用

• addSubRow(subRowData, rowData, cb): 树形表格模式下从底部插入一个子树节点行
• addSubRowFromTop(subRowData, rowData, cb): 树形表格模式下从顶部插入一个子树节点行
• updateRow(rowData, cb): 树形表格模式下更新当前行

其他

• toggleSubComp(rowData): 使指定的行显示或隐藏二级组件(subComp)。
• moveRowUp(rowData): 使指定的行向上移动一行
• moveRowDown(rowData): 使指定的行向下移动一行

Props

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	""	-	表格的数据源
fetchMethod	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
onFilter	function(filters)	optional	noop	9.0.0	未配置 fetchUrl 的情况下触发，传回需要进行过滤的参数
addRowClassName	function(rowData)	optional	noop	-	用于为特定的某几行添加特殊的 class，用于样式定制
rowSelection	object	optional	noop	-	选中复选框时触发的回调，rowSelection 是由回调函数组成的对象，包括 onSelect 和 onSelectAll，例子见此
rowGroupKey	string	optional		8.2.0	用于行分组，可选值为 columns 设置中 dataKey，使用对应的列内容做行分组
defaultEditable	boolean	optional	false	10.4.16	默认开启行编辑模式
useListActionBar	boolean	optional	false	10.5.0	新版listActionBar开关，actionBar配置，详细见此
getTooltipContainer	function()	optional	null	10.5.2	单元格编辑状态下，tooltip位置可控
columnResizeable	boolean	optional	false	10.5.9	表格列可拖拽
defaultRowGroupActiveKeys	number/array	optional	undefined	11.1.0	行分组默认展开设置，可设置指定分组展开或者设置总展开分组数
onRowGroupOpenChange	function(activeKeys, key)	optional	undefined	11.1.0	行分组展开状态变更回调
needCheckRightFixed	boolean	optional	false	11.1.0	是否开启右固定列检查，用于解决可能产生两个右固定列的场景
fixHeaderToTop	boolean	optional	false	11.2.0	是否显示一个固定顶部的header，用于滚动等状态下的标题贴顶功能
fixHeaderOffset	number	optional	0	11.2.1	fixed 状态下的header距离顶部的偏移量
fixActionBarToTop	boolean	optional	false	11.4.0	是否显示一个固定顶部的actionBar，用于滚动等状态下的操作栏贴顶功能
fixActionBarOffset	number	optional	0	11.4.0	fixed 状态下的actionBar距离顶部的偏移量
expandIconType	string	optional	undefined	11.3.0	树形和子表格模式下的展开按钮增加加减号样式 'adderSubtractor'

折叠展开专用

Name	Type	Require	Since Ver.	Default	Note
renderSubComp	function(rowData)	optional	1.3.15	-	传入二级组件，该函数需要返回值，返回 false，表示不渲染二级，返回 jsx，则渲染该 jsx
toggleSubCompOnRowClick	boolean	optional	8.5.0	false	在点击行的时候，展开和收起折叠面板，操作列不受影响。其他区域如果不想触发需要自行 stopPropagation
onToggleSubComp	function(isOpen, rowData, table)	optional	noop	11.8.0	折叠面板状态变更时触发

Tree 模式专用

Name	Type	Require	Since Ver.	Default	Note
renderModel	string	optional	-	''	使用 tree 模式时，此项为 'tree'
levels	number	optional	-	0	tree 模式默认展开的级数
toggleTreeExpandOnRowClick	boolean	optional	9.1.0	false	在点击行的时候，展开和收起对应的树节点，操作列不受影响。
loadTreeData	function	optional	9.1.1	---	异步加载子数据，返回值可以是一个promise对象(格式:{data: [...]},也可以是一个对象(格式: {data: [...]})}

行内编辑表格专用

Name	Type	Require	Since Ver.	Default	Note
onChange	function(data)	optional	-	noop	有表格编辑行为触发，参数的数据格式为 {data: 表格的所有数据, changedData: 变动行的数据, dataKey: xxx, editKey: xxx, pass: 正在编辑的域是否通过校验}
getSavedData	boolean	optional	-	true	getValues() 和 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'

列配置项(jsxcolumns)

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 传入选项。
filters	array	9.0.0	optional	表头的筛选菜单项。具体格式见下方

列配置项的例子

let columns = [
    // 定制 checkbox 列，dataKey 对应的应是一个 bool 值，表明是否被选中，可以用于控制行选中。
    { dataKey: 'check', type: 'checkbox' },
    // 定制渲染的例子
    { dataKey: 'name', render: (cellData) => (<a>{cellData}</a>) },
    // filters 配置的例子
    {
        dataKey: 'firstName',
        title: 'FristName',
        width: '15%',
        filters: [{
          text: 'Joe',
          value: 'Joe',
        }, {
          text: 'Jim',
          value: 'Jim',
        }, {
          text: 'Submenu',
          value: 'Submenu',
          children: [{
            text: 'Green',
            value: 'Green',
          }, {
            text: 'Black',
            value: 'Black',
          }],
        }],
        message: '这是一个提示',
        ordered: true,
      },
    }
 ]

列配置项的例子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},
            ]
        }
 ]

rowSelection 的例子

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;
      }
};

通过rowSelection以及processData两个回调的配合，即可实现业务上可能会碰到的跨页行选择等功能。

基本思路是：

1、设置一个记录当前选中行的数据结构，如allSelectedRows；

2、在processData中过滤出所有该数据结构中包含的行数据，并将jsxchecked属性设置为true；

3、在rowSelection.onSelect中判断当前选中项的状态，并修改allSelectedRows中的数据即可

返回的数据格式

• 数据格式的约定见此

   {
	"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 支持传入一个对象
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();
        }
    }

]

// 当启用useListActionBar时，actionBar上的所有功能将在`actionBar`内完成
actionBar: {
    className: 'my-list-action-bar',
    // 是否显示全选
    showSelectAll: true,
    // 按钮配置
    buttons: [
      {
        title: 'Action Button',
        render() {
          return (
            <Button type={'primary'}>切换子表格状态</Button>
          )
        },
        keepActiveInCustomView: false,
        callback: () => {
          this.forceUpdate();
          console.log(me.table.getData());
          me.table.toggleSubComp(me.table.getData().data.datas);
        },
      },
      {
        title: '按钮',
        keepActiveInCustomView: false,
        // size: 'large',
        type: 'primary',
        // className: 'xxxxx',
        callback: () => {
          me.table.selectAll(true);
        }
      }
    ],
    // 文案提示
    actionBarTip: '已经为您找到记录123条',
    // 自定义内容
    customBarItem: {
      render() {
        return (
          <p style={{color: 'red'}} onClick={(e) => {console.log(e)}}>自定义内容</p>
        )
      }
    },
    // 行排序
    rowOrder: {
      iconName: 'paixu-jiangxu',
      // keepActiveInCustomView: true,
      defaultValue: {
        text: '排序方式一',
        value: '123'
      },
      items: [
        {
          text: '排序方式一',
          value: '123'
        },
        {
          text: '排序方式二',
          value: '456'
        }
      ],
      onChange(data) {
        console.log(data)
      }
    },
    // 列排序
    columnsOrder: {
      iconName: 'huxiangguanzhu',
      // keepActiveInCustomView: true,
      title: '列排序',
      includeActionColumn: false,  // 优先级低于fixed和rightFixed
      onChange(dragInfo, data) {
        console.log(data)
      }
    },
    // 列选择
    columnsPicker: {
      iconName: 'zidingyilie',
      title: '自定义列',
      keepActiveInCustomView: true,
      onChange(data) {
        console.log(data)
      }
    },
    // 自定义视图，支持返回promise和component
    customView: {
      render(data, currentPage) {
        console.log(data, currentPage);
        // return (
        //   <Test name={'自定义的View'}/>
        // )
        return new Promise(function(resolve) {
          setTimeout(() => {
            resolve(<Test name={'自定义的View'}/>)
          })
        })
      }
    },
    // 是否显示翻页器
    showMiniPager: true,
    search: {
      // placeholder: '请输入搜索关键字',
      onSearch() {
        console.log(234234)
      }
    },
    // 在自定义视图下移出翻页器
    removePagerInCustomView: true,
    linkBar: [
      {
        title: '修改columns',
        callback: () => {
          this.setState({
            columns: this.state.columns.filter(item => {
              return item.title === 'LastName'
                || item.title === 'Email'
                || item.title === '操作1'
            })
          })
        },
      },
      {
        title: '操作外链二',
        callback: () => {
          alert(2);
        },
      },
    ],
}

actions 配置的例子

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 设置的行。当 多行 和 固定列 同时开启 时，表格需要经过比较大量的计算去调整固定列中行的高度，对 性能 产生一定的影响。