> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 小组件详解

> 适用版本 ≥ 2.0.0 ｜ 后台路径：主题设置 → 侧边栏

每个小组件的参数都在同名分组里，添加 / 排序在 [小组件与布局](/ethereal/sidebar/overview.md)。以下按分组顺序说明。

## 个人简介

| 选项   | 默认值      | 说明                         |
| ---- | -------- | -------------------------- |
| 头像   | 示例头像     | 建议 1:1 正方形                 |
| 昵称   | NanNan   | 显示在头像下方                    |
| 简介   | 示例文本     | 一两句话，建议不超过 60 字            |
| 链接   | `/about` | 点击卡片跳转的地址，可填 `/login` 直达登录 |
| 社交媒体 | 空        | 每条包含图标（Iconify）、名称、链接      |

在线状态子组：

| 选项     | 默认值 | 说明                                                |
| ------ | --- | ------------------------------------------------- |
| 启用在线状态 | 开启  | 关闭后隐藏昵称右侧状态表情与下方文案设置                              |
| 当前状态   | 在线中 | 在线中 / 元气满满 / emo中 / 学习中 / 忙碌中 / 请勿打扰 / 睡觉中 / 暂时离开 |
| 状态文案   | 空   | 每种状态可单独填写，留空用默认；最多 10 字                           |

> 登录管理员账号后，可**直接在前端点状态表情切换**，无需回后台。

## 公告

| 选项         | 默认值  | 说明                              |
| ---------- | ---- | ------------------------------- |
| 公告内容       | 示例公告 | 纯文本或 HTML                       |
| 内容呈现为 HTML | 关闭   | 开启后可写链接、图标、富文本；内容不过滤，只填可信 HTML  |
| 内容最大高度     | 640  | 仅 HTML 模式生效，超出后公告内部滚动（40\~1024） |
| 允许关闭       | 开启   | 访客可点击关闭按钮隐藏公告                   |

链接设置子组：启用链接（默认关闭）、链接文本（了解更多）、链接地址、外部链接（新标签页打开）。

> HTML 模式请使用 `px` / `rem` 固定尺寸，避免使用 `100%` 这类依赖父级宽度的写法；带脚本时用类选择器初始化，不要用 `id`。

## 站点统计

| 选项     | 默认值                    | 说明                             |
| ------ | ---------------------- | ------------------------------ |
| 统计项    | 文章、分类、标签、总字数、最后活动、运行天数 | 可多选，**勾选顺序即展示顺序**；一项都不选时该卡片不渲染 |
| 网站上线日期 | 空                      | 用于计算运行天数，留空则不显示该项              |

可选统计项还包括访问量、点赞数、评论数（依赖对应插件或接口）。

## 天气

| 选项         | 默认值    | 说明                                  |
| ---------- | ------ | ----------------------------------- |
| 腾讯位置服务 Key | 空      | 在腾讯位置服务控制台申请，免费                     |
| 默认城市编码     | 110000 | IP 定位失败时的回退城市，填写行政区划编码，如 310000（上海） |

> Key 会**明文出现在前端源码**，务必在控制台配置域名白名单，并为「天气」与「IP 定位」分别分配合额。欢迎弹窗共用这个 Key。

## 一言

| 选项        | 默认值        | 说明                               |
| --------- | ---------- | -------------------------------- |
| 一言 API 地址 | 空          | 留空使用内置 `https://v1.hitokoto.cn/` |
| 获取失败文案    | 世界很大，开心第一。 | 上游超时或失败时显示                       |
| 获取失败来源    | 楠南NanNan   | 失败时显示的作者 / 来源                    |

> 请求默认 5 秒超时，失败即回落文案；连续失败时不会阻塞页面其它脚本。

## 音乐播放器

| 选项             | 默认值   | 说明                                                        |
| -------------- | ----- | --------------------------------------------------------- |
| 平台             | 网易云音乐 | 网易云 / QQ 音乐 / 酷狗 / 虾米 / 百度                                |
| 类型             | 歌单    | 歌曲 / 歌单 / 专辑 / 歌手 / 搜索                                    |
| ID             | 空     | 对应类型的 ID；搜索类型填关键词。未填时前台提示「音乐播放器未配置 ID」                    |
| 播放模式           | 列表循环  | 列表循环 / 单曲循环 / 随机                                          |
| 默认音量           | 0.7   | 0\~1                                                      |
| 自定义 Meting API | 空     | 留空用 MetingJS 默认 API，地址支持 `:server`、`:type`、`:id`、`:r` 占位符 |

## 最近日程

| 选项   | 默认值 | 说明                 |
| ---- | --- | ------------------ |
| 显示条数 | 3   | 最多 10 条；条数过多会把侧栏撑高 |

> 依赖「日程日历」插件，插件未安装时卡片自动隐藏。

## 无需额外配置的小组件

| 小组件      | 数据来源            | 说明                           |
| -------- | --------------- | ---------------------------- |
| 热门文章     | Halo 文章浏览量      | 按访问量排序，数量由组件自身控制             |
| 文章分类     | Halo 分类         | 展示分类及数量                      |
| 文章标签     | Halo 标签         | 标签云样式                        |
| 自定义 HTML | 条目里的「名称 / HTML」 | 名称作为标题，HTML 原样渲染（不过滤，只填可信内容） |

## 注意事项

- 同一类型小组件可以重复添加，**共用同一份配置**，不会各自独立
- 依赖插件的小组件（天气、日程、音乐）在插件缺失或接口失败时会降级或隐藏，不会让整栏空白
- 自定义 HTML 会被原样插入页面，粘贴第三方脚本前请确认来源可信
- 小组件内容在换页时不会重新请求（侧栏常驻），需要刷新的数据（如天气）由组件自身的定时器控制