Dataframes
数据框是展示和编辑表格数据的绝佳方式。使用Pandas数据框和其他表格数据结构是数据科学工作流程的关键。如果开发者和数据科学家希望在Streamlit中展示这些数据，他们有多个选择：st.dataframe 和 st.data_editor。如果你只想在类似表格的UI中展示数据，st.dataframe 是合适的选择。如果你想交互式地编辑数据，使用 st.data_editor。我们将在以下部分探讨每种选项的用例和优势。
Display dataframes with st.dataframe
Streamlit 可以通过 st.dataframe 在类似表格的 UI 中显示数据框：
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},
]
)
st.dataframe(df, use_container_width=True)
st.dataframe UI features
st.dataframe 通过使用 glide-data-grid 提供了额外的功能：
- 列排序: 通过点击列标题来对列进行排序。
- 列调整大小: 通过拖放列标题边框来调整列的大小。
- 表格调整大小: 通过拖放右下角来调整表格大小。
- 全屏视图：通过点击工具栏中的全屏图标（全屏）将表格放大到全屏。
- 搜索: 点击工具栏中的搜索图标 (search) 或使用快捷键 (
⌘+F或Ctrl+F) 来搜索数据。 - 下载: 点击工具栏中的下载图标，将数据下载为CSV文件。
- 复制到剪贴板: 选择一个或多个单元格，将它们复制到剪贴板（
⌘+C或Ctrl+C），然后粘贴到您喜欢的电子表格软件中。
使用前一节中的嵌入式应用程序尝试所有用户界面功能。
除了Pandas DataFrames，st.dataframe 还支持其他常见的Python类型，例如列表、字典或numpy数组。它还支持Snowpark和PySpark DataFrames，这些允许您延迟评估并从数据库中提取数据。这对于处理大型数据集非常有用。
Edit data with st.data_editor
Streamlit 支持通过 st.data_editor 命令编辑数据框。查看其 API 在 st.data_editor。它以表格形式显示数据框，类似于 st.dataframe。但与 st.dataframe 不同的是，这个表格不是静态的！用户可以点击单元格并编辑它们。编辑后的数据随后会在 Python 端返回。以下是一个示例：
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) # 👈 An editable dataframe
favorite_command = edited_df.loc[edited_df["rating"].idxmax()]["command"]
st.markdown(f"Your favorite command is **{favorite_command}** 🎈")
尝试双击任何单元格。您会注意到可以编辑所有单元格的值。尝试编辑评分列中的值，并观察底部文本输出的变化：
st.data_editor UI features
st.data_editor 还支持一些额外的功能：
- 添加和删除行: 您可以通过在调用
st.data_editor时设置num_rows= "dynamic"来实现这一点。这将允许用户根据需要添加和删除行。 - 复制和粘贴支持: 在
st.data_editor和电子表格软件（如Google Sheets和Excel）之间进行复制和粘贴。 - 访问编辑后的数据: 通过会话状态仅访问单个编辑，而不是整个编辑后的数据结构。
- 批量编辑: 类似于Excel，只需拖动一个手柄即可编辑相邻的单元格。
- 自动输入验证: 列配置提供了强大的数据类型支持和其他可配置选项。例如，无法在数字单元格中输入字母。数字单元格可以指定最小值和最大值。
- 编辑常见数据结构:
st.data_editor支持列表、字典、NumPy ndarray 等！
Add and delete rows
使用 st.data_editor，查看者可以通过表格界面添加或删除行。此模式可以通过将 num_rows 参数设置为 "dynamic" 来激活：
edited_df = st.data_editor(df, num_rows="dynamic")
- 要添加新行，请点击工具栏中的加号图标（添加）。或者，点击表格底部行下方的阴影单元格内部。
- 要删除行，请使用左侧的复选框选择一行或多行。点击删除图标（delete）或按键盘上的
delete键。
Copy and paste support
数据编辑器支持从Google Sheets、Excel、Notion等许多类似工具中粘贴表格数据。您还可以在st.data_editor实例之间复制粘贴数据。这一功能由Clipboard API提供支持，对于需要在多个平台上处理数据的用户来说，可以大大节省时间。要尝试此功能：
- 从这个Google Sheets文档复制数据到你的剪贴板。
- 单击上方应用程序中
name列的任何单元格。使用快捷键（⌘+V或Ctrl+V）粘贴。
注意
粘贴数据的每个单元格将单独评估，如果数据与列类型兼容，则插入到单元格中。例如，将非数字文本数据粘贴到数字列中将被忽略。
提示
如果您使用iframe嵌入您的应用程序，并且希望使用复制粘贴功能，您需要允许iframe访问剪贴板。为此，请为iframe授予clipboard-write和clipboard-read权限。例如：
<iframe allow="clipboard-write;clipboard-read;" ... src="https://your-app-url"></iframe>
作为开发者，在使用TLS时，请确保应用程序使用有效且受信任的证书提供服务。如果用户在复制和粘贴数据时遇到问题，请引导他们检查浏览器是否已为Streamlit应用程序激活了剪贴板访问权限，无论是在提示时还是通过浏览器的站点设置。
Access edited data
有时候，了解哪些单元格已被更改比获取整个编辑后的数据框更为方便。Streamlit 通过使用 Session State 使这一过程变得简单。如果设置了 key 参数，Streamlit 将会把对数据框所做的任何更改存储在 Session State 中。
此代码片段展示了如何使用会话状态访问更改的数据：
st.data_editor(df, key="my_key", num_rows="dynamic") # 👈 Set a key
st.write("Here's the value in Session State:")
st.write(st.session_state["my_key"]) # 👈 Show the value in Session State
在这个代码片段中，key 参数被设置为 "my_key"。创建数据编辑器后，与 "my_key" 关联的值在应用程序中使用 st.write 显示。这显示了所做的添加、编辑和删除。
在处理大型数据框时，这可能很有用，因为你只需要知道哪些单元格发生了变化，而不是访问整个编辑过的数据框。
使用我们到目前为止学到的所有知识，并将它们应用到上述嵌入式应用程序中。尝试编辑单元格、添加新行和删除行。
注意表格的编辑如何反映在会话状态中。当您进行任何编辑时，会触发重新运行，将编辑发送到后端。小部件的状态是一个包含三个属性的JSON对象：edited_rows、added_rows和deleted rows:。
警告
当从 st.experimental_data_editor 升级到 1.23.0 版本的 st.data_editor 时，数据编辑器在 st.session_state 中的表示方式发生了变化。edited_cells 字典现在被称为 edited_rows，并且使用了不同的格式（{0: {"column name": "edited value"}} 而不是 {"0:1": "edited value"}）。如果你的应用结合使用了 st.experimental_data_editor 和 st.session_state，你可能需要调整你的代码。
edited_rows是一个包含所有编辑的字典。键是从零开始的行索引，值是映射列名到编辑的字典（例如{0: {"col1": ..., "col2": ...}}）。added_rows是新添加的行的列表。每个值都是一个字典，格式与上述相同（例如[{"col1": ..., "col2": ...}]）。deleted_rows是从表中删除的行号的列表（例如[0, 2]）。
st.data_editor 不支持重新排序行，因此添加的行将始终附加到数据框的末尾，任何编辑和删除操作仅适用于原始行。
Bulk edits
数据编辑器包含一个允许批量编辑单元格的功能。类似于Excel，您可以拖动一个手柄跨过选定的单元格来批量编辑它们的值。您甚至可以应用电子表格软件中常用的键盘快捷键。当您需要对多个单元格进行相同的更改，而不是逐个编辑每个单元格时，这非常有用。
Edit common data structures
编辑不仅适用于Pandas DataFrames！您还可以编辑列表、元组、集合、字典、NumPy数组或Snowpark和PySpark DataFrames。大多数数据类型将以其原始格式返回。但某些类型（例如Snowpark和PySpark）会转换为Pandas DataFrames。要了解所有支持的类型，请阅读st.data_editor API。
例如，您可以轻松地让用户向列表中添加项目：
edited_list = st.data_editor(["red", "green", "blue"], num_rows= "dynamic")
st.write("Here are all the colors you entered:")
st.write(edited_list)
或者 numpy 数组：
import numpy as np
st.data_editor(np.array([
["st.text_area", "widget", 4.92],
["st.markdown", "element", 47.22]
]))
或记录列表：
st.data_editor([
{"name": "st.text_area", "type": "widget"},
{"name": "st.markdown", "type": "element"},
])
或者字典以及更多类型！
st.data_editor({
"st.text_area": "widget",
"st.markdown": "element"
})
Automatic input validation
数据编辑器包括自动输入验证，以帮助防止编辑单元格时出现错误。例如，如果您有一个包含数值数据的列，输入字段将自动限制用户只能输入数值数据。这有助于防止用户意外输入非数值数据时可能发生的错误。可以通过列配置API配置其他输入验证。继续阅读以下内容，了解列配置的概述，包括验证选项。
Configuring columns
你可以通过Column configuration API配置st.dataframe和st.data_editor中列的显示和编辑行为。我们开发了这个API，让你可以在数据框和数据编辑器列中添加图片、图表和可点击的URL。此外，你还可以使单个列可编辑，将列设置为分类并指定它们可以采用的选项，隐藏数据框的索引等等。
列配置包括以下列类型：文本、数字、复选框、选择框、日期、时间、日期时间、列表、链接、图像、折线图、柱状图和进度条。还有一个通用的列选项。请查看下面的嵌入式应用程序以查看这些不同的列类型。每种列类型都在列配置API文档中单独预览。
Format values
在列配置中，format 参数可用于Text、Date、Time和Datetime列。类似图表的列也可以进行格式化。Line chart和Bar chart列有y_min和y_max参数来设置垂直边界。对于Progress column，您可以使用min_value和max_value来声明水平边界。
Validate input
在指定列配置时，您不仅可以声明列的数据类型，还可以声明值限制。所有列配置元素都允许您使用关键字参数required=True使列成为必填项。
对于文本和链接列，您可以使用max_chars指定最大字符数，或通过validate使用正则表达式验证条目。数值列，包括数字、日期、时间和日期时间，具有min_value和max_value参数。选择框列具有可配置的options列表。
Number 列的数据类型默认是 float。将类型为 int 的值传递给 min_value、max_value、step 或 default 中的任何一个，都会将该列的类型设置为 int。
Configure an empty dataframe
你可以使用st.data_editor来从用户那里收集表格输入。当从一个空的数据框开始时，默认的列类型是文本。使用列配置来指定你希望从用户那里收集的数据类型。
import streamlit as st
import pandas as pd
df = pd.DataFrame(columns=['name','age','color'])
colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet']
config = {
'name' : st.column_config.TextColumn('Full Name (required)', width='large', required=True),
'age' : st.column_config.NumberColumn('Age (years)', min_value=0, max_value=122),
'color' : st.column_config.SelectboxColumn('Favorite Color', options=colors)
}
result = st.data_editor(df, column_config = config, num_rows='dynamic')
if st.button('Get results'):
st.write(result)
Additional formatting options
除了列配置之外，st.dataframe 和 st.data_editor 还有一些参数可以自定义数据框的显示。
hide_index: 设置为True以隐藏数据框的索引。column_order: 传递一个列标签列表以指定显示顺序。disabled: 传递一个列标签列表以禁用它们的编辑功能。这让你可以避免逐个禁用它们。
Handling large datasets
st.dataframe 和 st.data_editor 设计上理论上可以处理数百万行的表格，这得益于它们使用 glide-data-grid 库和 HTML canvas 的高性能实现。然而，应用程序实际能够处理的最大数据量将取决于其他几个因素，包括：
- WebSocket消息的最大大小：Streamlit的WebSocket消息可以通过
server.maxMessageSize配置选项进行配置，该选项限制了通过WebSocket连接一次可以传输的数据量。 - 服务器内存：您的应用程序可以处理的数据量还取决于服务器上可用的内存量。如果超出服务器的内存，应用程序可能会变慢或无响应。
- 用户的浏览器内存：由于所有数据都需要传输到用户的浏览器进行渲染，用户设备上的可用内存量也会影响应用程序的性能。如果浏览器的内存超出限制，可能会导致崩溃或无响应。
除了这些因素外，缓慢的网络连接也会显著减慢处理大型数据集的应用程序。
当处理超过150,000行的大型数据集时，Streamlit会应用额外的优化并禁用列排序。这有助于减少一次性需要处理的数据量，并提高应用程序的性能。
Limitations
- Streamlit 在内部将所有列名转换为字符串，因此
st.data_editor将返回一个所有列名均为字符串的 DataFrame。 - 数据框架工具栏目前不可配置。
- 虽然Streamlit的数据编辑功能提供了很多功能，但编辑功能仅适用于有限的列类型（TextColumn、NumberColumn、LinkColumn、CheckboxColumn、SelectboxColumn、DateColumn、TimeColumn和DatetimeColumn）。我们正在积极努力支持其他列类型的编辑，例如图像、列表和图表。
- 几乎所有可编辑的数据类型都支持索引编辑。然而，
pandas.CategoricalIndex和pandas.MultiIndex不支持编辑。 - 当
num_rows="dynamic"时，st.data_editor不支持排序。 - 排序功能已停用，以优化超过150,000行的大型数据集的性能。
我们正在不断改进Streamlit对DataFrame的处理，并增加数据编辑功能，请密切关注更新。
还有问题吗？
我们的 论坛 充满了有用的信息和Streamlit专家。