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>
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

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

  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}
Copy to Clipboard Toggle word wrap

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;
    }
    Copy to Clipboard Toggle word wrap
  3. 编辑 它们/mytheme/login/theme.properties 并添加:

    styles=css/styles.css
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap
    注意

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

3.4.3. 将脚本添加到主题

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

流程

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

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

    alert('Hello');
    Copy to Clipboard Toggle word wrap

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

    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;
}
Copy to Clipboard Toggle word wrap

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

<img src="${url.resourcesPath}/img/image.jpg">
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

在使用消息值时,{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
    Copy to Clipboard Toggle word wrap

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

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

    locales=en,no
    Copy to Clipboard Toggle word wrap
  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
    Copy to Clipboard Toggle word wrap

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

    # encoding: UTF-8
    usernameOrEmail=....
    Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

所有图标都位于 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>
    ...
    Copy to Clipboard Toggle word wrap
  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>
Copy to Clipboard Toggle word wrap
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat