English | 简体中文

Install

npm install react-tabllist --save

Usage

Use in browser

<script src="https://cdn.bootcss.com/react/16.8.6/umd/react.development.js"></script>
<script src="https://cdn.bootcss.com/react-dom/16.8.6/umd/react-dom.development.js"></script>
<script src="https://cdn.bootcss.com/babel-standalone/7.0.0-beta.3/babel.min.js"></script>
<script src='https://cdn.bootcss.com/lodash.js/4.17.11/lodash.core.js'></script>
<script src='./react-tabllist.min.js'></script>

<div id='example'></div>
<script type='text/javascript'>
  var option = {
    data: [],
    property: {}
  }

  ReactDOM.render(
    React.createElement(ReactTabllist, option),
    document.getElementById('example')
  )
</script>

Use in ES6 & jsx

import ReactTabllist from 'react-tabllist';

// Use default configuration
ReactDOM.render(<ReactTabllist />, mountNode);

// Custom data and configuration items
const props = {
    className: 'demo',
    property: {},
    data: [
       ['1st column', '2nd column', '3rd column'],
       ['1st cell', '2nd cell', '3rd cell']
    ]
}

ReactDOM.render(<ReactTabllist {...props} />, mountNode);

Development

If you want to join the development to improve this component, please fork and start with the following command:

$ git clone [email protected]:oceanxy/react-tabllist.git
$ cd react-tabllist
$ npm install
$ npm start

Open your browser and visit http://localhost:3001 , see more at Development.

Version Information

Change Log

Configuration

props

|props type |description |details | |------------------------------------------------|------------------------------------------------|----------------------------------| |data {[Array, Array, Array,...]} |Render table data |props.data | |className {string} |Table outermost container style sheet name |'' | |property {Object} |Wrapper table properties |props.property |

props.className

You can customize the style by setting the props.className property

props.data

Data Format

The data data format is very similar to a two-dimensional array。

• Each subarray in the array represents a row, and each element in the subarray represents a cell. The order in which cells are displayed is the order in which the arrays are indexed, so the order and display of each cell should be determined when reconstructing the data.

[
    [cell, cell, cell],   // row
    [
        cell, // cell
        cell,
        cell
    ],
    [cell, cell, cell],
    ...
]

• An object can also represent a row in a two-dimensional array. This object has two required attributes: type='row' and cells=[], which respectively identify the object as a row and the cells contained in the row:

[
    {  // The rows are displayed as objects, and the in-row cells are contained in the cells field as an array.
        type: 'row',
        cells: [cell, cell, cell],
        ...
    },
    [  // Display rows as an array, each element representing a cell
        {type: 'button', ...},   // Generate a button in the cell
        cell,  // cell
        cell
    ],
    [
        cell,
        cell,
        [
            {type: 'radio'}, {type: 'radio'}, ... // Generate two or more radios in the same cell
        ]
    ],
    ...
]

Object Unit

The data format that cells can parse is divided into the following four categories:

• String
• Array，These four data formats can be nested inside the array again.
• jsx,Such as: <button className='test-button' onclick='()=>{return null}'>click</button>
• Object（Object cell），Details are as follows：

|type | description | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| |row |Generate a unit row, unit row object can only be written in the body, invalid elsewhere | |img |Generate an img tag inside the cell | |button |Generate a button in the cell | |link |Generate a link in the cell (a tag) | |radio |Generate a radio in the cell | |checkbox |Generate a checkbox in the cell | |select ^1.4.1 |Generate a select in the cell | |text ^1.5.0 |Generate a plain text inside the cell. You can also replace the object unit with a string. If you don't plan to add events to this cell, you can do that. | |input ^1.6.0 |Generate a text box in a cell. |

Here are some examples：

// row
{
    type: 'row',
    cells: [cell, cell, cell],
    data: 'row.id',
    value: 'row.typeID',
    event: 'onClick',
    callback: (data, cellData, event) => {},
    className: ''，
    key: ''
}

// button
{
    type: 'button',
    value: 'click me',
    className: 'test-btn',
    data: '123',
    event: 'onClick',
    callback: data => alert('hello react-tabllist', data) // hello react-tabllist, 123,
    key: ''
}

// img
{
    type: 'img',
    src: 'http://www.xieyangogo.cn/pic.png',
    alt: '',
    text: 'IMG description',
    className: 'test-img',
    key: '',
    value:''
}

// link (Choose one of the two)
{
    type: 'link',
    text: 'I am a link, I use the href attribute',
    className: 'test-link',
    key: '',
    href: 'https://github.com/oceanxy/react-tabllist',
    value:''
}
{
    type: 'link',
    text: 'I am a link, I use event and callback to implement custom functions',
    className: 'test-link',
    key: ''，
    data:  {},
    event: 'onClick',
    callback: (data, cellData, event) => {},
    value:''
}

// radio
{
    type: 'radio',
    name: 'group2',
    text: 'radio group 2-1',
    className: 'test-radio',
    callback: (data, cellData, event) => {},
    key: '',
    value:''
}

// checkbox
{
    type: 'checkbox',
    name: 'checkbox1',
    text: 'checkbox',
    className: 'test-checkbox',
    callback: (data, cellData, event) => {},
    key: '',
    value:''
}

// select
{
    type: 'select',
    text: 'please choose：',
    value: '',
    data: '',
    className: '',
    callback: (data, cellData, event) => {},
    option: [
        {
            id: '1',
            label: 'item 1',
            value: 1
        }
    ]
}

// text
{
    type: 'text',
    text: 'I am a normal text',
    callback: (data, cellData, event) => {}
}

// input
{
    type: 'input',
    text: 'username:',
    placeholder: 'enter username',
    defaultValue: 'oceanxy' // This attribute is not a standard HTML tag attribute, but it is a property of the React element (the purpose is to set the default value of the text box). As you can see, `you can also use React's officially defined properties in object cells.`
}

Object Cell Attribute

|Attribute {type} |Description |row |button |link |img |radio |checkbox |input |select |text | |-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|--------|------|----------|----------|----------|---------|---------|----------| |~~uid~~ {string} Available before version 1.2.2 |Deprecated A unique identifier for a cell that can be used to save ids, and so on. This field function is similar to the key, and can also be replaced with a data field in conjunction with a callback function, so it is decided to discard this field in version 1.2.2. |❌ |✅ |✅ |✅ |✅ |✅ |❌ |❌ |❌ | |type {string} |The type of HTML tag to be generated in the cell |✅ |✅ |✅ |✅ |✅ |✅ |✅ |✅ |✅ | |text {string} |The text of the rendered HTML tag |❌ |❌ |✅ |✅ |✅ |✅ |✅ |✅ |✅ | |event {string} |The way to trigger an event needs to be used with callback |✅ |✅ |✅ |❌ |✅ |✅ |✅ |✅ |✅ | |callback {function} |The callback function after the trigger event, see the callback for details. |✅ |✅ |✅ |❌ |✅ |✅ |✅ |✅ |✅ | |cells {object[]} |Can only be used with the row type, see the data for details. |✅ |❌ |❌ |❌ |❌ |❌ |❌ |❌ |❌ | |data {*} |Custom attributes can theoretically pass any value. This value is not used inside the component, you can get this value in the first parameter of the callback |✅ |✅ |✅ |✅ |✅ |✅ |✅ |✅ |✅ | |option {object[]} |Can only be used with the select type, see the option for details. |❌ |❌ |❌ |❌ |❌ |❌ |❌ |✅ |❌ |

HTML Attribute (The usage of these attributes is the same as that of native HTML tags. They are listed to indicate the points to be aware of when using them.)

|Attribute {type} |Description | |-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |name {string} |The attributes that the radio and checkbox must set, the same as the name attribute of the HTML-like tag. | |value {number\|string} |The value attribute of the generated HTML tag, **All object cell can be used starting with version 1.4.1** | |src {string} |Image link, such as: 'http(s)://xxx' or 'data:image/xxx' | |alt {string} |The alt attribute of the image | |href {string} |The hyperlink type of the link type (the same as the href of the HTML a tag), or you can use this combination of event and callback to customize the event callback without passing this attribute. |

For more tag attributes please visit w3schools.

React's Element Attribute

|Attribute {type} |Description | |-----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |key {string} |Jsx loop or array need to use the key attribute, Please ensure the uniqueness of the key | |className {string} |Custom style sheet name | |defaultValue {string|number} |The default value of labels such as text boxes, different from value |

For more attributes, see the type definition file (d.ts) of the react library.

Callback

• v1.5.0 and earlier

|callback(data, objectUnit, event) |Custom event callback function, can be used with event. If the event is undefined, the default click event is triggered after the callback. | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| |data |Custom data attribute in Object Unit | |objectUnit |Object unit data in the cell | |event |Event Object |

• v1.5.1

|callback(instance, objectUnit, event) |Custom event callback function, can be used with event. If the event is undefined, the default click event is triggered after the callback. | |--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| |instance |Some properties and methods exposed by the component instance object | |objectUnit |Object unit data in the cell | |event |React SyntheticBaseEvent |

• instance

{
    scrollTo(rowIndex, targetScrollTop), // Scroll the component to the specified row. If row Index is false, use a value to represent the scroll distance (target Scroll Top)
    props,              // The properties passed to the component can be re-assigned to update the component
    readonlyState,      // Component status (read only)
    renderData          // Render component data
}

Option

{type='select'}Object unit unique attribute.

|key {type} |description | |-----------------------|---------------| |id |option id | |label |option text | |value |option value |

props.property

Property

|props.property {type} |default |description | |--------------------------------------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |border {cssProperties border} |{...} |The border configuration of the table, including the row and cell inside the component (if the row or cell does not have a border style, this global configuration is used by default) | |style {cssProperties} |{...} |The style of the outermost container of the component | |~~isScroll~~ {boolean} ⚠ |true |Whether to enable component scrolling (valid when the height of all rows exceeds the height of the component's viewable area) ⚠ This property is deprecated in version 1.4.0, please use scroll.enable instead | |~~speed~~ {number} ⚠ |50 |The scrolling speed of the component list when scrolling is enabled ⚠ This property is deprecated in version 1.4.0, please use scroll.speed instead | |scroll ^1.4.0 {object} |{...} |Component scrolling related settings. speed milliseconds scrolling distance distance. | |scroll.enable ^1.4.0 {boolean} |true |Whether to enable component scrolling (valid when the height of all rows exceeds the height of the component's viewable area) | |scroll.speed ^1.4.0 {number} |50 |The interval at which the component scrolls once, in milliseconds. Tip: Set a small time interval to achieve continuous scrolling animation.If combined with scroll.distance, you can achieve an interval scrolling effect, and you can scroll N rows at a time. | |scroll.distance ^1.4.0 {number} |1 |The distance at which the component scrolls each time. If the value is a positive integer, the unit is pixel; if 0, it means stop scrolling, the same as scroll.enable: false; if it is a negative integer, it scrolls in the unit of row, and the number of rows equals the absolute value of the value. If it is a non-numeric, take 0; if it is a positive decimal, take an integral upward. If it is a negative decimal, it is rounded down | |header {object} |{...} |Header related settings | |header.show {boolean} |true |Whether to display the header. When true, the first subarray of data is the header data | |header.style {cssProperties} |{...} |Header style | |header.cellStyle {cssProperties} |{...} |The style of the cell inside the header. Note: The width value in this style will be invalid, because the header cell width of this component is automatically adapted according to the cell width in the body | |body {object} |{...} |Body related configuration | |body.style 1.5.0 {cssProperties} |{...} |You can define partial styles for the body that usually do not affect the layout of the list. For example, you can use "backgroundColor", "backgroundImage" or "opacity", etc., but you can't use attributes such as "width", "height", "padding", and "margin" that change the size or position of the body | |body.row {object} |{...} |Row configuration in the body | |~~body.row.onClick~~ 1.2.0 ()=>{} ⚠ |null |Deprecated Row click event, ⚠ This property is only available in version 1.2.0 | |body.row.transition {boolean} |true |Whether to enable the loading animation of the row inside the body | |body.row.spacing {boolean} |0 |Row spacing | |~~body.row.rowCheckBox~~ {boolean} ⚠ |false |Deprecated Whether to enable row selection ⚠ This property is deprecated in version 1.2.2, please use body.row.rowCheckbox instead | |~~body.row.rowCheckbox~~^1.2.2 {boolean} ⚠ |false |Deprecated Whether to enable row selection ⚠ The value of this property was changed from Boolean to an object in version 1.5.0, as detailed in the next line | |body.row.rowCheckbox ^1.5.0 {object} |{...} |Body row selection function related settings | |body.row.rowCheckbox.show ^1.5.0 {boolean} |false |Whether to enable row selection | |body.row.rowCheckbox.column ^1.5.0 {number} |1 |Which column of the list (table) is inserted into the column. Note that this value has a priority less than row.serialNumber.column, ie if the two values are the same, then this column will be ranked later | |body.row.rowCheckbox.style ^1.5.0 {cssProperties} |{...} |The style of the label of the wrapped row selection box, not the style of the cell in which the row selection box is located | |body.row.rowCheckbox.specialStyle ^1.5.0 {cssProperties} |[] |According to the array index, set the style of the label of the parcel row selection box. If you want to skip an index, you can use a comma placeholder | |body.row.style {cssProperties} |{...} |The style of the row inside the body | |body.row.specialStyle {[cssProperties, cssProperties, ...]} |[] |Set the style of each row according to the array index. If you want to skip an index, you can use a comma placeholder | |body.row.visual {object} |{...} |Improve the visual of the line: set another line style every N lines | |body.row.visual.show {boolean} |true |Whether to turn on visual enhancement | |body.row.visual.interval {number} |1 |Alternate every N lines | |body.row.visual.style {cssProperties} |{...} |Alternate row style configuration | |body.row.silent {object} |{...} |Whether to respond to mouse interaction | |body.row.silent.show {boolean} |false |Whether row does not respond to mouse events, such as hover events. The default is false, that is, respond to mouse events | |body.row.silent.style {cssProperties} |{...} |Style when responding to mouse events | |body.row.serialNumber {object} |{...} |Line number related configuration | |body.row.serialNumber.show {boolean} |false |Whether to display the line number | |body.row.serialNumber.columnName ^1.5.0 {string} |'SN' |The column name of the column | |body.row.serialNumber.formatter {string} |'{index}.' |Line number formatting. {index} resolves to a number that increments from 0 | |body.row.serialNumber.column ^1.5.0 {number} |1 |Which column of the list (table) is inserted into the column. Note that this value has a priority greater than row.rowCheckbox.column, ie if the two values are the same, then this column will be in front | |body.row.serialNumber.style {cssProperties} |{...} |The style of the label that wraps the line number, not the style of the cell in which the line number is located | |**body.row.serialNumber.specialStyle** <br> {[cssProperties, ...]} |\[] |According to the array index, set the style of the label of the package line number. If you want to skip an index, you can use a comma placeholder | |**body.cellOfColumn** <br>{object} |{...} |Configure cell styles by column | |**body.cellOfColumn.style** <br>{[cssProperties, ...]} |\[] |According to the array index, set the style of all the cells in each column. If you want to skip an index, you can use a comma placeholder | |**body.cell** <br>{object} |{...} |Cell related configuration | |**body.cell.style** <br>{cssProperties} |{...} |Cell style | |**body.cell.style.width** <br>{string|Array|number} |'auto' |widthis one of the properties of style, here you need to pay special attention: its usage is different from the width of css, seecellWidth | |**~~body.cell.iconStyle~~** <br>{cssProperties} |{...} |Deprecated` The icon style inside the cell needs to match the img of the object cell. In fact, you only need to use className instead of it in the object cell. ⚠ it looks a lot more, so it will be completely removed in a later version |

cellWidth

Optional value for cellWidth：

• 'auto'：Automatically set the cell width based on the specific data in the cell.
• 'avg'：Each cell width approaches equal, but the width is appropriately adjusted based on the specific data in the cell.
• [10, 20, 10]：Each cell in the row takes the value of the array in turn. If the value of an array index is a placeholder (ie ","), the width of the cell will be set to "auto"; when the length of the array is less than the number of columns, the remaining columns are set to "auto" by default.
• '10,20,10'：Each column takes values in turn, based on comma-separated values. The detailed rules are the same as the array form.

Note:

1. Regardless of the method, if the final rendered cell width value is less than style.minWidth, the style.minWidth value is used.
2. The total width of the component cannot be less than the sum of the widths of each column, otherwise the columns that exceed the width portion will be hidden.
3. When customizing the width values of multiple columns, if each column defines a specific value, you should ensure that the sum of these values is equal to the width value of the component, otherwise the actual width of the column after rendering may not be the expected value. Under normal circumstances, we should ensure that the width of at least one column is automatically adapted, that is, no value is set or skipped with a comma.
4. The priority order of the cell styles.

Configuration Demonstration

The default value of the component is based on this configuration table.

{
  className: '',
  data: [
    ['1st column', '2nd column', '3rd column'],
    ['1st cell', '2nd cell', '3rd cell']
  ],
  property: {
    border: {
      borderWidth: 1,
      borderStyle: 'solid',
      borderColor: '#f4f4f4'
    },
    style: {
      width: '100%',
      margin: '0 auto',
      height: 300
    },
    scroll: {
      enable: true,
      speed: 50,
      distance: 1
    },
    header: {
      show: true,
      style: {
        height: 40
      },
      cellStyle: {
        color: '#000000',
        border: ''
      }
    },
    body: {
      style: {
        backgroundImage: '',
        backgroundColor: ''
      },
      row: {
        transition: true,
        spacing: 0,
        style: {
          height: 30
        },
        serialNumber: {
          show: false,
          columnName: 'SN',
          formatter: '{index}.',
          column: 1,
          style: {
            width: '100%',
            height: '100%',
            display: 'flex',
            justifyContent: 'center',
            alignItems: 'center',
            backgroundColor: '',
            backgroundImage: '',
            color: '#ffffff'
          },
          specialStyle: []
        },
        rowCheckbox: {
          show: false,
          column: 1,
          style: {},
          specialStyle: []
        },
        visual: {
          show: false,
          interval: 1,
          style: {
            backgroundColor: '#e8f4fc'
          }
        },
        specialStyle: [],
        silent: {
          show: false, // false代表开启
          style: {
              opacity: 0.8
          }
        }
      },
      cellOfColumn: {
        style: []
      },
      cell: {
        style: {
          fontSize: 16,
          minWidth: 50,
          color: '#000000',
          textAlign: 'center',
          border: '',
          width: 'auto'
        },
        iconStyle: {
          width: 24,
          height: 'auto'
        }
      }
    }
  }
}

Thanks

The react-tabllist project can continue to serve everyone free of charge. One of the reasons is the free development tools provided by jetbrains. Thank them here!

Q&A

Q: Thanks to AimLuo for the question: Is it better to write object units in data or JSX syntax?

A: answer