--- title: "中间件与组件" description: "用中间件做关键词回复和消息过滤,用 JSX 写图文消息、按钮和卡片,并了解不同平台上的显示效果" --- # 中间件与组件 要在渲染前按会话选择文本表达,见[定制内置展示](./behavior-customization.md)。 - **中间件**是每条消息都会经过的拦截器,适合关键词回复、过滤、审核。 - **组件**是可复用的消息卡片,用 JSX 编写。 命令、中间件和组件都可以直接返回 JSX:同一份内容,在支持图片的平台显示为图片,在其他平台自动降级为文字。 ## 中间件 ### 关键词回复 ```ts // middlewares/keyword-reply/index.ts import { defineMiddleware } from 'zhin.js/middleware'; import type { Message } from 'zhin.js'; export default defineMiddleware({ handle({ input }, next) { if (input.content === '状态') return '在线'; return next(); }, }); ``` 用户发送"状态"时 Bot 回复"在线";其他消息通过 `next()` 交给后面的中间件和命令。`input` 就是收到的消息,常用的有 `content`(文字内容)、`sender`(发送者)和 `$reply()`。 ### 返回值决定了会发生什么 | 写法 | 结果 | | --- | --- | | `return '在线'` 或 `return 在线` | 不再往下传,直接用这个内容回复 | | `return next()` | 交给后面处理,沿用后面产生的回复 | | `await next()`,不返回 | 同上 | | `await next(); return OK` | 先让后面处理,再把它的回复**替换**成你的内容 | | 不调用 `next()`,也不返回 | 吞掉这条消息,不回复 | - 整条链走完后才会**自动回复一次**;如果中途用 `$reply()` 手动发送,可以发多次,且之后无法撤回。 - 每个中间件最多调用一次 `next()`。它的返回值只用于往回传递,不是可修改的消息对象。 - 命令匹配成功但没有返回内容,也视为"已处理",不会再交给 AI。 ### 控制执行顺序 ```ts export default defineMiddleware({ phase: 'before-dispatch', // 默认;或 'after-dispatch' order: 10, // 默认 0,越小越先执行 handle({ input }, next) { /* ... */ }, }); ``` 排序依次比较:`phase` → `order` → 插件挂载顺序 → 能力 id。 ### 只对部分消息生效(`permit`) 入站中间件可以声明 `permit`,规则与命令、Agent 工具相同、由同一个评估器判断(发送者的 zhin 角色、发送者的平台身份 `platform:*`、机器人自身的平台身份 `bot:*`,见[聊天角色](../concepts/chat-roles.md)): ```ts export default defineMiddleware({ permit: ['group()', 'bot:admin'], // 只在机器人是群管理员的群里处理 async handle({ input }, next) { /* 撤回违规消息… */ await next(); }, }); ``` 不满足时这条消息**跳过**该中间件、继续后续链路,不回复拒绝。评估是轻量的:机器人自身身份只读缓存(缓存缺失时在后台刷新),不会为每条消息增加平台请求,未知时 `bot:*` 不满足。出站中间件不接受 `permit`。 中间件的参数还包括 `config`(本插件配置)、`has(token)`、`use(token)`(取用插件服务)、`session`、`signal`、`onAfterDispatch`、`owner`、`generation`。声明 `adapter` 后,`$client` 会带上该平台 SDK 的类型。 需要给 `config` 加上强类型时,使用 `defineMiddleware.withConfig()`: ```ts import { defineMiddleware } from 'zhin.js/middleware'; import { databaseHostToken } from 'zhin.js'; interface MyConfig { triggerWord: string; } export default defineMiddleware.withConfig()({ handle({ input, config, has, use }, next) { if (input.content === config.triggerWord) { const db = has(databaseHostToken) ? use(databaseHostToken) : undefined; return `已命中配置词(数据库:${db ? '已连接' : '未连接'})`; } return next(); }, }); ``` ### 改写或拦截 Bot 发出的消息 设置 `target: 'outbound'` 后,中间件处理的是**即将发出**的消息: ```tsx // middlewares/review/index.tsx import { defineMiddleware } from 'zhin.js/middleware'; import type { OutboundEnvelope } from 'zhin.js/core/runtime'; export default defineMiddleware({ target: 'outbound', async handle({ input }, next) { input.replace(经过审核的内容); // 改写内容 await next(); // 不调用 next() 就不会发送 }, }); ``` 出站中间件不通过返回值改写,而是调用 `input.replace()`。`input.payload` 是当前将要发给平台的内容,适合审核和拦截;替换后的内容同样会经过渲染和平台校验。 ### 与渐进式回答配合 原有出站中间件默认继续接收完整回复;适用链中只要有一个中间件未声明支持增量, Core 就采用完整发送。不要为了开启流式直接给审核或有副作用的中间件加标记。 只有能安全处理累计前缀的出站中间件,才在 `target: 'outbound'` 同级声明 `incremental: true`。此时同一回复会多次经过渲染和中间件,已经公开的文字、格式、 引用和 @ 目标必须保持稳定;不能每次新增审批准入、外部发送或其他业务副作用。 无法保证这些性质时保留默认行为即可。详见[渐进式回答](./adapters.md#渐进式回答)。 ## 用 JSX 写消息 ### 准备工作 在项目 `tsconfig.json` 中设置: ```json { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "zhin.js" } } ``` 然后把文件保存为 `.tsx`,例如 `commands/card/index.tsx`。`npm create zhin-app` 生成的项目已经配置好。这里的 JSX 是 Zhin 自己的实现,**与 React 无关**。 ### 图文混排 小写标签都是内置的消息元素,不需要 import: ```tsx // commands/hi/index.tsx import { defineCommand } from 'zhin.js/command'; export default defineCommand({ execute: () => <> 你好 , }); ``` 一条消息按顺序包含:文字、图片、@某人。常用标签有 `text`、`image`、`mention`、`face`、`audio`、`video`、`file`、`reply`、`forward`、`link`、`qrcode`、`markdown`、`keyboard`、`tts` 等,全部列表见 [参考 · 内置标签](#内置标签)。 ### 按钮 ```tsx ``` 用户点击后,`onClick` 在原会话里执行,返回的内容会自动回复。支持原生按钮的平台显示按钮,不支持的平台显示为编号选项("回复 1 查看结果")。 ::: details 按钮的更多规则 - `onClick` 返回字符串、消息段或 JSX 时自动回复一次;返回 `null`、`undefined` 或布尔值不发送;数字 `0` 会回复 `0`。也可以在回调中调用 `message.$reply()`。 - 回调只对原会话和当前版本有效:一小时后、插件热重载或进程重启后失效。 - 要限制谁能点,给按钮加 `permit`(与命令同一套规则、同一个评估器,判断的是**点击者**):` ), }); ``` `` 里的内容会被渲染成 HTML;在不能直接显示 HTML 的平台上,安装了 `@zhin.js/html-renderer` 就转成图片,否则降级为文字。见下文 [不同平台上的效果](#不同平台上的效果)。 组件库不依赖 React 或截图引擎。主题通过 `ThemeProvider` 统一设置(配色、字体、圆角、阴影等),局部用 `custom.style`、`custom.text` 覆盖。完整组件列表见 [组件库说明](https://github.com/zhinjs/zhin/blob/main/packages/toolkit/components/README.md)。 ::: warning 不支持 CSS 文件 服务端 TSX 只做 JSX 转译,**不能 `import './card.css'`**,也不支持 CSS Modules、Sass、Less、PostCSS。请使用内联 `style`(对象或字符串)、主题,或下面的 Tailwind 工具类。 ::: ### 表格、Markdown 与代码块 ```tsx import { Table, Checkbox, Switch, Button, Markdown, CodeBlock } from '@zhin.js/components'; const report = 发布验收, , , ], ]} />; const article = ; const snippet = plugin.ts} source={'const ready = true;\nconsole.log(ready);'} />; ``` - `Checkbox`、`Radio`、`Switch`、`Button` 只用于**展示**状态,没有点击事件。需要交互请用上面的 `