Basic concepts of Streamlit

使用Streamlit非常简单。首先，你在一个普通的Python脚本中加入一些Streamlit命令，然后使用streamlit run运行它：

streamlit run your_script.py [-- script args]

一旦你如上所示运行脚本，一个本地Streamlit服务器将启动，你的应用程序将在默认的网页浏览器的新标签页中打开。这个应用程序是你的画布，你可以在上面绘制图表、文本、小部件、表格等。

在应用程序中绘制什么由您决定。例如 st.text 将原始文本写入您的应用程序，而 st.line_chart 绘制 — 您猜对了 — 一个折线图。请参阅我们的 API 文档查看所有可用的命令。

push_pin

注意

当向你的脚本传递一些自定义参数时，它们必须在两个破折号之后传递。否则，这些参数会被解释为Streamlit本身的参数。

另一种运行 Streamlit 的方法是将其作为 Python 模块运行。这在配置像 PyCharm 这样的 IDE 以与 Streamlit 一起工作时非常有用：

# Running
python -m streamlit run your_script.py

# is equivalent to:
streamlit run your_script.py

star

提示

你也可以传递一个URL给streamlit run！当与GitHub Gists结合使用时，这非常棒。例如：

streamlit run https://raw.githubusercontent.com/streamlit/demo-uber-nyc-pickups/master/streamlit_app.py

Development flow

每次你想更新你的应用程序时，保存源文件。当你这样做时，Streamlit 会检测是否有变化，并询问你是否要重新运行你的应用程序。选择屏幕右上角的“始终重新运行”，以便每次更改源代码时自动更新你的应用程序。

这使您可以在一个快速的交互式循环中工作：您输入一些代码，保存它，实时尝试，然后输入更多代码，保存它，尝试它，依此类推，直到您对结果满意为止。这种编码和实时查看结果之间的紧密循环是Streamlit使您的生活更轻松的方式之一。

star

提示

在开发Streamlit应用程序时，建议将编辑器和浏览器窗口并排放置，以便同时查看代码和应用程序。试试看吧！

自 Streamlit 版本 1.10.0 及更高版本起，Streamlit 应用程序无法从 Linux 发行版的根目录运行。如果您尝试从根目录运行 Streamlit 应用程序，Streamlit 将抛出 FileNotFoundError: [Errno 2] No such file or directory 错误。更多信息，请参阅 GitHub 问题 #5239。

如果您使用的是 Streamlit 1.10.0 或更高版本，您的主脚本应位于根目录以外的目录中。使用 Docker 时，您可以使用 WORKDIR 命令来指定主脚本所在的目录。有关如何执行此操作的示例，请阅读创建 Dockerfile。

Data flow

Streamlit的架构允许你以编写普通Python脚本的方式编写应用程序。为了实现这一点，Streamlit应用程序具有独特的数据流：每当屏幕上需要更新某些内容时，Streamlit会从头到尾重新运行你的整个Python脚本。

这可能在两种情况下发生：

每当你修改应用程序的源代码时。
每当用户与应用中的小部件交互时。例如，拖动滑块、在输入框中输入文本或点击按钮时。

每当通过on_change（或on_click）参数将回调传递给小部件时，回调将始终在脚本的其余部分之前运行。有关回调API的详细信息，请参阅我们的会话状态API参考指南。

为了使所有这些快速且无缝，Streamlit 在幕后为你做了很多繁重的工作。这个故事中的一个重要角色是@st.cache_data装饰器，它允许开发者在应用程序重新运行时跳过某些昂贵的计算。我们将在本页后面介绍缓存。

Display and style data

在Streamlit应用程序中有几种显示数据（表格、数组、数据框）的方法。下面，你将了解到magic和st.write()，它们可以用来写入从文本到表格的任何内容。之后，让我们看看专门用于可视化数据的方法。

Use magic

你也可以在不调用任何Streamlit方法的情况下写入你的应用程序。 Streamlit支持"魔法命令"，这意味着你根本不需要使用 st.write()！要查看实际操作，请尝试以下代码片段：

"""
# My first app
Here's our first attempt at using data to create a table:
"""

import streamlit as st
import pandas as pd
df = pd.DataFrame({
  'first column': [1, 2, 3, 4],
  'second column': [10, 20, 30, 40]
})

df

每当Streamlit看到一行中的变量或字面值时，它会自动使用st.write()将其写入您的应用程序。有关更多信息，请参阅magic commands的文档。

Write a data frame

除了magic commands， st.write() 是 Streamlit 的“瑞士军刀”。你可以将几乎任何东西传递给st.write()：文本、数据、Matplotlib 图表、Altair 图表等等。别担心，Streamlit 会识别并以正确的方式呈现它们。

import streamlit as st
import pandas as pd

st.write("Here's our first attempt at using data to create a table:")
st.write(pd.DataFrame({
    'first column': [1, 2, 3, 4],
    'second column': [10, 20, 30, 40]
}))

还有其他特定于数据的函数，如 st.dataframe() 和 st.table()，你也可以使用它们来显示数据。让我们了解何时使用这些功能以及如何为你的数据框添加颜色和样式。

你可能会问自己，“为什么我不总是使用st.write()？”有几个原因：

魔法和 st.write() 会检查你传入的数据类型，然后决定如何在应用程序中最佳地渲染它。有时你可能希望以另一种方式绘制它。例如，与其将数据框绘制为交互式表格，你可能希望使用 st.table(df) 将其绘制为静态表格。
第二个原因是其他方法返回的对象可以被使用和修改，无论是通过添加数据还是替换它。
最后，如果您使用更具体的 Streamlit 方法，您可以传递额外的参数来自定义其行为。

例如，让我们创建一个数据框并使用Pandas的Styler对象更改其格式。在这个例子中，你将使用Numpy生成一个随机样本，并使用st.dataframe()方法绘制一个交互式表格。

push_pin

注意

此示例使用Numpy生成随机样本，但您可以使用Pandas DataFrames、Numpy数组或普通Python数组。

import streamlit as st
import numpy as np

dataframe = np.random.randn(10, 20)
st.dataframe(dataframe)

让我们扩展第一个例子，使用Pandas Styler对象来突出显示交互式表格中的一些元素。

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

dataframe = pd.DataFrame(
    np.random.randn(10, 20),
    columns=('col %d' % i for i in range(20)))

st.dataframe(dataframe.style.highlight_max(axis=0))

Streamlit 还有一个用于静态表格生成的方法： st.table()。

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

dataframe = pd.DataFrame(
    np.random.randn(10, 20),
    columns=('col %d' % i for i in range(20)))
st.table(dataframe)

Draw charts and maps

Streamlit 支持多种流行的数据图表库，如 Matplotlib, Altair, deck.gl 等。在本节中，您将为您的应用程序添加柱状图、折线图和地图。

Draw a line chart

你可以轻松地使用st.line_chart()在你的应用中添加一个折线图。我们将使用Numpy生成一个随机样本，然后绘制它。

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

chart_data = pd.DataFrame(
     np.random.randn(20, 3),
     columns=['a', 'b', 'c'])

st.line_chart(chart_data)

Plot a map

使用st.map()，您可以在地图上显示数据点。让我们使用Numpy生成一些样本数据，并将其绘制在旧金山的地图上。

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

map_data = pd.DataFrame(
    np.random.randn(1000, 2) / [50, 50] + [37.76, -122.4],
    columns=['lat', 'lon'])

st.map(map_data)

Widgets

当你将数据或模型调整到想要探索的状态时，你可以添加一些小部件，比如st.slider()、st.button()或st.selectbox()。这非常简单——将小部件视为变量：

import streamlit as st
x = st.slider('x')  # 👈 this is a widget
st.write(x, 'squared is', x * x)

在第一次运行时，上面的应用程序应该输出文本“0的平方是0”。然后每次用户与小部件交互时，Streamlit 只需从头到尾重新运行您的脚本，在此过程中将小部件的当前状态分配给您的变量。

例如，如果用户将滑块移动到位置 10，Streamlit 将重新运行上面的代码，并将 x 相应地设置为 10。因此，您现在应该看到文本“10 的平方是 100”。

如果您选择指定一个字符串作为小部件的唯一键，也可以通过键访问小部件：

import streamlit as st
st.text_input("Your name", key="name")

# You can access the value at any point with:
st.session_state.name

每个带有键的小部件都会自动添加到会话状态中。有关会话状态的更多信息，其与小部件状态的关联及其限制，请参阅会话状态API参考指南。

Use checkboxes to show/hide data

复选框的一个用例是在应用程序中隐藏或显示特定的图表或部分。st.checkbox() 接受一个参数，即小部件的标签。在这个示例中，复选框用于切换条件语句。

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

if st.checkbox('Show dataframe'):
    chart_data = pd.DataFrame(
       np.random.randn(20, 3),
       columns=['a', 'b', 'c'])

    chart_data

Use a selectbox for options

使用st.selectbox从一系列选项中选择。你可以写入你想要的选项，或者传递一个数组或数据框列。

让我们使用我们之前创建的df数据框。

import streamlit as st
import pandas as pd

df = pd.DataFrame({
    'first column': [1, 2, 3, 4],
    'second column': [10, 20, 30, 40]
    })

option = st.selectbox(
    'Which number do you like best?',
     df['first column'])

'You selected: ', option

Layout

Streamlit 使得在小部件左侧面板边栏中组织小部件变得容易，使用 st.sidebar。传递给 st.sidebar 的每个元素都被固定在左侧，允许用户在专注于应用程序内容的同时，仍然可以访问用户界面控制。

例如，如果你想在侧边栏添加一个选择框和一个滑块，使用 st.sidebar.slider 和 st.sidebar.selectbox 而不是 st.slider 和 st.selectbox：

import streamlit as st

# Add a selectbox to the sidebar:
add_selectbox = st.sidebar.selectbox(
    'How would you like to be contacted?',
    ('Email', 'Home phone', 'Mobile phone')
)

# Add a slider to the sidebar:
add_slider = st.sidebar.slider(
    'Select a range of values',
    0.0, 100.0, (25.0, 75.0)
)

除了侧边栏，Streamlit 还提供了其他几种方式来控制应用程序的布局。st.columns 允许你将小部件并排放置，而 st.expander 则可以通过隐藏大块内容来节省空间。

import streamlit as st

left_column, right_column = st.columns(2)
# You can use a column just like st.sidebar:
left_column.button('Press me!')

# Or even better, call Streamlit functions inside a "with" block:
with right_column:
    chosen = st.radio(
        'Sorting hat',
        ("Gryffindor", "Ravenclaw", "Hufflepuff", "Slytherin"))
    st.write(f"You are in {chosen} house!")

push_pin

注意

st.echo 和 st.spinner 目前在侧边栏或布局选项中不受支持。不过请放心，我们正在努力添加对这些功能的支持！

Show progress

当向应用程序添加长时间运行的计算时，您可以使用 st.progress() 来实时显示状态。

首先，让我们导入时间。我们将使用time.sleep()方法来模拟一个长时间运行的计算：

import time

现在，让我们创建一个进度条：

import streamlit as st
import time

'Starting a long computation...'

# Add a placeholder
latest_iteration = st.empty()
bar = st.progress(0)

for i in range(100):
  # Update the progress bar with each iteration.
  latest_iteration.text(f'Iteration {i+1}')
  bar.progress(i + 1)
  time.sleep(0.1)

'...and now we\'re done!'

Previous: Fundamentals Next: Advanced concepts

forum

还有问题吗？

我们的论坛充满了有用的信息和Streamlit专家。