主题

简介

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

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

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

gr.themes.Base() - "base" 主题将主色设置为蓝色，但在其他方面具有最少的样式，使其特别适合作为创建新的自定义主题的基础。
gr.themes.Default() - "default" Gradio 5 主题，具有鲜艳的橙色主色和灰色辅助色。
gr.themes.Origin() - "origin" 主题与 Gradio 4 样式最相似。颜色，尤其是在浅色模式下，比 Gradio 5 默认主题更柔和。
gr.themes.Citrus() - "citrus" 主题使用黄色主色，突出显示处于焦点状态的表单元素，并在单击按钮时包含有趣的 3D 效果。
gr.themes.Monochrome() - "monochrome" 主题使用黑色主色和白色辅助色，并使用衬线字体，呈现出黑白报纸的外观。
gr.themes.Soft() - "soft" 主题使用紫色主色和白色辅助色。它还增加了按钮和表单元素周围的边框半径，并突出显示标签。
gr.themes.Glass() - "glass" 主题具有蓝色主色和半透明的灰色辅助色。该主题还使用垂直渐变来创建玻璃效果。
gr.themes.Ocean() - "ocean" 主题具有蓝绿色主色和灰色辅助色。该主题还使用水平渐变，特别是对于按钮和一些表单元素。

这些主题中的每一个都为数百个 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("IBM Plex Sans")。
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:
    ...

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

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

CSS 变量命名约定

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

目标元素，例如 button、slider 或 block。
目标元素类型或子元素，例如 button_primary 或 block_label。
属性，例如 button_primary_background_fill 或 block_label_border_width。
任何相关状态，例如 button_primary_background_fill_hover。
如果值在暗黑模式下不同，则后缀为 _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 的虚拟主题，并创建一个使用它的简单应用程序。

import gradio as gr
from gradio.themes.base import Base
import time

class Seafoam(Base):
    pass

seafoam = Seafoam()

with gr.Blocks(theme=seafoam) as demo:
    textbox = gr.Textbox(label="Name")
    slider = gr.Slider(label="Count", minimum=0, maximum=100, step=1)
    with gr.Row():
        button = gr.Button("Submit", variant="primary")
        clear = gr.Button("Clear")
    output = gr.Textbox(label="Output")

    def repeat(name, count):
        time.sleep(3)
        return name * count

    button.click(repeat, [textbox, slider], output)

demo.launch()

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

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

from __future__ import annotations
from typing import Iterable
import gradio as gr
from gradio.themes.base import Base
from gradio.themes.utils import colors, fonts, sizes
import time

class Seafoam(Base):
    def __init__(
        self,
        *,
        primary_hue: colors.Color | str = colors.emerald,
        secondary_hue: colors.Color | str = colors.blue,
        neutral_hue: colors.Color | str = colors.gray,
        spacing_size: sizes.Size | str = sizes.spacing_md,
        radius_size: sizes.Size | str = sizes.radius_md,
        text_size: sizes.Size | str = sizes.text_lg,
        font: fonts.Font
        | str
        | Iterable[fonts.Font | str] = (
            fonts.GoogleFont("Quicksand"),
            "ui-sans-serif",
            "sans-serif",
        ),
        font_mono: fonts.Font
        | str
        | Iterable[fonts.Font | str] = (
            fonts.GoogleFont("IBM Plex Mono"),
            "ui-monospace",
            "monospace",
        ),
    ):
        super().__init__(
            primary_hue=primary_hue,
            secondary_hue=secondary_hue,
            neutral_hue=neutral_hue,
            spacing_size=spacing_size,
            radius_size=radius_size,
            text_size=text_size,
            font=font,
            font_mono=font_mono,
        )

seafoam = Seafoam()

with gr.Blocks(theme=seafoam) as demo:
    textbox = gr.Textbox(label="Name")
    slider = gr.Slider(label="Count", minimum=0, maximum=100, step=1)
    with gr.Row():
        button = gr.Button("Submit", variant="primary")
        clear = gr.Button("Clear")
    output = gr.Textbox(label="Output")

    def repeat(name, count):
        time.sleep(3)
        return name * count

    button.click(repeat, [textbox, slider], output)

demo.launch()

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

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

from __future__ import annotations
from typing import Iterable
import gradio as gr
from gradio.themes.base import Base
from gradio.themes.utils import colors, fonts, sizes
import time

class Seafoam(Base):
    def __init__(
        self,
        *,
        primary_hue: colors.Color | str = colors.emerald,
        secondary_hue: colors.Color | str = colors.blue,
        neutral_hue: colors.Color | str = colors.blue,
        spacing_size: sizes.Size | str = sizes.spacing_md,
        radius_size: sizes.Size | str = sizes.radius_md,
        text_size: sizes.Size | str = sizes.text_lg,
        font: fonts.Font
        | str
        | Iterable[fonts.Font | str] = (
            fonts.GoogleFont("Quicksand"),
            "ui-sans-serif",
            "sans-serif",
        ),
        font_mono: fonts.Font
        | str
        | Iterable[fonts.Font | str] = (
            fonts.GoogleFont("IBM Plex Mono"),
            "ui-monospace",
            "monospace",
        ),
    ):
        super().__init__(
            primary_hue=primary_hue,
            secondary_hue=secondary_hue,
            neutral_hue=neutral_hue,
            spacing_size=spacing_size,
            radius_size=radius_size,
            text_size=text_size,
            font=font,
            font_mono=font_mono,
        )
        super().set(
            body_background_fill="repeating-linear-gradient(45deg, *primary_200, *primary_200 10px, *primary_50 10px, *primary_50 20px)",
            body_background_fill_dark="repeating-linear-gradient(45deg, *primary_800, *primary_800 10px, *primary_900 10px, *primary_900 20px)",
            button_primary_background_fill="linear-gradient(90deg, *primary_300, *secondary_400)",
            button_primary_background_fill_hover="linear-gradient(90deg, *primary_200, *secondary_300)",
            button_primary_text_color="white",
            button_primary_background_fill_dark="linear-gradient(90deg, *primary_600, *secondary_800)",
            slider_color="*secondary_300",
            slider_color_dark="*secondary_600",
            block_title_text_weight="600",
            block_border_width="3px",
            block_shadow="*shadow_drop_lg",
            button_primary_shadow="*shadow_drop_lg",
            button_large_padding="32px",
        )

seafoam = Seafoam()

with gr.Blocks(theme=seafoam) as demo:
    textbox = gr.Textbox(label="Name")
    slider = gr.Slider(label="Count", minimum=0, maximum=100, step=1)
    with gr.Row():
        button = gr.Button("Submit", variant="primary")
        clear = gr.Button("Clear")
    output = gr.Textbox(label="Output")

    def repeat(name, count):
        time.sleep(3)
        return name * count

    button.click(repeat, [textbox, slider], output)

demo.launch()

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

您可能会发现探索其他预构建主题的源代码很有帮助，以了解它们是如何修改基础主题的。您还可以找到浏览器的 Inspector 工具，以从 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 上标记我们，我们可以为您的主题加油助威！

主题

简介