企业官网建设流程全解析

• 教育
• 后端
• 前端

通知徽章（Notification Badges）是 Moodle 中用于在按钮、表格行、菜单项等界面元素旁展示"待评分数量""未读消息数"等简明状态信息的 UI 组件。本文以 componentlibrary 组件文档 为骨架，结合 core_renderer.php 与 badge 枚举 的源码实现，完整讲解徽章的使用方法、六种内置样式、PHP 渲染调用方式，以及如何在 Behat 测试与屏幕阅读器中正确处理徽章文本。

什么是通知徽章

通知徽章（Notification badge）是一种小巧的胶囊状（pill）状态指示器，用于向用户简洁地展示信息或状态。它的典型使用场景包括：

• 在"评分（Grade）"按钮旁显示"有 N 份作业待评分"；
• 在导航菜单或表格行中标记存在新的、需要用户关注的信息；
• 在列表项右侧显示数量统计，让用户一眼感知需要处理的条目数。

与完整的警告框（alert）不同，通知徽章只承担"数量/状态标记"这一单一职责，通常以1、(2)之类的短文本或短标签形式出现，并内嵌在按钮、链接、列表项等其他组件中。

最简 HTML 用法

原文档给出了一个内嵌在按钮中的经典示例：徽章本身是一个<span>元素，通过 Bootstrap 的badge、rounded-pill、text-bg-*系列类名完成外观渲染。

<button class="btn btn-outline-secondary"> Grade <span class="ms-1 badge rounded-pill text-bg-primary" title="Needs grading"> <span class="visually-hidden"> (</span>1<span class="visually-hidden">)</span> </span> </button>

结构拆解：

在 PHP 中使用notice_badge()方法

虽然可以直接手写 HTML，但 Moodle 推荐通过core_renderer提供的notice_badge方法生成徽章，这样既能保证输出风格统一，也能自动处理无障碍相关的括号逻辑。

方法签名与参数

从源码 core_renderer.php 可以看到方法定义：

public function notice_badge( string $contents, badge $badgestyle = badge::PRIMARY, string $title = '', ): string

三个参数的含义如下：

• contents（string，必填）：徽章内显示的内容（通常是数字或短文本）。
• badgestyle（core\output\local\properties\badge，可选）：徽章样式枚举，默认为badge::PRIMARY（primary 样式）。
• title（string，可选）：徽章的title悬停提示属性，便于辅助理解徽章含义。

需要特别说明的是，contents为空字符串时方法会直接返回空串（源码第 3029-3031 行），因此调用方可以放心地传入($needgrading > 0) ? $needgrading : ''这类表达式，无需自行判断——没有待办数量时徽章自然不渲染，不会留下空壳元素。

完整 PHP 渲染示例

原文档提供了一个结合依赖注入（Dependency Injection）与action_link的完整示例：

// 获取核心渲染器（通过依赖注入容器）。 $renderer = \core\di::get(\core\output\renderer_helper::class)->get_core_renderer(); // 将徽章存入变量。 $badge = $renderer->notice_badge( contents: ($needgrading > 0) ? $needgrading : '', title: get_string('numberofsubmissionsneedgrading', 'assign'), badgestyle: \core\output\local\properties\badge::SECONDARY, ); // 把徽章拼进一个链接里，并渲染整个链接。 $content = new action_link( url: new url('/some/index.php'), text: get_string('gradeverb') . $badge, ); echo $renderer->render($content);

示例中的关键点：

1. 获取渲染器：\core\di::get(\core\output\renderer_helper::class)->get_core_renderer()是 Moodle 5.0 起推荐的依赖注入写法，取代了旧的全局$PAGE->get_renderer()方式。
2. 命名参数（named arguments）：contents:、title:、badgestyle:让调用意图一目了然。
3. 字符串拼接进链接：get_string('gradeverb') . $badge把徽章 HTML 追加在"Grade"文本之后，使徽章成为链接的一部分，可点击、可悬停。
4. 条件渲染：($needgrading > 0) ? $needgrading : ''配合方法内部的空值短路逻辑，实现了"有数据才显示"的优雅降级。

在真实模块中，mod/assign的课程格式总览便使用了numberofsubmissionsneedgrading语言字符串配合徽章展示待评分数量（见 assign/lang/en/assign.php、assign/classes/courseformat/overview.php），与本示例的调用模式一致。

六种内置徽章样式（badge 枚举）

徽章样式由枚举类\core\output\local\properties\badge统一管理。源码 local/properties/badge.php 定义了六个 case，并通过classes()方法映射为对应的 CSS 类：

由于badge是 PHP 8.1+ 的原生enum badge: string（backed enum），badgestyle参数既可以直接传入枚举 case（如badge::SECONDARY），枚举值本身也与 Bootstrap 的text-bg-*语义一一对应，从源码的match表达式可以看出映射关系是硬编码且完全确定的。

六种样式的 HTML 形态完全一致，仅text-bg-*类名不同：

<span class="ms-1 badge rounded-pill text-bg-primary" title="">…</span> <!-- Primary --> <span class="ms-1 badge rounded-pill text-bg-secondary" title="">…</span> <!-- Secondary --> <span class="ms-1 badge rounded-pill text-bg-success" title="">…</span> <!-- Success --> <span class="ms-1 badge rounded-pill text-bg-danger" title="">…</span> <!-- Danger --> <span class="ms-1 badge rounded-pill text-bg-warning" title="">…</span> <!-- Warning --> <span class="ms-1 badge rounded-pill text-bg-info" title="">…</span> <!-- Info -->

无障碍实现原理：括号如何被朗读

细心的读者会发现，示例 HTML 中出现了两处visually-hidden包裹的括号：

<span class="visually-hidden"> (</span>1<span class="visually-hidden">)</span>

这在视觉上毫无意义（visually-hidden使内容不可见），却有着明确的无障碍（accessibility）设计意图。源码 core_renderer.php 中可以看到：

// We want the badges to be read as content in parentesis. $contents = trim($this->visually_hidden_text(' (')) . $contents . trim($this->visually_hidden_text(')'));

也就是说，notice_badge()会自动为徽章内容包上一对仅供屏幕阅读器朗读的括号。这样，视觉障碍用户听到的徽章内容与上下文是分离的、可独立理解的——例如在"Grade"按钮内，屏幕阅读器会把"Grade"和"1"分别朗读，且"1"被括号包裹（读作 "1 (1)"），从而明确这是按钮内的一个独立数量标记，而不是与按钮文字混在一起的乱序文本。

补充说明：visually_hidden_text()本身也是core_renderer的公开方法（见 core_renderer.php），它生成一个带visually-hidden类的<span>，是 Moodle 推荐的屏幕阅读器专用文本输出方式。

在 Behat 中验证徽章

徽章文本的断言需要遵循与无障碍设计一致的思路。原文档特别强调：

不要将徽章文本与其父元素文本放在一起断言，因为 mustache 模板可能引入换行，导致组合文本匹配不稳定。应当单独测试徽章文本。

以"Grade"徽章为例，推荐的 Behat 写法是：

And I should see "Grade" in the "Assign with pending grades" "table_row" And I should see "(2)" in the "Assign with pending grades" "table_row"

两条断言的含义：

• 第一条验证行内存在 "Grade" 文本（父元素文字）；
• 第二条单独验证行内存在 "(2)" 文本——注意括号中的数字即徽章内容，屏幕阅读器和 Behat 都会把徽章读作括号包裹的文本，因此断言时要包含括号。

这种"父子分离"的断言策略，既与屏幕阅读器的朗读方式保持一致（徽章被读作括号内文本），又规避了 mustache 模板在不同场景下引入换行符导致的断言脆弱性，是测试徽章相关界面的最佳实践。

适用前提与注意事项

• 版本前提：notice_badge()与badge枚举为 Moodle 5.0 起新增的 API（版权注释与依赖注入示例均指向 5.0 时代），升级或移植到旧版本时需确认渲染器是否包含该方法。
• 命名参数：示例使用了 PHP 8.0+ 的命名参数语法，请确保运行环境满足 Moodle 对 PHP 版本的要求（Moodle 5.x 要求 PHP 8.1+，同时这也是原生枚举可用性的前提）。
• 空值短路：contents传入空字符串时徽章完全不输出，因此"无数据不显示"是方法的内置行为，无需在调用方重复判断。
• 样式选择：默认PRIMARY适合绝大多数场景；需要弱化视觉权重时可用SECONDARY；表示警告、错误、成功等语义状态时，分别对应WARNING、DANGER、SUCCESS，请结合界面语义选择，避免仅凭喜好配色。

通过以上 API 与实战要点，开发者即可在任意模块的渲染逻辑中快速产出风格统一、无障碍友好、且可被 Behat 稳定验证的通知徽章。

• 教育
• 后端
• 前端