# 使用 bslib 主题闪亮应用程序使用 bslib 的 Bootstrap 5 主题系统自定义 Shiny 应用程序外观。从快速 Bootswatch 主题到高级 Sass 定制和动态颜色模式切换。 ## 快速入门 **“闪亮”预设（推荐起点）：** 页面侧边栏（ theme = bs_theme(), # 默认预设“闪亮”——经过精心设计，而不是简单的 Bootstrap ... ） **Bootswatch 主题（针对不同的视觉风格）：** 页面侧边栏（ theme = bs_theme(preset = "zephyr"), # 或 "cosmo"、"minty"、"darkly" 等。 ... ） **自定义颜色和字体：** 页面侧边栏（主题 = bs_主题( 版本=5， bg =“#FFFFFF”， fg = "#333333", 主要=“#2c3e50”， base_font = font_google("Lato"), header_font = font_google("蒙特塞拉特") ), ... ） **从`_brand.yml`自动品牌化：**如果应用程序或项目目录中存在`_brand.yml`文件，`bs_theme()`会自动发现并应用它。无需更改代码。需要 `brand.yml` R 包。 bs_theme(brand = FALSE) # 禁用自动发现 bs_theme(brand = TRUE) # 需要 _brand.yml （如果没有找到则出错） bs_theme(brand = "path/to/brand.yml") # 显式路径 ## 主题化工作流程 1. 从“shiny”预设（默认）或接近您想要的外观的 Bootswatch 主题开始 2. 自定义主颜色（`bg`、`fg`、`primary`） 3. 使用 `font_google()` 或其他字体助手调整字体 4. 通过 `...` 或 `bs_add_variables()` 使用 Bootstrap Sass 变量进行微调 5. 如果需要，使用 bs_add_rules() 添加自定义 Sass 规则 6. 启用 `thematic::thematic_shiny()` 使绘图与主题匹配 7. 开发时使用`bs_themer()`进行交互式预览 **示例：** 主题 <- bs_theme(preset = "minty") |> bs_主题_更新（主要=“#1a9a7f”， base_font = font_google("拉托") ) |> bs_add_rules（“ .card { box-shadow: 0 2px 8px rgba(0,0,0,0.1); } ”） ## bs_主题（）创建 Bootstrap 主题的核心功能。返回一个 `sass::sass_bundle()` 对象。 bs_主题（版本 = version_default(), 预设= NULL，#“shiny”（BS5+的默认值），“bootstrap”或Bootswatch名称 ..., # Bootstrap Sass 变量覆盖 brand = NULL, #brand.yml: NULL（自动）、TRUE（需要）、FALSE（禁用）或路径 bg = NULL，fg = NULL，主要 = NULL，次要 = NULL，成功= NULL，信息= NULL，警告= NULL，危险= NULL，基本字体 = NULL，代码字体 = NULL，标题字体 = NULL， font_scale = NULL, # 基本字体大小的标量乘数（例如，1.5 = 150%） bootswatch = NULL # 预设的别名）使用 bs_theme_update(theme, ...) 修改现有主题。使用“is_bs_theme(x)”来测试一个对象是否是主题。 ### 预设和 Bootswatch **“shiny”预设（推荐）：** 对于 Bootstrap 5+，`bs_theme()` 默认为 `preset = "shiny"`。这是一个精心设计的、专门为 Shiny 应用程序设计的主题——它**不是**普通的 Bootstrap。它为卡片、侧边栏、值框和其他 bslib 组件提供了专业的样式以及精心选择的默认值。从这里开始，在达到 Bootswatch 主题之前自定义颜色和字体。 **Vanilla Bootstrap：** 使用 `preset = "bootstrap"` 删除“闪亮”预设并获得未修改的 Bootstrap 5 样式。 **内置预设：** `builtin_themes()` 列出了 bslib 自己的预设。 **Bootswatch 主题：** `bootswatch_themes()` 列出所有可用的 Bootswatch 主题。选择适合应用程序用途和受众的一种 - 不要默认应用一种。流行的选项：“zephyr”（浅色、现代）、“cosmo”（干净）、“minty”（清新绿色）、“flatly”（平面设计）、“litera”（清爽）、“darkly”（深色）、“cyborg”（深色）、“simplex”（简约）、“sketchy”（手绘）。 ### 主要颜色最有影响力的颜色 - 通过变量级联更改这些颜色会影响 **数百** CSS 规则：参数|描述 ---|--- `背景` |背景颜色 `fg` |前景色（文本）颜色 `主要` |主要品牌颜色（链接、导航活动状态、输入焦点） `次要` |操作按钮的默认值 `成功` |积极/成功状态（通常为绿色） `信息` |信息内容（通常为蓝绿色） `警告` |警告（通常为黄色） `危险` |错误/破坏性行为（通常为红色） bs_主题（ bg =“#202123”，fg =“#B8BCC2”，主要=“#EA80FC”，次要=“#48DAC6” ） **颜色提示：** * `bg`/`fg`：色调相似，亮度差异大（保证对比度以提高可读性） * `primary`：与`bg`和`fg`形成对比；用于超链接、导航、输入焦点 * 颜色可以是 `htmltools::parseCssColors()` 理解的任何格式 ### 版式三个字体参数：`base_font`、`heading_font`、`code_font`。使用 `font_scale` 统一缩放所有字体大小（例如，`1.5` 表示 150%）。每个参数接受单个字体、“font_collection()”或字体名称的字符向量。 #### font_google() 在本地下载并缓存 Google 字体（默认情况下“local = TRUE”）。仅在首次下载时需要互联网。 bs_主题（ base_font = font_google("Roboto"), header_font = font_google("蒙特塞拉特"), code_font = font_google("Fira 代码") ）具有可变权重： `font_google("Crimson Pro", wght = "200..900")` 具有特定权重： `font_google("Raleway", wght = c(300, 400, 700))` **建议后备**以避免在慢速连接上出现不可见文本 (FOIT) 的闪烁： bs_主题（基本字体 = 字体集合( font_google("Lato", local = FALSE), “Helvetica Neue”、“Arial”、“无衬线字体” ））字体配对资源：fontpair.co #### 字体链接() 用于自定义字体 URL 的 CSS Web 字体接口： font_link("深红专业版", href =“https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@200..900”) #### font_face() 对于具有完整“@font-face”控制的本地托管字体文件：字体（家庭=“深红专业”，样式=“正常”，重量=“200 900”， src = "url(fonts/crimson-pro.woff2) 格式('woff2')" ） #### 字体集合() 将多种字体与后备顺序组合起来： font_collection(font_google("Lato")、"Helvetica Neue"、"Arial"、"sans-serif") ## 低级主题函数用于超出“bs_theme()”命名参数的自定义。它们直接与 Bootstrap 的 Sass 层一起工作。 ### bs_add_variables() 添加或覆盖 Bootstrap Sass 变量默认值：主题 <- bs_add_variables( bs_theme（预设=“粗略”，主要=“橙色”）， “body-bg”=“#EEEEEE”， "font-family-base" = "等宽字体", “字体大小基础”=“1.4rem”， “btn-padding-y”=“.16rem” ） **`.where` 参数**控制 Sass 编译顺序中的位置： `.where` |何时使用 ---|--- `“默认”`（默认）|使用 `!default` 标志设置变量默认值。放置在 Bootstrap 自己的默认值之前**。 `“声明”` |引用其他 Bootstrap 变量（例如“$ secondary”）。放置在 Bootstrap 默认值的**之后**。 `“规则”` |放置在所有规则之后。很少需要。 **引用 Bootstrap 变量：** # 这在 bs_theme() 中失败，因为 $ secondary 尚未定义： # bs_theme("进度条-bg" = "$secondary") # 使用 bs_add_variables 和 .where = "declarations" 代替： bs_主题() |> bs_add_variables("progress-bar-bg" = "$secondary", .where = "声明") ### bs_add_rules() 添加可以引用 Bootstrap 变量和 mixin 的自定义 Sass/CSS 规则：主题 <- bs_theme(primary = "#007bff") |> bs_add_rules（“ .自定义卡{ 背景：mix($bg, $primary, 95%); 边框：1px 实心$primary；填充：$spacer； @include 媒体断点向上(md) { 填充：$spacer * 2； } } ”）来自外部文件： `bs_add_rules(sass::sass_file("www/custom.scss"))` 可用的 Sass 函数：“lighten()”、“darken()”、“mix()”、“rgba()”、“color-contrast()”。可用的 Bootstrap mixins：`@include media-breakpoint-up()`、`@include box-shadow()`、`@include border-radius()`。 ### bs_add_functions() 和 bs_add_mixins() 将自定义 Sass 函数或 mixins 添加到主题包中：主题 |> bs_add_functions("@function my-tint($color) { @return mix(white, $color, 20%); }") |> bs_add_rules(".highlight { 背景：my-tint($primary); }") ### bs_bundle() 将 `sass::sass_bundle()` 对象附加到主题（用于打包可重用的主题扩展）： my_extension <- sass::sass_layer( 默认值=列表（“my-var”=“红色！默认”），规则 =“.my-class { 颜色：$my-var; }” ）主题 <- bs_theme() |> bs_bundle(my_extension) ## Bootstrap Sass 变量通过 `bs_theme(...)` 或 `bs_add_variables()` 传递任何 Bootstrap 5 Sass 变量。 **查找变量名称：** **常用变量：** bs_主题（ “边界半径”=“0.5rem”， "卡片边框半径" = "1rem", "card-bg" = "减轻($bg, 5%)", "navbar-bg" = "$primary", “链接颜色”=“$primary”， “字体大小基础”=“1rem”， “间隔”=“1rem”， “btn-padding-y”=“.5rem”， “btn-padding-x”=“1rem”， “输入边框颜色”=“#dee2e6” ）值可以是引用变量、函数和数学的 Sass 表达式。 ## Bootstrap CSS 自定义属性有关详细信息，请参阅 [sass-and-css-variables.md]()： * Sass 变量如何编译成 `--bs-*` CSS 自定义属性 * 运行时与编译时变量层 * Bootstrap 5.3 颜色模式如何使用 CSS 变量覆盖 * 使用“data-bs-theme”为每个元素设置主题 * 用于一次性样式的 CSS 实用程序类 ## 深色模式和彩色模式有关详细信息，请参阅 [dark-mode.md]()： * Bootstrap 5.3的客户端颜色模式系统（`data-bs-theme`属性） * `input_dark_mode()` 和 `toggle_dark_mode()` 用于用户控制的切换 * 使用 `session$setCurrentTheme()` 进行服务器端主题切换 * 编写跨亮/暗模式工作的自定义 Sass * 组件兼容性（什么响应主题，什么不响应主题） ## R 主题图 `bs_theme()` 只影响 CSS。 R 绘图输出（在服务器端渲染为图像）不会自动匹配。使用“thematic”包：图书馆（专题） thematic_shiny(font = "auto") # 在shinyApp()之前调用闪亮的应用程序（用户界面，服务器） * 适用于基础 R、ggplot2 和lattice * 将 CSS 颜色转换为 R 绘图默认值 * `font = "auto"` 也匹配 `bs_theme()` 中的字体 * 补充 `bs_themer()` 以实现实时预览设置全局 ggplot2 主题以进一步保持一致性：库（ggplot2）主题集（主题最小（）） ## 仪表板背景样式 `bslib-page-dashboard` CSS 类在主要内容区域后面添加了浅灰色背景，为仪表板式应用程序提供了精美的外观，其中卡片在背景下脱颖而出。这是一个主题细节——它不会改变布局行为，只会改变视觉处理。 **对于`page_sidebar()`仪表板：** 页面侧边栏（类 =“bslib-页面-仪表板”， title = "我的仪表板", 侧边栏=侧边栏（...）， ... ） **对于具有以仪表板为中心的页面的“page_navbar()”：**将该类应用于各个“nav_panel()”容器（而不是“page_navbar()”本身），因此只有面向仪表板的页面才会获得灰色背景：页面导航栏（ title = "分析", nav_panel("仪表板", class = "bslib-page-dashboard", 布局列_换行（...） ), nav_panel("报告", # 无仪表板类 — 散文/报告的标准白色背景 ... ）） ## 交互式主题工具 ### bs_theme_preview() 用于预览带有许多示例 UI 组件的主题的独立演示应用程序： bslib::bs_theme_preview() # 默认主题 bslib::bs_theme_preview(bs_theme(preset = "darkly")) # 自定义主题默认情况下包括主题 UI (`with_themer = TRUE`)。 ### run_with_themer() 使用主题编辑器覆盖运行现有的 Shiny 应用程序（而不是 `shiny::runApp()`）： run_with_themer(shinyApp(ui, 服务器)) run_with_themer(“路径/到/应用程序”) ### bs_themer() 将主题编辑器添加到您自己的应用程序的服务器功能中：服务器 <- 函数（输入、输出、会话）{ bs_themer() # 在开发期间添加，在生产期间删除 # ... } 所有这三个工具都将生成的“bs_theme()”代码打印到 R 控制台，以便于复制粘贴。 **限制：** 仅 Bootstrap 5+、Shiny 应用程序和 `runtime:shiny` R Markdown，不影响不使用 `bs_dependency_defer()` 的第 3 方小部件。 ## 主题检查 **检索计算的 Sass 变量值：** vars <- c("body-bg", "body-color", "primary", "border-radius") bs_get_variables(bs_theme(), varnames = vars) bs_get_variables(bs_theme(preset = "darkly"), varnames = vars) **检查对比度（可访问性）：** bs_get_contrast(bs_theme(), c("主", "暗", "亮")) 目标是达到 WCAG AA 合规性：普通文本为 4.5:1，大文本为 3:1。 ## 最佳实践 1. **优先选择`bs_theme()`而不是自定义CSS** \--变量自动级联到所有相关组件 2. **固定 Bootstrap 版本**：`bs_theme(version = 5)` 可防止默认值更改时出现损坏 3. **使用后备字体**与 `font_collection()` 以避免慢速连接上的 FOIT 4. **跨组件测试**：输入、按钮、卡片、导航、绘图、表格、模态、toast、移动 5. **使用“bs_get_contrast()”和浏览器开发工具检查可访问性** 6. **使用CSS实用程序类**进行一次性样式而不是自定义CSS（请参阅[sass-and-css-variables.md]()) 7. **在单独的`theme.R`中组织复杂的主题**： # 主题.R 应用程序主题 <- 函数() { bs_主题（版本=5，主要=“#2c3e50”， base_font = font_google("Lato"), header_font = font_google("蒙特塞拉特", wght = c(400, 700)) ) |> bs_add_rules(sass::sass_file(“www/custom.scss”)) } ## 参考文件 * **[sass-and-css-variables.md]()** \-- Bootstrap的两层变量系统、CSS自定义属性、实用类 * **[dark-mode.md]()** \-- 颜色模式、暗模式、动态主题、组件兼容性

闪亮的 Bslib 主题

包含技能