bootstrap5-ui

Bootstrap 5 UI

使用 Bootstrap 5.3、HTML 和 ASP.NET Core Razor Pages/Views 构建响应式、易访问 Web UI 的生产实践。目标版本为 Bootstrap 5.3.x（当前 CDN：5.3.8）。Bootstrap 5 已完全移除对 jQuery 的依赖。

在 ASP.NET Core 中设置

CDN（快速开始）

在 _Layout.cshtml 或 _Host.cshtml 中：

<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css"
      rel="stylesheet"
      integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB"
      crossorigin="anonymous">


<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js"
        integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI"
        crossorigin="anonymous"></script>

LibMan（生产环境推荐）

// libman.json
{
  "version": "1.0",
  "defaultProvider": "jsdelivr",
  "libraries": [
    {
      "library": "[email protected]",
      "destination": "wwwroot/lib/bootstrap/"
    }
  ]
}

在布局中引用本地文件：

<link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>

必需的全局设置

始终在 <head> 中包含：

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

网格系统

Bootstrap 使用包含 12 列的 Flexbox 网格，并支持 6 个响应式断点：

断点	前缀	最小宽度
超小	.col-	<576px
小	.col-sm-	>=576px
中	.col-md-	>=768px
大	.col-lg-	>=992px
超大	.col-xl-	>=1200px
XXL	.col-xxl-	>=1400px

核心模式

<div class="container">
  <div class="row">
    <div class="col-md-8">Main content</div>
    <div class="col-md-4">Sidebar</div>
  </div>
</div>

关键规则

• 始终将列放在 .container（或用于全宽布局的 .container-fluid）内的 .row 中
• 列必须是行的直接子元素
• 使用 .g-* 类设置间距（.g-0 移除间距，.gx-* 设置水平间距，.gy-* 设置垂直间距）
• 在行上使用 .row-cols-* 类统一列数：<div class="row row-cols-1 row-cols-md-3 g-4">
• 混合使用断点：<div class="col-6 col-md-4 col-lg-3"> — 在 xs 下每行 2 列，在 md 下每行 3 列，在 lg 下每行 4 列

容器类型

• .container — 响应式固定宽度
• .container-fluid — 始终全宽
• .container-{breakpoint} — 在断点前为流式宽度，达到断点后为固定宽度

间距工具类

格式：{property}{sides}-{breakpoint}-{size}

属性： m（外边距）、p（内边距） 方向： t 上、b 下、s 起始方向（左）、e 结束方向（右）、x 水平、y 垂直、留空 = 全部 尺寸： 0=0、1=0.25rem、2=0.5rem、3=1rem、4=1.5rem、5=3rem、auto

<div class="mt-3 mb-4 px-2">Spaced element</div>
<div class="mx-auto" style="width: 200px;">Centered block</div>
<div class="py-md-5">Padding only on md+</div>

颜色模式（深色/浅色）

Bootstrap 5.3 支持使用 data-bs-theme 属性设置深色模式：

<html lang="en" data-bs-theme="dark">


<div class="card" data-bs-theme="dark">...</div>
<nav class="navbar bg-dark" data-bs-theme="dark">...</nav>

使用能适配颜色模式的语义颜色类：

• bg-body、bg-body-secondary、bg-body-tertiary — 随主题适配
• text-body、text-body-secondary、text-body-emphasis — 随主题适配
• border-body — 随主题适配

避免使用硬编码颜色。 对于能够适配主题的背景，请使用 bg-body-tertiary，而不是 bg-light。

常见组件模式

导航栏

<nav class="navbar navbar-expand-lg bg-body-tertiary">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Brand</a>
    <button class="navbar-toggler" type="button"
            data-bs-toggle="collapse" data-bs-target="#mainNav"
            aria-controls="mainNav" aria-expanded="false"
            aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="mainNav">
      <ul class="navbar-nav me-auto mb-2 mb-lg-0">
        <li class="nav-item">
          <a class="nav-link active" aria-current="page" href="#">Home</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">About</a>
        </li>
      </ul>
    </div>
  </div>
</nav>

网格卡片

<div class="row row-cols-1 row-cols-md-2 row-cols-lg-3 g-4">
  <div class="col">
    <div class="card h-100">
      <img src="..." class="card-img-top" alt="...">
      <div class="card-body">
        <h5 class="card-title">Title</h5>
        <p class="card-text">Description text.</p>
        <a href="#" class="btn btn-primary">Action</a>
      </div>
    </div>
  </div>
  
</div>

表单

<form method="post">
  <div class="mb-3">
    <label for="email" class="form-label">Email</label>
    <input type="email" class="form-control" id="email">
  </div>
  <div class="mb-3">
    <label for="password" class="form-label">Password</label>
    <input type="password" class="form-control" id="password">
  </div>
  <div class="mb-3 form-check">
    <input type="checkbox" class="form-check-input" id="remember">
    <label class="form-check-label" for="remember">Remember me</label>
  </div>
  <button type="submit" class="btn btn-primary">Sign in</button>
</form>

浮动标签

<div class="form-floating mb-3">
  <input type="email" class="form-control" id="floatEmail" placeholder="[email protected]">
  <label for="floatEmail">Email address</label>
</div>

响应式表格

<div class="table-responsive">
  <table class="table table-striped table-hover">
    <thead class="table-dark">
      <tr><th>Name</th><th>Email</th><th>Actions</th></tr>
    </thead>
    <tbody>
      <tr><td>John</td><td>[email protected]</td><td><a class="btn btn-sm btn-outline-primary">Edit</a></td></tr>
    </tbody>
  </table>
</div>

Razor Pages 集成

有关 ASP.NET Core Razor Pages 集成模式的详细说明，包括标签帮助程序、验证、布局和分部视图，请参阅 references/razor-integration.md。

要点：

• 将 asp-for、asp-page、asp-action 标签帮助程序与 Bootstrap 类配合使用
• 将 asp-validation-for 与 .invalid-feedback / .is-invalid 类结合使用
• 通过 jQuery Validation Unobtrusive 或自定义 JS 添加 Bootstrap 验证类
• 在布局中使用 @section Scripts 添加页面专属脚本

组件参考

完整的组件模式（模态框、警告、Toast、手风琴、分页、面包屑、徽章、侧边栏、加载动画、进度条）请参阅 references/components.md。

工具类速查

显示

d-none、d-block、d-flex、d-grid、d-inline、d-inline-block 响应式：d-md-none、d-lg-flex

Flexbox

justify-content-{start|center|end|between|around|evenly} align-items-{start|center|end|stretch} flex-{row|column}、flex-wrap、flex-grow-1

文本

text-{start|center|end}、text-{lowercase|uppercase|capitalize} fw-{bold|semibold|normal|light}、fs-{1-6} text-truncate、text-nowrap、text-break

颜色

text-{primary|secondary|success|danger|warning|info|light|dark} bg-{primary|secondary|success|danger|warning|info|light|dark} text-bg-{color} — 同时设置相匹配的文本和背景颜色

边框与阴影

border、border-{top|bottom|start|end}、border-{color}、border-{1-5} rounded、rounded-{0-5|circle|pill} shadow、shadow-sm、shadow-lg、shadow-none

尺寸

w-{25|50|75|100|auto}、h-{25|50|75|100|auto} mw-100、mh-100、vw-100、vh-100 min-vw-100、min-vh-100

位置

position-{static|relative|absolute|fixed|sticky} top-{0|50|100}、start-{0|50|100}、translate-middle

无障碍要求

• 图标按钮和切换按钮如果仅包含图标，务必添加 aria-label
• 在当前导航链接上使用 aria-current="page"
• 在折叠或下拉菜单触发器上使用 aria-expanded
• 为图片提供 alt 文本；对于仅供屏幕阅读器使用的文本，请使用 .visually-hidden
• 确保颜色对比度符合 WCAG 2.1 AA 标准（文本为 4.5:1，大号文本为 3:1）
• 使用语义化 HTML：<nav>、<main>、<header>、<footer>、<section>、<article>
• 绝不要移除 :focus 样式；自定义焦点样式时，请使用 Bootstrap 的 .focus-ring 工具类

反模式

• 在没有父级 .row 的情况下使用 col-*——会破坏网格对齐
• 嵌套容器——只能嵌套行，不能在容器内嵌套容器
• 使用 <br> 和内联样式来控制间距——请使用间距工具类（mt-3、mb-4）
• 将 bg-light/bg-dark 写死——使用 bg-body-tertiary 来设置适配主题的背景
• 忘记添加 navbar-expand-{breakpoint}——导航栏将无法响应式折叠
• 混用 Bootstrap 4 类（例如 ml-3、mr-3）——请使用 ms-3、me-3（start/end 逻辑属性）
• 表单中非提交按钮未指定 type="button"——会导致意外提交表单
• 使用没有 href 的 <a> 执行动作——动作请使用 <button>，导航请使用 <a>
• 表单输入框未使用 .form-label——会影响无障碍性
• 未将表格包裹在 .table-responsive 中——会导致表格在移动设备上发生水平溢出