# @govuk-one-login/frontend-ui 中文文档

规范地址：https://npmcn.com/package/%40govuk-one-login/frontend-ui/

版本：5\.3\.10
npm 元数据更新时间：2026-11-06T15:38:51.068Z
中文译文更新时间：2026-11-17T05:14:47.174Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40govuk-one-login/frontend-ui
原文对照：https://npmcn.com/package/%40govuk-one-login/frontend-ui/?lang=original
项目主页：https://github.com/govuk-one-login/govuk-one-login-frontend#readme
源码仓库：https://github.com/govuk-one-login/govuk-one-login-frontend

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：329 kB，146 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 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
- 首次发布：2025-01-16T14:34:33.717Z
- 最新版本发布：2026-11-06T15:38:50.706Z
- 近 30 天下载量：6221（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 27 个）

## 中文简介

[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=govuk-one-login_frontend-ui&metric=coverage)](https://sonarcloud.io/summary/overall?id=govuk-one-login_frontend-ui)

## 安装

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

也可以使用：`pnpm add @govuk-one-login/frontend-ui`、`yarn add @govuk-one-login/frontend-ui`、`bun add @govuk-one-login/frontend-ui`

## README

[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=govuk-one-login_frontend-ui&metric=coverage)](https://sonarcloud.io/summary/overall?id=govuk-one-login_frontend-ui)

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

## 前端 UI 组件集成指南

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

### 1\. 安装

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

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

### 2\. 配置视图路径

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

```javascript
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` 文件导入并设置以下内容,以使用语言切换、相位标等.

爪哇语:

```javascript
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");
```

键入符 :

```typescript
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 设置不同):

```javascript
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 组件:

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

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

```html
{% 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:

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

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

### 仅限身份团队

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

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

```html
{% 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`在您的公共文件夹中。 然后将脚本标签添加到任何您使用的页面中 .

```html
  <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 组件整合指南),那么就可以使用进度按钮在模板中添加如下.

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

## 常见问题

### 如何安装 @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 和提交记录判断。

