For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /ethereal/sidebar/widgets.md.

小组件详解

适用版本 ≥ 2.0.0 | 后台路径:主题设置 → 侧边栏

每个小组件的参数都在同名分组里,添加 / 排序在 小组件与布局。以下按分组顺序说明。

个人简介

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

在线状态子组:

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

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

公告

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

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

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

站点统计

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

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

天气

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

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

一言

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

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

音乐播放器

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

最近日程

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

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

无需额外配置的小组件

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

注意事项

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