# @basenative/builder 中文文档

规范地址：https://npmcn.com/package/%40basenative/builder/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:46:55.493Z
中文译文更新时间：2026-10-31T16:55:38.471Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/builder
原文对照：https://npmcn.com/package/%40basenative/builder/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/builder#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：112 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-18T05:29:00.985Z
- 最新版本发布：2026-10-31T13:46:55.168Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

用于BaseNative的基于信号的拖放组件构建器-组合布局，生成干净的BaseNative代码

## 安装

```sh
npm install @basenative/builder
```

也可以使用：`pnpm add @basenative/builder`、`yarn add @basenative/builder`、`bun add @basenative/builder`

## README

# @basenative /建设者

BaseNative的基于信号的拖放组件构建器。可视化地组合布局，通过响应式检查器编辑道具，并生成干净的BaseNative模板代码作为输出。

-   **零依赖关系** 除了 `@basenative/runtime`.
-   **狗粮：消极的信号** -每个建设者状态都是一个 `signal()`.
-   **原生HTML5拖放** -没有阴影DOM，没有自定义DnD层。
-   **语义HTML** 完整的ARIA角色(`role="tree"`， `role="application"`， `role="toolbar"`）。
-   **`display: contents` 在每个主元素上** -包装不影响布局。
-   **csp安全代码生成** -输出是纯HTML/模板；否 `eval`.

## 安装

```bash
pnpm add @basenative/builder
```

## 快速启动（程序化）

```js
import { createBuilderState, defaultPalette, generateBaseNative } from '@basenative/builder';

const palette = defaultPalette();
const state = createBuilderState();

const hero = state.addNode(null, { type: 'section', props: { class: 'hero' } });
state.addNode(hero.id, { type: 'heading', props: { level: 'h1', text: 'Welcome' } });
state.addNode(hero.id, { type: 'text', props: { text: 'A quiet runtime.' } });

console.log(generateBaseNative(state, { palette }));
```

输出:

```html
<section class="hero" role="region">
  <h1>Welcome</h1>
  <p>A quiet runtime.</p>
</section>
```

## 快速启动（在浏览器中）

```html
<bn-builder></bn-builder>

<script type="module">
  import '@basenative/builder';

  const builder = document.querySelector('bn-builder');
  builder.addEventListener('bn-builder-export', (e) => {
    console.log(e.detail.code);
  });
</script>
```

这个 `<bn-builder>` 元素安装四个窗格：

| 元素 | 角色 |
| --- | --- |
| `<bn-builder-palette>` | 组件的拖动源 |
| `<bn-builder-canvas>` | 掉落目标-树的实时预览 |
| `<bn-builder-tree>` | 节点的层次轮廓 |
| `<bn-builder-inspector>` | 用于编辑道具和信号绑定的响应式表单 |

## 信号绑定

每个节点都有一个 `bindings` 将道具名称连接到用户作用域中的信号的映射。代码将其作为BaseNative指令发出：

```js
const node = state.addNode(null, { type: 'input' });
state.setBinding(node.id, 'value', { ref: 'username' });

generateBaseNative(state, { palette, signals: { username: '' } });
```

输出:

```html
<script type="module">
  import { signal } from '@basenative/runtime';

  const username = signal("");
</script>
<input type="text" @bind="username" />
```

对于文本内容：

```js
state.setBinding(id, 'text', { ref: 'count' });
// → <span>{{ count() }}</span>
```

## 公共API

```ts
createBuilderState(options?): BuilderState
createPalette(): ComponentPalette
defaultPalette(): ComponentPalette
generateBaseNative(state, options?): string
renderTreeView(state): string
renderInspector(state, palette): string
```

`BuilderState` 暴露信号(`tree`， `selection`， `hover`， `canUndo`， `canRedo`)和行动(`addNode`， `removeNode`， `updateProps`， `setBinding`， `moveNode`， `duplicateNode`， `select`， `undo`， `redo`， `clear`， `toJSON`， `fromJSON`， `subscribe`）。

信号是一流的——把它们连接到你自己的 `effect()` 对用户编辑作出反应：

```js
import { effect } from '@basenative/runtime';

effect(() => console.log('Tree size:', state.tree().length));
```

## 默认的面板

| 类型 | 标签 | 容器 | 类别 |
| --- | --- | --- | --- |
| `section` | `<section role="region">` | 是 | 布局 |
| `stack` | `<div>` | 是 | 布局 |
| `grid` | `<div>` | 是 | 布局 |
| `heading` | `<h1>`–`<h6>` | 否 | 文本 |
| `text` | `<p>` | 否 | 文本 |
| `button` | `<button>` | 否 | 输入 |
| `input` | `<input>` | 否 | 输入 |
| `textarea` | `<textarea>` | 否 | 输入 |
| `checkbox` | `<input type="checkbox">` | 否 | 输入 |
| `label` | `<label>` | 是 | 输入 |
| `form` | `<form>` | 是 | 输入 |
| `link` | `<a>` | 否 | 导航 |
| `image` | `<img>` | 否 | 媒体 |
| `signal-text` | `<span>{{ … }}</span>` | 否 | 无功 |

注册你自己的：

```js
palette.register({
  type: 'kbd',
  tag: 'kbd',
  category: 'text',
  props: [{ name: 'text', kind: 'string', label: 'Key' }],
  defaults: { text: '⌘K' },
});
```

## 持久性

```js
const json = state.toJSON();
// store somewhere

state.fromJSON(json); // wipes history, hydrates tree
```

## 键盘快捷键（画布）

| 键 | 行动 |
| --- | --- |
| `Delete` / `Backspace` | 移除所选节点 |
| `Cmd/Ctrl + Z` | 撤销 |
| `Cmd/Ctrl + Shift + Z` / `Cmd/Ctrl + Y` | 重做 |

## 测试

```bash
cd packages/builder && node --test
```

编写测试时使用 `node:test` -不需要Jest，不需要Vitest，不需要纯逻辑的浏览器控制。Web组件测试需要一个DOM，并在下游应用程序中进行。

## 许可证

apache - 2.0

## 常见问题

### @basenative/builder 是什么？

用于BaseNative的基于信号的拖放组件构建器-组合布局，生成干净的BaseNative代码

### 如何安装 @basenative/builder？

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

### @basenative/builder 支持 TypeScript 吗？

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

### @basenative/builder 支持 ESM 还是 CommonJS？

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

### @basenative/builder 可以商用吗？

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

### @basenative/builder 还在维护吗？

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