Shiny06---DT：一个Java包DataTables的R接口

R包DT提供一个Java包DataTables的R接口。R的数据对象，如矩阵、数据框能够以网页中表格的形式展现。并且提供筛选、排序、页码等功能。
可以从CRAN上安装稳定版，或者用​​​devtools::install_github('rstudio/DT')​​ 安装开发版本。

# if (!require("DT")) install.packages('DT')
devtools::session_info('DT')

1、用法

DT包中最主要的函数是​​datatable()​​ . 这个函数创建了一个网页部件用以展示R数据对象。

datatable(data, options = list(), class = "display", callback = JS("return table;"), 
    rownames, colnames, container, caption = NULL, filter = c("none", "bottom","top"), escape = TRUE, style = "default", width = NULL, height = NULL, 
    elementId = NULL, fillContainer = getOption("DT.fillContainer", NULL), autoHideNavigation = getOption("DT.autoHideNavigation", 
        NULL), selection = c("multiple", "single", "none"), extensions = list(),plugins = NULL)

下面是一个使用默认参数设置的例子：

library(DT)
datatable(iris)

2、参数

如果你已经十分熟悉DataTables，可以使用​​options​​​参数定制表格。具体细节见此处​。这里我们解释函数​​datatable()​​ 其余的参数设置。

2.1 CSS属性

属性参数特指表格的CSS属性。所以的参数值见此处​。 默认值​​display​​​ 有以下基础功能：行分段、添加行边界、鼠标选中时高亮等。也可以设置其他参数值：​​cell-border OR stripe​​。

2.2 式样

目前DT包只支持默认式样和Bootstrap式样。设置参数​​style='bootstrap'​​​ 获取Bootstrap式样，并且使用​​table-stripe OR table-hover​​​ 调整属性。实际DT将会自动调整类型名称即使你已经设置了DataTable的属性，如​​stripe OR hover​​ 。

DT:::DT2BSClass('display')
## [1] "table table-striped table-hover"
DT:::DT2BSClass(c('compact', 'cell-border'))
## [1] "table table-condensed table-bordered"

记住，同一个页面中只能设置一种式样。使用Bootstrap式样的案例见此处 。

2.3 展示行名

如果数据对象有列名，默认在表格的第一列展示行名，或者设置参数​​rownames=FALSE​​ 取消展示列名。也可以设置参数rownames等于一个向量，对行名重新命名。

DT::datatable(head(mtcars))

DT::datatable(head(mtcars), rownames = FALSE)  # no row names

DT::datatable(head(mtcars), rownames = head(LETTERS))  # new row names

2.4 自定义列名

​​datatable()​​ 函数默认展示数据的列名，有几种方法可以改变展示的列名。例如，可以用一个字符串向量替换已有的列名。

# colnames(iris) is a character vector of length 5, and we replace it
datatable(head(iris), colnames = c('Here', 'Are', 'Some', 'New', 'Names'))

如果只想替换其中一两个列名，而不是重命名全部列名，那么上述方法显得有些麻烦。针对这种情况，可以提供一个短的数值或者字符串向量，作为标识向量，替换需要修改的列名。例如：只需要把第二个列名修改为​​'A Nicer Name'​​​ ，可以用​​datatable(...,colnames=c('A Nicer Name' = 2))​​​ ;或者用​​'A Nicer Name'​​​ 替换​​'X5'​​​，可以用​​colnames=c('A Better Name' = 'X5')​​

DT::datatable(head(iris), colnames = c('A Better Name' = 'Sepal.Width'))
DT::datatable(head(iris), colnames = c('A Better Name' = 3))#行名占一列

当展示数据的行名时，行名这一列的列名默认为空。当然也可以为这一列设置列名。例如：

# change the first column name to 'ID'
DT::datatable(head(iris), colnames = c('ID' = 1))

2.5 自定义表容器

设置参数​​container​​ 可以提供不同的容器来存储表的表格单元。默认按照列名生成容器。下面是一个定制表格标题的案例：

# a custom table container
sketch = htmltools::withTags(table(
  class = 'display',
  thead(
    tr(
      th(rowspan = 2, 'Species'),
      th(colspan = 2, 'Sepal'),
      th(colspan = 2, 'Petal')
    ),
    tr(
      lapply(rep(c('Length', 'Width'), 2), th)
    )
  )
))
print(sketch)

<table class="display">
  <thead>
    <tr>
      <th rowspan="2">Species</th>
      <th colspan="2">Sepal</th>
      <th colspan="2">Petal</th>
    </tr>
    <tr>
      <th>Length</th>
      <th>Width</th>
      <th>Length</th>
      <th>Width</th>
    </tr>
  </thead>
</table>

# use rownames = FALSE here because we did not generate a cell for row names in
# the header, and the header only contains five columns
datatable(iris[1:20, c(5, 1:4)], container = sketch, rownames = FALSE)

还可以添加页脚容器 ， 例如 ：

# a custom table with both header and footer
sketch = htmltools::withTags(table(
  tableHeader(iris),
  tableFooter(iris)
))
print(sketch)

<table>
  <thead>
    <tr>
      <th>Sepal.Length</th>
      <th>Sepal.Width</th>
      <th>Petal.Length</th>
      <th>Petal.Width</th>
      <th>Species</th>
    </tr>
  </thead>
  <tfoot>
    <tr>
      <th>Sepal.Length</th>
      <th>Sepal.Width</th>
      <th>Petal.Length</th>
      <th>Petal.Width</th>
      <th>Species</th>
    </tr>
  </tfoot>
</table>

datatable(
  head(iris, 10),
  container = sketch, options = list(pageLength = 5, dom = 'tip'), rownames = FALSE
)

2.6 表格标题

通过​​caption​​​ 参数可以设置表格标题。参数的值可以是字符串或者​​htmltools::tags$caption()​​​ 产生的对象标签。更多数据见​​此处​​。

datatable(
  head(iris),
  caption = 'Table 1: This is a simple caption for the table.'
)

# display the caption at the bottom, and <em> the caption
datatable(
  head(iris),
  caption = htmltools::tags$caption(
    style = 'caption-side: bottom; text-align: center;',
    'Table 2: ', htmltools::em('This is a simple caption for the table.')
  )
)

2.7 筛选栏

DataTables 没有默认提供筛选栏功能，只在右上角有一个通用的筛选框。可以通过参数​​filter​​​ 自动生成筛选框。通常参数设置为​​filter='none'​​​ ,因此不展示筛选框。可以通过设置参数​​filter = 'top' OR filter = 'bottom'​​ 放置筛选框的位置。

iris2 = iris[c(1:10, 51:60, 101:110), ]
datatable(iris2, filter = 'top', options = list(
  pageLength = 5, autoWidth = TRUE
))

列类型的不同，筛选框的控制也不同。最开始，可以看到相同的筛选框。但是点击之后，筛选方式是不同的：

1. 数值、时间、日期类型，用滑块筛选范围
2. 因子型，用复选框筛选，可以多选
3. 字符串，普通的筛选框，通过筛选框输入的值进行匹配

---

初始筛选框的筛选值以不同方式储存：

1. 数值、时间、日期类型，筛选范围为最小值到最大值
2. 因子型，值为JSON数组形式​​['value1','value2','value3']​​

---

可以通过按键

清除筛选条件。如果不想使用控件，也可以直接在筛选框中输入值。例如数值型数据列的筛选框可以直接输入​​2...5​​ ,则滑块自动调整范围为[2，5]。如果筛选框太窄，难以看清里面的选项，可以移动鼠标放置在控件上，选项则会出现提示信息。

下面的案例是字符串、日期、时间类型筛选框的解释：

d = data.frame(
  names = rownames(mtcars),
  date = as.Date('2015-03-23') + 1:32,
  time = as.POSIXct('2015-03-23 12:00:00', tz = 'UTC') + (1:32) * 5000,
  stringsAsFactors = FALSE
)
str(d)
## 'data.frame':    32 obs. of  3 variables:
##  $ names: chr  "Mazda RX4" "Mazda RX4 Wag" "Datsun 710" "Hornet 4 Drive" ...
##  $ date : Date, format: "2015-03-24" "2015-03-25" ...
##  $ time : POSIXct, format: "2015-03-23 13:23:20" "2015-03-23 14:46:40" ...
datatable(d, filter = 'bottom', options = list(pageLength = 5))

上述关于筛选框的案例可以在客户端和服务器同时使用，但是存在些许差异。比如Java和R的正则表达式不同。

2.8 ​​callback​​ 参数

初始化之后， ​​callback​​ 参数调用Java函数应用于 DataTables对象上。下例为表格初始化后展示第二页：

datatable(head(iris, 30), callback = JS('table.page("next").draw(false);'))

上面例子中，真正的回调函数是：

function(table) {
  table.page("next").draw(false);
}

​​.DataTable()​​​方法初始化表格后，通过回调函数传递实例。
请记住​​​callback​​​只是​​datatable​​ 函数的参数，不要和DataTable中的option混淆。这个函数的目的是允许用户在DataTables对象生成之后操作它。

2.9 转义表内容【这个是什么鬼】

参数​​escape​​ 决定HTML实体是否存在表格中。当表格被渲染在动态web应用中，例如shiny时，会出现安全问题。例子如下：

m = matrix(c(
  '<b>Bold</b>', '<em>Emphasize</em>', '<a href="http://rstudio.com">RStudio</a>',
  '<a href="#" onclick="alert(\'Hello World\');">Hello</a>'
), 2)
colnames(m) = c('<span style="color:red">Column 1</span>', '<em>Column 2</em>')
datatable(m)  # escape = TRUE by default

datatable(m, escape = FALSE)

除了TRUE和FALSE，也可以指定需要转义的列。

datatable(m, escape = 1)  # escape the first column
datatable(m, escape = 2)  # escape the second column
datatable(m, escape = c(TRUE, FALSE))  # escape the first column
colnames(m) = c('V1', 'V2')
datatable(m, escape = 'V1')

REF

​​http://rstudio.github.io/DT/​​

后记

翻译的一塌糊涂，专业词汇实在是不明白。姑且这样吧~

2017-09-18 于杭州