用 bslib 定制 Shiny…

在 Shiny 应用中需要自定义外观（主题、颜色、字体、暗色模式、动态换肤、图表配色匹配）时使用 bslib 的 Bootstrap 5 主题系统。

适用场景

解决思路

1. 从 `bs_theme()` 默认的 `"shiny"` 预设开始（Bootstrap 5+ 下默认即为该预设，是专为 Shiny 打磨的主题，并非原生 Bootstrap），或选择一个接近目标风格的 Bootswatch 主题（如 `"zephyr"`、`"cosmo"`、`"minty"`、`"darkly"` 等），不要默认套用某个 Bootswatch。
2. 按工作流推进：先选预设 → 定制主色（`bg`、`fg`、`primary`）→ 用 `font_google()` 等调整字体 → 通过 `...` 或 `bs_add_variables()` 微调 Bootstrap Sass 变量 → 需要时用 `bs_add_rules()` 添加自定义 Sass 规则 → 调用 `thematic::thematic_shiny()` 让图表匹配主题 → 开发期用 `bs_themer()` 交互预览。
3. 用 `bs_theme()` 创建主题：可传 `version`、`preset`（`"shiny"`/`"bootstrap"`/Bootswatch 名）、`...`（Bootstrap Sass 变量覆盖）、`brand`、`bg`/`fg`/`primary`/`secondary`/`success`/`info`/`warning`/`danger`、`base_font`/`code_font`/`heading_font`、`font_scale`（如 1.5 表示 150%）、`bootswatch`（`preset` 的别名）；用 `bs_theme_update(theme, ...)` 修改已有主题，用 `is_bs_theme(x)` 判断对象是否为主题。
4. 用 `preset = "bootstrap"` 去掉 shiny 预设得到原生 Bootstrap 5 样式；用 `builtin_themes()` 列出 bslib 自带预设，用 `bootswatch_themes()` 列出所有 Bootswatch 主题。
5. 若应用或项目目录存在 `_brand.yml`，`bs_theme()` 会自动发现并应用（需 `brand.yml` R 包）；可用 `brand = FALSE` 禁用自动发现、`brand = TRUE` 强制要求（找不到则报错）、`brand = "path/to/brand.yml"` 指定路径。
6. 调整主色时注意：`bg`/`fg` 取相近色相但亮度差要大以保证可读性；`primary` 要与 `bg` 和 `fg` 都有对比，用于超链接、导航激活态、输入聚焦；颜色可为 `htmltools::parseCssColors()` 能解析的任意格式。
7. 字体用 `base_font`、`heading_font`、`code_font` 三个参数，每个可接受单个字体、`font_collection()` 或字体名字符向量；用 `font_scale` 统一缩放所有字号。
8. 用 `font_google()` 下载并本地缓存 Google 字体（默认 `local = TRUE`，仅首次需联网），可指定可变字重 `wght = "200..900"` 或具体字重 `wght = c(300, 400, 700)`；建议用 `font_collection()` 提供回退字体以避免慢连接下的 FOIT（如 `font_collection(font_google("Lato", local = FALSE), "Helvetica Neue", "Arial", "sans-serif")`）；字体搭配可参考 fontpair.co。
9. 用 `font_link()` 通过 CSS Web 字体 URL 引入字体（如 `font_link("Crimson Pro", href = "https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@200..900")`）；用 `font_face()` 对本地字体文件做完整 `@font-face` 控制（指定 `family`、`style`、`weight`、`src`）。
10. 用 `bs_add_variables()` 添加或覆盖 Bootstrap Sass 变量默认值（如 `"body-bg"`、`"font-family-base"`、`"font-size-base"`、`"btn-padding-y"`）；用 `.where` 控制编译顺序：`"defaults"`（默认，带 `!default`，置于 Bootstrap 默认值之前）、`"declarations"`（引用其他 Bootstrap 变量如 `$secondary` 时用，置于默认值之后）、`"rules"`（置于所有规则之后，很少用）。
11. 需要引用 Bootstrap 变量时（如 `"progress-bar-bg" = "$secondary"`），不要直接传给 `bs_theme()`（此时 `$secondary` 尚未定义），改用 `bs_add_variables(..., .where = "declarations")`。
12. 用 `bs_add_rules()` 添加可引用 Bootstrap 变量与 mixin 的自定义 Sass/CSS 规则（可用 `lighten()`、`darken()`、`mix()`、`rgba()`、`color-contrast()` 等函数，以及 `@include media-breakpoint-up()`、`@include box-shadow()`、`@include border-radius()` 等 mixin）；也可从外部文件引入：`bs_add_rules(sass::sass_file("www/custom.scss"))`。
13. 用 `bs_add_functions()` 和 `bs_add_mixins()` 向主题包添加自定义 Sass 函数或 mixin，再在 `bs_add_rules()` 中调用。
14. 用 `bs_bundle()` 把 `sass::sass_bundle()` 对象追加到主题，用于打包可复用的主题扩展（如 `sass::sass_layer(defaults = ..., rules = ...)`）。
15. 通过 `bs_theme(...)` 或 `bs_add_variables()` 传入任意 Bootstrap 5 Sass 变量（变量名见 https://rstudio.github.io/bslib/articles/bs5-variables/），常用如 `"border-radius"`、`"card-border-radius"`、`"card-bg"`、`"navbar-bg"`、`"link-color"`、`"font-size-base"`、`"spacer"`、`"btn-padding-y"`、`"btn-padding-x"`、`"input-border-color"`；值可为引用变量、函数与运算的 Sass 表达式。
16. 暗色模式与颜色模式：参考 references/dark-mode.md，使用 Bootstrap 5.3 的客户端颜色模式系统（`data-bs-theme` 属性）、`input_dark_mode()` 与 `toggle_dark_mode()` 让用户切换、用 `session$setCurrentTheme()` 做服务端主题切换，并编写跨明暗模式可用的自定义 Sass。
17. 让 R 图表匹配主题：`bs_theme()` 只影响 CSS，服务端渲染为图片的图表不会自动匹配，需在 `shinyApp()` 之前调用 `library(thematic); thematic_shiny(font = "auto")`（支持 base R、ggplot2、lattice，`font = "auto"` 也会匹配 `bs_theme()` 的字体）；可再用 `theme_set(theme_minimal())` 统一全局 ggplot2 主题。
18. 仪表盘背景样式：给 `page_sidebar()` 加 `class = "bslib-page-dashboard"` 让主内容区呈浅灰背景、卡片更突出；对 `page_navbar()` 则把该类加到单个 `nav_panel()` 容器上（而非 `page_navbar()` 本身），只让仪表盘类页面获得灰底。
19. 交互式主题工具：用 `bslib::bs_theme_preview()` 预览主题（默认含 theming UI，`with_themer = TRUE`）；用 `run_with_themer(shinyApp(ui, server))` 或 `run_with_themer("path/to/app")` 带主题编辑器运行已有应用；在 server 函数中调用 `bs_themer()`（开发期加、生产环境移除）。三者都会把生成的 `bs_theme()` 代码打印到 R 控制台便于复制。
20. 主题检查：用 `bs_get_variables(bs_theme(), varnames = vars)` 获取计算后的 Sass 变量值；用 `bs_get_contrast(bs_theme(), c("primary", "dark", "light"))` 检查对比度，目标为 WCAG AA（普通文本 4.5:1，大文本 3:1）。
21. 最佳实践：优先用 `bs_theme()` 而非自定义 CSS（变量会自动级联到所有相关组件）；用 `bs_theme(version = 5)` 固定 Bootstrap 版本防止默认值变化导致破坏；用 `font_collection()` 提供回退字体避免 FOIT；跨组件测试（输入、按钮、卡片、导航、图表、表格、模态框、toast、移动端）；用 `bs_get_contrast()` 与浏览器开发者工具检查可访问性；一次性样式用 CSS 工具类而非自定义 CSS；把复杂主题整理到单独的 `theme.R`（如定义 `app_theme()` 函数组合 `bs_theme()`、`bs_add_rules(sass::sass_file("www/custom.scss"))` 等）。

适用边界 · 注意事项

• 交互式主题工具（`bs_theme_preview()`、`run_with_themer()`、`bs_themer()`）仅支持 Bootstrap 5+、Shiny 应用与 `runtime: shiny` 的 R Markdown，且不影响未使用 `bs_dependency_defer()` 的第三方组件。
• `bs_theme()` 只影响 CSS，不会自动让服务端渲染为图片的 R 图表匹配主题，需额外使用 thematic 包。
• `_brand.yml` 自动发现需要安装 `brand.yml` R 包。