资料字段与数据来源
本篇说明资料卡上每个字段的读取来源、优先级与回退规则,便于理解卡片内容并判断数据异常的原因。
🧾 字段总览
| 字段 | 主要来源 | 回退方式 |
|---|---|---|
| QQ 昵称 | QQ 用户资料 | 多级回退,见下文 |
| 头像 | 群成员资料头像地址 | QQ 头像接口获取 |
| QQ 等级 | 个人等级字段 qqLevel / qq_level | 群等级 → 本地活跃等级 |
| 性别 | QQ 用户资料 | 显示未知状态 |
| 个性签名 | long_nick / longNick | 按群身份和等级显示备用短句 |
| 群名片 | 当前群成员资料 | —— |
| 群头衔 | 群资料中的真实头衔 | 按群身份和等级生成默认头衔 |
| 入群时间 / 最后发言 | 群成员资料 | 本地记录补充 |
| 本月发言 / 活跃天数 | 插件本地累计 | —— |
🏷️ QQ 昵称
主标题优先使用 QQ 用户资料中的真实昵称,群名片只作为副信息显示,不会替代 QQ 昵称。
昵称读取顺序:
- QQ 用户资料昵称;
- 消息事件中的昵称;
- 群成员昵称;
- QQ 号。
所有来源都为空时,卡片只能显示 QQ 号。
🖼️ 头像
- 优先使用群成员资料中的头像地址,无法取得时再通过 QQ 头像接口获取;
- 头像下载后会保存到本地缓存,缓存有效期内不会重复下载;
- 卡片中的头像不是独立矩形框,而是经过像素级透明度衰减后融入右侧信息区域。
📶 QQ 等级
插件优先读取个人 QQ 等级字段 qqLevel 或 qq_level,并使用 PNG 图标展示:
| 图标 | 对应等级 |
|---|---|
| ⭐ 星星 | 1 级 |
| 🌙 月亮 | 4 级 |
| ☀️ 太阳 | 16 级 |
| 👑 皇冠 | 64 级 |
换算规则为四进制:4 个星星 = 1 个月亮,4 个月亮 = 1 个太阳,4 个太阳 = 1 个皇冠。
等级读取的回退顺序:个人 QQ 等级 → 群等级 → 本地活跃等级。本地活跃等级由「每级发言数」与「最高等级」两个设置计算得出,仅在真实等级不可用时启用,详见活跃统计与缓存机制。
🚻 性别
性别来源于 QQ 用户资料。协议端返回未知或用户隐藏了该信息时,卡片显示未知状态。
💬 个性签名
插件读取 QQ 个性签名 long_nick 或 longNick。如果没有签名,会根据群身份和等级显示一条备用短句,保证信息区不空缺。
🎖️ 群名片与群头衔
- 群名片显示在 QQ 号旁边,便于识别用户在当前群中的名称;
- 群专属头衔优先使用群资料中的真实头衔;
- 没有真实头衔时,根据群身份和等级生成默认头衔。
📅 入群与发言数据
| 数据 | 统计口径 |
|---|---|
| 入群时间 | 优先读取群成员资料 |
| 最后发言 | 优先读取群成员资料,本地记录作为补充 |
| 本月发言 | 插件启用后在本地累计 |
| 活跃天数 | 统计插件记录到发言的不同日期数量 |
活跃数据的记录起点与缓存机制详见活跃统计与缓存机制。
💡 数据异常的常见原因
| 现象 | 原因 |
|---|---|
| 昵称显示为 QQ 号 | 协议端没有返回任何昵称来源 |
| 性别显示未知 | 用户隐藏了信息,或协议端未返回该字段 |
| 等级与预期不符 | 实际展示的是群等级或本地备用等级 |
| 本月发言数偏少 | 插件只统计启用后收到的消息 |
更多高频问题参见常见问题FAQ。
📚 下一节:卡片外观与实时预览
