Skip to content

elementType 10 — ARK 卡片 ​

对应 WeQ 解析实现:packages/codec/src/proto/msg/element.ts(elementType = 10)。

ARK 是 QQ 的结构化卡片消息:分享链接、小程序、群公告卡、游戏中心广告等等, 渲染样式由服务端下发的模板决定。

wire 层极其简单——只有三个字段,真正的内容全在一段 JSON 字符串里。

渲染支持:WeQ 已支持 21 个 app 类型的精确渲染,覆盖官方资源包里的常见卡片。 详见 apps/desktop/src/renderer/src/components/ark/ 里的 arkCards.ts / QqArk.tsx。


一、字段 ​

tag字段名类型必有含义
47901arkDatastring✅卡片 JSON 负载(UTF-8 字符串装的 JSON 文档)
47902arkSignaturestring64 字符 base64 卡片签名,与 JSON 里的 config.token 配对
47904arkCardIdstring卡片实例 UUID,如 33cad47c-09f0-42a6-ab42-6329c0898765

二、arkData 的 JSON 结构 ​

顶层形状固定(ArkPayload),但 meta 的内部结构随 view 而变—— 这是解析 ARK 的关键:先看 view,再决定怎么读 meta。

ts
interface ArkPayload {
  app: string;          // 应用标识,如 "com.tencent.gamecenter.mall"
  desc: string;         // 描述,如 "QQ手游消息"
  meta: Record<string, Record<string, unknown>>;  // 形状取决于 view
  prompt: string;       // 会话列表外显文案
  sourceName?: string;
  ver?: string;
  view: string;         // 模板名 —— 决定 meta 的形状
  config?: {
    ctime: number;      // unix 秒
    token: string;      // 卡片签名 token
  };
}

典型读法:

ts
const payload = JSON.parse(el.arkData) as ArkPayload;
if (payload.view === 'pubAdArkView') {
  const t = payload.meta.template3 as Record<string, unknown>;
  // ...
}

三、样例:view: "pubAdArkView" ​

代码里保留了一份实际抓取的完整样例 (packages/codec/src/element/ark.ts 的 SAMPLE_GAME_CENTER_AD), 是推送进聊天的 QQ 游戏中心广告,meta 下挂 template3:

字段说明
arkType具体子模板,如 pubSinglePicArk
title / contentText标题 / 正文
coverUrl封面图
url点击跳转地址
appid / adId / actId / feedId各类业务 id
time时间戳(字符串形式)
__preloadFields客户端预加载提示,值为需要预取的字段名

想支持新的卡片样式,就在 ark.ts 里再加一个样例常量:把逆向出来的 view 与对应 meta 形状固化下来,避免每次都重新猜。


四、渲染:app 才是真正的判别式 ​

上面说 view 决定 meta 的形状,那是从 JSON 文档自身看。但渲染这一侧, WeQ 的判别式是 app(如 com.tencent.structmsg)而不是 view—— 因为 QQ 官方的 ark 资源包本身就是按 app 组织的。

渲染链路(apps/desktop/src/renderer/src/components/ark/):

文件职责
ark-cards.generated.json机械提取的绑定表:app → metaKey → { jump, slots, bindings }
arkCards.ts在其上叠加人工策展(布局归类 + 标准字段兜底),产出渲染器直接消费的 ArkValues
QqArk.tsx按布局类型渲染

数据从哪来 ​

ark-cards.generated.json 由 scripts/extract-ark-cards.mjs 从 QQ 官方 ark 资源包 (resources/arks_resource/<app>/<时间戳>/index.js)机械提取:

  • 每个 index.js 用 _setViewTemplate('<id>', '<XML>') 注册布局模板;
  • 用 Lua 的 ViewModel:OnSetMetadata(value) 定义 data["字段"] → self.<节点> 的绑定。

脚本只抽取静态渲染需要的「排版 + 字段绑定」,运行时 Lua 逻辑、网络请求、动效一律忽略。

资源包不入库

原始资源包约 25MB,提取完成后已从仓库删除,只保留脚本与生成的 JSON。 需要重新生成时得先把 ark 包放回 resources/arks_resource/ 再跑 node scripts/extract-ark-cards.mjs。

生成 JSON 的结构 ​

jsonc
{
  "com.tencent.music.lua": {
    "defaultMetaKey": "music",          // payload 没命中已知变体时的兜底
    "variants": {
      "music": {
        "jump": "jumpUrl",              // 点击跳转取自 meta 的哪个字段
        "slots": {                      // 自动归一化的「语义槽 → meta 字段」
          "title": "title",
          "desc": "desc",
          "thumb": "preview",
          "sourceIcon": "tagIcon"
        },
        "bindings": {                   // 原始的「模板节点 id → meta 字段」,未归一化
          "titleView": "title",
          "descView": "desc",
          "background": "preview",
          "tagIcon": "tagIcon"
        }
      }
    }
  }
}

slots 与 bindings 的区别:bindings 是从 Lua 里原样抠出来的节点绑定, slots 是在其之上自动归一化出的语义槽位(长尾 app 的兜底); 常见 app 的权威槽位在 arkCards.ts 里手写覆盖。

已收录的 18 个 app ​

defaultMetaKey 是 payload 的 meta 里没有任何已知变体时的兜底选择。

app默认 metaKey变体
com.tencent.contact.luacontactcontact
com.tencent.gamecenter.malltemplate3template3
com.tencent.miniapp.luaminiappminiapp
com.tencent.mobileqq.cardsharecontactcontact
com.tencent.music.luamusicmusic
com.tencent.odpicpic, news, music, video, contact, messages, miniapp
com.tencent.qidian.generalpicpic, transfercontact
com.tencent.qqgxh.generalpicpic, news, music, video, contact, messages, miniapp
com.tencent.qun.invitepicpic, news, music, video, contact, messages, miniapp
com.tencent.structmsgnewsnews, music, video, contact, messages
com.tencent.tdoc.qqpushpicpic, news, music, video, contact, messages, miniapp
com.tencent.template.publicmailmail, singlePic
com.tencent.template.qqfavorite.sharenewsnews
com.tencent.tianxuan.sharepicpic, news, music, video, contact, messages, miniapp
com.tencent.togetherinviteinvite
com.tencent.troopsharecardpicpic, news, music, video, contact, messages, miniapp
com.tencent.tuwen.luanewsnews
com.tencent.weishi.public.sharepicpic, news, music, video, contact, messages, miniapp

布局归类 ​

布局不进 JSON —— 刻意保持「机械提取的数据」与「人工策展」分离。 arkCards.ts 里有两张表,按下面的优先级决定用哪种布局:

  1. APP_LAYOUT — 单一用途的 app 直接钉死布局(覆盖 metaKey 推断):

    app布局
    com.tencent.miniapp.luaappBlock
    com.tencent.contact.luacontact
    com.tencent.mobileqq.cardsharecontact
    com.tencent.music.luanews
    com.tencent.tuwen.luanews
    com.tencent.togethermediaBlock
    com.tencent.gamecenter.mallappBlock
  2. METAKEY_LAYOUT — 多模板分享类 app(structmsg / troopsharecard / …)按变体名推断:

    metaKey布局
    news / music / video / messages / picnews
    contact / transfercontactcontact
    miniappappBlock
    invitemediaBlock
    mailnews
    singlePicappBlock
  3. 两张表都没命中 → generic(仍然带槽位值,好过纯猜)。

语义槽位 ​

归一化后交给渲染器的字段(ArkValues):

槽位含义
title / desc / summary标题 / 描述 / 摘要
thumb小方缩略图
cover通栏大图
name / avatar名称 / 头像(联系人类卡片)
source / sourceIcon顶部主来源标签文字 / 图标
footerSource / footerIcon底部来源标签(部分卡片顶底各有一个来源,如小程序顶=来源、底=「QQ小程序」)
button按钮文案
jump点击跳转地址

槽位没覆盖到的,再用 QQ 通用字段名兜底(各卡字段命名高度一致), 按顺序尝试,例如 desc 依次试 desc → digest → contactInfo → contact → address, jump 依次试 jumpUrl → qqdocurl → url。


← 返回消息段索引

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准