7397 字
8 分钟
MDX 集成与 M3E 原子组件

这个页面演示如何在 MDX 里直接使用 TypeScript 泛型 风格的类型注解与组件 props。

import Button from “@components/atoms/action/Button.svelte”; import Chips from “@components/atoms/action/Chips.svelte”; import Card from “@components/atoms/display/Card.svelte”; import AccentBar from “@components/atoms/display/AccentBar.svelte”; import Badge from “@components/atoms/display/Badge.svelte”; import Divider from “@components/atoms/display/Divider.svelte”; import Skeleton from “@components/atoms/display/Skeleton.svelte”; import LoadingIndicator from “@components/atoms/feedback/LoadingIndicator.svelte”; import ProgressIndicator from “@components/atoms/feedback/ProgressIndicator.svelte”; import TextField from “@components/atoms/input/TextField.svelte”; import Switch from “@components/atoms/selection/Switch.svelte”; import Checkbox from “@components/atoms/selection/Checkbox.svelte”; import SegmentedButton from “@components/atoms/selection/SegmentedButton.svelte”; import Slider from “@components/atoms/selection/Slider.svelte”;

export const authorInfo = { framework: “Astro 7”, ui: “Svelte 5”, tokens: “M3E 设计令牌”, architecture: “群岛架构” };

export const showcaseItems = [ { name: “原子组件嵌入”, desc: “在文章正文里直接引入并渲染 60+ 个 M3E 原子与分子组件” }, { name: “Svelte 5 交互岛”, desc: “通过 client 选择性注水,杜绝任何多余的 JavaScript 开销” }, { name: “JSX 表达式”, desc: “原生 JavaScript 变量、数据映射与条件渲染” }, { name: “扩展管线”, desc: “Mermaid、KaTeX、提示块与 Expressive Code 的统一 SSOT 编译” } ];

export const filterChipOptions = [ { value: “all”, label: “全部组件” }, { value: “display”, label: “展示类原子” }, { value: “feedback”, label: “反馈类” }, { value: “action”, label: “交互类” } ];

export const segmentedOptions = [ { value: “linear”, label: “线性” }, { value: “circular”, label: “环形” }, { value: “morph”, label: “形变” } ];

1. Markdown 与 MDX 能力对照#

能力标准 Markdown(.md)Shirone MDX(.mdx)执行方式
排版与结构完整支持完整支持静态 SSR
代码高亮行号、外框、可折叠行号、外框、可折叠静态 SSR(Expressive Code)
图表与数学Mermaid、KaTeXMermaid、KaTeX客户端增强
提示块提示、技巧、重要、警告、注意提示、技巧、重要、警告、注意静态 SSR
M3E 展示类原子不可用直接集成(<Card>、<Skeleton>)纯 SSR(零客户端 JS)
Svelte 5 响应式岛不可用按需注水(<Button>、<Switch>)client:visible 懒加载注水
反馈与加载原子不可用形变动画(<LoadingIndicator>)client:visible 响应式
动态 JSX 表达式不可用原生求值({authorInfo.ui})编译期 / 客户端

2. 动态表达式与数据映射#

MDX 允许在文件顶部用 export const 声明作用域内的常量,随后可以内联求值,也可以在模板里循环渲染:

  • 核心框架:{authorInfo.framework}
  • UI 引擎:{authorInfo.ui}
  • 设计令牌:{authorInfo.tokens}
  • 架构模式:{authorInfo.architecture}

数组与集合可以动态渲染成网格布局:

{showcaseItems.map((item, idx) => (
{idx + 1} {item.name}

{item.desc}

))}

3. M3E 展示与布局原语(仅 SSR)#

按照 Shirone 的组件架构(docs/atomic-structure.md),无状态的展示类组件输出干净、无障碍的语义化 HTML,不携带任何客户端运行时负载。

3.1 卡片容器(Card.svelte)#

填充卡片
默认容器底色,不带高度投影。适合用来分组内容块。
抬升卡片
一级容器高度并带交互状态层,适合需要突出视觉焦点的场合。
描边卡片
1px 清晰描边,在中性底色上做出干净的分隔。

3.2 强调条与徽标(AccentBar 与 Badge)#

系统公告

把 AccentBar 与 Badge 组合起来,可以做出醒目的视觉提示

M3E v0.192

3.3 骨架占位(Skeleton.svelte)#

用于预览布局骨架,或给异步状态做原型:


4. 反馈与加载指示#

Shirone 内置完整还原的 Material 3 Expressive 动效与反馈原子:

4.1 形变加载指示器(LoadingIndicator.svelte)#

基于 androidx.graphics.shapes 的多边形形变实现,提供弹性插值的 7 种形状动画:

不定形形变
容器化环形变体
确定进度(68%)

4.2 线性与不定进度(ProgressIndicator.svelte)#

管线编译 80%
连续双向线条动画

5. Svelte 5 交互岛#

用 client:visible 声明的组件会在进入视口时通过 IntersectionObserver 懒加载注水:

5.1 按钮矩阵(Button.svelte)#

5.2 筛选标签与分段按钮(Chips 与 SegmentedButton)#

M3E 筛选标签
分段控件

5.3 开关、复选框与滑块(Switch、Checkbox、Slider)#

带状态图标的开关
选择复选框
色相滑块

5.4 输入控件(TextField.svelte)#


6. Markdown 扩展兼容性#

Shirone 的 SSOT 统一插件管线与全部 Markdown 扩展保持完全兼容:

6.1 GitHub 仓库卡片#

saicacafuwari

6.2 Mermaid 架构图#

flowchart TD
    MDX[MDX 源文件] --> Compiler["@astrojs/mdx 编译器"]
    Compiler --> Plugins["Remark / Rehype SSOT 管线"]
    Plugins --> Islands["Svelte 5 交互岛"]
    Islands --> Swup["Swup 客户端导航外壳"]
    Swup --> Screen["M3E 表现力文章视图"]

6.3 数学表达式(LaTeX / KaTeX)#

行内公式:质能等价 E=mc2E = mc^2 与高斯积分 ∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}。

块级公式:

LM3E=∑i=1N(Tokeni⋅ContrastRatio)+λ∥MotionElegance∥\mathcal{L}_{M3E} = \sum_{i=1}^{N} \left( \text{Token}_i \cdot \text{ContrastRatio} \right) + \lambda \|\text{MotionElegance}\|

7. 小结#

MDX 的原生集成让技术写作者可以构建丰富、可交互的文档,同时保留 Shirone 极快的静态性能。所有组件都遵循 Material 3 Expressive 令牌体系,确保一致性、无障碍与视觉和谐。

MDX 集成与 M3E 原子组件
https://www.dafeiyu.site/posts/mdx-showcase/
作者
蓝色大肥鱼
发布于
2026-08-20
许可协议
CC BY-NC-SA 4.0

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取

评论

0 条评论