# @bielu/scalar-signalr 中文文档

规范地址：https://npmcn.com/package/%40bielu/scalar-signalr/

版本：1\.0\.1
npm 元数据更新时间：2026-11-04T15:27:55.891Z
中文译文更新时间：2026-11-08T01:43:47.629Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bielu/scalar-signalr
原文对照：https://npmcn.com/package/%40bielu/scalar-signalr/?lang=original
项目主页：https://github.com/bielu/Bielu.AspNetCore.ApiDescriptions#readme
源码仓库：https://github.com/bielu/Bielu.AspNetCore.ApiDescriptions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：451 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-07-16T07:13:06.739Z
- 最新版本发布：2026-11-04T15:27:55.535Z
- 近 30 天下载量：8155（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：95（近 12 个月 95 个）

## 中文简介

Scalar API 参考的交互式信号控制台插件。 读取 SignalR AsyncAPI 绑定并让您连接到枢机,引用方法和订阅服务器事件.

## 安装

```sh
npm install @bielu/scalar-signalr
```

也可以使用：`pnpm add @bielu/scalar-signalr`、`yarn add @bielu/scalar-signalr`、`bun add @bielu/scalar-signalr`

## README

# @bielu/scalar-signalr (英语)

互动 **信号控制台** 该插件 [斯卡尔](https://scalar.com/) API 参考.

它读取信号R绑定(`signalr` 或者说 `x-signalr`)从您的 AsyncAPI 文档中生成一个面板 连接到一个中枢,引用客户端到服务器的方法,并实时观看服务器到客户端的事件. 没错 作为默认的倒置替换而建 `scalar.js` 捆绑: 装入重新曝光 `window.Scalar.createApiReference` 已注册的信号R插件.

这套货包来自、并被其消耗 [`Bielu.AspNetCore.AsyncApi.Scalar.SignalR`](https://github.com/bielu/Bielu.AspNetCore.ApiDescriptions) .NET 软件包(它嵌入了已建的捆绑),但它也单独被发布到 npm , 这样它就可以 从CDN装入或用手捆绑.

## 独立使用

```html
<div id="app"></div>
<!-- Replaces the default scalar.js bundle -->
<script src="https://cdn.jsdelivr.net/npm/@bielu/scalar-signalr/dist/standalone.js"></script>
<script>
  window.__BIELU_SCALAR_SIGNALR__ = {
    documents: [{ name: 'signalr', url: '/asyncapi/signalr.json' }],
  }
  Scalar.createApiReference('#app', {
    sources: [{ url: '/asyncapi/signalr.json' }],
  })
</script>
```

信号R文件可通过Global `window.__BIELU_SCALAR_SIGNALR__` 或将 Scalar 配置内置为 `config.signalr`。 。 。 .

## 程序用途

```ts
import { createApiReference, createSignalRPlugin } from '@bielu/scalar-signalr'

// Either use the wrapper (auto-registers the plugin) …
createApiReference('#app', { sources: [{ url: '/asyncapi/signalr.json' }] })

// … or register the plugin yourself on the stock Scalar API Reference:
// plugins: [createSignalRPlugin([{ name: 'signalr', url: '/asyncapi/signalr.json' }])]
```

## 认证集成

斯卡拉拥有顶级认证UI. 当用户在那里选择一个安全方案时 信号控制台自动拾取证书 **连接** 时间——没有单独的登录步骤 这是需要的.

**要求Scalar → 2.16.12** (插件认证状态 API, 上游为 [斯卡尔/斯卡尔#9639](https://github.com/scalar/scalar/pull/9639)) (中文(简体) ). 在旧的斯卡拉版本上 在 API 之前,控制台连接没有证书(graceful no-op).

### 如何将证书映射到 SignalR 客户端

| 计划 | 地点 | 信号R映射 |
| --- | --- | --- |
| `apiKey` | `query` | 附于中枢 URL 的密钥 `?<name>=<value>` |
| `apiKey` | `header` | **已登录的警告** ——浏览器 WS/SSE 无法设置信头;返回查询 |
| `http` 无记名者 | —— 说 | `accessTokenFactory: () => token` |
| `oauth2` 编号 : `openIdConnect` | —— 说 | `accessTokenFactory: () => token` |
| `http` 基础 | —— 说 | **已登录的警告** ——不能通过WS/SSE发送;在没有认证的情况下连接收益 |

方案定义从 `components.securitySchemes` asyncAPI 文档中。 这个 控制台将 Scalar 文档名称匹配到所选方案; 如果找不到精确的匹配 回到Scalar出口的认证状态中唯一的文档.

## 构建

```bash
npm install
npm run build      # -> dist/plugin.js (IIFE) + dist/scalar-plugin.mjs (ESM) + dist/standalone.js + dist/types
npm run typecheck
```

三项建筑产出,有三项不同的合同——不能互换:

| 产出 | 合同 | 用于 |
| --- | --- | --- |
| `dist/plugin.js` | IIFE; 通过钩子安装 `window.Scalar.createApiReference` | `MapScalarSignalRAssets()`在斯卡拉自己的包旁边 |
| `dist/scalar-plugin.mjs` | ES模块; **默认导出为插件**,没有登记本身 | 斯卡尔的 `pluginUrls` 选项——Aspire包如何将控制台添加到库存容器中 |
| `dist/standalone.js` | Scalar 预建的浏览器与附加插件捆绑 | 其它没有加载斯卡拉的页面; _替换_ Scalar自己的捆绑 |

## 许可证

麻省理工学院

## 常见问题

### @bielu/scalar-signalr 是什么？

Scalar API 参考的交互式信号控制台插件。 读取 SignalR AsyncAPI 绑定并让您连接到枢机,引用方法和订阅服务器事件\.

### 如何安装 @bielu/scalar-signalr？

在项目目录运行 npm install @bielu/scalar-signalr，或使用 pnpm add / yarn add / bun add。

### @bielu/scalar-signalr 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bielu/scalar-signalr 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bielu/scalar-signalr 可以商用吗？

@bielu/scalar-signalr 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bielu/scalar-signalr 的下载量有多少？

根据 npm 官方下载统计，@bielu/scalar-signalr 在 2026/10/08 – 2026/11/06 这 30 天内被下载 8,155 次，日均约 272 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bielu/scalar-signalr 还在维护吗？

最新版本 1\.0\.1 发布于 2026/11/04（3 天前）；至今共发布 95 个版本，其中过去 12 个月发布了 95 个；首次发布于 2026/07/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。