主题化

简介

Gradio 具有内置的主题引擎，可让您自定义应用程序的外观和风格。您可以从各种主题中选择，也可以创建自己的主题。为此，请将 theme= 关键字参数传递给 Blocks 或 Interface 构造函数。例如：

with gr.Blocks(theme=gr.themes.Soft()) as demo:
    ...

Gradio 附带了一组预构建的主题，您可以从 gr.themes.* 加载它们。这些主题包括：

• — gr.themes.Base()
• — gr.themes.Default()
• — gr.themes.Glass()
• — gr.themes.Monochrome()
• — gr.themes.Soft()

每个主题都为数百个 CSS 变量设置了值。您可以将预构建的主题作为自定义主题的起点，也可以从头开始创建自己的主题。让我们来看看每种方法。

使用主题构建器

构建主题最简单的方法是使用主题构建器。要在本地启动主题构建器，请运行以下代码：

import gradio as gr

gr.themes.builder()

您可以使用上面 Spaces 上运行的主题构建器，但通过 gr.themes.builder() 在本地启动时，运行速度会快得多。

当您在主题构建器中编辑值时，应用程序将实时预览更新。您可以下载生成主题的代码，以便在任何 Gradio 应用程序中使用它。

在本指南的其余部分，我们将介绍如何以编程方式构建主题。

通过构造函数扩展主题

尽管每个主题都有数百个 CSS 变量，但大多数这些变量的值都来自 8 个核心变量，这些变量可以通过每个预构建主题的构造函数进行设置。修改这 8 个参数可以让您快速更改应用程序的外观和风格。

核心颜色

前 3 个构造函数参数设置主题的颜色，并且是 gradio.themes.Color 对象。在内部，这些 Color 对象保存单个色调的调色板的亮度值，范围从 50、100、200...、800、900、950。其他 CSS 变量从这 3 种颜色派生而来。

3 个颜色构造函数参数是：

• — primary_hue：这是在您的主题中吸引注意力的颜色。在默认主题中，这设置为 gradio.themes.colors.orange。
• — secondary_hue：这是用于主题中辅助元素的颜色。在默认主题中，这设置为 gradio.themes.colors.blue。
• — neutral_hue：这是用于文本和主题中其他中性元素的颜色。在默认主题中，这设置为 gradio.themes.colors.gray。

您可以使用它们的字符串快捷方式修改这些值，例如：

with gr.Blocks(theme=gr.themes.Default(primary_hue="red", secondary_hue="pink")) as demo:
    ...

或者您可以直接使用 Color 对象，如下所示：

with gr.Blocks(theme=gr.themes.Default(primary_hue=gr.themes.colors.red, secondary_hue=gr.themes.colors.pink)) as demo:
    ...

预定义的颜色包括：

• — slate
• — gray
• — zinc
• — neutral
• — stone
• — red
• — orange
• — amber
• — yellow
• — lime
• — green
• — emerald
• — teal
• — cyan
• — sky
• — blue
• — indigo
• — violet
• — purple
• — fuchsia
• — pink
• — rose

您还可以创建自己的自定义 Color 对象并将其传入。

核心尺寸

接下来的 3 个构造函数参数设置主题的尺寸，并且是 gradio.themes.Size 对象。在内部，这些 Size 对象保存像素尺寸值，范围从 xxs 到 xxl。其他 CSS 变量从这 3 个尺寸派生而来。

• — spacing_size：这设置元素内部的填充和元素之间的间距。在默认主题中，这设置为 gradio.themes.sizes.spacing_md。
• — radius_size：这设置元素边角的圆角程度。在默认主题中，这设置为 gradio.themes.sizes.radius_md。
• — text_size：这设置文本的字体大小。在默认主题中，这设置为 gradio.themes.sizes.text_md。

您可以使用它们的字符串快捷方式修改这些值，例如：

with gr.Blocks(theme=gr.themes.Default(spacing_size="sm", radius_size="none")) as demo:
    ...

或者您可以直接使用 Size 对象，如下所示：

with gr.Blocks(theme=gr.themes.Default(spacing_size=gr.themes.sizes.spacing_sm, radius_size=gr.themes.sizes.radius_none)) as demo:
    ...

预定义的尺寸对象包括：

• — radius_none
• — radius_sm
• — radius_md
• — radius_lg
• — spacing_sm
• — spacing_md
• — spacing_lg
• — text_sm
• — text_md
• — text_lg

您还可以创建自己的自定义 Size 对象并将其传入。

核心字体

最后 2 个构造函数参数设置主题的字体。您可以将字体列表传递给这些参数中的每一个，以指定备用字体。如果您提供一个字符串，它将被加载为系统字体。如果您提供 gradio.themes.GoogleFont，字体将从 Google Fonts 加载。

• — font：这设置主题的主要字体。在默认主题中，这设置为 gradio.themes.GoogleFont("Source Sans Pro")。
• — font_mono：这设置主题的等宽字体。在默认主题中，这设置为 gradio.themes.GoogleFont("IBM Plex Mono")。

您可以修改这些值，例如以下示例：

with gr.Blocks(theme=gr.themes.Default(font=[gr.themes.GoogleFont("Inconsolata"), "Arial", "sans-serif"])) as demo:
    ...

通过 .set() 扩展主题

您还可以在主题加载后修改 CSS 变量的值。为此，请使用主题对象的 .set() 方法来访问 CSS 变量。例如：

theme = gr.themes.Default(primary_hue="blue").set(
    loader_color="#FF0000",
    slider_color="#FF0000",
)

with gr.Blocks(theme=theme) as demo:
    ...

在上面的示例中，我们将 loader_color 和 slider_color 变量设置为 #FF0000，尽管整体 primary_color 使用蓝色调色板。您可以以这种方式设置主题中定义的任何 CSS 变量。

您的 IDE 类型提示应该可以帮助您浏览这些变量。由于 CSS 变量太多，让我们看一下这些变量是如何命名和组织的。

CSS 变量命名约定

CSS 变量名称可能会很长，例如 button_primary_background_fill_hover_dark！但是，它们遵循一个通用的命名约定，可以轻松理解它们的作用并找到您要查找的变量。变量名称由下划线分隔，由以下部分组成：

• — 1. 目标元素，例如 button、slider 或 block。
• — 2. 目标元素类型或子元素，例如 button_primary 或 block_label。
• — 3. 属性，例如 button_primary_background_fill 或 block_label_border_width。
• — 4. 任何相关状态，例如 button_primary_background_fill_hover。
• — 5. 如果该值在暗黑模式下不同，则使用后缀 _dark。例如，input_border_color_focus_dark。

当然，许多 CSS 变量名称比这更短，例如 table_border_color 或 input_shadow。

CSS 变量组织

尽管有数百个 CSS 变量，但它们不必都具有单独的值。它们通过引用一组核心变量并相互引用来获取它们的值。这使我们只需修改几个变量即可更改整个主题的外观和风格，同时还可以更精细地控制我们可能想要修改的各个元素。

引用核心变量

要引用核心构造函数变量之一，请在变量名称前加上星号。要引用核心颜色，请使用 *primary_、*secondary_ 或 *neutral_ 前缀，后跟亮度值。例如：

theme = gr.themes.Default(primary_hue="blue").set(
    button_primary_background_fill="*primary_200",
    button_primary_background_fill_hover="*primary_300",
)

在上面的示例中，我们将 button_primary_background_fill 和 button_primary_background_fill_hover 变量设置为 *primary_200 和 *primary_300。这些变量将分别设置为蓝色主色调色板的 200 和 300 亮度值。

同样，要引用核心尺寸，请使用 *spacing_、*radius_ 或 *text_ 前缀，后跟尺寸值。例如：

theme = gr.themes.Default(radius_size="md").set(
    button_primary_border_radius="*radius_xl",
)

在上面的示例中，我们将 button_primary_border_radius 变量设置为 *radius_xl。此变量将设置为中等半径尺寸范围的 xl 设置。

引用其他变量

变量也可以相互引用。例如，请看下面的示例：

theme = gr.themes.Default().set(
    button_primary_background_fill="#FF0000",
    button_primary_background_fill_hover="#FF0000",
    button_primary_border="#FF0000",
)

将这些值设置为通用颜色有点繁琐。相反，我们可以使用 * 前缀在 button_primary_background_fill_hover 和 button_primary_border 变量中引用 button_primary_background_fill 变量。

theme = gr.themes.Default().set(
    button_primary_background_fill="#FF0000",
    button_primary_background_fill_hover="*button_primary_background_fill",
    button_primary_border="*button_primary_background_fill",
)

现在，如果我们更改 button_primary_background_fill 变量，button_primary_background_fill_hover 和 button_primary_border 变量也会自动更新。

如果您打算共享您的主题，这将特别有用 - 它使您可以轻松地修改主题，而无需更改每个变量。

请注意，暗黑模式变量会自动相互引用。例如：

theme = gr.themes.Default().set(
    button_primary_background_fill="#FF0000",
    button_primary_background_fill_dark="#AAAAAA",
    button_primary_border="*button_primary_background_fill",
    button_primary_border_dark="*button_primary_background_fill_dark",
)

button_primary_border_dark 将从 button_primary_background_fill_dark 获取其值，因为暗黑模式始终从变量的暗黑版本中获取。

创建完整主题

假设您想从头开始创建一个主题！我们将逐步进行 - 您还可以在 gradio 源代码库中查看预构建主题的源代码以供参考 - 这是 Monochrome 主题的源代码。

我们的新主题类将继承自 gradio.themes.Base，这是一个设置了许多方便默认值的主题。让我们创建一个简单的演示，创建一个名为 Seafoam 的虚拟主题，并创建一个使用它的简单应用程序。

$code_theme_new_step_1

Base 主题非常简陋，并使用 gr.themes.Blue 作为其主色 - 您会注意到主按钮和加载动画都是蓝色的。让我们更改应用程序的默认核心参数。我们将覆盖构造函数并为核心构造函数参数传递新的默认值。

我们将使用 gr.themes.Emerald 作为我们的主色，并将辅助色调和中性色调设置为 gr.themes.Blue。我们将使用 text_lg 使文本更大。我们将使用从 Google Fonts 加载的 Quicksand 作为我们的默认字体。

$code_theme_new_step_2

看看主按钮和加载动画现在变成绿色了吗？这些 CSS 变量与 primary_hue 变量相关联。

让我们更直接地修改主题。我们将调用 set() 方法来显式覆盖 CSS 变量值。我们可以使用任何 CSS 逻辑，并使用 * 前缀引用我们的核心构造函数参数。

$code_theme_new_step_3

看看我们的主题现在看起来多么有趣！只需更改几个变量，我们的主题看起来就完全不同了。

您可能会发现浏览其他预构建主题的源代码很有帮助，以了解它们是如何修改基础主题的。您还可以使用浏览器的检查器来选择 UI 中的元素，并在样式面板中查看正在使用的 CSS 变量。

共享主题

创建主题后，您可以将其上传到 HuggingFace Hub，让其他人查看、使用和在其基础上进行构建！

上传主题

有两种方法可以上传主题，通过主题类实例或命令行。我们将使用之前创建的 seafoam 主题来介绍这两种方法。

• 通过类实例

每个主题实例都有一个名为 push_to_hub 的方法，我们可以使用它将主题上传到 HuggingFace Hub。

seafoam.push_to_hub(repo_name="seafoam",
                    version="0.0.1",
					hf_token="<token>")

• 通过命令行

首先将主题保存到磁盘：

seafoam.dump(filename="seafoam.json")

然后使用 upload_theme 命令：

upload_theme\
"seafoam.json"\
"seafoam"\
--version "0.0.1"\
--hf_token "<token>"

为了上传主题，您必须拥有 HuggingFace 帐户，并将您的访问令牌作为 hf_token 参数传递。但是，如果您通过HuggingFace 命令行（与 gradio 一起安装）登录，则可以省略 hf_token 参数。

version 参数允许您为主题指定有效的语义版本字符串。这样，您的用户就可以指定他们想要在应用程序中使用的主题版本。这也使您可以发布主题更新，而无需担心更改先前创建的应用程序的外观。version 参数是可选的。如果省略，则会自动应用下一个补丁版本。

主题预览

通过调用 push_to_hub 或 upload_theme，主题资源将存储在HuggingFace Space中。

我们的 seafoam 主题的主题预览在这里：seafoam 预览。

发现主题

主题库显示了所有公开的 gradio 主题。发布您的主题后，它会在几分钟后自动显示在主题库中。

您可以按 Space 上的点赞数以及从最近创建到最旧对主题进行排序，以及在浅色和深色模式之间切换主题。

下载

要使用 Hub 中的主题，请在 ThemeClass 上使用 from_hub 方法并将其传递给您的应用程序：

my_theme = gr.Theme.from_hub("gradio/seafoam")

with gr.Blocks(theme=my_theme) as demo:
    ....

您也可以将主题字符串直接传递给 Blocks 或 Interface (gr.Blocks(theme="gradio/seafoam"))

您可以使用语义版本控制表达式将您的应用程序固定到上游主题版本。

例如，以下代码将确保我们从 seafoam 仓库加载的主题版本在 0.0.1 和 0.1.0 之间：

with gr.Blocks(theme="gradio/seafoam@>=0.0.1,<0.1.0") as demo:
    ....

尽情创建您自己的主题吧！如果您创建了一个您引以为傲的主题，请将其上传到 Hub 与世界分享！如果您在Twitter 上标记我们，我们可以为您的主题宣传一下！