用途
该技能用于说明 Streamlit 中 Markdown 的完整支持范围。Streamlit 在多个 API 中支持 Markdown,包括 st.markdown()、控件标签、帮助提示、指标、st.table() 单元格等。除标准 GitHub 风格 Markdown 外,Streamlit 还扩展了彩色文字、徽章、图标和 LaTeX。
主要能力
GitHub 风格 Markdown
标准 GFM 语法可正常使用,标题会自动生成用于导航的锚点链接。支持粗体、斜体、删除线、行内代码、链接、图片、标题、引用、水平线、无序列表、有序列表、任务列表、表格、Emoji 等。
彩色文字、背景与徽章
支持彩色文字(如 :red[Error])、彩色背景(如 :blue-background[Highlighted])和行内徽章(如 :green-badge[Active])。可用颜色包括 red、orange、yellow、green、blue、violet、gray/grey、rainbow、primary。注意 rainbow 不支持用于背景或徽章。独立徽章也可通过 st.badge() 使用。
Material 图标
使用 Google Material Symbols,语法为 :material/icon_name:,图标可在 fonts.google.com/icons 查找。Material 图标也可用于许多元素的 icon 参数(如 st.button、st.expander、st.info 等)。
Emoji
Unicode Emoji(推荐)和短代码均可使用。资料指出,相比 Emoji,Material 图标更适合追求专业外观的场景。
LaTeX 数学公式
单 $ 用于行内公式,双 $$ 用于显示模式。行内数学要求 $ 后为非空白字符,以避免与货币符号冲突(例如 "$5" 不会被解析为数学公式)。
Markdown 中的图片
支持 语法。在标签中,图片会以图标形式显示,最大高度等于字体高度。
元素标签中的 Markdown
控件、容器和其他元素支持在标签中使用 Markdown(使用标签子集)。例如 st.radio、st.tabs、st.metric 等。
转义特殊字符
使用反斜杠显示字面字符,如 [、*、1.。
st.table 中的 Markdown
st.table() 会在单元格和表头中渲染 Markdown。
组合功能
可混合多种功能实现丰富格式,例如在表格中结合徽章和 Material 图标。
st.markdown 的文本对齐与宽度
可通过 text_alignment 和 width 参数控制布局。text_alignment 可选 left、center、right、justify;width 可选 stretch、content 或像素值(如 400)。
HTML
可通过 unsafe_allow_html=True 将 Markdown 与 HTML 混用。若只需纯 HTML 而不经 Markdown 处理,应使用 st.html()。资料提示 HTML 应尽量少用。
使用方式
Markdown 在 Streamlit 中有三个支持级别:
-
完整 Markdown:支持上表所有语法,适用于 st.markdown()、st.write()、st.caption()、st.info()、st.warning()、st.error()、st.success()、st.table 单元格和表头、tooltips(help 参数)。
-
标签子集:仅支持内联格式,块级元素(如标题、列表、表格)会被静默移除。适用于控件和元素标签(st.button、st.checkbox、st.radio、st.expander、st.page_link 等)、st.radio 和 st.select_slider 选项、st.tabs 名称、st.metric 的 label/value/delta、st.title、st.header、st.subheader、st.image caption、st.dialog title、st.progress、st.spinner。
-
不支持 Markdown:文本按字面显示。适用于 st.text()、st.json()、st.dataframe() / st.data_editor() 单元格、st.selectbox / st.multiselect 选项、输入占位符、st.Page 标题、图表/地图标签。
适用场景
适用于需要在 Streamlit 应用中渲染富文本、格式化标签、展示状态徽章、使用图标和数学公式的场景。
限制
块级元素在标签子集中会被静默移除;rainbow 颜色不支持背景和徽章;行内数学要求 $ 后为非空白字符;HTML 应尽量少用。