@govuk-one-login/frontend-ui

中文文档
5.3.10发布于 2026/11/06ISCTypeScriptESM + CJS构建来源已验证近 30 天下载 6221

Coverage

中文使用文档
文档目录12 节
  1. 前端 UI 组件集成指南
  2. 1. 安装
  3. 2. 配置视图路径
  4. 3. 配置 Nunjucks 以使用导出函数
  5. 4. 装入翻译和配置中间软件
  6. 5. 进口宏
  7. 6. 进口所有.css
  8. 7. 在模板中添加组件
  9. 仅限身份团队
  10. 8. 进口前端联合材料
  11. 在页面上加载已添加到基本文件
  12. 1. 进度按钮模板中的渲染组件并传递必要的数据

Coverage

@govuk-one-login/frontend-ui (英语)

前端 UI 组件集成指南

本指南概述了将前端 UI 组件整合到您使用 Nunjucks turlating 的 Node.js 应用程序的步骤 .

1. 安装

安装国家预防机制软件包:

npm install @govuk-one-login/frontend-ui

2. 配置视图路径

在应用程序的启动文件中添加组件路径到您的 Nunjuck 视图路径( 例如 ), app.js 或者说 index.js:

const path = require('path');

// ... other configurations ...

app.set(
 'view engine',
 configureNunjucks(app, [
    // ... other view paths ...
    path.resolve('node_modules/@govuk-one-login/frontend-ui')
  ]),
);

警告: 保证通往您的路径 node_modules 文件夹正确 .

3. 配置 Nunjucks 以使用导出函数

在你身边 config/nunjucks 文件导入并设置以下内容,以使用语言切换、相位标等.

爪哇语:

const frontendUi = require("@govuk-one-login/frontend-ui");

nunjucksEnv.addGlobal("addLanguageParam", frontendUi.addLanguageParam);
nunjucksEnv.addGlobal("contactUsUrl", frontendUi.contactUsUrl);
nunjucksEnv.addGlobal("MAY_2025_REBRAND_ENABLED", process.env.MAY_2025_REBRAND_ENABLED == "true");

键入符 :

import {contactUsUrl, addLanguageParam } from "@govuk-one-login/frontend-ui";
nunjucksEnv.addGlobal("addLanguageParam", addLanguageParam);
nunjucksEnv.addGlobal("contactUsUrl", contactUsUrl);
nunjucksEnv.addGlobal("MAY_2025_REBRAND_ENABLED", process.env.MAY_2025_REBRAND_ENABLED == "true");

为了使用 MAY_2025_REBRAND_ENABLED 您需要创建或添加变量 .env 存档于 MAY_2025_REBRAND_ENABLED=[真/假]

4. 装入翻译和配置中间软件

在你身边 app.js,在初始化 i18next 后导入必要的函数并加载翻译(身份小组可能需要使用绕行函数,因为其 i18n 设置不同):

const {
setBaseTranslations
 setFrontendUiTranslations,
 frontendUiMiddleware,
} = require('@govuk-one-login/frontend-ui');

// ... other configurations ...

i18next
  .use(Backend)
  .use(i18nextMiddleware.LanguageDetector)
  .init(
    {
      ...i18nextConfigurationOptions(
        path.join(__dirname, 'locales/{{lng}}/{{ns}}.json'),
      ),
    },
    (err) => {

      if (err) {
        console.error('i18next init failed:', err);
      }
    },
  );

// Apply the middleware
setBaseTranslations(i18next);
setFrontendUiTranslations(i18next); 
app.use(i18nextMiddleware.handle(i18next));
app.use(frontendUiMiddleware);

// For Identity teams a language setting bypass may be required, first import the bypass function and then configure router to use the new function at the top of your router.use functions

const {
 frontendUiMiddlewareIdentityBypass,
} = require('@govuk-one-login/frontend-ui');
....

router.use(frontendUiMiddlewareIdentityBypass);

5. 进口宏

将所需的组件宏导入您的 Nunjucks 模板 。 例如,要使用 Cookie Banner 组件:

{% from "frontend-ui/build/components/cookie-banner/macro.njk" import frontendUiCookieBanner %}

要替换您的碱性文件, 您需要更改视图文件上方的相应扩展名 :

{% extends "frontend-ui/build/components/bases/identity/identity-base-form.njk" %}

or 

{% extends "frontend-ui/build/components/bases/identity/identity-base-page.njk" %}

6. 进口所有.css

方法是将前端- ui all.css 直接导入到您已有的 Css 文件底部

@import "../../../node_modules/@govuk-one-login/frontend-ui/build/all";

7. 在模板中添加组件

将组件放入模板,传递任何需要的数据。 对于Cookie Banner:

{{ frontendUiCookieBanner({
  translations: translations.translate.cookieBanner 
}) }}

这种设置可以确保翻译正确加载,中间软件可以设置必要的本地变量,使组件正常运行.

仅限身份团队

身份小组还需要安装可选依赖 hmpo-components 和基准文件

要替换您的碱性文件, 您需要更改视图文件上方的相应扩展名 :

{% extends "frontend-ui/build/components/bases/identity/identity-base-form.njk" %}

or 

{% extends "frontend-ui/build/components/bases/identity/identity-base-page.njk" %}

8. 进口前端联合材料

如果您需要使用包含前端( e. in- browser) 代码的组件, 您还需要包含前端的javascript 捆绑, 如果您使用前端捆绑解决方案的话, 您需要导入其中, 或者复制并曝光 esm 版本( 复制并曝光) @govuk-one-login/frontend-ui/build/esm/frontend/index.js在您的公共文件夹中。 然后将脚本标签添加到任何您使用的页面中 .

  <script nonce='{{ cspNonce }}' defer type="module" src="/public/javascripts/frontend-ui.js"></script>
  <script nonce='{{ cspNonce }}' defer type="module">
    import { useSpinner } from "/public/javascripts/frontend-ui.js";
    useSpinner();
  </script>

升级到 V2

在页面上加载已添加到基本文件

当升级到主要版本2时,GA4的页面负载将在识别和核心底文件内,如果GA4OPL已经使用,这将是一个突破性的变化,并在页面上执行一些重复

执行指南 - 进度按钮

何时使用进度按钮

进度按钮已设计用于用户点击提交表单等使用情况下的执行,请求正在进行中.

目的是防止多次提交表格,并在页面装入时提供可视提示.

当用户点击按钮和看到结果之间出现2秒多而10秒多的延迟时,应当使用.

它最适合触发向外部API提交信息或进行简短后端进程的行动.

不使用进步按钮时

当一个用户需要采取进一步行动时,例如检查他们的电子邮件、打开另一个应用程序或检索安全代码时,就不应该使用这个软件.

在点击按钮到看到结果之间出现不到2秒的延迟时,不应使用进度按钮.

同样,当延迟超过10秒时不应使用按钮.

何时适用,何时不适用?

如何执行进度按钮 .

1. 进度按钮模板中的渲染组件并传递必要的数据

如果遵循了上述整合步骤(Frontend UI 组件整合指南),那么就可以使用进度按钮在模板中添加如下.

 {{ frontendUiProgressButton({
   translations: translations.translation.progressButton,
   href: "#",
   errorPage: '/404'
 }) }}

版本与发布记录

@govuk-one-login/frontend-ui 共发布 61 个版本,首次发布于 2025/01/16;过去 12 个月发布了 27 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.3.10latest2026/11/0610 天前
5.3.92026/11/0313 天前
5.3.82026/11/0214 天前
5.3.72026/11/0214 天前
5.3.62026/10/131 个月前
5.3.52026/09/281 个月前

关于 @govuk-one-login/frontend-ui 的常见问题

如何安装 @govuk-one-login/frontend-ui?

在项目目录运行 npm install @govuk-one-login/frontend-ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:express(^5.1.0 || >= 4.21.2)、nunjucks(^3.2.4)、govuk-frontend(^4.10.1 || ^5.0.0)、@govuk-one-login/frontend-logger(^0.0.2)、@govuk-one-login/frontend-analytics( ^3.0.1 || ^4.0.3)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@govuk-one-login/frontend-ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@govuk-one-login/frontend-ui 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@govuk-one-login/frontend-ui 可以商用吗?

@govuk-one-login/frontend-ui 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@govuk-one-login/frontend-ui 的下载量有多少?

根据 npm 官方下载统计,@govuk-one-login/frontend-ui 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,221 次,日均约 207 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@govuk-one-login/frontend-ui 还在维护吗?

最新版本 5.3.10 发布于 2026/11/06(10 天前);至今共发布 61 个版本,其中过去 12 个月发布了 27 个;首次发布于 2025/01/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。