mcpField
B
bitrix-pull

bitrix-pull

github.com/bxmaximum开发47262 次安装2 周前更新
代码仓库

关于 bitrix-pull

bitrix-pull 是面向 Bitrix 应用开发的实时界面更新技能，涵盖 PHP 事件发送、监听标签、JavaScript 订阅和移动推送，并说明通知与持久后台任务的区别。

主要功能

  1. 01向用户或频道发布事件
  2. 02通过 CPullWatch 标签通知监听者
  3. 03在 JavaScript 中订阅命令
  4. 04发送移动推送通知
  5. 05处理排队发送与 CLI Worker

适用场景

  1. 01条目变更后刷新界面
  2. 02通知关注某条记录的用户
  3. 03发送移动端徽标更新
  4. 04由 Worker 触发客户端更新

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bxmaximum/bitrix-framework-skills --skill bitrix-pull

安装后在 Claude Code 中输入/bitrix-pull确认已加载。

详细介绍

实时 Pull（pull）

基线：main 23.0+ · 已验证：pull 26.100.0、main 26.800.0

pull 通过推送服务向浏览器和移动应用发送短命令。需要配置服务（CPullOptions::GetQueueServerStatus()）；移动推送还需要 CPullOptions::GetPushStatus()。

机制用途
Pull即时 UI 信号： “第 42 行已更改”、计数器
Messenger / agents（bitrix-background-jobs）需要重试的持久工作；当 UI 需要刷新时，由工作进程发送 Pull

从 PHP 发送

\Bitrix\Main\Loader::includeModule('pull');

$ok = \Bitrix\Pull\Event::add([$userId, $otherUserId], [
    'module_id' => 'vendor.module',   // lower-cased by the kernel
    'command' => 'itemUpdated',
    'params' => ['id' => $itemId],   // IDs and flags only; load data via AJAX afterwards
    // 'expiry' => 86400,            // seconds, default
]);
if (!$ok) {
    $error = \Bitrix\Pull\Event::getLastError();
}
  • 接收方：用户 ID、32 个字符的频道 ID 或 Bitrix\Pull\Model\Channel；第 3 个参数为 \CPullChannel::TYPE_PRIVATE（默认）/ TYPE_SHARED。
  • 每用户参数：'user_params' => [$userId => ['unread' => 3]]（合并到该用户的 params 中）、'dictionary' => [...]（为所有用户合并）。从 pull 26.100 起，结果可靠；在此之前，这些键返回的假值并不表示失败——请检查 getLastError()。
  • 负载中任意位置包含无效 UTF-8 → false（EVENT_BAD_ENCODING）。
  • 投递会加入队列，并由后台任务在本次请求结束时发送。长时间运行的 CLI 工作进程：调用 add() 后立即调用 \Bitrix\Pull\Event::send()。

标签（CPullWatch）

\CPullWatch::Add($userId, 'VENDOR_ITEM_' . $itemId);          // when rendering the page
\CPullWatch::AddToStack('VENDOR_ITEM_' . $itemId, [           // later, to all watchers
    'module_id' => 'vendor.module',
    'command' => 'itemUpdated',
    'params' => ['id' => $itemId],
]);
  • 对当前用户的 Add() 会在 OnAfterEpilog 时写入；对于其他用户或在 Web 请求之外，请传入第 3 个参数 true（立即写入）。
  • 监听有效期约为 30 分钟；页面通过 BX.PULL.extendWatch(tag) 使其保持有效。
  • AddToStack() 接受标签数组和 skip_users。

在 JS 中订阅

将 pull.client 添加到 rel（import { PULL } from 'pull.client'，全局变量为 BX.PULL）。moduleId 必须为小写。

// With command: (params, extra, command, info)
const off = BX.PULL.subscribe({
    moduleId: 'vendor.module',
    command: 'itemUpdated',
    callback: (params, extra, command) => reload(params.id),
});

// Without command: one object for every module command
BX.PULL.subscribe({
    moduleId: 'vendor.module',
    callback: (data) => { /* data.command, data.params, data.extra */ },
});

BX.PULL.extendWatch('VENDOR_ITEM_' + itemId);
off(); // unsubscribe
  • 处理程序对象：BX.PULL.attachCommandHandler({ getModuleId: () => 'vendor.module', handleItemUpdated(params, extra) {} }) — 方法名为 handle + 首字母大写的命令，或者使用 getMap()。
  • Vue：在 mounted 中调用 this.$Bitrix.PullClient.get().subscribe(...)，并在 unmounted 中调用返回的函数（bitrix-vue）。
  • 切勿使用 Pull 的全局 protobuf：从 pull 26.100 起，它是精简构建版本（load、parse、Root、Type 均已移除）。请自行打包 protobufjs，但不要赋值给 globalThis.protobuf——Pull 会读取 globalThis.protobuf.roots['push-server']。

移动推送

\Bitrix\Pull\Push::add($users, ['module_id' => 'vendor.module', 'push' => ['message' => 'Text', 'params' => [...]]]) — 用于推送的内核入口点（会丢弃 command/params）；或者向 Event::add() 添加 push / pushParamsCallback，以同时发送两者。CPullStack 已弃用。

徽标刷新：Push::add($userId, ['module_id' => 'pull', 'push' => ['badge' => 'Y']])。CPushManager::sendBadges() 已在 pull 26.0 中移除（会触发致命错误），而 MobileCounter::send() 不执行任何操作；Push::add() 调用适用于所有版本。

检查清单

  • PHP 和 JS 中的 module_id / command 保持一致（模块名为小写）。
  • 负载精简且使用 UTF-8；较大的数据按需获取。
  • 标签：渲染时调用 CPullWatch::Add，并在 JS 中调用 extendWatch。
  • 在卸载 / 销毁时移除订阅。
  • 绝不将 Pull 用作任务队列。

评论

支持 Markdown