Streamlit（十二）- API 参考文档（五）- 输入组件

文章目录

一、按钮类（BUTTONS）
- [1.1 `st.button`：基础按钮](#1.1 st.button：基础按钮)
- - [1.1.1 核心参数](#1.1.1 核心参数)
  - [1.1.2 示例代码](#1.1.2 示例代码)
- [1.2 `st.download_button`：下载按钮](#1.2 st.download_button：下载按钮)
- - [1.2.1 核心参数](#1.2.1 核心参数)
  - [1.2.2 示例代码](#1.2.2 示例代码)
- [1.3 `st.form_submit_button`：表单提交按钮](#1.3 st.form_submit_button：表单提交按钮)
- - [1.3.1 核心参数](#1.3.1 核心参数)
  - [1.3.2 示例代码](#1.3.2 示例代码)
[1.4 `st.link_button`：链接按钮](#1.4 st.link_button：链接按钮)
- - [1.4.1 核心参数](#1.4.1 核心参数)
  - [1.4.2 示例代码](#1.4.2 示例代码)
[1.5 `st.page_link`：页面跳转链接](#1.5 st.page_link：页面跳转链接)
- - [1.5.1 核心参数](#1.5.1 核心参数)
  - [1.5.2 示例代码](#1.5.2 示例代码)
二、选择类（SELECTIONS）
- [2.1 `st.checkbox`：复选框](#2.1 st.checkbox：复选框)
- - [2.1.1 核心参数](#2.1.1 核心参数)
  - [2.1.2 示例代码](#2.1.2 示例代码)
- [2.2 `st.color_picker`：颜色选择器](#2.2 st.color_picker：颜色选择器)
- - [2.2.1 核心参数](#2.2.1 核心参数)
  - [2.2.2 示例代码](#2.2.2 示例代码)
- [2.3 `st.feedback`：反馈组件](#2.3 st.feedback：反馈组件)
- - [2.3.1 核心参数](#2.3.1 核心参数)
  - [2.3.2 返回值](#2.3.2 返回值)
  - [2.3.3 示例代码](#2.3.3 示例代码)
- [2.4 `st.multiselect`：多选下拉框](#2.4 st.multiselect：多选下拉框)
- - [2.4.1 核心参数](#2.4.1 核心参数)
  - [2.4.2 返回值](#2.4.2 返回值)
  - [2.4.3 示例代码](#2.4.3 示例代码)
- [2.5 `st.pills`：标签选择器](#2.5 st.pills：标签选择器)
- - [2.5.1 核心参数](#2.5.1 核心参数)
  - [2.5.2 返回值](#2.5.2 返回值)
  - [2.5.3 示例代码](#2.5.3 示例代码)
- [2.6 `st.radio`：单选按钮组](#2.6 st.radio：单选按钮组)
- - [2.6.1 核心参数](#2.6.1 核心参数)
  - [2.6.2 返回值](#2.6.2 返回值)
  - [2.6.3 示例代码](#2.6.3 示例代码)
- [2.7 `st.segmented_control`：分段控制器](#2.7 st.segmented_control：分段控制器)
- - [2.7.1 核心参数](#2.7.1 核心参数)
  - [2.7.2 返回值](#2.7.2 返回值)
  - [2.7.3 示例代码](#2.7.3 示例代码)
- [2.8 `st.selectbox`：下拉选择框](#2.8 st.selectbox：下拉选择框)
- - [2.8.1 核心参数](#2.8.1 核心参数)
  - [2.8.2 返回值](#2.8.2 返回值)
  - [2.8.3 示例代码](#2.8.3 示例代码)
- [2.9 `st.select_slider`：选择滑块](#2.9 st.select_slider：选择滑块)
- - [2.9.1 核心参数](#2.9.1 核心参数)
  - [2.9.2 返回值](#2.9.2 返回值)
  - [2.9.3 示例代码](#2.9.3 示例代码)
- [2.10 `st.toggle`：开关切换](#2.10 st.toggle：开关切换)
- - [2.10.1 核心参数](#2.10.1 核心参数)
  - [2.10.2 返回值](#2.10.2 返回值)
  - [2.10.3 示例代码](#2.10.3 示例代码)
三、数值类（NUMERIC）
- [3.1 `st.number_input`：数值输入框](#3.1 st.number_input：数值输入框)
- - [3.1.1 核心参数](#3.1.1 核心参数)
  - [3.1.2 返回值](#3.1.2 返回值)
  - [3.1.3 示例代码](#3.1.3 示例代码)
- [3.2 `st.slider`：数值滑块](#3.2 st.slider：数值滑块)
- - [3.2.1 核心参数](#3.2.1 核心参数)
  - [3.2.2 返回值](#3.2.2 返回值)
  - [3.2.3 示例代码](#3.2.3 示例代码)
[四、日期与时间类（DATE AND TIME）](#四、日期与时间类（DATE AND TIME）)
[4. 日期与时间类组件（Date and Time）](#4. 日期与时间类组件（Date and Time）)
- [4.1 `st.date_input`：日期选择器](#4.1 st.date_input：日期选择器)
- - [4.1.1 核心参数](#4.1.1 核心参数)
  - [4.1.2 返回值](#4.1.2 返回值)
  - [4.1.3 示例代码](#4.1.3 示例代码)
- [4.2 `st.time_input`：时间选择器](#4.2 st.time_input：时间选择器)
- - [4.2.1 核心参数](#4.2.1 核心参数)
  - [4.2.2 返回值](#4.2.2 返回值)
  - [4.2.3 示例代码](#4.2.3 示例代码)
五、文本类（TEXT）
- [5.1 `st.chat_input`：聊天输入框](#5.1 st.chat_input：聊天输入框)
- - [5.1.1 核心参数](#5.1.1 核心参数)
  - [5.1.2 返回值](#5.1.2 返回值)
  - [5.1.3 示例代码](#5.1.3 示例代码)
- [5.2 `st.text_area`：多行文本输入框](#5.2 st.text_area：多行文本输入框)
- - [5.2.1 核心参数](#5.2.1 核心参数)
  - [5.2.2 返回值](#5.2.2 返回值)
  - [5.2.3 示例代码](#5.2.3 示例代码)
- [5.3 `st.text_input`：单行文本输入框](#5.3 st.text_input：单行文本输入框)
- - [5.3.1 核心参数](#5.3.1 核心参数)
  - [5.3.2 返回值](#5.3.2 返回值)
  - [5.3.3 示例代码](#5.3.3 示例代码)
[六、媒体与文件类（MEDIA AND FILES）](#六、媒体与文件类（MEDIA AND FILES）)
- [6.1 `st.audio_input`：音频录制输入](#6.1 st.audio_input：音频录制输入)
- - [6.1.1 核心参数](#6.1.1 核心参数)
  - [6.1.2 返回值](#6.1.2 返回值)
  - [6.1.3 示例代码](#6.1.3 示例代码)
- [6.2 `st.camera_input`：摄像头拍照输入](#6.2 st.camera_input：摄像头拍照输入)
- - [6.2.1 核心参数](#6.2.1 核心参数)
  - [6.2.2 返回值](#6.2.2 返回值)
  - [6.2.3 示例代码](#6.2.3 示例代码)
- [6.3 `st.data_editor`：数据编辑器](#6.3 st.data_editor：数据编辑器)
- - [6.3.1 核心参数](#6.3.1 核心参数)
  - [6.3.2 返回值](#6.3.2 返回值)
  - [6.3.3 示例代码](#6.3.3 示例代码)
- [6.4 `st.file_uploader`：文件上传器](#6.4 st.file_uploader：文件上传器)
- - [6.4.1 核心参数](#6.4.1 核心参数)
  - [6.4.2 返回值](#6.4.2 返回值)
  - [6.4.3 示例代码](#6.4.3 示例代码)

一、按钮类（BUTTONS）

1.1 `st.button`：基础按钮

Streamlit 中最常用的交互按钮，支持自定义样式、图标和点击回调。

1.1.1 核心参数

参数	说明
`label`	按钮显示文本，支持部分 Markdown 格式（加粗、斜体、链接、Emoji 等）
`key`	组件唯一标识，用于存储状态，不填则自动生成
`help`	鼠标悬停时显示的提示信息，支持 Markdown
`on_click`	点击按钮时触发的回调函数
`args`/`kwargs`	传递给回调函数的参数
`type`	按钮样式类型： - `"primary"`：主色强调按钮 - `"secondary"`（默认）：普通按钮 - `"tertiary"`：无背景/边框的文字按钮
`icon`	按钮图标，支持单个 Emoji 字符或 Material Symbols 图标（格式 `:material/icon_name:`）
`disabled`	是否禁用按钮（默认 `False`）
`width`	按钮宽度，可选 `"content"`（默认，自适应内容）、`"stretch"`（占满容器）或固定像素值

1.1.2 示例代码

python 复制代码

import streamlit as st

# 1. 不同类型的按钮
st.button("重置", type="primary")
if st.button("Say hello"):
    st.write("Why hello there")
else:
    st.write("Goodbye")
if st.button("Aloha", type="tertiary"):
    st.write("Ciao")

# 2. 带图标的按钮
left, middle, right = st.columns(3)
if left.button("Plain button", width="stretch"):
    left.markdown("You clicked the plain button.")
if middle.button("Emoji button", icon="😀", width="stretch"):
    middle.markdown("You clicked the emoji button.")
if right.button("Material button", icon=":material/mood:", width="stretch"):
    right.markdown("You clicked the Material button.")

1.2 `st.download_button`：下载按钮

用于提供文件下载功能的按钮，支持下载文本、字节流、DataFrame 等数据。

1.2.1 核心参数

参数	说明
`label`	按钮显示文本，支持部分 Markdown 格式
`data`	要下载的数据，支持字符串、字节流、文件对象等
`file_name`	下载文件的默认名称（如 `"data.csv"`）
`mime`	文件的 MIME 类型，默认自动识别（文本为 `text/plain`，二进制为 `application/octet-stream`）
`on_click`	按钮点击时的响应方式： - `"rerun"`（默认）：下载后重新运行应用 - `"ignore"`：仅下载不触发重运行 - 回调函数：下载前执行
`icon`/`disabled`/`width`	与 `st.button` 用法一致

1.2.2 示例代码

python 复制代码

import streamlit as st
import pandas as pd
import numpy as np

# 示例1：下载 DataFrame 为 CSV 文件
@st.cache_data
def get_data():
    return pd.DataFrame(np.random.randn(50, 20), columns=[f"col {i}" for i in range(20)])

@st.cache_data
def convert_df(df):
    return df.to_csv(index=False).encode("utf-8")

df = get_data()
csv = convert_df(df)

st.download_button(
    label="Download CSV",
    data=csv,
    file_name="data.csv",
    mime="text/csv",
    icon=":material/download:"
)

# 示例2：下载文本内容
message = st.text_area("Message", value="Lorem ipsum.\nStreamlit is cool.")
if st.button("Prepare download"):
    st.download_button(
        label="Download text",
        data=message,
        file_name="message.txt",
        on_click="ignore",
        type="primary",
        icon=":material/download:"
    )

# 示例3：下载本地文件
with open("flower.png", "rb") as file:
    st.download_button(
        label="Download image",
        data=file,
        file_name="flower.png",
        mime="image/png"
    )

1.3 `st.form_submit_button`：表单提交按钮

仅能在 st.form 内部使用的提交按钮，点击后会批量提交表单内所有组件的值。

1.3.1 核心参数

参数	说明
`label`	按钮显示文本，默认值为 `"Submit"`
`help`	鼠标悬停提示信息
`on_click`/`args`/`kwargs`	点击按钮时触发的回调函数及参数
`type`/`icon`/`disabled`/`width`	与 `st.button` 用法一致

1.3.2 示例代码

python 复制代码

import streamlit as st

with st.form("my_form"):
    st.write("请填写表单：")
    name = st.text_input("姓名")
    age = st.number_input("年龄", min_value=0, max_value=120)
    gender = st.radio("性别", ["男", "女", "其他"])
    
    # 表单提交按钮
    submitted = st.form_submit_button("提交", type="primary", icon=":material/send:")

if submitted:
    st.success(f"表单提交成功！\n姓名：{name}\n年龄：{age}\n性别：{gender}")

1.4 `st.link_button`：链接按钮

用于打开外部链接的按钮，点击后会在新标签页中打开指定 URL。

1.4.1 核心参数

参数	说明
`label`	按钮显示文本，支持部分 Markdown 格式
`url`	点击后跳转的目标 URL（必须是完整链接）
`help`	鼠标悬停提示信息
`type`	按钮样式：`"primary"`/`"secondary"`（默认）/`"tertiary"`
`icon`	按钮图标，支持单个 Emoji 或 Material Symbols 图标
`disabled`	是否禁用按钮
`width`	按钮宽度，可选 `"content"`（默认）、`"stretch"` 或固定像素值

1.4.2 示例代码

python 复制代码

import streamlit as st

# 打开 Streamlit 官方画廊
st.link_button("Go to gallery", "https://streamlit.io/gallery")

# 带图标和主色样式的链接按钮
st.link_button(
    "查看文档", 
    "https://docs.streamlit.io/", 
    type="primary", 
    icon=":material/book:"
)

1.5 `st.page_link`：页面跳转链接

用于在多页应用中跳转页面，或打开外部链接。

1.5.1 核心参数

参数	说明
`page`	目标页面路径（相对路径，如 `pages/page1.py`）或外部 URL（必须以 `http://`/`https://` 开头）
`label`	链接显示文本（外部页面必须提供标签）
`icon`	链接图标，支持单个 Emoji 或 Material Symbols 图标
`help`	鼠标悬停提示信息
`disabled`	是否禁用链接
`width`	链接按钮宽度，可选 `"content"`（默认）、`"stretch"` 或固定像素值

1.5.2 示例代码

python 复制代码

import streamlit as st

# 多页应用内跳转
st.page_link("your_app.py", label="Home", icon="🏠")
st.page_link("pages/page_1.py", label="Page 1", icon="📄")
st.page_link("pages/page_2.py", label="Page 2", icon="📄", disabled=True)

# 外部链接跳转
st.page_link("http://www.google.com", label="Google", icon="🌐")

二、选择类（SELECTIONS）

2.1 `st.checkbox`：复选框

用于布尔值选择的组件，支持单个勾选或取消勾选操作。

2.1.1 核心参数

参数	说明
`label`	复选框显示文本，支持部分 Markdown 格式
`value`	默认是否勾选（默认 `False`）
`key`	组件唯一标识
`help`	鼠标悬停提示信息
`on_change`	勾选状态变化时触发的回调函数
`disabled`	是否禁用复选框
`label_visibility`	标签可见性：`"visible"`（默认）/`"hidden"`/`"collapsed"`
`width`	组件宽度，可选 `"content"`（默认）、`"stretch"` 或固定像素值

2.1.2 示例代码

python 复制代码

import streamlit as st

agree = st.checkbox("I agree")
if agree:
    st.write("Great!")

2.2 `st.color_picker`：颜色选择器

用于选择颜色的组件，返回十六进制颜色值。

2.2.1 核心参数

参数	说明
`label`	选择器显示文本，支持部分 Markdown 格式
`value`	默认颜色值（十六进制字符串，如 `"#00f900"`，默认黑色）
`key`	组件唯一标识
`help`	鼠标悬停提示信息
`on_change`	颜色变化时触发的回调函数
`disabled`	是否禁用选择器
`label_visibility`	标签可见性

2.2.2 示例代码

python 复制代码

import streamlit as st

color = st.color_picker("Pick A Color", "#00f900")
st.write("The current color is", color)

2.3 `st.feedback`：反馈组件

用于用户评分/反馈的组件，支持三种样式：点赞、表情、星级。

2.3.1 核心参数

参数	说明
`options`	反馈样式： - `"thumbs"`（默认）：点赞/点踩按钮 - `"faces"`：表情评分（5级） - `"stars"`：星级评分（5级）
`key`	组件唯一标识
`disabled`	是否禁用组件
`on_change`	反馈选择变化时触发的回调函数

2.3.2 返回值

thumbs 模式：0（点踩）/1（点赞）/None（未选择）
faces/stars 模式：0（最低）到 4（最高）/None（未选择）

2.3.3 示例代码

python 复制代码

import streamlit as st

# 星级反馈
sentiment_mapping = ["one", "two", "three", "four", "five"]
selected = st.feedback("stars")
if selected is not None:
    st.markdown(f"You selected {sentiment_mapping[selected]} star(s).")

# 点赞反馈
sentiment_mapping = [":material/thumb_down:", ":material/thumb_up:"]
selected = st.feedback("thumbs")
if selected is not None:
    st.markdown(f"You selected: {sentiment_mapping[selected]}")

2.4 `st.multiselect`：多选下拉框

支持多选的下拉选择组件，可设置最大选择数量。

2.4.1 核心参数

参数	说明
`label`	下拉框显示文本，支持部分 Markdown 格式
`options`	可选值列表（如 `["Red", "Green", "Blue"]`）
`default`	默认选中值列表
`format_func`	自定义选项显示格式的函数
`max_selections`	最大可选择数量
`placeholder`	未选择时的提示文本（默认 `"Choose an option"`）
`disabled`	是否禁用下拉框
`label_visibility`	标签可见性

2.4.2 返回值

包含所有选中值的列表

2.4.3 示例代码

python 复制代码

import streamlit as st

options = st.multiselect(
    "What are your favorite colors",
    ["Green", "Yellow", "Red", "Blue"],
    ["Yellow", "Red"]
)
st.write("You selected:", options)

2.5 `st.pills`：标签选择器

以按钮组形式展示选项的选择组件，支持单选或多选模式。

2.5.1 核心参数

参数	说明
`label`	组件显示文本，支持部分 Markdown 格式
`options`	选项列表
`selection_mode`	选择模式：`"single"`（默认，单选）/`"multi"`（多选）
`default`	默认选中值（单选模式为单个值，多选模式为列表）
`format_func`	自定义选项显示格式的函数
`disabled`	是否禁用组件
`label_visibility`	标签可见性

2.5.2 返回值

单选模式：选中的单个选项值（或 None）
多选模式：包含所有选中值的列表

2.5.3 示例代码

python 复制代码

import streamlit as st

# 多选标签
options = ["North", "East", "South", "West"]
selection = st.pills("Directions", options, selection_mode="multi")
st.markdown(f"Your selected options: {selection}.")

# 带图标的单选标签
option_map = {
    0: ":material/add:",
    1: ":material/zoom_in:",
    2: ":material/zoom_out:",
    3: ":material/zoom_out_map:",
}
selection = st.pills(
    "Tool",
    options=option_map.keys(),
    format_func=lambda option: option_map[option],
    selection_mode="single",
)
st.write(
    "Your selected option: "
    f"{None if selection is None else option_map[selection]}"
)

2.6 `st.radio`：单选按钮组

提供一组互斥选项的单选组件，支持水平/垂直布局、自定义选项样式和说明文字。

2.6.1 核心参数

参数	说明
`label`	按钮组显示文本，支持部分 Markdown 格式
`options`	选项列表（如 `["Comedy", "Drama", "Documentary"]`）
`index`	默认选中项的索引（默认 `0`，设为 `None` 时初始未选中）
`format_func`	自定义选项显示格式的函数
`horizontal`	是否水平排列按钮（默认 `False`，垂直排列）
`captions`	每个选项下方的说明文字列表
`disabled`	是否禁用按钮组
`label_visibility`	标签可见性：`"visible"`（默认）/`"hidden"`/`"collapsed"`

2.6.2 返回值

选中的选项值（或 None，初始未选中时）

2.6.3 示例代码

python 复制代码

import streamlit as st

# 带说明文字的单选按钮组
genre = st.radio(
    "What's your favorite movie genre",
    [":rainbow[Comedy]", "***Drama***", "Documentary :movie_camera:"],
    captions=[
        "Laugh out loud.",
        "Get the popcorn.",
        "Never stop learning.",
    ],
)

if genre == ":rainbow[Comedy]":
    st.write("You selected comedy.")
else:
    st.write("You didn't select comedy.")

# 初始未选中的单选按钮组
genre = st.radio(
    "What's your favorite movie genre",
    [":rainbow[Comedy]", "***Drama***", "Documentary :movie_camera:"],
    index=None,
)
st.write("You selected:", genre)

2.7 `st.segmented_control`：分段控制器

以分段按钮形式展示选项的组件，支持单选或多选模式，类似标签选择器但样式更紧凑。

2.7.1 核心参数

参数	说明
`label`	组件显示文本，支持部分 Markdown 格式
`options`	选项列表
`selection_mode`	选择模式：`"single"`（默认，单选）/`"multi"`（多选）
`default`	默认选中值（单选模式为单个值，多选模式为列表）
`format_func`	自定义选项显示格式的函数
`disabled`	是否禁用组件
`label_visibility`	标签可见性

2.7.2 返回值

单选模式：选中的单个选项值（或 None）
多选模式：包含所有选中值的列表

2.7.3 示例代码

python 复制代码

import streamlit as st

# 多选分段控制器
options = ["North", "East", "South", "West"]
selection = st.segmented_control("Directions", options, selection_mode="multi")
st.markdown(f"Your selected options: {selection}.")

# 带图标的单选分段控制器
option_map = {
    0: ":material/add:",
    1: ":material/zoom_in:",
    2: ":material/zoom_out:",
    3: ":material/zoom_out_map:",
}
selection = st.segmented_control(
    "Tool",
    options=option_map.keys(),
    format_func=lambda option: option_map[option],
    selection_mode="single",
)
st.write(
    "Your selected option: "
    f"{None if selection is None else option_map[selection]}"
)

2.8 `st.selectbox`：下拉选择框

标准的下拉选择组件，适合选项较多时使用，支持自定义提示文本和初始状态。

2.8.1 核心参数

参数	说明
`label`	下拉框显示文本，支持部分 Markdown 格式
`options`	选项列表
`index`	默认选中项的索引（默认 `0`，设为 `None` 时初始未选中）
`placeholder`	未选择时的提示文本（默认 `"Choose an option"`）
`format_func`	自定义选项显示格式的函数
`disabled`	是否禁用下拉框
`label_visibility`	标签可见性

2.8.2 返回值

选中的选项值（或 None，初始未选中时）

2.8.3 示例代码

python 复制代码

import streamlit as st

# 基础下拉选择框
option = st.selectbox(
    "How would you like to be contacted?",
    ("Email", "Home phone", "Mobile phone"),
)
st.write("You selected:", option)

# 初始未选中的下拉选择框
option = st.selectbox(
    "How would you like to be contacted?",
    ("Email", "Home phone", "Mobile phone"),
    index=None,
    placeholder="Select contact method...",
)
st.write("You selected:", option)

2.9 `st.select_slider`：选择滑块

用于从选项列表中选择值的滑块组件，支持范围选择，可自定义选项显示格式。

2.9.1 核心参数

参数	说明
`label`	滑块显示文本，支持部分 Markdown 格式
`options`	选项列表（支持任意数据类型）
`value`	默认选中值（单个值或包含两个值的列表/元组，用于范围选择）
`format_func`	自定义选项显示格式的函数
`disabled`	是否禁用滑块
`label_visibility`	标签可见性

2.9.2 返回值

单选模式：选中的选项值
范围选择模式：包含起始值和结束值的元组

2.9.3 示例代码

python 复制代码

import streamlit as st

# 基础选择滑块
color = st.select_slider(
    "Select a color of the rainbow",
    options=[
        "red",
        "orange",
        "yellow",
        "green",
        "blue",
        "indigo",
        "violet",
    ],
)
st.write("My favorite color is", color)

# 范围选择滑块
start_color, end_color = st.select_slider(
    "Select a range of color wavelength",
    options=[
        "red",
        "orange",
        "yellow",
        "green",
        "blue",
        "indigo",
        "violet",
    ],
    value=("red", "blue"),
)
st.write("You selected wavelengths between", start_color, "and", end_color)

2.10 `st.toggle`：开关切换

用于布尔值选择的开关组件，适合表示功能开启/关闭状态。

2.10.1 核心参数

参数	说明
`label`	开关显示文本，支持部分 Markdown 格式
`value`	默认状态（默认 `False`，关闭）
`disabled`	是否禁用开关
`label_visibility`	标签可见性

2.10.2 返回值

布尔值：True（开启）或 False（关闭）

2.10.3 示例代码

python 复制代码

import streamlit as st

on = st.toggle("Activate feature")
if on:
    st.write("Feature activated!")

三、数值类（NUMERIC）

3.1 `st.number_input`：数值输入框

用于直接输入数字的组件，支持整数、浮点数，可设置范围、步长和显示格式。

3.1.1 核心参数

参数	说明
`label`	输入框显示文本，支持部分 Markdown 格式
`min_value`/`max_value`	允许输入的最小/最大值（不设置则无限制）
`value`	默认值（设为 `None` 时初始为空，需用户输入）
`step`	输入步长（整数默认 `1`，浮点数默认 `0.01`）
`format`	显示格式字符串（如 `"%0.1f"` 表示保留1位小数）
`placeholder`	未输入时的提示文本
`disabled`	是否禁用输入框
`label_visibility`	标签可见性

3.1.2 返回值

输入的数值（整数/浮点数，或 None，初始未输入时）

3.1.3 示例代码

python 复制代码

import streamlit as st

# 基础数值输入框
number = st.number_input("Insert a number")
st.write("The current number is ", number)

# 初始为空的数值输入框
number = st.number_input(
    "Insert a number", value=None, placeholder="Type a number..."
)
st.write("The current number is ", number)

3.2 `st.slider`：数值滑块

通过滑动条选择数值的组件，支持整数、浮点数、日期/时间类型，也可设置范围选择。

3.2.1 核心参数

参数	说明
`label`	滑块显示文本，支持部分 Markdown 格式
`min_value`/`max_value`	滑块的最小/最大值
`value`	默认值（单个值或包含两个值的列表/元组，用于范围选择）
`step`	滑动步长（整数默认 `1`，浮点数默认 `0.01`，日期/时间类型支持 `timedelta`）
`format`	显示格式字符串（如 `"%d"` 表示整数，`"MM/DD/YY - hh:mm"` 表示日期时间格式）
`disabled`	是否禁用滑块
`label_visibility`	标签可见性

3.2.2 返回值

单选模式：选中的数值（整数/浮点数/日期/时间/日期时间）
范围选择模式：包含起始值和结束值的元组

3.2.3 示例代码

python 复制代码

import streamlit as st
from datetime import time, datetime

# 基础数值滑块
age = st.slider("How old are you?", 0, 130, 25)
st.write("I'm ", age, "years old")

# 范围选择滑块
values = st.slider("Select a range of values", 0.0, 100.0, (25.0, 75.0))
st.write("Values:", values)

# 时间范围滑块
appointment = st.slider(
    "Schedule your appointment:", value=(time(11, 30), time(12, 45))
)
st.write("You're scheduled for:", appointment)

# 日期时间滑块
start_time = st.slider(
    "When do you start?",
    value=datetime(2020, 1, 1, 9, 30),
    format="MM/DD/YY - hh:mm",
)
st.write("Start time:", start_time)

四、日期与时间类（DATE AND TIME）

4. 日期与时间类组件（Date and Time）

4.1 `st.date_input`：日期选择器

用于选择日期的组件，支持范围选择，可自定义格式和可选日期范围。

4.1.1 核心参数

参数	说明
`label`	选择器显示文本，支持部分 Markdown 格式
`value`	默认日期（支持 `"today"`、`datetime.date` 对象、ISO 日期字符串，或列表/元组表示日期范围；设为 `None` 时初始为空）
`min_value`/`max_value`	可选的最小/最大日期（默认分别为当前日期前后10年）
`format`	日期显示格式（默认 `"YYYY/MM/DD"`，支持 `"DD/MM/YYYY"`、`"MM/DD/YYYY"` 等）
`disabled`	是否禁用选择器
`label_visibility`	标签可见性

4.1.2 返回值

单选模式：选中的 datetime.date 对象（或 None，初始未选中时）
范围选择模式：包含起始日期和结束日期的元组

4.1.3 示例代码

python 复制代码

import datetime
import streamlit as st

# 基础日期选择器
d = st.date_input("When's your birthday", datetime.date(2019, 7, 6))
st.write("Your birthday is:", d)

# 日期范围选择器
today = datetime.datetime.now()
next_year = today.year + 1
jan_1 = datetime.date(next_year, 1, 1)
dec_31 = datetime.date(next_year, 12, 31)

d = st.date_input(
    "Select your vacation for next year",
    (jan_1, datetime.date(next_year, 1, 7)),
    jan_1,
    dec_31,
    format="MM.DD.YYYY",
)

# 初始为空的日期选择器
d = st.date_input("When's your birthday", value=None)
st.write("Your birthday is:", d)

4.2 `st.time_input`：时间选择器

用于选择时间的组件，支持自定义步长和初始状态。

4.2.1 核心参数

参数	说明
`label`	选择器显示文本，支持部分 Markdown 格式
`value`	默认时间（支持 `"now"`、`datetime.time` 对象、ISO 时间字符串；设为 `None` 时初始为空）
`step`	时间选择步长（默认 `900` 秒，即15分钟，也可使用 `datetime.timedelta`）
`disabled`	是否禁用选择器
`label_visibility`	标签可见性

4.2.2 返回值

选中的 datetime.time 对象（或 None，初始未选中时）

4.2.3 示例代码

python 复制代码

import datetime
import streamlit as st

# 基础时间选择器
t = st.time_input("Set an alarm for", datetime.time(8, 45))
st.write("Alarm is set for", t)

# 初始为空的时间选择器
t = st.time_input("Set an alarm for", value=None)
st.write("Alarm is set for", t)

五、文本类（TEXT）

5.1 `st.chat_input`：聊天输入框

专门为聊天界面设计的输入框，默认固定在页面底部，也可嵌入布局容器中。

5.1.1 核心参数

参数	说明
`placeholder`	输入框为空时的提示文本（默认 `"Your message"`）
`max_chars`	允许输入的最大字符数（不设置则无限制）
`disabled`	是否禁用输入框
`on_submit`	提交消息时触发的回调函数

5.1.2 返回值

用户提交的消息文本（非空时返回，否则返回 None）

5.1.3 示例代码

python 复制代码

import streamlit as st

# 基础聊天输入框（固定在底部）
prompt = st.chat_input("Say something")
if prompt:
    st.write(f"User has sent the following prompt: {prompt}")

# 嵌入侧边栏的聊天输入框
with st.sidebar:
    messages = st.container(height=300)
    if prompt := st.chat_input("Say something"):
        messages.chat_message("user").write(prompt)
        messages.chat_message("assistant").write(f"Echo: {prompt}")

5.2 `st.text_area`：多行文本输入框

支持多行文本输入的组件，适合输入大段文字，可自定义高度和字符限制。

5.2.1 核心参数

参数	说明
`label`	输入框显示文本，支持部分 Markdown 格式
`value`	默认文本内容（设为 `None` 时初始为空）
`height`	输入框高度（像素，默认显示3行，最小68像素）
`max_chars`	允许输入的最大字符数（不设置则无限制）
`placeholder`	输入框为空时的提示文本
`disabled`	是否禁用输入框
`label_visibility`	标签可见性

5.2.2 返回值

输入的文本内容（或 None，初始未输入时）

5.2.3 示例代码

python 复制代码

import streamlit as st

txt = st.text_area(
    "Text to analyze",
    "It was the best of times, it was the worst of times, it was the age of "
    "wisdom, it was the age of foolishness, it was the epoch of belief, it "
    "was the epoch of incredulity, it was the season of Light, it was the "
    "season of Darkness, it was the spring of hope, it was the winter of "
    "despair, (...)"
)
st.write(f"You wrote {len(txt)} characters.")

5.3 `st.text_input`：单行文本输入框

单行文本输入组件，支持普通文本和密码模式，可自定义提示文本和字符限制。

5.3.1 核心参数

参数	说明
`label`	输入框显示文本，支持部分 Markdown 格式
`value`	默认文本内容（设为 `None` 时初始为空）
`max_chars`	允许输入的最大字符数（不设置则无限制）
`type`	输入框类型：`"default"`（普通文本，默认）/`"password"`（密码模式，内容被隐藏）
`placeholder`	输入框为空时的提示文本
`disabled`	是否禁用输入框
`label_visibility`	标签可见性

5.3.2 返回值

输入的文本内容（或 None，初始未输入时）

5.3.3 示例代码

python 复制代码

import streamlit as st

# 基础文本输入框
title = st.text_input("Movie title", "Life of Brian")
st.write("The current movie title is", title)

# 带占位符的文本输入框
text_input = st.text_input(
    "Enter some text",
    placeholder="This is a placeholder"
)
if text_input:
    st.write("You entered: ", text_input)

六、媒体与文件类（MEDIA AND FILES）

6.1 `st.audio_input`：音频录制输入

通过麦克风录制音频的组件，返回 WAV 格式的音频数据。

6.1.1 核心参数

参数	说明
`label`	组件显示文本，支持部分 Markdown 格式
`key`	组件唯一标识
`help`	鼠标悬停提示信息
`disabled`	是否禁用组件
`label_visibility`	标签可见性

6.1.2 返回值

UploadedFile 对象（可直接用于 st.audio 组件播放，或读取字节数据），未录制时返回 None

6.1.3 示例代码

python 复制代码

import streamlit as st

audio_value = st.audio_input("Record a voice message")
if audio_value:
    st.audio(audio_value)

6.2 `st.camera_input`：摄像头拍照输入

通过摄像头拍摄照片的组件，返回图片数据，支持与图像处理库（如 Pillow、OpenCV）结合使用。

6.2.1 核心参数

参数	说明
`label`	组件显示文本，支持部分 Markdown 格式
`key`	组件唯一标识
`help`	鼠标悬停提示信息
`disabled`	是否禁用组件
`label_visibility`	标签可见性

6.2.2 返回值

UploadedFile 对象（可直接用于 st.image 组件显示，或读取字节数据），未拍摄时返回 None

6.2.3 示例代码

python 复制代码

import streamlit as st
from PIL import Image
import numpy as np

enable = st.checkbox("Enable camera")
picture = st.camera_input("Take a picture", disabled=not enable)

if picture:
    # 显示原始图片
    st.image(picture)
    
    # 转换为 PIL 图像并处理
    img = Image.open(picture)
    img_array = np.array(img)
    st.write("图片形状：", img_array.shape)

6.3 `st.data_editor`：数据编辑器

交互式表格组件，支持编辑 DataFrame 等数据结构，可自定义列配置和编辑权限。

6.3.1 核心参数

参数	说明
`data`	要编辑的数据（支持 `pandas.DataFrame`、`numpy.ndarray` 等格式）
`width`/`height`	编辑器的宽度/高度（像素）
`use_container_width`	是否占满父容器宽度（默认 `False`）
`hide_index`	是否隐藏索引列
`column_config`	列配置字典，可设置列标题、编辑类型、格式等
`num_rows`	行编辑模式：`"fixed"`（默认，固定行数）/`"dynamic"`（可添加/删除行）
`disabled`	是否禁用编辑（或指定禁用的列名列表）

6.3.2 返回值

编辑后的数据（保持原数据类型，如 pandas.DataFrame）

6.3.3 示例代码

python 复制代码

import streamlit as st
import pandas as pd

df = pd.DataFrame(
    [
        {"command": "st.selectbox", "rating": 4, "is_widget": True},
        {"command": "st.balloons", "rating": 5, "is_widget": False},
        {"command": "st.time_input", "rating": 3, "is_widget": True},
    ]
)

# 基础数据编辑器
edited_df = st.data_editor(df)
favorite_command = edited_df.loc[edited_df["rating"].idxmax()]["command"]
st.markdown(f"Your favorite command is **{favorite_command}** 🎈")

# 动态行编辑模式
edited_df = st.data_editor(df, num_rows="dynamic")

6.4 `st.file_uploader`：文件上传器

用于上传文件的组件，支持单文件/多文件上传，可限制文件类型。

6.4.1 核心参数

参数	说明
`label`	组件显示文本，支持部分 Markdown 格式
`type`	允许上传的文件扩展名列表（如 `["png", "jpg"]`，默认无限制）
`accept_multiple_files`	是否允许多文件上传（默认 `False`）
`key`	组件唯一标识
`help`	鼠标悬停提示信息
`disabled`	是否禁用上传器
`label_visibility`	标签可见性

6.4.2 返回值

单文件模式：UploadedFile 对象（或 None，未上传时）
多文件模式：包含多个 UploadedFile 对象的列表（未上传时为空列表）

6.4.3 示例代码

python 复制代码

import streamlit as st
import pandas as pd
from io import StringIO

# 单文件上传
uploaded_file = st.file_uploader("Choose a CSV file")
if uploaded_file is not None:
    # 读取文件数据
    dataframe = pd.read_csv(uploaded_file)
    st.write("上传的文件内容：", dataframe)

# 多文件上传
uploaded_files = st.file_uploader(
    "Choose multiple files", accept_multiple_files=True
)
for uploaded_file in uploaded_files:
    st.write("文件名：", uploaded_file.name)
    bytes_data = uploaded_file.read()
    st.write("文件内容（字节数）：", len(bytes_data))

Streamlit（十二）- API 参考文档（五）- 输入组件

文章目录

一、按钮类（BUTTONS）

1.1 st.button：基础按钮

1.1.1 核心参数

1.1.2 示例代码

1.2 st.download_button：下载按钮

1.2.1 核心参数

1.2.2 示例代码

1.3 st.form_submit_button：表单提交按钮

1.3.1 核心参数

1.3.2 示例代码

1.4 st.link_button：链接按钮

1.4.1 核心参数

1.4.2 示例代码

1.5 st.page_link：页面跳转链接

1.5.1 核心参数

1.5.2 示例代码

二、选择类（SELECTIONS）

2.1 st.checkbox：复选框

2.1.1 核心参数

2.1.2 示例代码

2.2 st.color_picker：颜色选择器

2.2.1 核心参数

2.2.2 示例代码

2.3 st.feedback：反馈组件

2.3.1 核心参数

2.3.2 返回值

2.3.3 示例代码

2.4 st.multiselect：多选下拉框

2.4.1 核心参数

2.4.2 返回值

2.4.3 示例代码

2.5 st.pills：标签选择器

2.5.1 核心参数

2.5.2 返回值

2.5.3 示例代码

2.6 st.radio：单选按钮组

2.6.1 核心参数

2.6.2 返回值

2.6.3 示例代码

2.7 st.segmented_control：分段控制器

2.7.1 核心参数

2.7.2 返回值

2.7.3 示例代码

2.8 st.selectbox：下拉选择框

2.8.1 核心参数

2.8.2 返回值

2.8.3 示例代码

2.9 st.select_slider：选择滑块

2.9.1 核心参数

2.9.2 返回值

2.9.3 示例代码

2.10 st.toggle：开关切换

2.10.1 核心参数

2.10.2 返回值

2.10.3 示例代码

三、数值类（NUMERIC）

3.1 st.number_input：数值输入框

3.1.1 核心参数

3.1.2 返回值

3.1.3 示例代码

3.2 st.slider：数值滑块

3.2.1 核心参数

3.2.2 返回值

3.2.3 示例代码

四、日期与时间类（DATE AND TIME）

4. 日期与时间类组件（Date and Time）

4.1 st.date_input：日期选择器

4.1.1 核心参数

4.1.2 返回值

4.1.3 示例代码

4.2 st.time_input：时间选择器

4.2.1 核心参数

4.2.2 返回值

4.2.3 示例代码

五、文本类（TEXT）

5.1 st.chat_input：聊天输入框

5.1.1 核心参数

5.1.2 返回值

1.1 `st.button`：基础按钮

1.2 `st.download_button`：下载按钮

1.3 `st.form_submit_button`：表单提交按钮

1.4 `st.link_button`：链接按钮

1.5 `st.page_link`：页面跳转链接

2.1 `st.checkbox`：复选框

2.2 `st.color_picker`：颜色选择器

2.3 `st.feedback`：反馈组件

2.4 `st.multiselect`：多选下拉框

2.5 `st.pills`：标签选择器

2.6 `st.radio`：单选按钮组

2.7 `st.segmented_control`：分段控制器

2.8 `st.selectbox`：下拉选择框

2.9 `st.select_slider`：选择滑块

2.10 `st.toggle`：开关切换

3.1 `st.number_input`：数值输入框

3.2 `st.slider`：数值滑块

4.1 `st.date_input`：日期选择器

4.2 `st.time_input`：时间选择器

5.1 `st.chat_input`：聊天输入框

5.2 `st.text_area`：多行文本输入框

5.3 `st.text_input`：单行文本输入框

6.1 `st.audio_input`：音频录制输入

6.2 `st.camera_input`：摄像头拍照输入

6.3 `st.data_editor`：数据编辑器

6.4 `st.file_uploader`：文件上传器