组件特性

常用组件

Estel Docs 自定义内容组件速查文档。

组件使用方式

Estel Docs 基于 Nuxt Content MDC 语法，将 app/components/content/ 下的 Vue 组件暴露给 Markdown 使用。组件名通常会转换为 kebab-case，例如：

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

部分组件也有单独页面说明，例如 CodeTree、FileTree、Playground、Tabs、ReadMore。本页作为总览与速查。

组件清单

组件	用途	关键参数
`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`、`trailingIcon`、`variant`、`size`
`Playground`	嵌入 StackBlitz 或 CodeSandbox。	`provider`、`id`、`repo`、`branch`、`dir`、`file`、`title`
`ReadMore`	阅读更多提示卡片。	`to`、`title`、`icon`、`color`、`variant`
`SmartIcon`	自动识别 Iconify 图标、Emoji 或图片 URL。	`name`、`size`
`ColorModeSwitch`	大尺寸明暗模式切换开关。	无

ECard

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

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

带图片：

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

ETabs

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

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

npm install


## Stack

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

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

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

FileTree

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

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

约定：

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

CodeTree

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

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

app/app.vue

<template>
  <NuxtPage />
</template>


## ButtonLink

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

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

外链：

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

Playground

用于嵌入 StackBlitz 或 CodeSandbox。

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

支持：

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

用于给出延伸阅读入口。

::read-more{to="/docs/简单文档/deployment" title="继续阅读部署指南" icon="lucide-cloud" color="primary"}
了解 Docker、CI/CD、微信签名服务与生产检查清单。
::

SmartIcon

SmartIcon 会根据 name 自动判断：

Iconify 图标名。
Emoji。
图片 URL。

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

ColorModeSwitch

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

::color-mode-switch
::

编写新组件的建议

新增内容组件时建议：

放在 app/components/content/ 下。
使用明确的 props 类型。
保持 SSR 安全，避免在服务端直接访问 window 或 document。
为复杂组件提供示例文档。
如果组件依赖外部脚本，应使用 ClientOnly 或在 onMounted 中加载。

可扩展方向

为每个内容组件补充独立 API 页面。
自动生成组件 props 文档。
增加更多交互组件，如复制块、投票、反馈、步骤进度。
将组件示例纳入 E2E 截图测试，防止样式退化。

编辑页面 or 提交问题