Need Package Maintenance

    datagrid
    TypeScript icon, indicating that this package has built-in type declarations

    0.6.2 • Public • Published

    DataGrid NPM Version

    插件式表格组件。查看在线示例

    安装

    使用 NPM 安装:

    npm install datagrid
    

    然后在项目中导入:

    // ES6 模块语法
    import DataGrid, {
      BaseGrid,
      fixedHeader,
      fixedTable,
      sort,
      selection
    } from 'datagrid'
     
    // CommonJS 模块语法
    const {
      default: DataGrid,
      BaseGrid,
      fixedHeader,
      fixedTable,
      sort,
      selection 
    = require('datagrid')

    也可以直接下载 datagrid.js 并在 HTML 文件中导入:

    <script src="path/to/datagrid.js"></script>
    <script>
    const {
      default: DataGrid,
      BaseGrid,
      fixedHeader,
      fixedTable,
      sort,
      selection 
    = datagrid
    </script> 

    选择插件

    默认导出的 DataGrid 应用了全部内置插件,但你也可以选择用的到的插件自行构造:

    import {
      BaseGrid, // 最基础的表格,没有使用任何插件
      fixedHeader, // 固定表头
      fixedTable, // 生成固定在两侧的表格,不随左右滚动而移动
      sort, // 点击表头排序
      selection // 选择表格中的行
    } from 'datagrid'
     
    // 生成一个包含固定表头和排序的表格构造函数,插件的顺序没有要求
    const MyGrid = sort(fixedHeader(BaseGrid))

    默认导出的 DataGrid 等同于 selection(sort(fixedHeader(fixedTable(BaseGrid))))

    样式主题

    DataGrid 和它的插件将必要的样式使用 <style> 元素插入到了 DOM 中,所以使用 DataGrid 时无需引入额外的样式文件,你可以自定义表格的样式。

    同时,DataGrid 内置了一个样式主题,你可以下载 theme.css 到你的项目中使用。如果你使用了模块打包工具,则可以直接在项目中引用:

    import 'datagrid/theme.css'

    API

    BaseGrid

    BaseGrid 是最基础的表格,可以这样使用:

    import { BaseGrid } from 'datagrid'
     
    const grid = new BaseGrid(options)

    其中 options 及它的所有设置项都是可选的,它接收如下两个设置:

    • th:表格中的 <th> 元素的渲染函数。第一个参数是一个 Column 对象(详细介绍见下文),第二个参数是这个 Column 对象的索引号。可以返回一段 HTML 字符串,或者一个 Node,也可以返回一个包含多个元素的 DocumentFragment。第三个参数是当前渲染的 <th> 元素,方便直接操作此元素的 title 等属性,当然你也可以通过这个元素直接设置内容。默认返回 Column 对象中的 key 属性的值。
    • td:表格中的 <td>元素的渲染函数。第一个参数是一个 Column 对象(详细介绍见下文),第二个参数是一个 Row 对象,第三个参数是当前渲染的 <td> 元素,方便直接操作此元素的 title 等属性,当然你也可以通过这个元素直接设置内容。第四个是 Column 对象的索引号,第五个是 Row 对象的索引号。可以返回一段 HTML 字符串,或者一个 Node,也可以返回一个包含多个元素的 DocumentFragment。默认返回 Row 对象中对应 Column.key 的值。

    内置插件可能会添加其他一些设置项,后面介绍内置插件时会详细说明。

    BaseGrid 有且仅有一个公开属性:el,一个 div 元素,表示表格的根元素。

    BaseGrid 有这些方法:

    setData({ columns: string[] | Column[], rows: Row[] })

    使用数据渲染表格。参数是可选的,如果不传任何参数,则表格会显示“暂无数据”的提示。

    Column 目前只有一个属性:name,它是表头的内容,同时也是 Row 中用于读取对应数据的字段名。如果传入的是字符串,则会在内部被转换为一个 name 属性为字符串值的对象。

    示例:

    grid.setData({
      // 也可以写成 columns: ['年龄']
      columns: [
        {
          name: '年龄'
        }
      ],
      rows: [
        {
          年龄: 24
        }
      ]
    })

    showModal(msg: string = '暂无数据')

    显示一段消息,默认会显示“暂无数据”,消息中可以包含 HTML 标签。

    hideModal()

    隐藏消息。

    destroy(remove: Boolean)

    销毁实例。如果传入 true 作为参数,还会从 DOM 中删除表格元素。

    fixedTable 插件

    fixedTable 插件提供了在主表格左右两侧生成固定表格的功能,这些表格不会随着主表格左右滚动,但会随着表格上下滚动。

    fixedTable 没有给 BaseGrid 添加任何设置和属性。

    fixedTable 给 BaseGrid 添加了两个方法:

    setFixed(count: number, place = 'left')

    第一个参数表示要从表格中同步多少列数据。第二个参数指定固定表格的位置,默认为左侧,也可以传 right 在右侧生成。

    syncFixedWidth(place: 'left' | 'right')

    同步左侧或右侧表格的数据、宽度等。调用 setFixed 方法时会自动运行这个方法,但如果你在其他情况下改变了主表格的宽度、高度等状态,可以手动调用此方法重新定位固定表格。

    fixedHeader 插件

    fixedHeader 插件将表格的表头固定在了最顶部,不随着表格上下滚动而隐藏。

    fixedHeader 没有给 BaseGrid 添加任何设置和属性。

    fixedHeader 给 BaseGrid 添加了一个方法:

    syncFixedHeader()

    从主表格同步表头的宽度、高度等状态。调用 setData 方法后会自动运行这个方法,但如果在其他情况下修改了主表格的状态,可以手动调用此方法同步到固定表头。

    selection 插件

    让表格行可以被单选。

    selection 插件没有给 BaseGrid 添加任何设置、属性。

    selection 插件给 BaseGrid 添加了一个方法:

    setSelected(row?: object)

    将指定行设为选中状态,如果要取消选中状态则不要传参数。注意:调用这一方法不会触发下面的 select 事件。

    当用户选中了一行数据时,会触发 BaseGrid 的 select 事件,参数是选中行的 Row 对象。

    示例:

    import { BaseGrid, selection } from 'datagrid'
     
    const MyGrid = selection(BaseGrid)
    const grid = new MyGrid()
    grid.on('select', row => {
      console.log(`用户选中了这个对象:`, row)
    })

    sort 插件

    sort 插件会在用户点击表头时触发事件,并在表头右侧显示正确方向的箭头。

    sort 插件给 BaseGrid 添加了一个可选的设置:sortBlock,可以使用这个属性替代默认的上下箭头。这个属性可以设置成一段 HTML 字符串,或者是返回 NodeDocumentFragment函数。在用户点击表头后,sort 插件会触发事件。

    完整示例:

    import { BaseGrid, sort } from 'datagrid'
     
    const MyGrid = sort(BaseGrid)
    const grid = new MyGrid({
      // 使用 asc 或者 desc 标注排序时要显示的元素
      sortBlock: '<span class="asc">上</span><span class="desc">下</span>'
    })
    const orderMap = {
      0: '无方向',
      1: '朝上',
      2: '朝下'
    }
    grid.on('sort', (column, order) => {
      console.log('用户点击了这个列', column)
      console.log('当前排序方向:', orderMap[order])
    })

    sort 插件给 BaseGrid 添加了一个方法:

    setSort([column: Column, order: number])

    设置当前表格的选中状态指示标志。如果要清空指示标志不需要传入任何参数。

    关于 sort 插件的一点说明

    sort 插件在内部保存了当前正处于排序状态的 Column 对象本身,所以即使你改变了 columns 的顺序,箭头仍然会跟随那个 Column 对象显示,举例来说:

    import DataGrid from 'datagrid'
    let columns = [{ name: '你好' }, { name: '世界' }]
    const rows = [{ 你好: '测试', 世界: '一下' }]
    const grid = new DataGrid()
    grid.setData({ columns, rows })
    // 使用「你好」这一列排序
    grid.setSort(columns[0], 1)
    // 将「你好」与「世界」这两列的位置调换
    columns = [columns[1], columns[0]]
    // 重新设置数据
    grid.setData({ columns, rows })

    现在你会发现指示的箭头仍然是显示在「你好」这一列(此时它是表格中的第二列)。

    这样当然很好,但是当你使用字符串形式的 columns 时,DataGrid 在内部给你转换成了一个对象,而对象之间并不相等,所以上面的代码如果将 columns 写成字符串形式就不起作用了:

    grid.setData({
      columns: ['你好', '世界']
    })
    grid.setData({
      columns: ['世界', '你好']
    })
    // 现在排序箭头并没有显示在「你好」这一列上,这是因为前后两次调用 setData 方法时内部生成的 Column 对象并不相等

    同样的情况也会出现在你使用新的对象调用 setData 时:

    grid.setData({
      columns: [{ name: '你好' }, { name: '世界' }]
    })
    grid.setData({
      columns: [{ name: '世界' }, { name: '你好' }]
    })

    你可能会希望排序箭头能跟随「你好」这一列,但是前后两次调用 setData 方法时,columns 中的对象并不相等,所以导致第二次生成的表格中没有排序箭头显示。

    许可

    MIT

    Keywords

    none

    Install

    npm i datagrid

    DownloadsWeekly Downloads

    103

    Version

    0.6.2

    License

    MIT

    Unpacked Size

    144 kB

    Total Files

    19

    Last publish

    Collaborators

    • milklee