---
title: 常用组件
description: MDC 写法、28 个自定义组件、Nuxt UI 内容组件及 Markdown 渲染覆盖的完整索引。
navigation:
  icon: lucide-component
---

## 组件使用方式

Estel Docs 基于 Nuxt Content MDC 语法，把 Vue 组件放进 Markdown。组件名使用 kebab-case，例如：

- `ECard.vue` → `::e-card`
- `ETabs.vue` → `::e-tabs`
- `FileTree.vue` → `::file-tree`
- `ButtonLink.vue` → `::button-link`

::tip
从 [MDC 语法与注册](/docs/简单文档/components/mdc-guide) 开始学习。新增组件的 [说明与可复制代码](/docs/简单文档/components/content-blocks) 和 [交互演示](/docs/简单文档/components/mdc-showcase) 都是实际 Markdown 页面，博客示例见 [用 MDC 组织技术文章](/blog/技术栈/mdc-article-example)。
::

进阶组件的 [API 与示例](/docs/简单文档/components/interactive-blocks) 和 [交互演示](/docs/简单文档/components/interactive-showcase) 已补充数据、接口和阅读互动能力。

## 组件清单

| 组件 | 用途 | 关键参数 |
| --- | --- | --- |
| `ECard` | 卡片容器，基于 `UPageCard`。 | `title`、`description`、`icon`、`img`、`spotlight`、`content` |
| `ETabs` | 标签页容器，从默认插槽读取 tab。 | 子项 `label`、`icon` |
| `Stack` | 将多个内容块放入分割卡片中。 | 默认插槽 |
| `FileTree` | 展示文件/目录结构。 | `tree`、`title`、`icon`、`autoSlash`、`showArrow`、`showIcon` |
| `CodeTree` | 基于 ProseCodeTree 展示代码文件树。 | 透传属性 |
| `ButtonLink` | 按钮式链接。 | `to`、`href`、`target`、`blank`、`icon`、`leftIcon`、`rightIcon`、`trailingIcon`、`variant`、`size`、`color` |
| `Playground` | 嵌入 StackBlitz 或 CodeSandbox。 | `provider`、`id`、`repo`、`branch`、`dir`、`file`、`title` |
| `ReadMore` | 阅读更多提示卡片。 | `to`、`title`、`description`、`icon`、`color`、`variant` |
| `SmartIcon` | 自动识别 Iconify 图标、Emoji 或图片 URL。 | `name`、`size` |
| `ColorModeSwitch` | 大尺寸明暗模式切换开关。 | 无 |
| `Alert` | 兼容旧文章中的 `::alert`。 | `title`、`icon`、`type`、`color`、`to`、`target`、`external`、`showLinkIcon` |
| `ArticleSummary` | 文章摘要、结论或阅读要点。 | `title`、`icon`；默认与 `takeaway` 插槽 |
| `ExpandBox` | 折叠补充说明、FAQ、长输出。 | `title`、`open`；默认插槽 |
| `LinkCard` | 参考文献或文档入口卡片。 | `title`、`to`、`description`、`icon`、`target`；默认插槽 |
| `QuoteBlock` | 引用正文与来源署名。 | `author`、`source`、`to`；默认插槽 |
| `StatGrid` | 指标与成果数字展示。 | `items`、`columns` |
| `DocTimeline` | 更新日志、事件或调查过程。 | `label`；嵌套 `TimelineItem` |
| `TimelineItem` | 时间线条目，正文支持 Markdown。 | `title`、`date`、`datetime`；默认插槽 |
| `TaskChecklist` | 可勾选的阅读/操作检查清单。 | `title`、`items`、`readonly`、`storageKey` |
| `ImageGallery` | 图片网格与键盘可操作的大图预览。 | `title`、`images`、`columns` |
| `ApiEndpoint` | 接口方法、路径、认证与请求/响应示例。 | `path`、`method`、`title`、`auth`、`status`；request/response 插槽 |
| `ParameterTable` | 参数类型、必填、弃用、默认值与枚举。 | `title`、`parameters` |
| `DataTable` | 搜索、排序、分页和 CSV 导出的结构化数据表。 | `title`、`columns`、`rows`、`searchable`、`pageSize`、`exportable` |
| `PackageInstall` | 切换 pnpm/npm/yarn/bun 并复制安装命令。 | `packages`、`dev`、`title` |
| `ImageCompare` | 可拖动与键盘操作的图片前后对比。 | `beforeSrc`、`afterSrc`、`beforeAlt`、`afterAlt`、`title`、`initialPosition` |
| `GlossaryTerm` | 行内术语解释，支持原生 popover。 | `term`、`definition` |
| `ContentQuiz` | 当前页面的单选阅读自测。 | `question`、`choices`、`answer`、`explanation` |
| `DownloadCard` | 站内文件下载或外部下载链接。 | `title`、`href`、`filename`、`description`、`version`、`size` |

表中共 28 个公共自定义组件。`FileTreeItem` 是 `FileTree` 的内部递归节点，使用者应传 `tree`，不直接写 `::file-tree-item`。`CodeTree` 是代理组件，Markdown 的 `::code-tree` 默认由 Nuxt UI 映射至同一底层 `ProseCodeTree`。

### Nuxt UI 提供的 MDC 组件

以下 24 个语法入口由当前安装的 Nuxt UI 4 的 MDC 映射提供，实际实现为 `Prose*`，并非本站重新实现：

| 用途 | MDC 入口 |
| --- | --- |
| 提醒 | `::callout`、`::note`、`::tip`、`::warning`、`::caution` |
| 卡片 | `::card`、`::card-group` |
| 代码 | `::code-group`、`::code-collapse`、`::code-preview`、`::code-tree`、`:code-icon` |
| 分组交互 | `::accordion` + `::accordion-item`、`::collapsible`、`::tabs` + `::tabs-item` |
| 文档说明 | `::steps`、`:field`、`::field-group` |
| 行内内容 | `:badge`、`:icon`、`:kbd`、`:prompt` |

卡片、标签页等旧名称继续可用。`::callout` 使用 `color`；本站 `::alert` 额外兼容旧 `type`。新文档优先参考当前 [Nuxt UI Typography](https://ui.nuxt.com/docs/typography/callout)，不要套用已过时的 shadcn 模板属性。

### 自动渲染的 Markdown 覆盖

`ProseH1`～`ProseH6`、`ProsePre`、`ProseImg`、`ProseStrong`、`ProseStyle` 共 10 个文件覆盖标题、代码块、图片图注、粗体样式和公式生成的 CSS。直接写 `# 标题`、代码围栏、`![图片](/logo.png)` 或 `**重点**` 即可，不需要写 `::prose-h1`。`ProseStyle` 是内部渲染适配，保证 MathJax 的样式在 SSR 和客户端一致；其余段落、列表、表格、链接等使用上游 Prose 组件。

### 教学示例组件

`app/components/example/` 下的 9 个组件按需全局注册，供讲解和实验使用：`ExampleAlert`、`ExampleCard`、`ExampleTitle`、`ExampleHero`、`ExampleIconCard`、`ExampleLandingHero`，以及 `ExampleFulltextContentSearch`、`ExampleFulltextFusejs`、`ExampleFulltextMiniSearch`。写法例如 `::example-title`。搜索示例会查询本站内容；文章排版优先使用上面的公共内容组件。原有博客中的 `::example-title` 也能继续渲染。

## ECard

用于创建内容卡片，可展示标题、描述、图标、图片和插槽内容。

```mdc
::e-card{title="功能卡片" description="用于突出展示一段内容" icon="lucide-sparkles"}
这里是卡片正文，支持 **Markdown**。
::
```

带图片：

```mdc
::e-card{title="图片卡片" img="/images/default-blog.jpg"}
图片会展示在卡片内部。
::
```

## ETabs

`ETabs` 会读取默认插槽中的 `div` 节点，并从其 props 中获取 `label` 与 `icon`。

````mdc
::e-tabs
  ::div{label="pnpm" icon="simple-icons-pnpm"}
  ```bash
  pnpm install
  ```
  ::

  ::div{label="npm" icon="simple-icons-npm"}
  ```bash
  npm install
  ```
  ::
::
````

## Stack

`Stack` 适合把多个段落、图片或代码块按分割线堆叠展示。

```mdc
::stack
  ::div
  第一段内容。
  ::

  ::div
  第二段内容。
  ::
::
```

## FileTree

`FileTree` 使用 `tree` 数组描述目录结构。

```mdc
::file-tree{title="项目结构" :tree='[
  { "app": ["app.vue", { "components": ["ThemeSettings.vue"] }] },
  { "content": ["docs/", "blog/"] },
  "nuxt.config.ts"
]'}
::
```

约定：

- 文件名用字符串表示。
- 目录用对象表示。
- `^文件名^` 可标记高亮。
- `+文件名` / `-文件名` 可表示新增/删除差异。

## CodeTree

`CodeTree` 透传给 Nuxt UI ProseCodeTree，适合展示多个代码文件。

````mdc
::code-tree{defaultValue="nuxt.config.ts"}
```ts [nuxt.config.ts]
export default defineNuxtConfig({})
```

```vue [app/app.vue]
<template>
  <NuxtPage />
</template>
```
::
````

## ButtonLink

用于在文档中放置按钮链接。

```mdc
::button-link{to="/docs" icon="lucide-book-open" trailingIcon="lucide-arrow-right" variant="solid" size="md"}
进入文档
::
```

外链：

```mdc
::button-link{href="https://nuxt.com" blank=true icon="simple-icons-nuxtdotjs"}
Nuxt 官网
::
```

## Playground

用于嵌入 StackBlitz 或 CodeSandbox。默认点击“加载在线示例”后再连接外部网站，避免读文章时自动启动在线 IDE。确实需要自动加载时设置 `:autoload="true"`。

```mdc
::playground{provider="stackblitz" repo="nuxt/nuxt" branch="main" file="package.json" title="Nuxt Playground"}
::
```

支持：

- `provider="stackblitz"`
- `provider="codesandbox"`
- `id` 模式
- GitHub `repo + branch + dir + file` 模式

## ReadMore

用于给出延伸阅读入口。

```mdc
::read-more{to="/docs/简单文档/deployment" title="继续阅读部署指南" icon="lucide-cloud" color="primary"}
了解静态生成、SSH 发布、微信签名服务和版本回滚。
::
```

## SmartIcon

`SmartIcon` 会根据 `name` 自动判断：

1. Iconify 图标名。
2. Emoji。
3. 图片 URL。

```mdc
:smart-icon{name="lucide-star" size=24}
:smart-icon{name="🚀" size=24}
:smart-icon{name="/favicon.ico" size=24}
```

## ColorModeSwitch

用于展示一个较大的明暗模式开关。

```mdc
::color-mode-switch
::
```

## 编写新组件的建议

新增内容组件时建议：

1. 放在 `app/components/content/` 下；公共 API 同时加入 `app/plugins/content-components.ts` 和 `shared/mdc-components.ts`，让 Markdown 注册与 Studio 选择器保持一致。
2. 使用明确的 props 类型。
3. 保持 SSR 安全，避免在服务端直接访问 `window` 或 `document`。
4. 提供 props、插槽、可复制代码及真实渲染示例，并在 docs/blog 两种页面验证。
5. 如果组件依赖外部脚本，应使用 `ClientOnly` 或在 `onMounted` 中加载。

## 可扩展方向

- 为每个内容组件补充独立 API 页面。
- 自动生成组件 props 文档。
- 投票、反馈和需要跨设备同步的进度属于有后端的新功能；现有检查清单可通过 `storageKey` 保存到当前浏览器。
- 将组件示例纳入 E2E 截图测试，防止样式退化。