重做设置面板的经过，以及把底层组件开源出去的事

大家好，我是开发 BotShade 的 Tettu。

在 v2.5.4 中，我们重做了所有带设置界面的功能在 Discord 上的设置面板。发布说明里写的是「外观与按钮位置会统一」，这没错，但它没有解释这些东西当初是怎么变得不统一的。写在发布说明里太长，所以单独开了这一篇。

文章最后还会讲讲，把这次重做中诞生的组件开源发布 这件事。

本文目录：

• 按钮位置为什么会跑偏
• 让「写错」这件事无法表达
• 重做过程中发现的东西
• 抽离为 KageKit
• 已经发布了

按钮位置为什么会跑偏

BotShade 的 Bot 拥有 19 项功能，其中大部分都会在 Discord 上显示设置面板。执行 /protection settings 会出现保护功能的设置，执行 /ticket settings 会出现工单的设置，就是这些。

它们由同一批人写在同一个仓库里，然而 「返回」按钮的位置却因功能而异。有的面板把它放在卡片内部，有的则放在消息最下方。设置的分组方式、颜色的用法，也都各有各的做法。

原因很简单：Discord 提供的新组件机制（Components V2）什么都能做。而「什么都能做」意味着，每做一张面板，都要把下面这些事重新决定一遍：

• 筛选标签放在卡片里，还是卡片外？
• 表示「无法撤销」的红色，用哪一个红？
• 打开子菜单时，是叠一条新消息，还是改写当前这条？

19 项功能，在 19 个不同的日子里各自决定，答案当然会不一致。就算写成规范说「请这样写」，规范就算被违反，程序照样能跑，所以忙起来的时候就会被违反。

让「写错」这件事无法表达

于是我们把规范从文字变成了 结构。位置由我们统一决定，写代码的人 只声明内容。

具体来说，面板现在由四层来表达：

• 标签栏 —— 「进行中 / 已结束 / 全部」这类，用来切换 这一页在显示什么。这是关于整页的事，所以放在卡片外侧的最上方。
• 卡片 —— 设置的内容本身。内容不同的设置分属不同卡片，卡片的颜色（绿 / 灰 / 红）表示该设置的状态或危险程度。
• 分页条 —— 用来翻动卡片 内部 的内容，形式为 ⏮ ◀ [ 3 / 12 ] ▶ ⏭，按下中间的页码可以直接跳转。
• 操作栏 —— 「刷新」「返回」「关闭」。这些是针对 整条消息 的操作，因此放在最下方、所有卡片之外。

关键在于，这个顺序 是不可选的。写代码的人不需要指定「标签栏放这里」「返回放那里」，只要把标签栏、卡片和返回的处理函数交出去，位置由结构决定。「把位置放错」这个行为，从根本上变得无法表达了。

另一个立竿见影的改进是，发送之前先检查容量。Discord 规定一条消息最多 40 个组件，超出就会被拒绝，而拒绝时的报错并不会告诉你是什么超了。以前这类失误只能靠实际发出去才发现，现在会在发送前停下，并告诉你 该删掉什么。

重做过程中发现的东西

把 19 项功能逐个迁移过去，本身就成了一次对既有面板的盘点。有些迁移之前没注意到的问题，在重新排布的过程中浮了出来。

• 欢迎消息的面板中，只有在正文已配置的情况下，设置行才会串进预览的容器里。这是手写卡片分隔造成的，改为声明式之后就消失了。
• 直接以数值写死的颜色 散落在各处，同一个「成功的绿色」在不同地方竟是略有差异的数值。现在统一从一处取用。
• 存在「看着是按钮、按下去却什么都不发生」的状态。现在，未指定按下行为的按钮会以 不可点击的样式 显示。

这些都不是收到缺陷报告的问题，只是「确实不太对」而已。作为重做的副产物，它们是最让人高兴的那一类收获。

抽离为 KageKit

上面写到的「标签栏、卡片、分页条、操作栏」这套机制，没有一处是 BotShade 特有的。任何用 Components V2 做设置面板的人，都会在同样的地方犯难。

于是我们把这部分从 BotShade 本体中剥离出来，做成了名为 KageKit 的独立组件。名字取自日语的「影（かげ）」，既延续了 BotShade 的 Shade，又避开了与现有库重名的问题。

剥离时我们特意做到：KageKit 内部 完全不包含 BotShade 的文案、配色和套餐上限。这些都由外部传入，并且加入了检测机制，确保它们不会混进来。BotShade 的品牌色只是由 BotShade 一侧注入的，KageKit 本身并不持有任何颜色。

它依赖的只有 discord.py 和 Python 标准库。

已经发布了

KageKit 以 MIT 许可证发布。

• 源代码：github.com/VorEdgeJP/kagekit
• 软件包：discord-kagekit

pip install discord-kagekit

可在 Python 3.11 以上、discord.py 2.7 以上的环境中运行。当前版本为 0.1.0，仍处于 Beta 阶段。它在生产环境中的使用记录，目前就只有 v2.5.4 中 19 项功能的迁移这一件。

缺陷报告，以及「希望能有某某组件」这类需求，欢迎通过 GitHub Issue 提出。

对使用 BotShade 的各位来说，坦白讲，这件事除了「设置面板变好用了」之外并没有更多关联。只是我们因为自己遇到麻烦才做了这个东西，如果它能帮到在同样地方犯难的人，那还是放出去为好——动机仅此而已。

意见和感想欢迎通过 支持页面 告诉我们。

那么，下次再会。