# @basenative/runtime 中文文档

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

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

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

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

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

- 包体积（解压后）：111 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-20T05:27:52.876Z
- 最新版本发布：2026-10-31T13:47:03.245Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

基于信号的web运行时在本地HTML -零构建步骤，零生产依赖

## 安装

```sh
npm install @basenative/runtime
```

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

## README

# @basenative /运行时

> 原生HTML的基于信号的响应式运行时——零构建步骤，零生产依赖

部分 [BaseNative](https://github.com/DuganLabs/basenative) 生态系统——基于信号的web运行时，基于原生HTML。

## 安装

```bash
npm install @basenative/runtime
```

## 快速入门

```js
import { signal, computed, effect, hydrate } from '@basenative/runtime';

// Create reactive state
const count = signal(0);
const doubled = computed(() => count() * 2);

// React to changes
effect(() => {
  console.log(`count: ${count()}, doubled: ${doubled()}`);
});

count.set(5); // logs: count: 5, doubled: 10

// Hydrate server-rendered HTML with signal bindings
hydrate(document.body, { count });
```

## API

### 信号

-   `signal(initial)` —创建可读/可写的响应值。调用它来读取(`count()`),使用 `.set(value)` 写, `.peek()` 无迹可寻地阅读。
-   `computed(fn)` -创建一个派生信号，当它的依赖改变时重新计算。懒惰的自动依赖跟踪。
-   `effect(fn)` ——运行 `fn` 立即运行，并在内部读取的任何信号发生变化时重新运行。返回一个 `dispose` 停止跟踪功能。
-   `batch(fn)` -组信号写在里面 `fn` 转换为单次刷新，而不是每次写入一次刷新。巢;只有最外层的调用刷新。
-   `registerPlugin(plugin)` -注册一个全局变量 `{ onSignalWrite(signal, prev, next) }` 观察每个信号写入的钩子。返回一个注销函数。不同于 `definePlugin`/`createPluginRegistry` 下面是生命周期系统。

### 水合作用

-   `hydrate(root, ctx)` -附加信号响应到服务器端呈现的HTML。读取 `<!--bn:*-->` 发出的标记 `@basenative/server`.

### 浏览器特性

-   `browserFeatures` -包含检测到的浏览器功能标志的信号。
-   `detectBrowserFeatures()` -运行特性检测和更新 `browserFeatures`.
-   `supportsFeature(name)` -对命名功能返回true/false。

### 诊断和DevTools

-   `emitDiagnostic(diagnostic)` -发出结构化运行时诊断。
-   `reportHydrationMismatch(info)` -报告服务器/客户端HTML不匹配。
-   `enableDevtools()` / `disableDevtools()` / `isDevtoolsEnabled()` -切换BaseNative devtools钩子（实时信号/效果/水合状态） `globalThis.__BASENATIVE_DEVTOOLS__`;创建在启用时自动注册)。
-   `trackSignal(signal)` / `trackEffect(effect)` / `recordHydration(info)` - DevTools工具挂钩。

### 调试模式

-   `enableDebug(options)` / `disableDebug()` / `isDebugEnabled()` -为信号/效果活动切换详细控制台日志记录。关闭时零开销。
-   `getDebugStats()` -返回计数器的快照(`signalsCreated`， `effectsCreated`， `signalWrites`， `signalReads`， `effectRuns`）。
-   `debugSignal(signal, name)` / `debugEffect(fn, name)` -包装信号或效果，以便记录其活动。
-   `debugTime(label, fn)` -时间和日志同步调用；仍运行 `fn` 并在调试模式关闭时返回其结果。
-   `debugAssert(condition, message)` -投掷 `condition` 为false，并开启调试模式；关闭时完全无操作。
-   `debugDeps(signal, name)` -记录信号的当前值；当调试模式关闭时，无操作。

### 错误的边界

-   `createErrorBoundary(options)` -创建可重复使用的边界(`{ onError, fallback }`), `try(fn)` / `getError()` / `hasError()` / `getFallback()` / `reset()`。捕获呈现错误并公开回退。
-   `renderWithBoundary(renderFn, options)` -单一渲染调用的单镜头版本；相同 `{ onError, fallback }` 选项，没有可重用的边界对象。如果没有，则返回到HTML注释 `fallback` 给出。

### 插件

-   `definePlugin(plugin)` 注册一个带有生命周期钩子的运行时插件。
-   `createPluginRegistry()` -创建一个独立的插件注册表。

### 懒惰的水合作用

-   `lazyHydrate(el, fn)` -按需水合一种元素。
-   `hydrateOnIdle(el, fn)` -当浏览器空闲时通过 `requestIdleCallback`.
-   `hydrateOnInteraction(el, fn)` -在用户与元素的第一次交互时进行补水。
-   `hydrateOnMedia(fn, query)` -当CSS媒体查询匹配时，会发生水合物。注意: `fn` 首先出现，不像其他 `hydrateOn*` 帮手。
-   `createLazyHydrator(options)` -创建一个懒惰的水合控制器与共享选项。

### Web命脉

-   `createVitalsReporter(options)` —创建一个报告器，将核心Web生命体征发送到端点。
-   `observeLCP(cb)` / `observeFID(cb)` / `observeCLS(cb)` / `observeFCP(cb)` / `observeTTFB(cb)` / `observeINP(cb)` -观察个别Web Vital指标。每个返回一个清理函数，或 `null` 当 `PerformanceObserver` 不可用（例如在SSR期间）。

### 共享实用程序（子路径导出）

-   `raw(value)` -将字符串标记为可信标记，免除html转义。也可以从包根目录中获得。
-   `@basenative/runtime/shared/escape` - - - - - - `isRaw`， `unwrapRaw`， `escapeText`， `escapeAttr`， `isUrlAttribute`， `sanitizeUrl`， `findInterpolations`。共享的输出转义原语 `@basenative/server`.
-   `@basenative/runtime/shared/expression` - - - - - - `compileExpression`， `evaluateExpression`， `clearExpressionCache`， `isScopeSlot`， `SCOPE_SLOT`。共享的csp安全表达式求值器 `@basenative/server`;看到 `docs/api/runtime.md` 了解完整的API及其安全约束。

## 许可证

apache - 2.0

## 常见问题

### @basenative/runtime 是什么？

基于信号的web运行时在本地HTML -零构建步骤，零生产依赖

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

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

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

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

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

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

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

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

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

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