3.4. 创建主题

主题包括：

HTML 模板(自由标记模板)
镜像
消息捆绑包
风格表
脚本
主题属性

除非计划替换每个页面，否则您应该扩展另一个主题。最有可能您要扩展某些现有主题。或者，如果您想提供自己的 admin 或帐户控制台实施，请考虑扩展 基础 主题。该 基础 主题由一个消息捆绑包组成，因此此类实施需要从头开始，包括实施主 index.ftl Freemarker 模板，但它可以使用消息捆绑包中的现有转换。

在扩展主题时，您可以覆盖单个资源(templates、样式表等)。如果您决定覆盖 HTML 模板，您可能需要在升级到新版本时更新自定义模板。

在创建主题时，最好禁用缓存，因为这可以直接从主题目录中编辑主题资源，而无需重启 Red Hat build of Keycloak。

流程

使用以下选项运行 Keycloak：

bin/kc.[sh|bat] start --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false

bin/kc.[sh|bat] start --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false

Copy to Clipboard

Toggle word wrap

在 themes 目录中创建目录。
目录的名称成为主题的名称。例如，要创建一个名为 mytheme 的主题，请创建目录 themes/mytheme。
在主题目录中，为您的主题将提供的每个类型创建一个目录。
例如，要将登录类型添加到 mytheme theme 中，请创建目录 themes/mytheme/login。
对于每个类型，创建一个 file theme.properties，它允许为主题设置一些配置。
例如，要将主题主题/mytheme/login 配置为扩展 基础 主题并导入一些通用资源，请使用以下内容创建文件 themes/mytheme/login /theme.properties ：
```
parent=base
import=common/keycloak
```
```
parent=base
import=common/keycloak
```
Copy to Clipboard Toggle word wrap
您现在已创建了支持登录类型的主题。
登录管理控制台以签出您的新主题
选择您的域
从菜单中选择 Realm Settings。
点 Themes 选项卡。
对于 Login Theme，请选择 mytheme，然后单击 Save。
打开域的登录页面。
您可以通过应用程序登录或打开帐户控制台(/realms/{realm-name}/account)来完成此操作。
要查看更改父主题的影响，请在me .properties 中设置 parent=keycloak 并刷新登录页面。

注意

务必在生产环境中重新启用缓存，因为它将对性能有严重影响。

注意

如果要手动删除主题缓存的内容，可以通过删除服务器分发的 data/tmp/kc-gzip-cache 目录来实现。如果您重新部署了自定义供应商或自定义主题，则在之前的服务器执行中不禁用主题缓存，则它对实例很有用。

3.4.1. 主题属性
复制链接

me 属性在主题目录中的 &lt ;THEME TYPE>/theme.properties 文件中设置。

parent - 涉及要扩展的主题
import - 从另一个主题导入资源
common - 覆盖通用资源路径。如果没有指定，默认值为 common/keycloak。这个值将用作 ${url.resourcesCommonPath} 的后缀值，它通常用于 freemarker 模板（前缀 ${url.resoucesCommonPath} 值是主题 root uri）。
样式 - 要包括的以空格分开的样式列表
locales - 以逗号分隔的支持的区域设置列表

有一些属性列表可用于更改用于特定元素类型的 cs 类。如需这些属性的列表，请查看 keycloak theme 对应的类型中的me.properties 文件(themes/keycloak/<THEME TYPE>/theme.properties)。

您还可以添加自己的自定义属性并从自定义模板中使用它们。

当这样做时，您可以使用以下格式替换系统属性或环境变量：

${some.system.property} - for system properties
${env.ENV_VAR }- 用于环境变量。

也可以在系统属性或环境变量中使用 ${foo:defaultValue} 找到时提供默认值。

注意

如果没有提供默认值，且没有对应的系统属性或环境变量，则不会替换任何内容，并且您最终使用模板中的格式。

下面是一个可能的例子：

javaVersion=${java.version}

unixHome=${env.HOME:Unix home not found}
windowsHome=${env.HOMEPATH:Windows home not found}

javaVersion=${java.version}

unixHome=${env.HOME:Unix home not found}
windowsHome=${env.HOMEPATH:Windows home not found}

Copy to Clipboard

Toggle word wrap

3.4.2. 向主题添加一个风格表
复制链接

您可以在主题中添加一个或多个风格表。

流程

在主题的 &lt ;THEME TYPE>/resources/css 目录中创建一个文件。
将此文件添加到 theme.properties 中的 styles 属性中。
例如，要将 styles.css 添加到 mytheme 中，请使用以下内容创建 themes/mytheme/login/resources/css/styles.css ：
```
.login-pf body {
    background: DimGrey none;
}
```
```
.login-pf body {
    background: DimGrey none;
}
```
Copy to Clipboard Toggle word wrap
编辑 themes/mytheme/login/theme.properties 并添加：
```
styles=css/styles.css
```
```
styles=css/styles.css
```
Copy to Clipboard Toggle word wrap
要查看更改，请打开您的域的登录页面。
您会注意到应用的唯一风格是来自您的自定义风格表。
要包含父主题的样式，请从该主题加载样式。编辑 themes/mytheme/login/theme.properties，并将 样式 更改为：
```
styles=css/login.css css/styles.css
```
```
styles=css/login.css css/styles.css
```
Copy to Clipboard Toggle word wrap
注意
要覆盖父风格表中的样式，请确保最后列出了您的风格表。

3.4.3. 在主题中添加脚本
复制链接

您可以在主题中添加一个或多个脚本。

流程

在主题的 &lt ;THEME TYPE>/resources/js 目录中创建一个文件。
将此文件添加到 theme.properties 中的 scripts 属性中。
例如，要将 脚本.js 添加到 mytheme 中，请使用以下内容创建 themes/mytheme/login/resources/js/script.js ：
```
alert('Hello');
```
```
alert('Hello');
```
Copy to Clipboard Toggle word wrap
然后编辑 themes/mytheme/login/theme.properties 并添加：
```
scripts=js/script.js
```
```
scripts=js/script.js
```
Copy to Clipboard Toggle word wrap

3.4.4. 将镜像添加到主题中
复制链接

要使镜像可用于主题，请将它们添加到主题的 &lt ;THEME TYPE>/resources/img 目录中。它们可以从样式表或直接在 HTML 模板中使用。

例如，将镜像添加到 mytheme 将镜像复制到 themes/mytheme/login/resources/img/image.jpg 中。

然后，您可以从自定义风格表中使用此镜像：

body {
    background-image: url('../img/image.jpg');
    background-size: cover;
}

body {
    background-image: url('../img/image.jpg');
    background-size: cover;
}

Copy to Clipboard

Toggle word wrap

或者直接在 HTML 模板中使用，请将以下内容添加到自定义 HTML 模板中：

<img src="${url.resourcesPath}/img/image.jpg" alt="My image description">

<img src="${url.resourcesPath}/img/image.jpg" alt="My image description">

Copy to Clipboard

Toggle word wrap

3.4.5. 在登录主题中添加自定义页脚
复制链接

要使用自定义页脚，请使用所需内容在自定义登录中创建一个 footer.ftl 文件。

自定义 footer.ftl 的示例可能类似如下：

<#macro content>
<#-- footer at the end of the login box -->
<div>
    <ul id="kc-login-footer-links">
        <li><a href="#home">Home</a></li>
        <li><a href="#about">About</a></li>
        <li><a href="#contact">Contact</a></li>
    </ul>
<div>
</#macro>

<#macro content>
<#-- footer at the end of the login box -->
<div>
    <ul id="kc-login-footer-links">
        <li><a href="#home">Home</a></li>
        <li><a href="#about">About</a></li>
        <li><a href="#contact">Contact</a></li>
    </ul>
<div>
</#macro>

Copy to Clipboard

Toggle word wrap

3.4.6. 将镜像添加到电子邮件主题
复制链接

要使镜像可用于主题，请将它们添加到主题的 &lt ;THEME TYPE>/email/resources/img 目录中。它们可以从直接在 HTML 模板中使用。

例如，将镜像添加到 mytheme 将镜像复制到 themes/mytheme/email/resources/img/logo.jpg。

要直接在 HTML 模板中使用，请将以下内容添加到自定义 HTML 模板中：

<img src="${url.resourcesUrl}/img/image.jpg" alt="My image description">

<img src="${url.resourcesUrl}/img/image.jpg" alt="My image description">

Copy to Clipboard

Toggle word wrap

3.4.7. messages
复制链接

模板中的文本是从消息捆绑包加载的。扩展另一个主题的主题将继承父消息捆绑包中的所有消息，您可以通过将 < THEME TYPE>/messages/messages_en.properties 添加到您的主题来覆盖单个消息。

例如，要将登录表单上的 Username 替换为 mytheme 的 Your Username，请创建文件 themes/mytheme/login/messages/messages_en.properties 替换为以下内容：

usernameOrEmail=Your Username

usernameOrEmail=Your Username

Copy to Clipboard

Toggle word wrap

在使用消息时，在消息值（如 {0} 和能）中被替换为参数。例如，登录 {0} 到 {0} 被替换为域的名称。

这些消息捆绑包的文本可以被特定于域的值覆盖。特定于域的值可以通过 UI 和 API 进行管理。

3.4.8. 在域中添加语言
复制链接

先决条件

要为域启用国际化，请参阅服务器管理指南。

流程

在主题的目录中创建文件 <THEME TYPE>/messages/messages_<LOCALE>.properties。
将此文件添加到 < THEME TYPE>/theme.properties 中的 locales 属性中。要使用户可用的语言是域 登录、帐户和 电子邮件，主题必须支持语言，因此您需要为主题类型添加您的语言。
例如，要将 Norwegian 翻译添加到 mytheme theme 中，请使用以下内容创建文件 themes/mytheme/login/messages/messages_no.properties ：
```
usernameOrEmail=Brukernavn
password=Passord
```
```
usernameOrEmail=Brukernavn
password=Passord
```
Copy to Clipboard Toggle word wrap
如果您省略了消息的翻译，将使用英语。
编辑 themes/mytheme/login/theme.properties 并添加：
```
locales=en,no
```
```
locales=en,no
```
Copy to Clipboard Toggle word wrap
为 帐户 添加相同的内容并通过 电子邮件 主题类型。为此，可创建 themes/mytheme/account/messages/messages_no.properties 和 themes/mytheme/email/messages/messages_no.properties。将这些文件留空将导致使用英语消息。
将 themes/mytheme/login/theme.properties 复制到 themes/mytheme/account/theme.properties 和 themes/mytheme/email/theme.properties。
为语言选择器添加翻译。这可以通过在英语翻译中添加消息来完成。要做到这一点，将以下内容添加到 themes/mytheme/account/messages/messages_en.properties 和 themes/mytheme/login/messages/messages_en.properties ：
```
locale_no=Norsk
```
```
locale_no=Norsk
```
Copy to Clipboard Toggle word wrap

默认情况下，消息属性文件应使用 UTF-8 进行编码。如果 Keycloak 无法读取内容为 UTF-8，则 Keycloak 会返回 ISO-8859-1 处理。Unicode 字符可以进行转义，如 Java 文档中用于 PropertyResourceBundle 所述。以前的 Keycloak 版本支持在第一行中指定带有注释的编码，如 # encoding: UTF-8，它不再被支持。

3.4.9. 添加自定义身份提供程序图标
复制链接

红帽构建的 Keycloak 支持为自定义身份提供程序添加图标，这些图标显示在登录屏幕上。

流程

在登录 theme.properties 文件中定义图标类（例如： themes/mytheme/login/theme.properties），其键模式为 kcLogoIdP-<alias>。
对于带有别名 myProvider 的身份提供程序，您可以在自定义 主题的me.properties 文件中添加一行。例如：
```
kcLogoIdP-myProvider = fa fa-lock
```
```
kcLogoIdP-myProvider = fa fa-lock
```
Copy to Clipboard Toggle word wrap

所有图标都位于 PatternFly4 的官方网站上。社交提供程序的图标已在 基本 登录属性(themes/keycloak/login/theme.properties)中定义，您可以在其中自己激发。

3.4.10. 创建自定义 HTML 模板
复制链接

Red Hat build of Keycloak 使用 Apache Freemarker 模板来生成 HTML 和呈现页面。

虽然可以创建自定义模板来完全改变页面的呈现方式，但建议尽可能利用内置模板。原因包括：

在升级过程中，您可能被强制更新自定义模板，以便从更新的版本获取最新的更新
通过为主题配置 CSS 风格，您可以调整 UI 以匹配 UI 设计标准和准则。
用户配置文件允许您支持自定义用户属性并配置它们的呈现方式。

在大多数情况下，您不需要更改模板来根据您的需求调整红帽 Keycloak 的构建，但您可以通过创建 < THEME TYPE>/<TEMPLATE>.ftl 来覆盖您自己的主题中的各个 模板。管理员和帐户控制台使用单个模板 index.ftl 渲染应用程序。

对于其他主题类型中的模板列表，请查看 $KEYCLOAK _HOME/lib/lib/main/org.keycloak.keycloak-themes-<VERSION>.jar 中的me/base/<THEME_TYPE &gt; 目录。

流程

将模板从基础主题复制到您自己的主题。
应用您需要的修改。
例如，要为 mytheme 主题创建一个自定义登录表单，请将 themes/base/login/login.ftl 复制到 themes/mytheme/login，并在编辑器中打开它。
第一行(<#import …>)后，添加 & lt;h1>HELLO WORLD!</h1& gt;，如下所示：
```
<#import "template.ftl" as layout>
<h1>HELLO WORLD!</h1>
...
```
```
<#import "template.ftl" as layout>
<h1>HELLO WORLD!</h1>
...
```
Copy to Clipboard Toggle word wrap
备份修改后的模板。当升级到一个新版本的 Red Hat build of Keycloak 时，您可能需要更新自定义模板，以便在适用的情况下对原始模板应用更改。

3.4.11. 电子邮件
复制链接

要编辑电子邮件的主题和内容，如密码恢复电子邮件，请在主题 的电子邮件 类型中添加一个消息捆绑包。每个电子邮件都有三个消息。一个用于主题，一个用于纯文本正文，另一个用于 html 正文。

要查看所有可用的电子邮件，请查看 themes/base/email/messages/messages_en.properties。

例如，要更改 mytheme 的密码恢复电子邮件，使用以下内容创建 themes/mytheme/email/messages/messages_en.properties ：

passwordResetSubject=My password recovery
passwordResetBody=Reset password link: {0}
passwordResetBodyHtml=<a href="{0}">Reset password</a>

passwordResetSubject=My password recovery
passwordResetBody=Reset password link: {0}
passwordResetBodyHtml=<a href="{0}">Reset password</a>

Copy to Clipboard

Toggle word wrap

3.4. 创建主题

3.4.1. 主题属性
复制链接

3.4.2. 向主题添加一个风格表
复制链接

3.4.3. 在主题中添加脚本
复制链接

3.4.4. 将镜像添加到主题中
复制链接

3.4.5. 在登录主题中添加自定义页脚
复制链接

3.4.6. 将镜像添加到电子邮件主题
复制链接

3.4.7. messages
复制链接

3.4.8. 在域中添加语言
复制链接

3.4.9. 添加自定义身份提供程序图标
复制链接

3.4.10. 创建自定义 HTML 模板
复制链接

3.4.11. 电子邮件
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

3.4. 创建主题

3.4.1. 主题属性复制链接链接已复制到粘贴板!

3.4.2. 向主题添加一个风格表复制链接链接已复制到粘贴板!

3.4.3. 在主题中添加脚本复制链接链接已复制到粘贴板!

3.4.4. 将镜像添加到主题中复制链接链接已复制到粘贴板!

3.4.5. 在登录主题中添加自定义页脚复制链接链接已复制到粘贴板!

3.4.6. 将镜像添加到电子邮件主题复制链接链接已复制到粘贴板!

3.4.7. messages复制链接链接已复制到粘贴板!

3.4.8. 在域中添加语言复制链接链接已复制到粘贴板!

3.4.9. 添加自定义身份提供程序图标复制链接链接已复制到粘贴板!

3.4.10. 创建自定义 HTML 模板复制链接链接已复制到粘贴板!

3.4.11. 电子邮件复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

3.4.1. 主题属性
复制链接

3.4.2. 向主题添加一个风格表
复制链接

3.4.3. 在主题中添加脚本
复制链接

3.4.4. 将镜像添加到主题中
复制链接

3.4.5. 在登录主题中添加自定义页脚
复制链接

3.4.6. 将镜像添加到电子邮件主题
复制链接

3.4.7. messages
复制链接

3.4.8. 在域中添加语言
复制链接

3.4.9. 添加自定义身份提供程序图标
复制链接

3.4.10. 创建自定义 HTML 模板
复制链接

3.4.11. 电子邮件
复制链接