3.4. 创建主题


主题包括:

除非计划替换每个页面,否则您应该扩展另一个主题。您最有可能想扩展 Red Hat Single Sign-On 主题,但如果您对页面的外观有很大更改,您还可能考虑对基础进行扩展。其基础主题主要由 HTML 模板和消息捆绑包组成,而 Red Hat Single Sign-On theme 主要包含镜像和样式表。

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

在创建主题时,最好禁用缓存,因为这样可以直接从 themes 目录中编辑主题资源,而无需重启 Red Hat Single Sign-On。

流程

  1. 编辑 standalone.xml
  2. 对于 主题,将 staticMaxAge 设置为 -1,将 cacheTemplatescacheThemes 设置为 false

    <theme>
        <staticMaxAge>-1</staticMaxAge>
        <cacheThemes>false</cacheThemes>
        <cacheTemplates>false</cacheTemplates>
        ...
    </theme>
  3. 主题 目录中创建一个目录。

    目录的名称成为主题的名称。例如,要创建一个名为 mytheme 的主题,请创建目录 themes/mytheme

  4. 在me 目录中,为您要提供的每种类型创建一个目录。

    例如,要将登录类型添加到 mytheme theme 中,请创建目录 themes/mytheme/login

  5. 对于每个类型,创建一个文件 theme.properties,允许为主题设置一些配置。

    例如,要配置主题 themes/mytheme/login 以扩展基础主题并导入一些常见资源,请使用以下内容创建文件 themes/mytheme/login/theme.properties

    parent=base
    import=common/keycloak

    您现在已创建了支持登录类型的主题。

  6. 登录到 Admin Console 以签出您的新主题
  7. 选择您的域
  8. 从菜单中点 Realm Settings
  9. Themes 选项卡。
  10. 对于 Login Theme,选择 mytheme 并点 Save
  11. 打开域的登录页面。

    您可以通过应用程序登录或打开帐户管理控制台(/realms/{realm name}/account)来执行此操作。

  12. 要查看更改父主题的效果,请在me .properties 中设置 parent=keycloak 并刷新登录页面。
注意

确保在生产环境中重新启用缓存,因为它会对性能有严重影响。

3.4.1. me 属性

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

  • 父项 - 要扩展的主题
  • import - 从另一主题导入资源
  • 样式 - 空格分隔的样式列表包括
  • locales - 以逗号分隔的支持区域列表

有一个属性列表可用于更改用于某些元素类型的 cs 类。如需这些属性的列表,请查看对应类型 keycloak theme 中的 theme.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}

3.4.2. 将风格表添加到主题

您可以在主题中添加一个或多个样式表。

流程

  1. 在 < THEME TYPE>/resources/css 目录中创建一个文件。
  2. 将此文件添加到 theme.properties 中的 styles 属性中。

    例如,要将 风格.cs 添加到 mytheme 中,请使用以下内容创建 themes/mytheme/login/resources/css/styles.css

    .login-pf body {
        background: DimGrey none;
    }
  3. 编辑 它们/mytheme/login/theme.properties 并添加:

    styles=css/styles.css
  4. 要查看更改,请打开您的域的登录页面。

    您将注意到应用的唯一样式是来自您的自定义风格表。

  5. 为了包括来自父主题的样式,请从该主题加载 样式。编辑 themes/mytheme/login/theme.properties 并更改 样式 以:

    styles=web_modules/@fontawesome/fontawesome-free/css/icons/all.css web_modules/@patternfly/react-core/dist/styles/base.css web_modules/@patternfly/react-core/dist/styles/app.css node_modules/patternfly/dist/css/patternfly.min.css node_modules/patternfly/dist/css/patternfly-additions.min.css css/login.css css/styles.css
    注意

    要从父风格表中覆盖样式,请确保您的风格表已列出最后。

3.4.3. 将脚本添加到主题

您可以将一个或多个脚本添加到主题。

流程

  1. 在 < THEME TYPE>/resources/js 目录中创建一个文件。
  2. 将此文件添加到 theme.properties 中的 scripts 属性中。

    例如,要将 script.js 添加到 mytheme 中,请使用以下内容创建 themes/mytheme/login/resources/js/script.js

    alert('Hello');

    然后编辑它们 /mytheme/login/theme.properties 并添加:

    scripts=js/script.js

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;
}

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

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

3.4.5. 消息

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

例如,在登录表单上,使用 Your Username for mytheme create file themes/mytheme/login/messages/messages_en.properties 替换为以下内容:

usernameOrEmail=Your Username

在使用消息值时,{0}{1} 等消息值会被替换为参数。例如,{0} 中的 {0} 被替换为该域的名称。

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

3.4.6. 在域中添加语言

先决条件

流程

  1. 在主题的目录中创建文件 <THEME TYPE>/messages/messages_<LOCALE>.properties
  2. 将此文件添加到 < THEME TYPE>/theme.properties 中的 locales 属性。要使语言提供给用户 登录帐户和 电子邮件,主题必须支持该语言,因此您需要为这些主题类型添加您的语言。

    例如:要将 Norwegian 转换添加到 mytheme theme create file themes/mytheme/login/messages/messages_no.properties 中以下内容:

    usernameOrEmail=Brukernavn
    password=Passord

    如果省略了消息的翻译,将使用英语。

  3. 编辑 它们/mytheme/login/theme.properties 并添加:

    locales=en,no
  4. 帐户 添加相同的 电子邮件 类型。要执行此操作,请创建它们 /mytheme/account/messages/messages_no.propertiesthemes/mytheme/email/messages_no.properties。这些文件为空将导致使用英语消息。
  5. themes/mytheme/login/theme.properties 复制到 themes/mytheme/account/theme.properties 以及 themes/mytheme/email/theme.properties
  6. 为语言选择器添加翻译。这是通过向英语翻译添加消息来完成的。要执行此操作,请将以下内容添加到 themes/mytheme/account/messages/messages_en.propertiesthemes/mytheme/login/messages/messages_en.properties:

    locale_no=Norsk

    默认情况下,消息属性文件应使用 ISO-8859-1 进行编码。也可以使用特殊标头指定编码。例如,使用 UTF-8 编码:

    # encoding: UTF-8
    usernameOrEmail=....

3.4.7. 添加自定义身份提供程序图标

Red Hat Single Sign-On 支持为自定义身份提供程序添加图标,该图标显示在登录屏幕中。

流程

  1. 在 login theme.properties 文件中定义图标类(例如 themes/mytheme/login/theme.properties)使用键模式 kcLogoIdP-<alias& gt;。
  2. 对于带有别名 myProvider 的身份提供程序,您可以在自定义主题的 me.properties 文件中添加一行。例如:

    kcLogoIdP-myProvider = fa fa-lock

所有图标都位于 PatternFly4 的官方网站上。社交供应商的图标已在基本登录主题属性中定义(它们/密钥/登录/theme.properties),您可以激励自己。

3.4.8. 创建自定义 HTML 模板

Red Hat Single Sign-On 使用 Apache Freemarker 模板来生成 HTML。您可以通过创建 < THEME TYPE>/<TEMPLATE>.ftl 来覆盖您的主题中的单个模板。有关使用的模板列表,请查看 themes/base/<THEME TYPE>

流程

  1. 将模板从基础主题复制到您自己的主题。
  2. 应用您需要的修改。

    例如,要为 mytheme theme 创建自定义登录表单,请将 themes/base/login/login.ftl 复制到他们 es/mytheme/login,并在编辑器中打开它。

    第一行(<#import …​>)后,添加 <h1>HELLO WORLD!</h1& gt;,如下所示:

    <#import "template.ftl" as layout>
    <h1>HELLO WORLD!</h1>
    ...
  3. 备份修改后的模板。当升级到新版本的 Red Hat Single Sign-On 时,您可能需要更新自定义模板,以对原始模板应用更改(如果适用)。

3.4.9. 电子邮件

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

要查看所有可用电子邮件,请查看 主题/基础/电子邮件/messages/messages_en.properties

例如,要更改 mytheme 的密码恢复电子邮件,请创建主题主题创建 主题/mytheme/email/messages/messages_en.properties 以及以下内容:

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

学习

尝试、购买和销售

社区

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

关于红帽文档

Legal Notice

Theme

© 2026 Red Hat
返回顶部