@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'
}) }}