其他
主题

使用我们的文档 MCP

刚开始使用 Gradio？从这里开始：入门指南

查看发布历史

←

Flagging

NO_RELOAD

→

主题

简介

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` 使文本更大。我们将使用 `Quicksand` 作为我们的默认字体，从 Google Fonts 加载。

$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 中。

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

发现主题

主题画廊显示了所有公共 gradio 主题。发布主题后，它会在几分钟后自动显示在主题画廊中。

您可以按空间上的点赞数、从最新创建到最不最近创建以及在亮模式和暗模式之间切换来对主题进行排序。

下载

要使用 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 上标记我们，我们可以为您的主题大声疾呼！

←

Flagging

NO_RELOAD

→

构建演示

Blocks 布局

组件

助手

Modals

Routes

其他

主题

简介

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

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

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

使用主题构建器

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

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

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

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

通过构造函数扩展主题

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

核心颜色

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

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

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

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

预定义的颜色是

核心尺寸

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

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

预定义的尺寸对象是

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

核心字体

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

您可以修改这些值，例如以下内容

通过 .set() 扩展主题

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

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

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

CSS 变量命名约定

CSS 变量名称可能很长，例如 button_primary_background_fill_hover_dark！但是它们遵循一个常见的命名约定，这使得它们易于理解其作用并找到您正在寻找的变量。变量名称由下划线分隔，由以下部分组成

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

CSS 变量组织

引用核心变量

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

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

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

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

引用其他变量

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

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

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

如果您打算共享主题，这特别有用 - 它使修改主题变得容易，而无需更改每个变量。

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

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

创建完整主题

假设您想从头开始创建主题！我们将逐步完成它 - 您也可以参考 gradio 源存储库中预构建主题的源代码 - 这是 Monochrome 主题的源代码。

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

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

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

共享主题

上传主题

主题预览

发现主题

下载

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

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

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

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

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

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

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

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

通过 `.set()` 扩展主题

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

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

CSS 变量名称可能很长，例如 `button_primary_background_fill_hover_dark`！但是它们遵循一个常见的命名约定，这使得它们易于理解其作用并找到您正在寻找的变量。变量名称由下划线分隔，由以下部分组成

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

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

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

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

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

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

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

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

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

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

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