本教程详细阐述了如何在streamlit应用中加载并显示来自本地文件夹的多个gif图片。通过利用python的glob模块进行文件路径匹配，结合base64编码将gif内容嵌入到html的标签中，我们提供了一种健壮且跨平台兼容的解决方案。文章将涵盖环境配置、代码实现细节以及关键注意事项，确保用户能够成功地在streamlit界面中展示动态图片。
Streamlit应用中展示本地GIF集合
在开发Streamlit应用时，经常需要展示本地存储的图片或动态图，例如GIF。直接使用st.image()虽然方便，但在处理批量本地GIF文件时，尤其是在需要动态加载和显示的情况下，可能会遇到路径解析或兼容性问题。本教程旨在提供一个可靠的方法，通过将GIF文件内容编码为Base64字符串并嵌入到html中，从而在Streamlit应用中无缝地显示多个本地GIF。
核心原理
Streamlit的st.markdown()函数允许渲染HTML内容，并通过设置unsafe_allow_html=True来启用此功能。利用这一特性，我们可以将本地GIF文件的二进制内容读取出来，然后使用Base64编码将其转换为字符串，最终嵌入到标准的<img>标签的src属性中。这种方法绕过了直接处理文件路径的复杂性，尤其是在部署到不同操作系统环境时。
实现步骤
以下是详细的实现步骤，包括必要的模块导入、路径配置、文件查找与显示逻辑。
-
导入所需模块 我们需要streamlit用于构建ui，base64用于编码GIF内容，os用于操作系统路径操作，glob用于文件模式匹配，以及platform用于识别当前操作系统。
import streamlit as st import base64 import os import glob import platform
-
确定工作目录与GIF文件夹路径 为了确保代码在不同环境下都能正确找到文件，我们需要首先确定当前脚本的绝对路径，并据此构建GIF文件所在的目录路径。同时，需要考虑windows和类unix系统路径分隔符的差异。
sys_platform = platform.system() work_dir = os.path.dirname(os.path.abspath(__file__)) # 根据操作系统确定GIF文件夹路径 if sys_platform == "windows": gif_folder_path = os.path.join(work_dir, "forecast", "fr") else: gif_folder_path = os.path.join(work_dir, "forecast", "fr") # 示例路径，根据实际情况调整
注意：os.path.join是构建路径的最佳实践，它会自动处理不同操作系统的路径分隔符。原代码中手动拼接或/可能导致错误。
-
查找所有GIF文件glob模块提供了一种强大的方式来查找符合特定模式的文件。通过切换到GIF文件夹目录，然后使用glob.glob(“*.gif”)，我们可以轻松获取该目录下所有GIF文件的列表。
# 切换到GIF文件夹，以便glob能正确匹配文件名 # 注意：os.chdir()会改变整个python进程的当前工作目录， # 如果应用中有其他需要相对路径的操作，请谨慎使用或在操作完成后切换回原目录。 # 另一种更安全的方式是使用glob.glob(os.path.join(gif_folder_path, "*.gif")) # 推荐使用更安全的glob方式，避免改变工作目录 gif_files = glob.glob(os.path.join(gif_folder_path, "*.gif"))
与原始问题中os.listdir的潜在问题（它只返回文件名，而不是完整路径，导致os.path.isfile(f)在当前工作目录而非目标目录查找）相比，glob方法更加健壮。
-
循环显示GIF文件 遍历找到的GIF文件列表，对每个文件执行以下操作：
- 以二进制读取模式打开文件。
- 读取文件内容。
- 使用base64.b64encode()将内容编码为Base64。
- 使用.decode(“utf-8”)将Base64字节串解码为UTF-8字符串。
- 构建一个HTML <img> 标签，将Base64字符串作为src属性的值。
- 使用st.markdown()将HTML内容渲染到Streamlit应用中，并设置unsafe_allow_html=True。
for file_path in gif_files: with open(file_path, "rb") as file_: contents = file_.read() data_url = base64.b64encode(contents).decode("utf-8") st.markdown( f'<img src="/uploads/20251107/1762459015690cfd876e6a3.gif" alt="{os.path.basename(file_path)}" style="max-width:100%;">', unsafe_allow_html=True, )这里添加了alt属性以提高可访问性，并设置了style=”max-width:100%;”以确保GIF图片能自适应Streamlit布局。
完整示例代码
将以上步骤整合，得到以下完整的Streamlit应用代码：
import streamlit as st import base64 import os import glob import platform # 1. 确定工作目录和GIF文件夹路径 sys_platform = platform.system() work_dir = os.path.dirname(os.path.abspath(__file__)) # 示例：假设GIF文件在 'your_app_root/forecast/fr/' 目录下 # 请根据实际情况调整 'forecast/fr' 部分 if sys_platform == "Windows": gif_folder_path = os.path.join(work_dir, "forecast", "fr") else: gif_folder_path = os.path.join(work_dir, "forecast", "fr") st.title("本地GIF集合展示") st.write(f"正在从目录: `{gif_folder_path}` 加载GIF文件...") # 2. 确保GIF文件夹存在 if not os.path.isdir(gif_folder_path): st.error(f"错误：GIF文件夹不存在或路径不正确：`{gif_folder_path}`") else: # 3. 查找所有GIF文件 # 使用os.path.join确保glob路径正确 gif_files = glob.glob(os.path.join(gif_folder_path, "*.gif")) if not gif_files: st.warning(f"在目录 `{gif_folder_path}` 中未找到任何GIF文件。") else: # 4. 循环显示GIF文件 for file_path in gif_files: try: with open(file_path, "rb") as file_: contents = file_.read() data_url = base64.b64encode(contents).decode("utf-8") # 使用st.markdown嵌入HTML img标签 st.markdown( f'<img src="/uploads/20251107/1762459015690cfd876e6a3.gif" alt="{os.path.basename(file_path)}" style="max-width:100%; display: block; 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}") st.write("所有GIF文件已加载完毕。")
注意事项
- unsafe_allow_html=True的安全性：启用此选项意味着Streamlit将渲染您提供的任何HTML字符串。如果HTML内容来源于不可信的外部输入，可能存在跨站脚本攻击（xss）的风险。在本教程中，内容完全由您本地文件生成，因此风险可控。
- 性能考虑：对于大量或体积较大的GIF文件，Base64编码会增加数据量（约33%），并在每次应用运行时重新编码。这可能会影响应用的加载速度和内存使用。如果GIF数量非常庞大，可以考虑将GIF上传到cdn或使用Streamlit的st.image()配合外部URL。
- 文件路径：确保gif_folder_path变量指向正确的GIF文件目录。在部署应用时，此路径应相对于应用根目录进行配置。
- 错误处理：示例代码中加入了对文件夹不存在和文件加载错误的简单处理，建议在生产环境中进行更完善的错误日志记录和用户提示。
- GIF优化：为了更好的用户体验，建议使用工具对GIF文件进行压缩优化，减小文件大小。
总结
通过上述方法，我们成功地解决了在Streamlit应用中展示本地GIF集合的问题。利用Base64编码和st.markdown()的HTML渲染能力，我们能够以一种灵活且跨平台的方式集成动态图像。这种方法不仅适用于GIF，也可扩展到其他需要嵌入HTML内容的场景。遵循本教程的指导和注意事项，您可以构建出功能丰富、用户友好的Streamlit应用。