shiny-bslib

使用 bslib 构建现代 Shiny 应用

使用 bslib 的 Bootstrap 5 组件和布局，构建专业的 Shiny 仪表盘。本技能聚焦于现代 UI/UX 模式，用于替代旧版 Shiny 方案。

快速入门

单页仪表盘：

library(shiny)
library(bslib)

ui <- page_sidebar(
  title = "My Dashboard",
  theme = bs_theme(version = 5),  # "shiny" preset by default
  sidebar = sidebar(
    selectInput("variable", "Variable", choices = names(mtcars))
  ),
  layout_column_wrap(
    width = 1/3,
    fill = FALSE,
    value_box(title = "Users", value = "1,234", theme = "primary"),
    value_box(title = "Revenue", value = "$56K", theme = "success"),
    value_box(title = "Growth", value = "+18%", theme = "info")
  ),
  card(
    full_screen = TRUE,
    card_header("Plot"),
    plotOutput("plot")
  )
)

server <- function(input, output, session) {
  output$plot <- renderPlot({
    hist(mtcars[[input$variable]], main = input$variable)
  })
}

shinyApp(ui, server)

多页仪表盘：

ui <- page_navbar(
  title = "Analytics Platform",
  theme = bs_theme(version = 5),
  nav_panel("Overview", overview_ui),
  nav_panel("Analysis", analysis_ui),
  nav_panel("Reports", reports_ui)
)

核心概念

页面布局

• page_sidebar() -- 带侧边栏的单页仪表盘（最常见）
• page_navbar() -- 带顶部导航栏的多页应用
• page_fillable() -- 填满视口的布局，适用于自定义排布
• page_fluid() -- 适用于长篇内容的滚动布局

详见 page-layouts.md。

网格系统

• layout_column_wrap() -- 自动换行的统一网格（大多数情况下推荐使用）
• layout_columns() -- 可精确控制的 12 列 Bootstrap 网格

详见 grid-layouts.md。

卡片

仪表盘内容的主要容器。支持页眉、页脚、多个正文区块和全屏展开。

详见 cards.md。

数值框

展示关键指标和 KPI，可选配图标、迷你图和内置主题。

详见 value-boxes.md。

导航

• 页面级：用于多页应用的 page_navbar()
• 组件级：用于标签页内容的 navset_card_underline()、navset_tab()、navset_pill()

详见 navigation.md。

侧边栏

• 页面级：page_sidebar() 或 page_navbar(sidebar = ...)
• 组件级：卡片内的 layout_sidebar()
• 支持条件内容、动态展开/收起和手风琴面板
• 默认 resizable = TRUE — 用户可在桌面端拖动边缘调整大小

详见 sidebars.md。

填充式布局

填充系统用于控制组件如何调整大小，以填满可用空间。关键概念：可填充容器、填充项、填充载体。只有容器定义了高度时，填充才会生效。

详见 filling.md。

主题

• 使用 Bootswatch 主题的 bs_theme()，可快速设置样式
• 自定义颜色：bg、fg、primary 会影响数百条 CSS 规则
• 字体：使用 font_google() 设置排版
• 动态主题：input_dark_mode() + session$setCurrentTheme()

详见 theming.md。

UI 组件

• 手风琴面板 -- 可折叠区块，尤其适用于侧边栏
• 工具提示 -- 悬停时显示的帮助文字
• 弹出框 -- 点击后显示的次级 UI/输入容器
• Toast 通知 -- 临时通知消息
• 工具栏 -- 由按钮、选择框和分隔线组成的紧凑水平栏，适用于卡片页眉和页脚

详见 accordions.md、tooltips-popovers.md、toasts.md 和 toolbars.md。

图标

推荐使用 bsicons 包（Bootstrap Icons，专为 bslib 设计）：

bsicons::bs_icon("graph-up")
bsicons::bs_icon("people", size = "2em")

浏览图标：https://icons.getbootstrap.com/

替代方案：fontawesome 包：

fontawesome::fa("envelope")

仅图标触发器的无障碍支持： 如果图标是工具提示、弹出框或类似交互元素的唯一触发器（没有配套文本），则必须确保屏幕阅读器能够识别它。默认情况下，图标包会将图标标记为装饰性内容（aria-hidden="true"），使辅助技术无法读取。

• bsicons::bs_icon()：提供 title — 这会自动设置 a11y = "sem"

  tooltip(
    bs_icon("info-circle", title = "More information"),
    "Tooltip content here"
  )
  

• fontawesome::fa()：设置 a11y = "sem" 并提供 title

  tooltip(
    fa("circle-info", a11y = "sem", title = "More information"),
    "Tooltip content here"
  )
  

title 应描述触发器的用途（例如“更多信息”“设置”），而不是图标本身（例如不要写“信息圆圈图标”）。

特殊输入

• input_switch() -- 切换开关（现代复选框替代方案）
• input_dark_mode() -- 暗色模式切换
• input_task_button() -- 用于长时间运行操作的按钮
• input_code_editor() -- 带语法高亮的代码编辑器
• input_submit_textarea() -- 带显式提交功能的文本区域

详细说明请参阅 inputs.md。

常见工作流

构建仪表板

1. 选择页面布局：page_sidebar()（单页）或 page_navbar()（多页）
2. 使用 bs_theme() 添加主题（可考虑使用 Bootswatch 快速入门）
3. 创建侧边栏，并添加用于筛选和控制的输入项
4. 在顶部添加用于展示关键指标的数值框（在容器上设置 fill = FALSE）
5. 使用 layout_column_wrap() 或 layout_columns() 排列卡片
6. 为所有可视化卡片启用 full_screen = TRUE
7. 添加 thematic::thematic_shiny()，为绘图设置主题

现代化现有应用

完整的旧版模式与现代等效方案映射，请参阅 migration.md。主要步骤：

1. 将 fluidPage() 替换为 page_sidebar() 或 page_navbar()
2. 将 fluidRow()/column() 替换为 layout_columns()
3. 使用 card(full_screen = TRUE) 包装输出
4. 添加 theme = bs_theme(version = 5)
5. 将关键指标转换为 value_box() 组件
6. 将 tabsetPanel() 替换为 navset_card_underline()

指南

1. 优先使用 bslib 页面函数（page_sidebar()、page_navbar()、page_fillable()、page_fluid()），而非旧版对应函数（fluidPage()、navbarPage()）
2. 使用 layout_column_wrap() 或 layout_columns() 创建网格布局，而不要使用不支持填充布局的 fluidRow()/column()
3. 使用 card(full_screen = TRUE) 包装输出来构建仪表板——全屏展开是一项价值很高的功能
4. 对包含数值框的 layout_column_wrap() 容器设置 fill = FALSE（数值框不应拉伸以填满高度）
5. 固定 Bootstrap 版本：添加 theme = bs_theme(version = 5) 或预设主题
6. 在服务端使用 thematic::thematic_shiny()，使基础 R 和 ggplot2 绘图与应用主题一致
7. 在 layout_column_wrap() 中使用 width = "250px" 等响应式宽度，以自动调整列数
8. 当侧边栏包含许多控件时，使用 accordion() 对输入项分组
9. 请参阅 migration.md，了解旧版 Shiny 模式与现代 bslib 等效方案的映射

避免常见错误

1. 避免直接嵌套 card() 容器。navset_card_*() 函数本身已经是卡片；nav_panel() 内容应直接放在其中，无需再用 card() 包装
2. 仅在需要排列多个元素时使用 layout_columns() 和 layout_column_wrap()。单个子元素应直接传给其容器函数。
3. 切勿嵌套 page_*() 函数。每个应用只能使用一个顶层页面函数。

参考文件

• migration.md -- 从旧版 Shiny 迁移到现代 bslib 的指南
• page-layouts.md -- 页面级布局函数和模式
• grid-layouts.md -- 多列网格系统
• cards.md -- 卡片组件和功能
• value-boxes.md -- 用于展示指标和 KPI 的数值框
• navigation.md -- 导航容器和模式
• sidebars.md -- 侧边栏布局和组织方式
• filling.md -- 可填充容器和填充项
• theming.md -- 基础主题设置（颜色、字体、Bootswatch）。高级主题设置请参阅 shiny-bslib-theming 技能
• accordions.md -- 可折叠区块和侧边栏组织方式
• tooltips-popovers.md -- 悬停提示和点击触发的弹出框
• toasts.md -- 临时通知消息
• toolbars.md -- 卡片页眉和页脚的工具栏组件
• inputs.md -- 特殊的 bslib 输入小部件
• best-practices.md -- bslib 专属模式和常见注意事项