# @genrojs/bag 中文文档

规范地址：https://npmcn.com/package/%40genrojs/bag/

版本：0\.12\.0
npm 元数据更新时间：2026-11-01T10:34:47.900Z
中文译文更新时间：2026-11-16T03:53:28.144Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：235 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- 首次发布：2026-10-01T13:42:24.654Z
- 最新版本发布：2026-11-01T10:34:47.573Z
- 近 30 天下载量：4479（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Genro-bag的 JavaScript 端口 - 等级数据容器

## 安装

```sh
npm install @genrojs/bag
```

也可以使用：`pnpm add @genrojs/bag`、`yarn add @genrojs/bag`、`bun add @genrojs/bag`

## README

# 格鲁巴基斯

当前发布 : **0.12.0 (中文(简体) )**。解析器输入是宣布的参数;读取时间为一次性读取。 见 `BREAKING_CHANGES.md`。 。 。 .

> **0.11.0——打破API:** 读取 [摄取和安排迁移说明](https://npmcn.com/package/%40genrojs/bag/docs/migration-ingestion.md) 在升级附属项目之前.

类型脚本/ Java脚本端口 [外科医生](https://github.com/nicofirst1/genro-bag) - 具有XML序列化、构建器模式和编译器系统的分级数据容器.

## 状态

**发展状况**: 前阿尔法(文件和规划)

## 概览

genro-bag-js将 Python genro-bag 架构带到 JavaScript/ TypeScript 用于:

-   **浏览器**: DOM 操作,UI框架,被动更新
-   **节点.js**: 服务器侧处理, CLI 工具
-   **互通性**: XML/JSON 格式与 Python 版本相同
-   **现代运行时间**: Deno, Bun 支持

## 建筑

```
┌─────────────────────────────────────────────────────────────────┐
│                         SERVER (Python)                         │
│                                                                 │
│   Builder Python → creates "recipe" (structured Bag)           │
│   bag.to_xml() → serializes for transport                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼  (HTTP / WebSocket)
┌─────────────────────────────────────────────────────────────────┐
│                        BROWSER (JavaScript)                     │
│                                                                 │
│   Bag.fromXml() → reconstructs structure                       │
│   Expander → expands macros/components (optional)              │
│   DOMCompiler → builds DOM/widgets dynamically                 │
└─────────────────────────────────────────────────────────────────┘
```

## 核心类

| 类 | 说明 |
| --- | --- |
| `Bag` | 标有节点的分级容器 |
| `BagNode` | 有值和属性的个人节点 |
| `BagBuilderBase` | 申报结构建造者的基础类 |
| `BagCompilerBase` | 输出生成器(DOM、HTML等)的基础类 |
| `BagResolver` | 懒惰加载支持 |

## 安装

在两个登记册上公布了同样的一揽子计划:

```bash
# npm
npm install @genrojs/bag

# JSR
npx jsr add @genro/bag
```

从 npm 从导入 `@genrojs/bag`; 从 JSR 从 `@genro/bag`。 。 。 .

## 使用量

```typescript
import { Bag } from '@genrojs/bag';

// Create a Bag
const bag = new Bag();
bag.set('config.name', 'My App');
bag.set('config.version', '1.0.0');

// Serialize
const xml = bag.toXml();
const json = bag.toJson();

// Parse
const restored = Bag.fromXml(xml);
```

### 使用构建器

```typescript
import { Bag, BagBuilderBase, element } from '@genrojs/bag';

class GUIBuilder extends BagBuilderBase {
  @element({ subTags: 'button,textfield' })
  panel(title: string) {}

  @element({ subTags: '' })
  button(label: string, action?: string) {}
}

const gui = new Bag({ builder: GUIBuilder });
const panel = gui.panel('Settings');
panel.button('Save', 'doSave');
panel.button('Cancel', 'doCancel');
```

### 使用编译器

```typescript
import { BagCompilerBase, compiler } from '@genrojs/bag';

class DOMCompiler extends BagCompilerBase {
  @compiler
  panel(node, children): HTMLElement {
    const div = document.createElement('div');
    div.className = 'panel';
    children.forEach(child => div.appendChild(child));
    return div;
  }

  @compiler
  button(node, children): HTMLElement {
    const btn = document.createElement('button');
    btn.textContent = node.attr.label;
    btn.onclick = () => this.handleAction(node.attr.action);
    return btn;
  }
}
```

## 文档

-   [Python 对齐和 TYTX 兼容性](https://npmcn.com/package/%40genrojs/bag/docs/python-alignment.md)
    
-   [结构分析](https://npmcn.com/package/%40genrojs/bag/docs/analysis/analisi_bag_js_builder_js.md) - 对现有联合来文执行情况的详细分析
    
-   [计划](https://npmcn.com/package/%40genrojs/bag/docs/plan.md) - 执行路线图
    

## 发展

```bash
# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

# Type check
pnpm typecheck
```

## 许可证

Apache 许可证 2. 0 - 见 [自由主义](https://npmcn.com/package/%40genrojs/bag/LICENSE) 详细情况.

版权:2025 Softwell S.r.l.

## JSR分发

JavaScript 软件包发布为 `@genro/bag` 关于JSR. 使用 `bunx jsr add @genro/bag` 或者说 `npx jsr add @genro/bag`。 。 。 . Node.js 22+, Bun和有Web Crypto的现代浏览器是被支持的目标. TYTX由JSR解决;不需要GitHub软件包取出.

[![JSR](https://jsr.io/badges/@genro/bag)](https://jsr.io/@genro/bag)

Deno 出版物为外部依赖和豁免保持24小时冷却 Genro JSR 软件包(`jsr:@genro/*` 联合国 `npm:@jsr/genro__*` 兼容性 页:1 仅发布给 JSR; npm 格式下载 `npm.jsr.io`,而不是npmjs.com. (中文(简体) ). 在通过之前, 检查每个已公布的依赖性 .

### 可选开发者 HTML 表示

实验检查员是一个单独的切入点,不包括主切入点 模块和浏览器捆绑。 可在将来释放时取出.

```js
import { htmlRepr } from '@genrojs/bag/devtools';
// With a bundler that supports CSS imports:
import '@genrojs/bag/devtools/html-repr.css';

const html = htmlRepr(bag, {title: 'Inspect Bag', showTypes: true});
```

不使用 CSS 意识捆绑器时, 单独装入样式表 。 职能 返回已逃出 HTML 碎片; 渲染它不需要额外的脚本. 袋面板和属性开始崩溃 。 选项 `openDepth` (默认 ) , `openAttributes` (默认为假), `showTypes` 和 `className` 控制演示文稿。 渲染器读取静态值而不引用 解决者。 可选 `resolverParameters(resolver)` 额外车钩用品 元数据,包括命名的回调; 钩子不能执行解析器. 解析器徽章使用构造器名,而微分化可能改变.

所有节点即使倒塌也会被排放出来: 这是一个静态开发者检查员, 不是大数据集的虚拟查看器。 祖先周期没有标记 变异"包". 检查官被故意不安装在 `Bag.prototype`。 。 。 .

## 常见问题

### @genrojs/bag 是什么？

Genro-bag的 JavaScript 端口 - 等级数据容器

### 如何安装 @genrojs/bag？

在项目目录运行 npm install @genrojs/bag，或使用 pnpm add / yarn add / bun add。

### @genrojs/bag 支持 TypeScript 吗？

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

### @genrojs/bag 支持 ESM 还是 CommonJS？

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

### @genrojs/bag 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @genrojs/bag 可以商用吗？

@genrojs/bag 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @genrojs/bag 的下载量有多少？

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

### @genrojs/bag 还在维护吗？

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

