第6章 Gradio 组件
Gradio 提供了大量组件，用来构建交互式界面。
你不需要把它们全部记住。事实上，试图记住每个组件都是在浪费时间。
更好的做法是：理解主要组件各自的用途，并学会如何配置它们。
掌握了这个模式之后，之后查某个具体参数就会容易得多。
Textbox
Textbox 是最常用的组件之一。
text = gr.Textbox()
它既可以接收用户输入的文本，也可以显示应用生成的文本。
更详细的写法是：
text = gr.Textbox(
label="Your Question",
placeholder="Ask a question...",
lines=5
)
文本框适用于：
姓名
问题
提示词
描述
段落
代码
生成的回复
摘要
错误信息
Number
当应用需要输入数字时，就用 gr.Number。
number = gr.Number(
label="Enter a number"
)
也可以指定默认值：
number = gr.Number(
label="Quantity",
value=1
)
如果值本质上是数字，用 Number 比文本框更合适。
Slider
滑块让用户在一个范围内选择数值。
temperature = gr.Slider(
minimum=0,
maximum=100,
value=50,
label="Temperature"
)
当用户需要从连续或有界的数值范围中取值时，滑块就很有用。
例如：
置信度阈值
百分比
图像亮度
生成参数设置
音量
各类数值参数
Slider Steps
你可以控制滑块每次移动的步长。
gr.Slider(
minimum=0,
maximum=1,
value=0.5,
step=0.1
)
这样可选的值就是诸如：
0.0
0.1
0.2
0.3
...
1.0
对于需要按固定步长变化的参数，这种方式非常实用。
Dropdown
下拉框允许用户从列表中选择一个选项。
model = gr.Dropdown(
choices=["Model A", "Model B", "Model C"],
label="Choose a model"
)
可以设置默认值：
model = gr.Dropdown(
choices=["Model A", "Model B", "Model C"],
value="Model A",
label="Choose a model"
)
当选项较多、全部平铺显示会占用过多空间时，下拉框尤其适用。
Radio
Radio 适合用户需要从少量选项中单选的场景。
language = gr.Radio(
choices=["Python", "JavaScript", "Java"],
label="Programming Language"
)
选项只有几个且需要始终可见时，Radio 比下拉框更方便。
Checkbox
复选框表示一个布尔型选择。
subscribe = gr.Checkbox(
label="Subscribe to updates"
)
Python 函数接收到的值为布尔值：
True
或：
False
例如：
def get_status(subscribed):
if subscribed:
return "You are subscribed."
return "You are not subscribed."
CheckboxGroup
当用户可以同时选择多个选项时，使用复选框组。
interests = gr.CheckboxGroup(
choices=[
"AI",
"Web Development",
"Data Science",
"Cybersecurity"
],
label="Choose your interests"
)
函数会接收到所有被选中的值。
适用于需要同时勾选多项的表单场景。
Button
按钮用于触发动作。
button = gr.Button("Submit")
按钮与事件结合后尤为实用：
button.click(
fn=process,
inputs=input_component,
outputs=output_component
)
按钮还可以根据界面设计风格采用不同的视觉变体。
例如：
gr.Button(
"Submit",
variant="primary"
)
具体可用的变体取决于你使用的 Gradio 版本，依赖某个特定样式时请查阅最新文档。
Markdown
Gradio 可以在界面中直接渲染 Markdown。
gr.Markdown(
"# Welcome\n\nThis is my Gradio application."
)
以下场景尤其适用：
标题层级
操作说明
功能解释
文档内容
状态提示
格式化排版
只需加上清晰的 Markdown 分区，应用的整体观感就能提升不少。
HTML
当 Markdown 不够用时，Gradio 也支持直接嵌入 HTML。
gr.HTML(
"<h1>My Application</h1>"
)
动态 HTML 要特别小心，尤其是处理用户输入的内容时。切勿假设任意用户输入都可以安全地直接拼进 HTML。
JSON
JSON 组件适合展示结构化数据。
假设你的 Python 函数返回：
{
"name": "Eva",
"score": 95,
"passed": True
}
用如下方式展示：
output = gr.JSON(
label="Result"
)
在处理返回结构化信息的 API 和机器学习系统时，这个组件特别实用。
Dataframe
Gradio 同样支持以表格形式展示数据。
table = gr.Dataframe(
headers=["Name", "Score"],
datatype=["str", "number"]
)
Dataframe 可用于：
数据分析
CSV 处理
结果表格
数据集展示
预测结果
统计报表
例如：
import gradio as gr
def create_data():
return [
["Alice", 92],
["Bob", 87],
["Charlie", 95]
]
with gr.Blocks() as demo:
button = gr.Button("Load Data")
table = gr.Dataframe(
headers=["Name", "Score"],
datatype=["str", "number"]
)
button.click(
fn=create_data,
outputs=table
)
demo.launch()
File
File 组件允许用户上传文件。
file = gr.File(
label="Upload a file"
)
常用于上传：
PDF
文本文档
CSV 文件
JSON 文件
图片
数据集
其他支持的文件类型
文件处理值得单独用一章来讲，我们后面会再回到这个话题。
Image
Image 组件允许用户上传或提供图片。
image = gr.Image(
label="Upload an image"
)
适用于：
图像分类
目标检测
图像编辑
OCR
计算机视觉
图像生成工作流
图像类型
处理图像时，你可能会遇到不同的数据表示形式。
例如，根据组件配置和 Gradio 版本的不同，你的函数可能接收到 NumPy 数组或其他支持的表示形式。
在需要时，你可以配置组件使用特定的类型。
比如：
image = gr.Image(
type="numpy"
)
或者使用其他支持的输入类型。
具体行为和可用选项在 Gradio 各版本之间可能有所变化，构建生产应用时请查阅当前文档。
Audio
Gradio 提供了 Audio 组件。
audio = gr.Audio(
label="Upload audio"
)
音频组件可用于：
语音识别
语音转录
音频分类
声音分析
语音交互界面
根据你的应用需求，可以配置让用户上传音频、录音，或两者都支持。
Video
视频处理：
video = gr.Video(
label="Upload video"
)
由此可以实现：
视频分类
帧提取
视频分析
目标跟踪
教育工具
Chatbot
针对对话类应用，Gradio 提供了 Chatbot 组件。
chatbot = gr.Chatbot()
Chatbot 组件可以展示对话消息。
结合 Blocks 构建自定义对话界面时尤其方便。
后续我们会介绍 gr.ChatInterface，它能以更简洁的方式创建聊天应用。
ColorPicker
需要用户选择颜色时，Gradio 提供了颜色选择器。
color = gr.ColorPicker(
label="Choose a color"
)
适用于自定义工具、可视化应用、设计工具等交互场景。
DateTime
有些应用需要获取日期和时间信息。
使用 DateTime 组件即可让用户便捷地选择，无需手动输入。
适用于：
日程安排
时间戳选择
规划工具
时间序列分析
Code
Code 组件用于展示或接收代码。
示例：
code = gr.Code(
language="python",
label="Python Code"
)
在教育应用和开发者工具中尤为实用。
比如做一个 Python 代码解释器：用户粘贴代码，即可获得解释。
Label
Label 组件适合展示分类结果。
例如，模型可能返回：
{
"cat": 0.91,
"dog": 0.07,
"rabbit": 0.02
}
标签式输出可以直观地展示分类结果。
Gallery
应用生成多张图片时，Gallery 组件能将它们集中展示。
gallery = gr.Gallery(
label="Generated Images"
)
适用于以下场景：
图像生成
搜索结果
照片处理
图像对比
视觉数据集
音频、图像和视频本质上仍是数据
媒体组件和文本、数字看起来完全不同，容易让人以为处理逻辑也截然不同。
但从应用角度看，它们只是另一种形式的输入数据。
例如：
def process_image(image):
...
图像直接传入 Python 函数。
同理：
def transcribe(audio):
...
音频传入函数即可。
关键问题始终是：你的函数期望接收什么？想清楚这一点，组件选型就简单多了。
组件配置
Gradio 组件通常暴露大量参数。
例如：
gr.Textbox(
label="Prompt",
placeholder="Enter your prompt...",
lines=5,
max_lines=10
)
不必记住每个参数。先关注影响应用行为和可用性的那几个，其他配置选项随时可以查。
选对组件
假设需要用户输入年龄：
用
gr.Textbox()
也行，但
gr.Number()
通常更合适。
假设需要选择类别：
gr.Dropdown()
更合理。
假设可以多选兴趣：
gr.CheckboxGroup()
更贴切。
假设需要上传 PDF：
gr.File()
即可满足。
目标不是尽可能多地使用组件，而是为用户的任务选择最合适的组件。组合使用组件
真实应用很少只包含一个组件。
以一个情感分析器为例：
import gradio as gr
def analyze_sentiment(text):
return "Positive"
with gr.Blocks() as demo:
gr.Markdown("# Sentiment Analyzer")
text = gr.Textbox(
label="Enter text",
lines=6
)
button = gr.Button("Analyze")
result = gr.Label(
label="Sentiment"
)
button.click(
fn=analyze_sentiment,
inputs=text,
outputs=result
)
demo.launch()
注意，每个组件各司其职。
Markdown 负责介绍应用，文本框接收输入，按钮触发操作，标签展示预测结果。
这已经是一个小而完整的用户界面了。
动手练习
创建一个简单的“学生档案”应用。
它应包含：
一个姓名文本框
一个年级下拉框
一个兴趣复选框组
一个最爱编程语言单选组
一个按钮
以及一个 Markdown 或文本框输出
函数应根据所选内容生成一段简短的个人简介。
重点在于理解组件之间如何连接，而不是把界面做得多么美观。
要点总结
Gradio 为多种用户交互场景提供了组件。
Textbox、Number、Slider和Dropdown覆盖了大多数常见输入场景。Checkbox表示布尔选择。CheckboxGroup支持多选。File、Image、Audio和Video处理媒体和上传内容。Markdown、JSON、Dataframe、Label和Gallery是常用的输出组件。
组件可以通过标签、默认值、占位符、可见性等属性进行配置。
应根据应用实际涉及的数据和交互需求来选择合适的组件。
