本教程详细介绍了如何在streamlit应用中展示本地文件夹内的多个gif图片。通过利用`base64`编码将gif文件转换为数据uri，并结合`st.markdown`组件的html渲染能力，实现了跨平台的文件路径处理和动态图片显示。文章提供了完整的代码示例，并强调了相关注意事项，旨在帮助开发者构建富媒体的streamlit应用。
在开发Streamlit应用时，我们经常需要展示本地存储的图片或动态图，例如GIF。直接使用st.image()组件通常适用于静态图片，但对于本地GIF文件，尤其是在需要批量显示时，可能会遇到路径问题或显示不兼容的情况。本教程将深入探讨一种健壮且跨平台的方法，通过将GIF文件编码为Base64数据URI并利用Streamlit的st.markdown组件来高效地显示多个本地GIF。
核心概念：Base64编码与HTML嵌入
Streamlit应用在浏览器中运行，而浏览器对本地文件系统的直接访问是受限的。为了在HTML内容中嵌入本地图片，一种常见的解决方案是将其内容编码为Base64字符串，然后作为数据URI（data:image/gif;base64,...）直接嵌入到<img>标签的src属性中。Streamlit的st.markdown组件允许我们渲染自定义的HTML内容，这为我们提供了将Base64编码的GIF嵌入应用的能力。
步骤一：导入必要的库
首先，我们需要导入处理文件系统、Base64编码以及Streamlit应用所需的库：
import streamlit as st import base64 import os import glob # 用于查找符合特定模式的文件 import platform # 用于识别操作系统，以便正确处理文件路径
步骤二：确定GIF文件路径
为了确保代码在不同操作系统（Windows、Linux、macOS）上都能正常运行，我们需要根据当前操作系统类型构建正确的文件路径。同时，使用glob模块可以方便地查找指定目录下的所有GIF文件。
# 获取当前脚本的绝对路径
work_dir = os.path.dirname(os.path.abspath(__file__))
# 判断操作系统类型并构建GIF文件夹路径
sys_platform = platform.system()
if sys_platform == "Windows":
# Windows系统使用反斜杠作为路径分隔符
gif_folder_path = os.path.join(work_dir, "forecast", "fr")
else:
# 类Unix系统（Linux, macOS）使用正斜杠
gif_folder_path = os.path.join(work_dir, "forecast", "fr")
# 检查GIF文件夹是否存在，如果不存在则创建（可选，但推荐）
if not os.path.exists(gif_folder_path):
st.error(f"GIF文件夹不存在：{gif_folder_path}")
st.stop() # 停止应用运行，避免后续错误
# 使用glob查找所有.gif文件
# os.path.join确保路径正确拼接，glob.glob返回完整文件路径列表
gif_files = glob.glob(os.path.join(gif_folder_path, "*.gif"))
if not gif_files:
st.warning(f"在文件夹 '{gif_folder_path}' 中未找到任何GIF文件。")注意： 上述代码假定GIF文件位于当前脚本所在目录下的forecast/fr子文件夹中。请根据实际情况调整gif_folder_path。
步骤三：编码并显示GIF文件
遍历找到的每个GIF文件，将其内容读取为二进制数据，然后使用base64.b64encode()进行编码。最后，将编码后的数据嵌入到<img>标签中，并通过st.markdown显示。
st.header("本地GIF动画展示")
if gif_files:
for file_path in gif_files:
try:
with open(file_path, "rb") as file_:
contents = file_.read()
# 将二进制内容编码为Base64字符串
data_url = base64.b64encode(contents).decode("utf-8")
# 使用st.markdown渲染包含Base64数据URI的HTML图片标签
# unsafe_allow_html=True 必须设置为True才能渲染自定义HTML
st.markdown(
f'<img src="data:image/gif;base64,{data_url}" alt="{os.path.basename(file_path)}" style="max-width:100%; height:auto;">',
unsafe_allow_html=True,
)
st.write(f"显示文件：{os.path.basename(file_path)}") # 可选：显示文件名
except Exception as e:
st.error(f"无法加载或显示GIF文件 '{os.path.basename(file_path)}': {e}")
else:
st.info("没有GIF文件可供显示。请确保指定文件夹中存在GIF文件。")完整示例代码
将以上所有步骤整合，即可得到一个完整的Streamlit应用，用于显示指定文件夹中的所有GIF文件。
import streamlit as st
import base64
import os
import glob
import platform
# 获取当前脚本的绝对路径
work_dir = os.path.dirname(os.path.abspath(__file__))
# 判断操作系统类型并构建GIF文件夹路径
sys_platform = platform.system()
if sys_platform == "Windows":
# Windows系统使用反斜杠作为路径分隔符
gif_folder_path = os.path.join(work_dir, "forecast", "fr")
else:
# 类Unix系统（Linux, macOS）使用正斜杠
gif_folder_path = os.path.join(work_dir, "forecast", "fr")
st.header("本地GIF动画展示")
# 检查GIF文件夹是否存在
if not os.path.exists(gif_folder_path):
st.error(f"错误：GIF文件夹不存在。请检查路径：`{gif_folder_path}`")
st.stop() # 停止应用运行，避免后续错误
# 使用glob查找所有.gif文件
# os.path.join确保路径正确拼接，glob.glob返回完整文件路径列表
gif_files = glob.glob(os.path.join(gif_folder_path, "*.gif"))
if not gif_files:
st.warning(f"在文件夹 '{gif_folder_path}' 中未找到任何GIF文件。")
else:
st.write(f"在 '{gif_folder_path}' 找到 {len(gif_files)} 个GIF文件。")
for file_path in gif_files:
try:
with open(file_path, "rb") as file_:
contents = file_.read()
# 将二进制内容编码为Base64字符串
data_url = base64.b64encode(contents).decode("utf-8")
# 使用st.markdown渲染包含Base64数据URI的HTML图片标签
# unsafe_allow_html=True 必须设置为True才能渲染自定义HTML
st.markdown(
f'<img src="data:image/gif;base64,{data_url}" alt="{os.path.basename(file_path)}" style="max-width:100%; height:auto; margin-bottom: 15px;">',
unsafe_allow_html=True,
)
st.caption(f"文件名: {os.path.basename(file_path)}") # 可选：显示文件名
except Exception as e:
st.error(f"无法加载或显示GIF文件 '{os.path.basename(file_path)}': {e}")
注意事项与总结
- unsafe_allow_html=True的安全性： 使用st.markdown并设置unsafe_allow_html=True时，Streamlit将直接渲染您提供的HTML字符串。这意味着如果您的HTML内容来自不可信的来源，可能存在跨站脚本（XSS）攻击的风险。在本教程中，我们是渲染自己的本地文件，风险可控。
- 性能考量： 对于数量非常庞大或文件尺寸巨大的GIF图片，Base64编码会增加页面的初始加载时间，因为所有图片数据都被嵌入到HTML中。在这种情况下，可以考虑对GIF进行优化压缩，或者在某些场景下，如果GIF文件可以通过网络访问，直接使用其URL可能更高效。
- 文件路径： 确保gif_folder_path变量指向正确的GIF文件目录。如果应用部署在不同的环境中，可能需要调整此路径。
- 错误处理： 示例代码中加入了基本的错误处理，例如检查文件夹是否存在、文件是否可读等。在生产环境中，可以根据需要添加更详细的错误日志和用户提示。
- 图片样式： 在<img>标签中添加style="max-width:100%; height:auto;"可以使GIF图片自适应Streamlit应用的宽度，避免图片过大超出显示范围。
通过本教程，您应该能够熟练地在Streamlit应用中显示本地文件夹内的多个GIF图片。这种方法不仅解决了本地文件访问的限制，还提供了跨平台的兼容性，为您的Streamlit应用增添了丰富的动态视觉效果。
