组件
画廊

Gradio 新手？从这里开始：入门指南

FileExplorer

HighlightedText

画廊

gradio.Gallery(···)

import gradio as gr with gr.Blocks() as demo: cheetahs = [ "https://upload.wikimedia.org/wikipedia/commons/0/09/TheCheethcat.jpg", "https://nationalzoo.si.edu/sites/default/files/animals/cheetah-003.jpg", "https://img.etimg.com/thumb/msid-50159822,width-650,imgsize-129520,,resizemode-4,quality-100/.jpg", "https://nationalzoo.si.edu/sites/default/files/animals/cheetah-002.jpg", "https://images.theconversation.com/files/375893/original/file-20201218-13-a8h8uq.jpg?ixlib=rb-1.1.0&rect=16%2C407%2C5515%2C2924&q=45&auto=format&w=496&fit=clip", ] gr.Gallery(value=cheetahs, columns=4) demo.launch()

描述

创建一个画廊组件，允许展示图像或视频网格，并可选择添加标题。如果用作输入，用户可以上传图像或视频到画廊。如果用作输出，用户可以点击单个图像或视频以更高分辨率查看。

行为

作为输入组件: 传递图像或视频列表，作为 (媒体, 标题) 元组的列表，或者如果未提供标题，则作为 (媒体, None) 元组的列表（通常是这种情况）。图像可以是 `str` 文件路径，`numpy` 数组，或 `PIL.Image` 对象，具体取决于 `type`。视频始终是 `str` 文件路径。

您的函数应接受以下类型之一

def predict(
	value: List[tuple[str, str | None]] | List[tuple[PIL.Image.Image, str | None]] | List[tuple[np.ndarray, str | None]] | None
)
	...

作为输出组件: 期望函数返回图像或视频的 `list`，或 (媒体, `str` 标题) 元组的 `list`。每个图像可以是 `str` 文件路径，`numpy` 数组，或 `PIL.Image` 对象。每个视频可以是 `str` 文件路径。

您的函数应返回以下类型之一

def predict(···) -> list[GalleryImageType | CaptionedGalleryImageType] | None
	...	
	return value

初始化

🔗

value: list[np.ndarray | PIL.Image.Image | str | Path | tuple] | Callable | None

默认值 = None

默认情况下在画廊中显示的图像或视频列表。如果提供了函数，则每次加载应用程序时都会调用该函数以设置此组件的初始值。

🔗

format: str

默认值 = "webp"

将图像保存为前端之前的格式，例如 'jpeg' 或 'png'。此参数仅适用于从预测函数作为 numpy 数组或 PIL 图像返回的图像。该格式应受 PIL 库支持。

🔗

file_types: list[str] | None

默认值 = None

当用作输入组件时，要上传的文件扩展名或文件类型列表（例如 ['image', '.mp4']）。 “image” 仅允许上传图像文件，“video” 仅允许上传视频文件，“.mp4” 仅允许上传 mp4 文件，依此类推。如果为 None，则允许任何图像和视频文件类型。

🔗

label: str | None

默认值 = None

此组件的标签。显示在组件上方，如果此组件有示例表，则也用作标题。如果为 None 且在 `gr.Interface` 中使用，则标签将是分配给此组件的参数名称。

🔗

every: Timer | float | None

默认值 = None

如果 `value` 是函数，则持续调用 `value` 以重新计算（否则无效）。可以提供一个定时器，其刻度重置 `value`，或者提供一个浮点数，以提供重置定时器的常规间隔。

🔗

inputs: Component | list[Component] | set[Component] | None

默认值 = None

如果 `value` 是函数，则用作计算 `value` 输入的组件（否则无效）。每当输入发生更改时，`value` 都会重新计算。

🔗

show_label: bool | None

默认值 = None

如果为 True，将显示标签。

🔗

container: bool

默认值 = True

如果为 True，则将组件放置在容器中 - 在边框周围提供一些额外的填充。

🔗

scale: int | None

默认值 = None

相对于相邻组件的相对大小。例如，如果组件 A 和 B 在同一行中，并且 A 的 scale=2，B 的 scale=1，则 A 的宽度将是 B 的两倍。应为整数。scale 应用于行，以及 Blocks 中 fill_height=True 的顶级组件。

🔗

min_width: int

默认值 = 160

最小像素宽度，如果屏幕空间不足以满足此值，则会换行。如果某个 scale 值导致此组件比 min_width 窄，则将首先考虑 min_width 参数。

🔗

visible: bool

默认值 = True

如果为 False，组件将被隐藏。

🔗

elem_id: str | None

默认值 = None

一个可选字符串，用作此组件在 HTML DOM 中的 id。可用于定位 CSS 样式。

🔗

elem_classes: list[str] | str | None

默认值 = None

一个可选的字符串列表，用作此组件在 HTML DOM 中的类。可用于定位 CSS 样式。

🔗

render: bool

默认值 = True

如果为 False，组件将不会在 Blocks 上下文中呈现。如果目的是现在分配事件侦听器，但稍后呈现组件，则应使用此选项。

🔗

key: int | str | None

默认值 = None

如果分配，将用于在重新渲染时假定身份。在重新渲染中具有相同 key 的组件将保留其值。

🔗

columns: int | list[int] | tuple[int, ...] | None

默认值 = 2

表示在六个标准屏幕尺寸（<576px、<768px、<992px、<1200px、<1400px、>1400px）的每一行中应显示的图像数量。如果给出的数量少于 6 个，则最后一个将用于所有后续断点

🔗

rows: int | list[int] | None

默认值 = None

表示图像网格中的行数，对于六个标准屏幕尺寸中的每一个（<576px、<768px、<992px、<1200px、<1400px、>1400px）。如果给出的数量少于 6 个，则最后一个将用于所有后续断点

🔗

height: int | float | str | None

默认值 = None

画廊组件的高度，如果传递数字，则以像素为单位指定，如果传递字符串，则以 CSS 单位指定。如果显示的图像超过高度所能容纳的数量，则会出现滚动条。

🔗

allow_preview: bool

默认值 = True

如果为 True，画廊中的图像在单击时将被放大。默认为 True。

🔗

preview: bool | None

默认值 = None

如果为 True，画廊将以预览模式启动，该模式显示所有图像的缩略图，并允许用户单击它们以全尺寸查看。仅当 allow_preview 为 True 时才有效。

🔗

selected_index: int | None

默认值 = None

应初始选择的图像的索引。如果为 None，则启动时不会选择任何图像。如果提供，则会将画廊设置为预览模式，除非 allow_preview 设置为 False。

🔗

object_fit: Literal['contain', 'cover', 'fill', 'none', 'scale-down'] | None

默认值 = None

画廊中缩略图图像的 CSS object-fit 属性。可以是 "contain"、"cover"、"fill"、"none" 或 "scale-down"。

🔗

show_share_button: bool | None

默认值 = None

如果为 True，将在组件的角落显示一个共享图标，允许用户将输出共享到 Hugging Face Spaces Discussions。如果为 False，则不显示图标。如果设置为 None（默认行为），则如果此 Gradio 应用程序在 Spaces 上启动，则会显示该图标，否则不显示。

🔗

show_download_button: bool | None

默认值 = True

如果为 True，将在所选图像的角落显示一个下载按钮。如果为 False，则不显示图标。默认为 True。

🔗

interactive: bool | None

默认值 = None

如果为 True，画廊将是交互式的，允许用户上传图像。如果为 False，画廊将是静态的。默认为 True。

🔗

type: Literal['numpy', 'pil', 'filepath']

默认值 = "filepath"

图像在传递到预测函数之前转换成的格式。“numpy” 将图像转换为形状为 (高度, 宽度, 3) 且值从 0 到 255 的 numpy 数组，“pil” 将图像转换为 PIL 图像对象，“filepath” 传递一个 str 路径到包含图像的临时文件。如果图像是 SVG，则忽略 `type` 并返回 SVG 的文件路径。

🔗

show_fullscreen_button: bool

默认值 = True

如果为 True，将在组件的角落显示一个全屏图标，允许用户以全屏模式查看画廊。如果为 False，则不显示图标。如果设置为 None（默认行为），则如果此 Gradio 应用程序在 Spaces 上启动，则会显示该图标，否则不显示。

快捷方式

类	Interface 字符串快捷方式	初始化
`gradio.Gallery`	"gallery"	使用默认值

演示

# 此演示需要从 repo 文件夹运行。 # python demo/fake_gan/run.py import random import gradio as gr def fake_gan(): images = [ (random.choice( [ "http://www.marketingtool.online/en/face-generator/img/faces/avatar-1151ce9f4b2043de0d2e3b7826127998.jpg", "http://www.marketingtool.online/en/face-generator/img/faces/avatar-116b5e92936b766b7fdfc242649337f7.jpg", "http://www.marketingtool.online/en/face-generator/img/faces/avatar-1163530ca19b5cebe1b002b8ec67b6fc.jpg", "http://www.marketingtool.online/en/face-generator/img/faces/avatar-1116395d6e6a6581eef8b8038f4c8e55.jpg", "http://www.marketingtool.online/en/face-generator/img/faces/avatar-11319be65db395d0e8e6855d18ddcef0.jpg", ] ), f"label {i}") for i in range(3) ] return images with gr.Blocks() as demo: gallery = gr.Gallery( label="Generated images", show_label=False, elem_id="gallery" , columns=[3], rows=[1], object_fit="contain", height="auto") btn = gr.Button("Generate images", scale=0) btn.click(fake_gan, None, gallery) if __name__ == "__main__": demo.launch()

# This demo needs to be run from the repo folder.
# python demo/fake_gan/run.py
import random

import gradio as gr

def fake_gan():
    images = [
        (random.choice(
            [
                "http://www.marketingtool.online/en/face-generator/img/faces/avatar-1151ce9f4b2043de0d2e3b7826127998.jpg",
                "http://www.marketingtool.online/en/face-generator/img/faces/avatar-116b5e92936b766b7fdfc242649337f7.jpg",
                "http://www.marketingtool.online/en/face-generator/img/faces/avatar-1163530ca19b5cebe1b002b8ec67b6fc.jpg",
                "http://www.marketingtool.online/en/face-generator/img/faces/avatar-1116395d6e6a6581eef8b8038f4c8e55.jpg",
                "http://www.marketingtool.online/en/face-generator/img/faces/avatar-11319be65db395d0e8e6855d18ddcef0.jpg",
            ]
        ), f"label {i}")
        for i in range(3)
    ]
    return images

with gr.Blocks() as demo:
    gallery = gr.Gallery(
        label="Generated images", show_label=False, elem_id="gallery"
    , columns=[3], rows=[1], object_fit="contain", height="auto")
    btn = gr.Button("Generate images", scale=0)

    btn.click(fake_gan, None, gallery)

if __name__ == "__main__":
    demo.launch()

事件侦听器

描述

事件侦听器允许您响应用户与您在 Gradio Blocks 应用程序中定义的 UI 组件的交互。当用户与元素交互时，例如更改滑块值或上传图像，将调用一个函数。

支持的事件侦听器

Gallery 组件支持以下事件侦听器。每个事件侦听器都采用相同的参数，这些参数在下面的事件参数表中列出。

侦听器	描述
`Gallery.select(fn, ···)`	当用户选择或取消选择画廊时的事件侦听器。使用事件数据 gradio.SelectData 来携带 `value`，指的是画廊的标签，以及 `selected`，指的是画廊的状态。有关如何使用此事件数据的更多信息，请参阅 EventData 文档
`Gallery.upload(fn, ···)`	当用户将文件上传到画廊时，将触发此侦听器。
`Gallery.change(fn, ···)`	当画廊的值因用户输入（例如，用户在文本框中键入内容）或函数更新（例如，图像从事件触发器的输出接收到一个值）而更改时触发。有关仅由用户输入触发的侦听器，请参阅 `.input()`。
`Gallery.preview_close(fn, ···)`	当用户关闭画廊预览时，会触发此事件
`Gallery.preview_open(fn, ···)`	当用户打开画廊预览时，会触发此事件

事件参数

🔗

fn: Callable | None | Literal['decorator']

默认值 = "decorator"

触发此事件时要调用的函数。通常是机器学习模型的预测函数。函数的每个参数对应一个输入组件，并且函数应返回单个值或值元组，元组中的每个元素对应一个输出组件。

🔗

inputs: Component | BlockContext | list[Component | BlockContext] | Set[Component | BlockContext] | None

默认值 = None

用作输入的 gradio.components 列表。如果函数不接受任何输入，则应为空列表。

🔗

outputs: Component | BlockContext | list[Component | BlockContext] | Set[Component | BlockContext] | None

默认值 = None

用作输出的 gradio.components 列表。如果函数不返回任何输出，则应为空列表。

🔗

api_name: str | None | Literal[False]

默认值 = None

定义端点在 API 文档中的显示方式。可以是字符串、None 或 False。如果设置为字符串，则端点将在 API 文档中公开，并带有给定的名称。如果为 None（默认值），则函数的名称将用作 API 端点。如果为 False，则端点将不会在 API 文档中公开，并且下游应用程序（包括 `gr.load` 此应用程序的应用程序）将无法使用此事件。

🔗

scroll_to_output: bool

默认值 = False

如果为 True，则在完成后滚动到输出组件

🔗

show_progress: Literal['full', 'minimal', 'hidden']

默认值 = "full"

事件运行时如何显示进度动画：“full” 显示一个覆盖输出组件区域的微调器以及右上角的一个运行时显示，“minimal” 仅显示运行时显示，“hidden” 不显示任何进度动画

🔗

show_progress_on: Component | list[Component] | None

默认值 = None

要在其上显示进度动画的组件或组件列表。如果为 None，则将在所有输出组件上显示进度动画。

🔗

queue: bool

默认值 = True

如果为 True，则如果队列已启用，则将请求放置在队列中。如果为 False，即使队列已启用，也不会将此事件放入队列中。如果为 None，则将使用 gradio 应用程序的队列设置。

🔗

batch: bool

默认值 = False

如果为 True，则函数应处理一批输入，这意味着它应接受每个参数的输入值列表。列表的长度应相等（且长度最多为 `max_batch_size`）。然后 *必须* 函数返回列表的元组（即使只有一个输出组件），元组中的每个列表对应一个输出组件。

🔗

max_batch_size: int

默认值 = 4

如果从队列调用此方法，则要批量处理的最大输入数（仅在 batch=True 时相关）

🔗

preprocess: bool

默认值 = True

如果为 False，则在运行“fn”之前不会运行组件数据的预处理（例如，如果使用 `Image` 组件调用此方法，则将其保留为 base64 字符串）。

🔗

postprocess: bool

默认值 = True

如果为 False，则在将“fn”输出返回到浏览器之前不会运行组件数据的后处理。

🔗

cancels: dict[str, Any] | list[dict[str, Any]] | None

默认值 = None

触发此侦听器时要取消的其他事件的列表。例如，设置 cancels=[click_event] 将取消 click_event，其中 click_event 是另一个组件 .click 方法的返回值。尚未运行的函数（或正在迭代的生成器）将被取消，但当前正在运行的函数将被允许完成。

🔗

trigger_mode: Literal['once', 'multiple', 'always_last'] | None

默认值 = None

如果为 “once”（除 `.change()` 之外的所有事件的默认值），则在事件挂起期间不允许任何提交。如果设置为 “multiple”，则在挂起期间允许无限次提交，而 “always_last”（`.change()` 和 `.key_up()` 事件的默认值）将在挂起事件完成后允许第二次提交。

🔗

js: str | Literal[True] | None

默认值 = None

在运行“fn”之前要运行的可选前端 js 方法。js 方法的输入参数是 “inputs” 和 “outputs” 的值，返回值应为输出组件的值列表。

🔗

concurrency_limit: int | None | Literal['default']

默认值 = "default"

如果设置，这是可以同时运行的此事件的最大数量。可以设置为 None，表示没有 concurrency_limit（可以同时运行任意数量的此事件）。设置为 “default” 以使用默认并发限制（由 `Blocks.queue()` 中的 `default_concurrency_limit` 参数定义，默认情况下为 1）。

🔗

concurrency_id: str | None

默认值 = None

如果设置，这是并发组的 id。具有相同 concurrency_id 的事件将受到最低设置的 concurrency_limit 的限制。

🔗

show_api: bool

默认值 = True

是否在 Gradio 应用程序的 “view API” 页面或 Gradio 客户端的 “.view_api()” 方法中显示此事件。与将 api_name 设置为 False 不同，将 show_api 设置为 False 仍将允许下游应用程序以及客户端使用此事件。如果 fn 为 None，show_api 将自动设置为 False。

🔗