这篇文章展示了博客中所有可用的 MDX 自定义组件,包括使用示例和最佳实践。
目录
- Alert 提示框组件
- Callout 标注框组件
- Image 图片组件
- YouTube 视频组件
- CodeSandbox 代码沙盒
- 组合使用示例
Alert 提示框组件
Alert 组件用于显示重要提示、警告、错误或成功信息,支持 4 种类型。
Info - 信息提示
这是一个信息提示框,用于显示一般性的提示信息。支持 Markdown
语法,包括加粗、斜体、行内代码等。
Warning - 警告提示
这是一个警告提示框,用于提醒用户注意某些重要事项。
- 可以包含列表
- 支持多行内容
- 自动适配深色/浅色主题
Error - 错误提示
这是一个错误提示框,用于显示错误信息或失败状态。
# 甚至可以包含代码块
npm install error-packageSuccess - 成功提示
这是一个成功提示框,用于显示操作成功的消息。非常适合用于教程中标记完成的步骤!
Callout 标注框组件
Callout 组件用于突出显示重要内容或补充说明,可以自定义 emoji 图标。
参考资料: 使用 📚 图标,适合引用文档或外部资源。可以包含链接:MDX 官方文档
快速提示: Callout 组件非常适合用于: - 重点标注关键信息 - 补充说明和注意事项 - 提供额外的上下文 - 分享技巧和最佳实践
Image 图片组件
Image 组件提供了强大的图片展示功能,支持多种尺寸预设、图片说明、加载状态和错误处理。
基础用法
尺寸预设
图片组件提供 4 种尺寸预设: - small: 400px 最大宽度,适合小图标、示意图 - medium: 600px 最大宽度,默认尺寸,适合常规配图 - large: 800px 最大宽度,适合重要配图 - full: 100% 宽度,适合全宽展示
Small 小图
Medium 中图 (默认)
Large 大图
Full 全宽
1:1 长宽比图片
问题解决: 1:1 长宽比的图片不再占满整个宽度,而是根据尺寸预设合理显示,避免图片过大的问题。
图片说明文字
YouTube 视频组件
YouTube 组件用于嵌入 YouTube 视频,自动响应式布局。
只需提供 YouTube 视频 URL 中 v= 后面的视频 ID 即可。 例如:
https://www.youtube.com/watch?v=dQw4w9WgXcQ 中的 ID 是 dQw4w9WgXcQ
CodeSandbox 代码沙盒
CodeSandbox 组件用于嵌入可交互的代码示例,非常适合技术教程。
提供 CodeSandbox 项目的 ID,可以从 CodeSandbox URL 中获取。 例如:
https://codesandbox.io/s/react-new 中的 ID 是 react-new
CodeSandbox 组件会嵌入一个完整的在线 IDE,读者可以直接在文章中编辑和运行代码。
组合使用示例
MDX 的强大之处在于可以灵活组合使用各种组件,创建丰富的内容体验。
示例 1: 教程步骤
首先安装必要的依赖包: bash npm install react react-dom
创建你的第一个 React 组件!
示例 2: 问题解决方案
如果遇到 "Module not found" 错误,请检查以下几点: - 依赖是否正确安装 - 导入路径是否正确 - package.json 配置是否完整
解决方案: 1. 删除 node_modules 文件夹 2. 删除 package-lock.json 3. 重新运行 npm install
按照上述步骤操作后,问题应该就能解决了!
示例 3: 对比展示
使用全局变量存储状态
使用 React Hooks 管理状态
主题适配
所有组件都完美支持深色/浅色主题切换:
自动主题适配: 所有 MDX 组件都使用 CSS 变量,会自动适配当前主题。试试切换主题看看效果!
组件使用 --mdx-* CSS 变量,在 globals.css 中统一管理颜色,确保主题切换时的一致性。
最佳实践
组件使用建议: 1. Alert: 用于重要信息、警告、错误提示 2. Callout: 用于补充说明、技巧、最佳实践 3. Image: 合理选择尺寸,添加有意义的 caption 4. YouTube/CodeSandbox: 用于增强教程的互动性 5. 组合使用: 创建结构化、易读的内容
- 不要过度使用组件,保持内容的可读性 - 确保 alt 文本和 caption 有意义 - 外部资源(YouTube/CodeSandbox)需要网络连接
现在你已经掌握了所有 MDX 组件的使用方法!开始创作精彩的博客文章吧!
代码示例
当然,标准的 Markdown 代码块也完全支持:
// TypeScript 代码示例
interface User {
id: number;
name: string;
email: string;
}
const user: User = {
id: 1,
name: "Alice",
email: "alice@example.com",
};
console.log(`Hello, ${user.name}!`);// React 组件示例
function Welcome({ name }) {
return (
<div className="welcome">
<h1>Hello, {name}!</h1>
<p>Welcome to our blog!</p>
</div>
);
}总结
MDX 让你可以在 Markdown 中无缝使用 React 组件,创建丰富、交互式的博客内容!