1. 组件
  2. 按钮

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

查看 发布历史

←

条形图

聊天机器人

→

按钮

gradio.Button(···)

描述

创建一个可以分配任意 .click() 事件的按钮。按钮的值（标签）可以用作函数的输入（很少使用），或者通过函数的输出来设置。

行为

作为输入组件: （很少使用）按钮被点击时对应的按钮标签的 str

您的函数应接受其中一种类型
def predict(
	value: str | None
)
	...

作为输出组件: 对应按钮标签的字符串

您的函数应返回其中一种类型
def predict(···) -> str | None
	...	
	return value

初始化

参数
🔗 
value: str | I18nData | Callable
默认 = "运行"

按钮显示的默认文本。如果提供了一个函数，该函数将在每次应用加载时调用，以设置此组件的初始值。

🔗 
every: Timer | float | None
默认 = None

如果 `value` 是一个函数，则持续调用 `value` 来重新计算它（否则无效）。可以提供一个 Timer，其 tick 会重置 `value`，或者一个 float 来提供重置 Timer 的常规间隔。

🔗 
inputs: Component | list[Component] | set[Component] | None
默认 = None

如果 `value` 是一个函数（否则不起作用），则用作计算 `value` 的输入的组件。`value` 在输入更改时会重新计算。

🔗 
variant: Literal['primary', 'secondary', 'stop', 'huggingface']
默认 = "secondary"

设置按钮的背景和文本颜色。使用 'primary' 用于主要行动号召按钮，'secondary' 用于更柔和的风格，'stop' 用于停止按钮，'huggingface' 用于与 Hugging Face 的按钮样式一致的黑色背景和白色文本。

🔗 
size: Literal['sm', 'md', 'lg']
默认 = "lg"

按钮的大小。可以是 "sm"、"md" 或 "lg"。

🔗 
icon: str | Path | None
默认 = None

用于在按钮内显示的图标文件的 URL 或路径。如果为 None，则不显示图标。

🔗 
visible: bool | Literal['hidden']
默认 = True

如果为 False，则组件将隐藏。如果为“hidden”，则组件将视觉上隐藏并且不会在布局中占用空间，但仍存在于 DOM 中。

🔗 
interactive: 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 | tuple[int | str, ...] | None
默认 = None

在 `gr.render` 中，跨重渲染具有相同键的组件被视为同一个组件，而不是一个新组件。在 `preserved_by_key` 中设置的属性在重渲染时不会重置。

🔗 
preserved_by_key: list[str] | str | None
默认 = "value"

此组件构造函数中的参数列表。在 `gr.render()` 函数内部，如果一个组件使用相同的键进行重渲染，则这些（也是唯一的）参数将在 UI 中被保留（如果它们已被用户或事件监听器更改），而不是根据构造函数中提供的值进行重渲染。

🔗 
scale: int | None
默认 = None

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

🔗 
min_width: int | None
默认 = None

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

快捷方式

快捷方式
gradio.Button
接口字符串快捷方式 "button"
初始化 使用默认值
gradio.ClearButton
接口字符串快捷方式 "clearbutton"
初始化 使用默认值
gradio.DeepLinkButton
接口字符串快捷方式 "deeplinkbutton"
初始化 使用默认值
gradio.DuplicateButton
接口字符串快捷方式 "duplicatebutton"
初始化 使用默认值
gradio.LoginButton
接口字符串快捷方式 "loginbutton"
初始化 使用默认值

事件监听器

描述

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

支持的事件监听器

该 Button 组件支持以下事件监听器。每个事件监听器都接受相同的参数，这些参数列在下面的 事件参数 表中。

监听器
Button.click(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
默认 = None

定义该端点在 API 文档中如何显示。可以是字符串或 None。如果设置为字符串，则该端点将在 API 文档中以给定名称显示。如果为 None（默认），则使用函数的名称作为 API 端点。

🔗 
api_description: str | None | Literal[False]
默认 = None

API 端点的描述。可以是字符串、None 或 False。如果设置为字符串，则该端点将在 API 文档中以给定描述显示。如果为 None，则使用函数的 docstring 作为 API 端点描述。如果为 False，则 API 文档中不会显示任何描述。

🔗 
scroll_to_output: bool
默认 = False

完成后是否滚动到输出组件

🔗 
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，表示没有并发限制（此事件可以同时运行任意数量）。设置为 "default" 可使用 `Blocks.queue()` 中的 `default_concurrency_limit` 参数定义的默认并发限制（该参数本身默认为 1）。

🔗 
concurrency_id: str | None
默认 = None

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

🔗 
api_visibility: Literal['public', 'private', 'undocumented']
默认 = "public"

控制此端点的可见性和可访问性。可以是 "public"（在 API 文档中显示并可由客户端调用）、"private"（在 API 文档中隐藏，不可由客户端调用）或 "undocumented"（在 API 文档中隐藏，但可由客户端通过 gr.load 调用）。如果 fn 为 None，则 api_visibility 将自动设置为 "private"。

🔗 
time_limit: int | None
默认 = None
🔗 
stream_every: float
默认 = 0.5
🔗 
key: int | str | tuple[int | str, ...] | None
默认 = None

此事件监听器的唯一键，用于 @gr.render()。如果设置，此值标识在重渲染时具有相同键的事件为相同的事件。

🔗 
validator: Callable | None
默认 = None

可选的验证函数，在主函数运行之前执行。如果提供，此函数将首先使用 queue=False 执行，只有在成功完成后才会调用主函数。验证器接收与主函数相同的输入，并应为每个输入值返回一个 `gr.validate()`。

←

条形图

聊天机器人

→
gradio