本教程详细介绍了如何在streamlit应用中，从本地指定文件夹高效展示多个gif图像。文章阐述了利用base64编码将gif文件转换为数据url，并通过st.markdown结合html 标签嵌入显示的核心原理。同时，强调了使用glob模块进行文件查找以及正确管理文件路径（包括os.chdir）以确保跨平台兼容性和代码健壮性。
引言：在Streamlit中展示本地GIF图像的挑战
在开发Streamlit应用程序时，有时我们需要展示存储在本地文件系统中的图像，特别是动态的GIF图像。尽管Streamlit提供了st.image等组件用于显示图片，但对于需要批量展示本地GIF，或者通过自定义html结构进行精细控制的场景，直接使用st.image可能无法完全满足需求。一个常见的挑战是，如何将本地文件安全有效地嵌入到Web页面中，并确保路径处理在不同操作系统上都能兼容。
本文将深入探讨一种健壮且跨平台的解决方案，利用base64编码和st.markdown组件，配合python的glob模块来批量发现并展示本地GIF文件。
核心原理：Base64编码与HTML嵌入
Web浏览器通常无法直接访问用户本地文件系统中的文件。为了在HTML中显示本地图像，我们必须将图像数据本身嵌入到HTML文档中。base64编码提供了一种将二进制数据（如图像文件）转换为ASCII字符串的方法，这个字符串可以直接作为数据URL（Data URL）嵌入到HTML的<img>标签的src属性中。
其基本格式为：data:image/gif;base64,{base64编码字符串}。
Streamlit的st.markdown组件允许我们渲染Markdown格式的内容，并且通过设置unsafe_allow_html=True参数，可以安全地嵌入自定义HTML代码。这为我们提供了将base64编码的GIF图像嵌入到Streamlit应用中的途径。
文件发现与路径管理：glob模块的应用
在处理本地文件时，正确地定位和列出文件至关重要。
为什么os.listdir可能不足
最初的尝试可能使用os.listdir()来列出文件夹内容，然后通过os.path.isfile()进行筛选。然而，os.listdir()返回的只是文件名或目录名，不包含完整的路径。如果当前工作目录不是目标文件夹，那么os.path.isfile(f)将无法正确判断文件的存在性，因为f是一个相对路径，且相对于当前工作目录，而不是目标GIF目录。
glob的优势
glob模块提供了一种更灵活的文件名模式匹配机制。glob.glob(pattern)函数可以根据指定的模式返回所有匹配的文件或目录路径列表。例如，glob.glob(“*.gif”)将返回当前工作目录下所有.gif文件的列表。它的优势在于：
- 模式匹配： 可以方便地筛选特定类型的文件。
- 路径处理： 当配合os.chdir()使用时，可以简化文件路径的构建。
os.chdir的重要性
在某些情况下，为了让glob.glob()能够直接使用简单的模式（如”*.gif”）来匹配目标文件夹中的文件，我们需要临时改变Python脚本的当前工作目录到目标文件夹。os.chdir(path)函数可以实现这一点。改变工作目录后，glob.glob(“*.gif”)就会在新的工作目录中查找文件。
实现步骤与代码示例
以下是实现这一功能的完整步骤和代码示例：
1. 导入必要模块
我们需要streamlit用于构建Web应用，base64用于编码GIF数据，os用于路径操作，glob用于文件查找，以及platform用于跨平台兼容性。
import streamlit as st import base64 import os, glob import platform
2. 动态确定GIF目录
为了使代码在windows、linux或macOS等不同操作系统上都能正常运行，我们需要根据当前操作系统的路径分隔符（或/）动态构建GIF文件所在的目录路径。
sys_platform = platform.system() work_dir = os.path.dirname(os.path.abspath(__file__)) # 获取当前脚本的绝对路径 # 根据操作系统确定GIF文件夹路径 if sys_platform == "Windows": mypath = os.path.join(work_dir, "forecast", "fr") + "" # Windows使用反斜杠 else: mypath = os.path.join(work_dir, "forecast", "fr") + "/" # unix/Linux/macOS使用正斜杠 # 确保路径存在 if not os.path.exists(mypath): st.error(f"GIF目录不存在: {mypath}") st.stop()
3. 列出所有GIF文件
使用os.chdir()切换到GIF目录，然后使用glob.glob(“*.gif”)获取所有GIF文件的列表。
# 改变当前工作目录到GIF文件夹 original_cwd = os.getcwd() # 保存原始工作目录 os.chdir(mypath) # 使用glob查找所有GIF文件 fileslist = [] for file in glob.glob("*.gif"): fileslist.append(file) # 恢复原始工作目录，这是一个良好的实践 os.chdir(original_cwd) if not fileslist: st.warning(f"在目录 '{mypath}' 中未找到任何GIF文件。") st.stop()
4. 循环展示GIF
遍历GIF文件列表，对每个文件执行以下操作：
- 构建完整的文件路径。
- 以二进制模式读取文件内容。
- 将内容base64编码。
- 构建HTML <img> 标签，并将编码后的数据作为src属性。
- 使用st.markdown(…, unsafe_allow_html=True)显示。
st.markdown("### 本地GIF图像展示") for gif_filename in fileslist: # 确保文件路径是完整的，因为我们之前改变了工作目录，glob返回的是相对路径 full_gif_path = os.path.join(mypath, gif_filename) try: with open(full_gif_path, "rb") as file_: contents = file_.read() data_url = base64.b64encode(contents).decode("utf-8") st.markdown( f'<img src="/uploads/20251107/1762460255690d025f55e57.gif" alt="{gif_filename}" style="max-width:100%; height:auto;">', unsafe_allow_html=True, ) st.caption(f"显示: {gif_filename}") # 添加文件标题 except FileNotFoundError: st.error(f"文件未找到: {full_gif_path}") except Exception as e: st.error(f"处理文件 '{gif_filename}' 时发生错误: {e}")
完整代码示例
将以上片段整合，形成一个完整的Streamlit应用脚本。假设你的项目结构如下：
your_streamlit_app/ ├── app.py └── forecast/ └── fr/ ├── gif1.gif ├── gif2.gif └── ...
其中app.py是你的Streamlit脚本。
import streamlit as st import base64 import os, glob import platform # 1. 动态确定GIF目录 sys_platform = platform.system() work_dir = os.path.dirname(os.path.abspath(__file__)) # 获取当前脚本的绝对路径 # 根据操作系统确定GIF文件夹路径 # os.path.join 是更推荐的方式来构建路径，它会自动处理分隔符 mypath = os.path.join(work_dir, "forecast", "fr") # 确保路径存在 if not os.path.exists(mypath): st.error(f"GIF目录不存在: {mypath}") st.stop() # 2. 列出所有GIF文件 # 保存原始工作目录，这是一个良好的实践，以便在操作完成后恢复 original_cwd = os.getcwd() try: os.chdir(mypath) # 改变当前工作目录到GIF文件夹 fileslist = [f for f in glob.glob("*.gif")] finally: os.chdir(original_cwd) # 无论如何都要恢复原始工作目录 if not fileslist: st.warning(f"在目录 '{mypath}' 中未找到任何GIF文件。") st.stop() # 3. 循环展示GIF st.markdown("### 本地GIF图像展示") for gif_filename in fileslist: full_gif_path = os.path.join(mypath, gif_filename) # 构建完整路径 try: with open(full_gif_path, "rb") as file_: contents = file_.read() data_url = base64.b64encode(contents).decode("utf-8") st.markdown( f'<img src="/uploads/20251107/1762460255690d025f55e57.gif" alt="{gif_filename}" style="max-width:100%; height:auto;">', unsafe_allow_html=True, ) st.caption(f"显示: {gif_filename}") # 添加文件标题 except FileNotFoundError: st.error(f"文件未找到: {full_gif_path}") except Exception as e: st.error(f"处理文件 '{gif_filename}' 时发生错误: {e}")
关键代码解析
- os.path.dirname(os.path.abspath(__file__)): 这行代码用于获取当前脚本文件所在的目录的绝对路径，确保无论脚本从何处运行，都能正确找到相对路径下的forecast/fr目录。
- os.path.join(): 这是构建跨平台路径的最佳实践，它会根据当前操作系统自动选择正确的路径分隔符。
- os.chdir(mypath) 和 os.chdir(original_cwd): 临时改变工作目录是为了让glob.glob(“*.gif”)能够直接在目标文件夹中查找文件。try…finally块确保即使在处理文件过程中发生错误，也能恢复到原始工作目录，保持程序的健壮性。
- with open(full_gif_path, “rb”) as file_:: 使用with语句确保文件在读取完毕后会被正确关闭，”rb”模式表示以二进制读取。
- base64.b64encode(contents).decode(“utf-8”): 将二进制文件内容编码为base64字符串，然后解码为UTF-8文本，以便嵌入到HTML中。
- st.markdown(f'<img src=”/uploads/20251107/1762460255690d025f55e57.gif” …>’, unsafe_allow_html=True): 这是将GIF图像显示到Streamlit应用的关键。unsafe_allow_html=True是必需的，因为它允许Streamlit渲染包含HTML标签的字符串。style=”max-width:100%; height:auto;”可以确保图像在不同屏幕尺寸下都能自适应显示。
注意事项与最佳实践
- 性能考量: base64编码的图像会增加HTML文档的大小。如果GIF文件数量众多或单个文件体积较大，可能会导致页面加载缓慢或浏览器性能下降。对于大量或大型图像，考虑将它们托管到CDN或使用Streamlit的st.image直接引用URL（如果GIFs在可公开访问的路径）。
- 安全性提示: unsafe_allow_html=True参数允许在Streamlit应用中渲染任意HTML内容。这意味着如果你的应用处理用户输入并将其直接传递给st.markdown，可能会存在跨站脚本攻击（xss）的风险。在本教程的场景中，我们只处理本地信任的GIF文件，风险较低，但仍需注意。
- 错误处理: 示例代码中加入了try…except块来捕获文件未找到或处理过程中可能发生的其他错误，这对于生产环境中的应用至关重要。
- 用户体验: 可以考虑添加一个加载指示器或进度条，尤其是在GIF文件较多时，提升用户体验。
- 文件组织: 保持GIF文件在一个独立的、结构清晰的文件夹中是一个好习惯，便于管理和维护。
总结
通过结合base64编码、st.markdown的HTML嵌入能力以及glob模块的文件发现机制，我们成功地构建了一个在Streamlit应用中高效、跨平台展示多个本地GIF图像的解决方案。这个方法不仅解决了本地文件访问的限制，还提供了灵活的展示控制。在实际应用中，请务必考虑性能和安全性因素，并根据具体需求进行优化。