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

  /**
   * Event callback function
   * @param {SyntheticEvent} event
   * @param {Exposes} exposes An object containing exposed properties and methods
   */
  function handleScroll(event, exposes) {
    // some code
  }

  // Use React native events
  ReactDOM.render(<ReactTabllist {...props} onScroll={handleScroll} />, mountNode);

  // Use custom events built into components
  ReactDOM.render(<ReactTabllist {...props} custom_onScrollToEnd={handleScroll} />, 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.

📝 Version Information

Change Log

🧰 Configuration

props.className

You can customize the style through the props.classname attribute.

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：

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 Unit Attribute

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.

For more tag attributes please visit w3schools.

React Element Attribute

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

Callback

• v1.5.0 and earlier

  callback(data:Array[], objectUnit:object, event:SyntheticEvent)

  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: React SyntheticBaseEvent

• v1.5.1 - v1.6.1

  callback(instance:object, objectUnit:object, event:SyntheticEvent)

  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
  }
  

• v1.7.0 and later

  callback(exposes:object, objectUnit:object, event:SyntheticEvent)

  Custom event callback function, can be used with event. If the event is undefined, the default click event is triggered after the callback.

  • exposes: Some properties and methods exposed
  • objectUnit: Object unit data in the cell
  • event: React SyntheticBaseEvent

  exposes

  Method	Parameter	Description
  scrollTo(rowIndex: number)	rowIndex{number}:row index	scrolls the list to the specified row
  pause(isPause?: boolean)	isPause{boolean}:Is the list paused. By default, you can pause scrolling or start scrolling according to the paused attribute inside the component.	Pause or start the scrolling of the list

  Attribute	Type	description
  paused	{boolean}	The scrolling status of the current component (effective when the component turns on the scrolling function). True means suspended; False means scrolling
  props	{object}	The props of the component can be re assigned to update the component
  indeterminate	{boolean}	The indeterminate status of the row selection box in the header
  selected	{object}	It includes row selection boxes, custom check boxes, and check status sets of custom radio buttons
  rowsHeight	{number}	Total height of all rows
  scrollFrequency	{number}	Number of turns from component loading to current scrolling
  renderData	{Array[]}	Final used for rendering list after processing data
  header	{JSX.Element}	Header container element
  body	{JSX.Element}	Body container element
  container	{JSX.Element}	Component outermost container element
  firstRowIndexInViewableArea	{number}	The index of the first row in the current viewing area (the current version is only available when scroll.distance < 0)

Option

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

props.property

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.

Event

• v1.7.0 and later versions support React native events, and remove the event binding written inside the code in the previous version.

• Added 3 custom scroll events：

  • custom_onScrollTo：Triggered after the end of discontinuous scrolling (when scroll.distance < 0) or after calling the public scroll to function.
  • custom_onScrollToEnd：Scroll to the end of the component to trigger. Triggered when the last line completely appears in the visible area of the component.
  • custom_onScrollFullCircle：Triggered after a complete roll.

• For all events, including react native events and custom scroll events, there are two callback parameters:

  • event {SyntheticEvent}: Event callback parameter of event handle.
  • exposes {object}: An object that contains exposed properties and methods.

⛱️ 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