From 572d0338f136e807967290521588a4f523bac9ad Mon Sep 17 00:00:00 2001 From: liruifengv Date: Sat, 22 Nov 2025 10:56:28 +0800 Subject: [PATCH] =?UTF-8?q?i18n(zh-cn):=20Update=20`mdx.mdx`=E3=80=81`cont?= =?UTF-8?q?ent-collections.mdx`=20and=20`directive-reference.mdx`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs/zh-cn/guides/content-collections.mdx | 2 + .../zh-cn/guides/integrations-guide/mdx.mdx | 68 ++++++++++++------- .../zh-cn/reference/directives-reference.mdx | 2 +- 3 files changed, 47 insertions(+), 25 deletions(-) diff --git a/src/content/docs/zh-cn/guides/content-collections.mdx b/src/content/docs/zh-cn/guides/content-collections.mdx index d00fae769942e..4898982009755 100644 --- a/src/content/docs/zh-cn/guides/content-collections.mdx +++ b/src/content/docs/zh-cn/guides/content-collections.mdx @@ -419,6 +419,8 @@ const { Content, headings } = await render(entry); ``` +在处理 MDX 条目时，你也可以 [将自定义组件传递给 ``](/zh-cn/guides/integrations-guide/mdx/#将-components-传给-mdx-内容)，使用自定义组件替换 HTML 元素。 + #### 将内容作为 props 传递 组件还可以将整个集合条目作为 prop 传递。 diff --git a/src/content/docs/zh-cn/guides/integrations-guide/mdx.mdx b/src/content/docs/zh-cn/guides/integrations-guide/mdx.mdx index fff267ef647bf..d6c037fa4ccdc 100644 --- a/src/content/docs/zh-cn/guides/integrations-guide/mdx.mdx +++ b/src/content/docs/zh-cn/guides/integrations-guide/mdx.mdx @@ -172,7 +172,7 @@ author: 'Houston' 在 [MDX 文档](https://mdxjs.com/docs/what-is-mdx/#esm)中查看有关使用导入和导出语句的更多示例。 -```mdx title="src/blog/post-1.mdx" {4,9} +```mdx title="src/blog/post-1.mdx" {4,10} --- title: 我的第一篇博客 --- @@ -184,47 +184,67 @@ import ReactCounter from '../components/ReactCounter.jsx'; ``` +#### 将自定义组件分配给 HTML 元素 -#### 使用导入的 MDX 自定义组件 +使用 MDX，你可以将 Markdown 语法映射到自定义组件，而不是它们的标准 HTML 元素。这允许你以标准的 Markdown 语法编写，但是将特殊的组件样式应用于所选的元素。 -渲染导入的 MDX 内容时，可以通过 `components` 属性传递 [自定义组件](#将自定义组件分配给-html-元素)。 +例如，你可以创建一个 `Blockquote.astro` 组件来为 `
` 内容提供自定义样式： -```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" +```astro title="src/components/Blockquote.astro" --- -import { Content, components } from '../content.mdx'; -import Heading from '../Heading.astro'; +const props = Astro.props; --- - - +
+ “ + +
``` +将你的自定义组件导入 `.mdx`文件，然后将标准 HTML 元素映射到自定义组件的 `components` 对象以导出： + +```mdx title="src/blog/posts/post-1.mdx" +import Blockquote from '../components/Blockquote.astro'; +export const components = {blockquote: Blockquote} + +> 这个引用将是自定义引用块组件。 +``` +访问 [MDX 网站](https://mdxjs.com/table-of-components/)，了解可以覆盖为自定义组件的 HTML 元素的完整列表。 + :::note -在 MDX 文件中定义并导出的自定义组件必须通过 `components` 属性导入并传递回 `` 组件。 +在 MDX 文件中定义并导出的自定义组件必须始终先被导入，然后通过 `components` 属性传回给 `` 组件。 ::: -#### 将自定义组件分配给 HTML 元素 +#### 将 `components` 传给 MDX 内容 -使用 MDX，你可以将 Markdown 语法映射到自定义组件，而不是它们的标准 HTML 元素。这允许你以标准的 Markdown 语法编写，但是将特殊的组件样式应用于所选的元素。 +在使用 `` 组件渲染导入的 MDX 内容时（包括使用内容集合渲染 MDX 条目），可以通过 `components` 属性传入自定义组件。这些组件必须先被导入，才能使 `` 组件可用。 -将自定义组件导入 `.mdx`文件，然后将标准 HTML 元素映射到自定义组件的 `components` 对象以导出： +`components` 对象将 HTML 元素名称（`h1`、`h2`、`blockquote` 等）映射到你的自定义组件。你也可以使用扩展运算符（...）[包含从 MDX 文件本身导出的所有组件](#将自定义组件分配给-html-元素)，这些组件也必须作为 `components` 从你的 MDX 文件中导入。 -```mdx title="src/blog/posts/post-1.mdx" -import Blockquote from '../components/Blockquote.astro'; -export const components = {blockquote: Blockquote} +如果你直接从单个文件导入 MDX 在 Astro 组件中使用，请同时导入 `Content` 组件以及你 MDX 文件中导出的任何组件。 -> 这个引用将是自定义引用块组件。 +```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" {2} +--- +import { Content, components } from '../content.mdx'; +import Heading from '../Heading.astro'; +--- + + ``` -```astro title="src/components/Blockquote.astro" +如果你的 MDX 文件是内容集合中的一条条目，则使用来自 `astro:content` 的 `render()` 函数来访问 `` 组件。 + +下面的示例通过 `components` 属性向 `` 组件传入一个自定义标题，以取代所有 `

` HTML 元素： + + +```astro title="src/pages/blog/post-1.astro" ins="components={{ h1: CustomHeading }}" --- -const props = Astro.props; +import { getEntry, render } from 'astro:content'; +import CustomHeading from '../../components/CustomHeading.astro'; +const entry = await getEntry('blog', 'post-1'); +const { Content } = await render(entry); --- -
- “ - -
+ ``` -访问 [MDX 网站](https://mdxjs.com/table-of-components/)，了解可以覆盖为自定义组件的 HTML 元素的完整列表。 ## 配置 @@ -379,7 +399,7 @@ export default defineConfig({

以前称为 `customComponentNames`。 -`optimize` 的一个可选属性，用于防止 MDX 优化器处理某些元素名称，例如通过 components 属性传递给导入的 MDX 内容的[自定义组件](/zh-cn/guides/integrations-guide/mdx/#使用导入的-mdx-自定义组件)。 +`optimize` 的一个可选属性，用于防止 MDX 优化器处理某些元素名称，例如通过 components 属性传递给导入的 MDX 内容的[自定义组件](/zh-cn/guides/integrations-guide/mdx/#将-components-传给-mdx-内容)。 你需要将这些组件从优化中排除，因为优化器会急切地将内容转换为静态字符串，这将破坏需要动态呈现的自定义组件。 diff --git a/src/content/docs/zh-cn/reference/directives-reference.mdx b/src/content/docs/zh-cn/reference/directives-reference.mdx index 979e8e5e6594b..9598c9cff38be 100644 --- a/src/content/docs/zh-cn/reference/directives-reference.mdx +++ b/src/content/docs/zh-cn/reference/directives-reference.mdx @@ -115,7 +115,7 @@ import api from '../db/api.js'; 默认情况下，UI 框架组件不会在客户端激活。如果没有 `client:*` 指令，它的 HTML 将被渲染到页面上，而无需 JavaScript。 -客户端指令只能用于直接引入到 `.astro` 组件中的 UI 框架组件。 使用 [动态标签](/zh-cn/reference/astro-syntax/#动态标签) 和 [通过 `components` prop 传递的自定义组件](/zh-cn/guides/integrations-guide/mdx/#使用导入的-mdx-自定义组件) 时，不支持 Hydration 指令。 +客户端指令只能用于直接引入到 `.astro` 组件中的 UI 框架组件。 使用 [动态标签](/zh-cn/reference/astro-syntax/#动态标签) 和 [通过 `components` prop 传递的自定义组件](/zh-cn/guides/integrations-guide/mdx/#将-components-传给-mdx-内容) 时，不支持 Hydration 指令。 ### `client:load`