Rspress全局组件
/ 3 min read
在 Rspress 中,你可以在 MDX 文件中注册全局可用的组件,主要通过 markdown.globalComponents
配置实现。这与之前讨论的 globalUIComponents
不同,后者是在整个站点层面注册组件,而 markdown.globalComponents
专门用于在 MDX 文件中注册全局可用的组件。
在配置文件中注册 MDX 全局组件
你可以在 rspress.config.ts
中通过 markdown.globalComponents
配置项注册全局可用的 MDX 组件:
import { defineConfig } from 'rspress/config';import path from 'path';
export default defineConfig({ markdown: { globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')], },});
config-build.mdx:225-233
注册后,你可以在任何 MDX 文件中直接使用这些组件,而无需导入:
<Alert type="info">This is a info alert</Alert>
config-build.mdx:238-240
通过插件注册 MDX 全局组件
你也可以通过插件系统注册 MDX 全局组件:
import { RspressPlugin } from '@rspress/shared';
export function pluginForDoc(): RspressPlugin { return { name: 'plugin-name', markdown: { mdxRs: false, globalComponents: [ // 为 MDX 注册全局组件 ], }, };}
plugin-api.mdx:218-236
重要注意事项
使用 markdown.globalComponents
时,必须将 markdown.mdxRs
设置为 false
,否则全局组件将不会生效:
export default defineConfig({ markdown: { mdxRs: false, globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')], },});
config-build.mdx:242-244
这是因为 Rspress 默认使用基于 Rust 的 MDX 编译器(mdxRs),但全局组件功能需要使用 JavaScript 版本的编译器才能正常工作。
与 globalUIComponents 的区别
markdown.globalComponents
:仅在 MDX 文件内部可用,需要禁用 Rust 版本的 MDX 编译器globalUIComponents
:在整个站点层面注册组件,不受 MDX 编译器版本的影响
组件实现示例
你的全局 MDX 组件是普通的 React 组件,例如:
import React from 'react';
const Alert = ({ type, children }) => { return ( <div className={`alert alert-${type}`}> {children} </div> );};
export default Alert;
注册后,这个组件可以在任何 MDX 文件中直接使用,无需导入。
Notes
在 Rspress 中注册 MDX 全局组件需要使用 markdown.globalComponents
配置,并且必须将 markdown.mdxRs
设置为 false
。这与 globalUIComponents
不同,后者是在整个站点层面注册组件,而前者专门用于在 MDX 文件内部使用的组件。