# @arkitektio/bsx 中文文档

规范地址：https://npmcn.com/package/%40arkitektio/bsx/

版本：2\.2\.1
npm 元数据更新时间：2026-10-31T13:31:59.357Z
中文译文更新时间：2026-10-31T14:14:05.396Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40arkitektio/bsx
原文对照：https://npmcn.com/package/%40arkitektio/bsx/?lang=original
项目主页：https://github.com/arkitektio/bsx#readme
源码仓库：https://github.com/arkitektio/bsx

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

- 包体积（解压后）：7.5 MB，1071 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^4\.0\.0，clsx ^2\.1\.1，vaul ^1\.1\.2，react ^19\.2\.0，three \>=0\.180\.0，graphql ^16\.8\.0，zustand ^5\.0\.0，blurhash ^2\.0\.5，radix-ui ^1\.4\.3，recharts ^2\.15\.0，input-otp ^1\.4\.2，react-dom ^19\.2\.0，tailwindcss ^4\.1\.0，lucide-react \>=0\.500\.0，monaco-editor \>=0\.50\.0，tailwind-merge ^3\.4\.0，react-day-picker ^9\.11\.0，@react-three/drei ^10\.7\.0，@react-three/fiber ^9\.4\.0，@monaco-editor/react ^4\.7\.0，embla-carousel-react ^8\.6\.0，@testing-library/react ^16\.3\.0，react-resizable-panels ^3\.0\.6，class-variance-authority ^0\.7\.1，react-lazy-load-image-component ^1\.6\.0
- 首次发布：2026-10-28T12:35:48.451Z
- 最新版本发布：2026-10-31T13:31:59.062Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

BSX语言、块规范、运行时和React渲染器：每个Arkitekt前端都有一份副本。

## 安装

```sh
npm install @arkitektio/bsx
```

也可以使用：`pnpm add @arkitektio/bsx`、`yarn add @arkitektio/bsx`、`bun add @arkitektio/bsx`

## README

# @arkitektio / bsx

BSX语言，块目录，块运行时和React渲染器：每个都有一个副本 Arkitekt前端（Orkestrator, newswitch, pocket）。

| 进口 | 什么 | 需要 |
| --- | --- | --- |
| `@arkitektio/bsx` | 语言(`parseBsx`， `printBsx`， `analyzeBsx`， `completeBsx`，…)，词汇表和规范JSON | 没有什么 |
| `@arkitektio/bsx/catalogs` | 全局目录契约(`uiCatalog`， `htmlCatalog`， `logoCatalog`， `sceneCatalog`， `structureCatalog`， `shadcnCatalog`)和prop-schema词汇表 | 萨德 |
| `@arkitektio/bsx/runtime` | 运行时, `defineBlokCatalog` / `implementBlokCatalog` / `ownBlokCatalog` / `declareBlokUi`、声明、持久化、 `configureBlokPlatform` | React, zd, zustand, graphql |
| `@arkitektio/bsx/web` | `BlokRenderer`， `BlokComponentHost`， `BlokCatalogProvider`， `addBlokComponents` | react-dom |
| `@arkitektio/bsx/shadcn` | 选择加入：ui@1、html@1、logo@1和shadcn@1，使用shadcn/ui (`shadcnUi`， `shadcnHtml`， `shadcnLogo`， `shadcnExtras`） | 基数，顺风，… |
| `@arkitektio/bsx/scene` | 选择加入：scene@1抽签三名(`threeScene`)，现场主持人 | 三个，@react-three/fiber, @react-three/drei |
| `@arkitektio/bsx/editor` | 摩纳哥BSX的编辑 | @monaco-editor /反应 |
| `@arkitektio/bsx/tailwind` | 类块在运行时带来的顺风 | 顺风车，顺风车`?raw`） |

每个模块也可以通过其路径访问(`@arkitektio/bsx/renderer/runtime/task`）。

## 目录

一、 **目录** 契约：它包含哪些组件，每个组件需要什么（一个模式） 组件、位置、文本道具、回调事件)。它什么也没画。UI定义目录，在 打字稿;规范JSON是根据它们编写的。

-   **全球目录** 是有版本的(`ui@1`)，并在这里定义。实现一个完整声明的UI 因此，只使用全局目录的块会在每个声明它们的UI中呈现。
-   **UI自己的目录** 是由UI: newswitch的 `newswitch@2`， 构造器的模块块。使用一个的块只在那里渲染。

一个 **实现** 应用的：是每个组件的渲染，是编译器检查的映射 合同（丢失或未知渲染失败） `tsc`）。

```ts
import {uiCatalog} from '@arkitektio/bsx/catalogs';
import {configureBlokPlatform, declareBlokUi, implementBlokCatalog, type BlokRender} from '@arkitektio/bsx/runtime';
import {shadcnExtras, shadcnHtml, shadcnLogo, shadcnUiRenders} from '@arkitektio/bsx/shadcn';
import {threeScene} from '@arkitektio/bsx/scene';

// Draw over one part of the reference implementation:
const MyButton: BlokRender<typeof uiCatalog.components.Button> = ({component, schema}) => { /* … */ };
const ui = implementBlokCatalog(uiCatalog, {...shadcnUiRenders, Button: MyButton});

export const app = declareBlokUi({
  name: 'myapp',
  implements: [ui, shadcnHtml, shadcnLogo, shadcnExtras, threeScene, myOwnCatalog],
});
// app.catalog: what the renderers draw. app.claims: the global catalogs it implements whole.

// Once, before the first render: what the bloks get from the app.
configureBlokPlatform({toast, describeError, useKeepLive, useColorScheme, tailwindTheme: appThemeCss, catalog: app.catalog});
```

UI自己的组件将该语言的默认视图（解析器、检查器、编辑器）与 `registerBlokModules([parseSpecCatalog(blokModuleSpec(name, description, app.catalog), name)])`.

## 在应用程序中

-   **顺风。** 块本身的类在运行时编译(`./tailwind`）. 器官捐献 实现自己的类不覆盖块外的门户，并且 `tw-animate-css` 是 仅仅构建。一个应用程序 `./shadcn` 增加了 `@source "<path to>/node_modules/@arkitektio/bsx/dist";`. 一个自带组件的不需要它。
-   在vitest下，内联包(`test.server.deps.inline: ['@arkitektio/bsx']`): `./tailwind` 读取样式表 `?raw`.
-   三个必须是应用程序中的一个副本（它是对等的）。
-   `radix-ui` 1.4.X是shadcn实现测试的对象（它的制表符触发） `onValueChange` 1.8年两次。

## 规范JSON

`src/spec/catalogs/<name>@<version>.json` 因为全球目录是从合同中写出来的： `pnpm build && pnpm spec:export` （当他们不同意时，测试失败）。arkitekt-spec的 `scripts/sync_standard_catalog.py` 把它们复制进去，然后把自己的语言写进去 付款: `vocabulary.json`， `catalogs/base@2.json` 宇称语料库 `bsx_v2.json`． 从来没有 编辑这三个。

## 常见问题

### @arkitektio/bsx 是什么？

BSX语言、块规范、运行时和React渲染器：每个Arkitekt前端都有一份副本。

### 如何安装 @arkitektio/bsx？

在项目目录运行 npm install @arkitektio/bsx，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）、react（^19\.2\.0）、graphql（^16\.8\.0）、zustand（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @arkitektio/bsx 支持 TypeScript 吗？

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

### @arkitektio/bsx 支持 ESM 还是 CommonJS？

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

### @arkitektio/bsx 可以商用吗？

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

### @arkitektio/bsx 还在维护吗？

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