htmlwidgets.org

htmlwidgets 是 R 的一个框架，用来把 JavaScript 可视化库接入 R。它的核心用法是：用一两行 R 代码生成交互式网页可视化，效果类似 R 的 plot，但输出是可交互的网页组件。这些组件可以在 R 控制台直接使用，也可以嵌入 R Markdown 文档和 Shiny 应用。如果你需要在 R 里做交互式图表、地图或网络图，又不想直接写 JavaScript，htmlwidgets 是主要入口。

它解决什么问题

R 自带的绘图系统输出静态图片。htmlwidgets 把 JavaScript 可视化库封装成 R 函数，让 R 用户用熟悉的语法调用它们，产物是 HTML 组件，能在浏览器里缩放、悬停、筛选。

官方描述的原话是：HTML widgets 的工作方式就像 R 的 plot，只不过它们产生的是交互式网页可视化。一行或两行 R 代码就足以生成一个 D3 图形或 Leaflet 地图。

现成组件覆盖哪些可视化类型

官网 showcase 列出了以下组件，按用途分类：

官网提到 gallery 中有 50 多个可用组件，showcase 只展示了其中一部分。所以选型时先去 gallery 搜，很可能已有现成封装。

三种使用场景

官网把使用场景分成三类：

• R 控制台：像调用 plot 一样直接生成组件。
• R Markdown 文档：把组件嵌入报告，输出 HTML 时保留交互性。
• Shiny 应用：作为应用中的交互元素。

这三种场景共用同一套组件，不需要为不同输出重写代码。

组合与联动

单个组件之外，htmlwidgets 生态提供了两个组合工具：

• flexdashboard：把多个 htmlwidgets 组合成仪表盘，支持按行和列灵活指定布局。
• crosstalk：把多个组件连接起来，目前支持组件间的联动刷选（linked brushing）和客户端筛选。

如果需要更复杂的交互，官网建议使用 Shiny。

自己封装新组件

如果 gallery 里没有你需要的 JavaScript 库，可以用 htmlwidgets 框架为它写一个 R binding，封装后同样能在 R 控制台、R Markdown 和 Shiny 中使用。官网的 Develop 部分提供了创建 widget 的指引，另有 widget 尺寸设置和高级主题文档。

从哪里开始

• 看效果：访问 showcase，浏览上面列出的组件示例。
• 找组件：访问 gallery，检索 50 多个可用组件。
• 学开发：访问 Develop 部分，了解如何为 JavaScript 库写 R 封装。
• 源码与问题：项目托管在 GitHub。

flexdashboard 解决的是布局问题：把多个 htmlwidgets 按行、列组合成一个仪表盘页面。crosstalk 解决的是联动问题：让多个 widget 之间共享选择状态，实现联动刷选和客户端过滤。两者都是围绕 htmlwidgets 的配套扩展包，前者管“摆在哪里”，后者管“怎么互相响应”。如果还需要服务端逻辑驱动的复杂交互，则要用 Shiny，而不是仅靠 crosstalk。

flexdashboard：把多个 widget 拼成仪表盘

htmlwidgets 本身只负责把单个 JavaScript 可视化渲染到 R 控制台、R Markdown 文档或 Shiny 应用里。当你想在一个页面里同时放地图、时间序列、表格等多个 widget 时，就需要一个布局方案，flexdashboard 就是为此设计的。

它的定位是：

• 用基于行和列的布局组织多个 widget，官方描述为“灵活且易于指定”。
• 适合做交互式仪表盘（dashboard）这类多视图并列的场景。
• 与 htmlwidgets 直接配合，widget 作为仪表盘中的面板内容。

适用条件：你的需求是“多个可视化同屏展示、按网格排布”，且不需要复杂的服务端交互逻辑。这时 flexdashboard 比手写布局更省事。

crosstalk：让多个 widget 互相关联

crosstalk 解决的是另一类问题：多个 widget 各自独立渲染时，用户在其中一个上做的选择不会影响其他 widget。crosstalk 把它们“接线”到一起。

根据官方说明，它当前支持的能力是：

• 联动刷选（linked brushing）：在一个 widget 上刷选数据，其他关联 widget 同步高亮或过滤。
• 客户端过滤（client side filtering）：过滤在浏览器端完成，不依赖服务端往返。

适用条件：你希望多个视图共享同一份选择状态，比如在一张图上选中若干点，另一张图同步显示这些点对应的数据。注意官方明确说，如果需要更复杂的交互，应当使用 Shiny——crosstalk 的能力边界就是联动刷选和客户端过滤这两类。

两者的分工对比

怎么选

• 只需要把多个 widget 排成一个仪表盘：用 flexdashboard。
• 需要多个 widget 之间联动响应：用 crosstalk。
• 两者可以叠加使用：在 flexdashboard 布局里放入通过 crosstalk 联动的 widget。
• 需要服务端驱动的复杂交互：用 Shiny，而不是只靠 crosstalk。

配套资源入口

• 仪表盘创建：flexdashboard 包（官网 “Create a dashboard” 入口）。
• 联动机制：crosstalk 包（官网 “Learn about crosstalk” 入口）。
• 更复杂交互：Shiny。
• 想先看效果：官网 showcase 展示精选 widget，gallery 收录了 50 多个可用 widget。

htmlwidgets 是 R 的一个框架，把 JavaScript 可视化库封装成 R 函数，用法和普通绘图函数类似：写一两行 R 代码就能生成 D3 图形或 Leaflet 地图。同一份 widget 对象可以在三个地方使用——R 控制台、R Markdown 文档、Shiny 应用。如果你已经会用 plot()，迁移成本几乎为零；需要额外配置的只有仪表盘组合（flexdashboard）和组件联动（crosstalk）这两类进阶场景。

先理解它的工作方式

htmlwidgets 本身不是可视化库，而是一座桥：R 端负责准备数据、生成配置，JavaScript 端负责渲染成交互式 HTML。官方页面把它和 R 绘图直接类比——"HTML widgets work just like R plots except they produce interactive web visualizations"。

这意味着两件事：

• 你不需要写 JavaScript，除非你要自己开发新 widget。
• 渲染结果依赖浏览器环境，所以它在 RStudio Viewer、R Markdown 输出和 Shiny 页面里表现一致，但在纯文本终端里看不到图形。

在 R 控制台运行

这是验证环境和熟悉 API 最快的方式。

1. 安装一个具体 widget 包，例如 install.packages("leaflet")。
2. 加载并调用：

library(leaflet)
leaflet() %>%
  addTiles() %>%
  addMarkers(lng = 116.4, lat = 39.9, popup = "示例点")

预期结果：RStudio 的 Viewer 面板出现一张可缩放、可点击标记的地图。如果只在控制台看到一段 HTML 或什么都没出现，通常是没有在支持 HTML 输出的环境里运行，而不是代码写错了。

嵌入 R Markdown 文档

在代码块里直接返回 widget 对象即可，不需要 print() 或额外包装：

```{r}
library(dygraphs)
dygraph(nhtemp, main = "年降水量") %>%
  dyRangeSelector()

预期结果：knit 之后文档中出现可交互的时间序列图，鼠标拖动即可缩放区间。

常见卡点：

- 输出格式必须是 HTML 类（`html_document` 等）。输出 PDF 或 Word 时 widget 无法交互，只会退化成静态图或直接失败。
- 自包含文档（`self_contained: true`，默认值）会把 JavaScript 依赖内嵌进 HTML，文件变大但便于分享；依赖外部 CDN 时体积小，但离线打开会失效。

## 嵌入 Shiny 应用

在 `ui` 里用对应的 `xxxOutput()` 占位，在 `server` 里用 `renderXxx()` 渲染：

```r
library(shiny)
library(plotly)

ui <- fluidPage(
  plotlyOutput("p")
)

server <- function(input, output, session) {
  output$p <- renderPlotly({
    plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
  })
}

shinyApp(ui, server)

预期结果：页面中出现可悬停、可框选的散点图。

常见卡点：widget 包通常提供自己的 render 函数（如 renderPlotly、renderLeaflet），不要用通用的 renderPlot 去接，否则不会渲染。另外，Shiny 中的交互（如点击事件）需要通过 widget 包暴露的 event 接口回传到 R，而不是自动变成 input$ 值。

组合多个 widget：flexdashboard 与 crosstalk

单个 widget 只能解决一张图的问题。官方给出两条组合路径：

crosstalk 的定位值得注意：它做的是客户端联动，筛选和刷选在浏览器内完成，因此不需要 Shiny 后端。如果你的联动逻辑需要重新查询数据库或跑模型，那就该用 Shiny 而不是 crosstalk。

选哪个 widget

官方 showcase 列出了常用组件，gallery 里有 50 多个可选。按任务对应：

• 地理映射：Leaflet
• 时间序列：dygraphs
• 通用交互图形（基于 D3）：Plotly
• 表格展示：DataTables
• 网络/图数据：visNetwork、networkD3
• 图表库绑定：Highcharter（Highcharts）、rbokeh（Bokeh）
• 3D 与场景：threejs、rglwidget
• 流程图：DiagrammeR

选择时优先看该 widget 是否仍在维护、是否支持你需要的交互事件回传，而不是只看默认样式。

自己开发 widget

当现有包覆盖不了你需要的 JavaScript 库时，可以按官方 Develop 文档为它写一个 R binding，写好后同样能在控制台、R Markdown 和 Shiny 三处使用。这是框架层面的工作，需要同时理解 R 端的数据传递和 JS 端的渲染约定，不属于日常使用范围。

为 JavaScript 库创建 htmlwidgets 组件，本质是写一个 R 绑定（binding），把 R 对象和 JavaScript 可视化库桥接起来。htmlwidgets.org 的 Develop / Creating a widget 页面给出的路径是：为某个 JavaScript 库实现 R 绑定后，这个组件就能在 R 控制台、R Markdown 文档和 Shiny 应用中使用。适用条件是：你已经选定了一个 JavaScript 可视化库，并希望它在 R 里像 plot 一样被调用。

一个 htmlwidgets 组件由什么构成

htmlwidgets 的定位是“把最好的 JavaScript 数据可视化带到 R”。它让 HTML widgets 用起来和 R 的 plot 类似，区别是产出交互式网页可视化——一两行 R 代码就能生成 D3 图形或 Leaflet 地图。

要让它同时能在控制台、R Markdown 和 Shiny 中工作，组件需要处理三件事：

• R 侧：接收 R 数据与参数，序列化为 JavaScript 可读的形式。
• JavaScript 侧：接收数据，调用目标库完成渲染。
• 桥接层：由 htmlwidgets 框架负责 R 与 JavaScript 之间的无缝衔接。

开发步骤

1. 选定目标 JavaScript 库

先确定要绑定的库。网站展示的组件覆盖了多种类型，可作为选型参考：

2. 编写 R 绑定

按照 Develop / Creating a widget 的指引，为你的 JavaScript 库编写 R 绑定。绑定完成后，组件即可在 R 控制台、R Markdown 文档和 Shiny 应用三处使用。

3. 处理组件尺寸

网站把 Widget sizing 单列为开发主题，说明尺寸设置是组件开发中需要专门处理的一环，而不是可忽略的细节。

4. 按需深入进阶主题

Advanced topics 面向更复杂的开发需求。如果组件需要与其他组件联动，可以了解 crosstalk：它支持组件之间的联动刷选（linked brushing）和客户端过滤；更复杂的交互则用 Shiny 实现。

开发完成后能做什么

• 在 R 控制台使用：像调用 plot 一样调用组件。
• 嵌入 R Markdown 文档：在报告中直接输出交互式可视化。
• 嵌入 Shiny 应用：作为交互式 Web 应用的一部分。
• 组合成仪表盘：用 flexdashboard 把多个 htmlwidgets 组合进仪表盘，它提供基于行和列的灵活布局。
• 组件间联动：用 crosstalk 把组件连接起来。

从哪里开始

网站提供 Showcase 展示精选组件，Gallery 可浏览 50 多个可用组件。开发新组件时，先看 Showcase 里同类组件的实现方式，再进入 Develop / Creating a widget 按步骤操作。如果目标只是使用现成组件而非开发新组件，直接查 Gallery 即可。

htmlwidgets.org 是 R 语言生态中 HTML widgets 框架的官方站点。它解决的核心问题是：让 R 用户不必写 JavaScript，就能在 R 控制台、R Markdown 文档和 Shiny 应用里直接使用基于 JavaScript 的交互式可视化。如果你已经在用 R 做数据分析，又想要可交互的图表而不是静态图片，这个站点就是入口；如果你打算把某个 JavaScript 可视化库接入 R，它也是开发文档的来源。

它提供什么

站点围绕三件事组织内容：

• 框架本身：一套在 R 和 JavaScript 之间建立桥接的机制，让 JavaScript 可视化库能以 R 函数的形式调用。
• 展示区（Showcase）：用实际例子演示 widgets 能做什么，包括在 R 控制台、R Markdown 文档和 Shiny 应用中的使用方式。
• 组件库（Gallery）：收录 50 多个可用的 widgets，按可视化类型分类浏览。

能用来做什么

按站点首页的说明，HTML widgets 的工作方式“就像 R 绘图一样，只不过产出的是交互式网页可视化”。一行或两行 R 代码就能生成一个 D3 图形或 Leaflet 地图。

首页列出的代表性 widgets 包括：

这些 widgets 可以三种方式使用：在 R 控制台直接调用、嵌入 R Markdown 报告、嵌入 Shiny Web 应用。

组合与联动

单个 widget 之外，站点还指向两个扩展方向：

• Flexdashboard：把多个 htmlwidgets 组合成一个仪表盘，提供基于行和列的灵活布局。
• Crosstalk：把多个 widgets 连接起来，目前支持 widgets 之间的联动刷选（linked brushing）和客户端筛选。需要更复杂的交互时，站点建议改用 Shiny。

面向开发者

除了使用现成 widgets，站点还有 “Develop” 部分，讲如何为你偏好的 JavaScript 库创建 R binding，使其能在 R 控制台、R Markdown 文档和 Shiny 应用中使用。另有 “Widget sizing” 和 “Advanced topics” 等进阶内容。

适合谁

• 想在 R 里快速做出交互式图表的分析人员：从 Gallery 挑一个 widget，按 Showcase 的示例调用即可。
• 需要把多个图表组织成仪表盘的人：看 flexdashboard 和 crosstalk 部分。
• 想把新的 JavaScript 可视化库接入 R 的开发者：看 Develop 部分。

站点版权信息显示为 2014–2015 年 Ramnath Vaidyanathan、Kenton Russell 和 RStudio, Inc.，属于该框架的早期官方资料。