# @arrow-js/sandbox 中文文档

规范地址：https://npmcn.com/package/%40arrow-js/sandbox/

版本：1\.0\.6
npm 元数据更新时间：2026-04-01T14:32:29.128Z
中文译文更新时间：2026-11-06T20:33:09.925Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：244 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2026-03-19T20:15:43.268Z
- 最新版本发布：2026-04-01T14:32:28.876Z
- 近 30 天下载量：3240（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

在主机窗口域外执行Arrow模板的快JS/WASM后置沙盒运行时间.

## 安装

```sh
npm install @arrow-js/sandbox
```

也可以使用：`pnpm add @arrow-js/sandbox`、`yarn add @arrow-js/sandbox`、`bun add @arrow-js/sandbox`

## README

# @ arrow-js/ sandbox (英语)

![ArrowJS](https://npmcn.com/package/%40arrow-js/sandbox/arrow-logo.png)

ArrowJS sandbox执行用户授权的Arrow JavaScript或TypeScript在一个Aync快JS/WASM VM内部执行,同时通过可信赖的主机DOM代码渲染.

[文档](https://arrow-js.com/) • 妇女 [API 参考](https://arrow-js.com/api) • 妇女 [游戏场](https://arrow-js.com/play/)

## 这个软件包做什么

`@arrow-js/sandbox` 允许您运行未信任的箭头代码而不执行页面中的代码 `window` 领域.

它规定:

-   用户授权模块的ASync QuickJS/WASM运行时间
-   基于默认箭头导入和模板提取的 AST 预处理
-   特定沙盒 `@arrow-js/core` 嘘
-   一个主机 DOM 渲染器和授权的事件桥

## 安装

```sh
pnpm add @arrow-js/sandbox
```

## 基本用途

```ts
import { sandbox } from '@arrow-js/sandbox'

const view = sandbox({
  source: {
    'main.ts': `
      const state = reactive({ count: 0 })

      export default html\`<button @click="\${() => state.count++}">
        Clicked \${() => state.count}
      </button>\`
    `,
  },
})

view(document.getElementById('app')!)
```

箭头标识符,例如 `html`, (中文(简体) ), `reactive`, (中文(简体) ), `component`, (中文(简体) ), `pick`, (中文(简体) ), `props`, (中文(简体) ), `nextTick`,以及 `onCleanup` 当它们被用作免费识别符时,可以自动注入. 明确用户进口得到保存,包括从 `@arrow-js/core`。 。 。 .

## 多文件模块

```ts
const view = sandbox({
  source: {
    'main.ts': `
      import App from './App.ts'

      export default App
    `,
    'state.ts': `
      import { reactive } from '@arrow-js/core'
      export const state = reactive({ count: 0 })
    `,
    'App.ts': `
      import { html } from '@arrow-js/core'
      import { state } from './state.ts'

      export default html\`
        <button @click="\${() => state.count++}">
          Clicked \${() => state.count}
        </button>
      \`
    `,
  },
})

view(mountPoint)
```

支持的虚拟导入 :

-   提供的虚拟文件之间的相对导入
-   `.ts`, (中文(简体) ), `.js`, (中文(简体) ), `.mjs`,以及 `index.*` 后退分辨率
-   `@arrow-js/core`{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我对沙盒心存决心

不支持的导入失败快 。 没有网络获取回落.

## API 密码

```ts
export interface SandboxProps {
  source: Record<string, string>
  shadowDOM?: boolean
  onError?: (error: Error | string) => void
  debug?: boolean
}

export interface SandboxEvents {
  output?: (payload: unknown) => void
}

export type HostBridgeFn = (...args: unknown[]) => unknown | Promise<unknown>
export type HostBridgeModule = Record<string, HostBridgeFn>
export type HostBridge = Record<string, HostBridgeModule>

export function sandbox<T extends {
  source: object
  shadowDOM?: boolean
  onError?: (error: Error | string) => void
  debug?: boolean
}>(
  props: T,
  events?: SandboxEvents,
  hostBridge?: HostBridge
): ArrowTemplate
```

`sandbox()` 返回箭头模板。 您可以直接挂载, 或在更大的箭头模板内作曲 :

```ts
html`<section>${sandbox({ source })}</section>`
```

给定的主机元素总是 `<arrow-sandbox>`。 。 。 .

来源要求:

-   完全一个条目文件 : `main.ts` 或者说 `main.js`
-   选项 `main.css`,注入沙盒主机根
-   所有其他条目均为JS/TS/MJS虚拟模块

`shadowDOM` 默认为 `true`。启用时,沙盒会挂入打开的阴影根 `<arrow-sandbox>`。在禁用时,它会挂入元件的光DOM.

### 主机桥模块

任选第三项 `hostBridge` 参数显示主机拥有的功能为可导入的沙盒模块 :

```ts
const view = sandbox(
  {
    source: {
      'main.ts': `
        import { getGreeting } from 'host-bridge:greetings'

        const payload = await getGreeting('Arrow')
        export default html\`<div>\${payload.message}</div>\`
      `,
    },
  },
  undefined,
  {
    'host-bridge:greetings': {
      getGreeting(name) {
        return { message: \`Hello \${String(name)}\` }
      },
    },
  }
)
```

每个顶级 `hostBridge` 键作为模块指定符直接导入。 Bridge导出仅被命名为函数,而沙盒代码总是得到"承诺回放"的函数. 桥站参数和返回值必须是简单的序列数据.

### 沙盒输出桥

可选 `events.output` 回调通过全局接收从QuickJS内部发出的值 `output(payload)` 函数 :

```ts
const view = sandbox(
  {
    source: {
      'main.ts': `
        output({ status: 'ready' })
        export default html\`<div>Sandbox Ready</div>\`
      `,
    },
  },
  {
    output(payload) {
      console.log(payload)
    },
  }
)
```

`output(payload)` 接受一个有效载荷值。 有效载荷在从VM进入主机前被序列化为纯数据.

## 安保模式

-   由用户授权的逻辑运行在QuickJS/WASM内部.
-   主机页面仅通过可信任的渲染器代码来变换出真实的 DOM.
-   关于真正的DOM前置消毒有效载荷的活动听众返回VM.
-   沙盒不能直接进入 `window`, (中文(简体) ), `document`,DOM节点,存储,或任意浏览器API.
-   `html` 模板被预处理成描述符. 主机从不评价用户表达式.
-   DOM主机中的收听器从不附加来自沙盒代码的原始用户回调.
-   合成沙盒事件保持了共同的进入模式,如 `event.target.value` 财务报告和审定财务报表 `event.currentTarget.checked` 不暴露现场 主机DOM节点.

目前明确覆盖的全球包括: `setTimeout`, (中文(简体) ), `clearTimeout`, (中文(简体) ), `setInterval`, (中文(简体) ), `clearInterval`和限制 `fetch()` 代理服务器。 主机拥有实时计时器和网络,但已注册的回调和响应处理仍然在QuickJS内部执行.

事件有效载荷作为简单数据传送。 VM收到一个狭小的快照, 不是活的 DOM 事件对象 .

沙盒会暴露 `event.target`, (中文(简体) ), `event.currentTarget`,以及 `event.srcElement` 作为带有故意小表面的简单数据快照: `value`, (中文(简体) ), `checked`, (中文(简体) ), `id`,以及 `tagName`。兼容性快捷键,例如 `event.value` 财务报告和审定财务报表 `event.checked` 仍然在场,但 `event.target.value` 是首选形状.

### 沙盒获取

那个沙盒 `fetch()` 桥面有意比浏览器窄 `window.fetch`数字 :

-   仅绝对 `https:` 允许使用 URL,加 `http:` 本地主机地址
-   没有 `Request` 对象, 没有相对的 URL, 没有继承的浏览器请求上下文
-   证书总是被迫 `omit`
-   `referrerPolicy` 总是被迫 `no-referrer`
-   `mode` 总是被迫 `cors`
-   请求头仅是用户提供的和敏感的环境头,例如 `authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `origin`, (中文(简体) ), `referer`,以及 `user-agent` 被封锁
-   反应作为小型反应类物体与 `ok`, (中文(简体) ), `status`, (中文(简体) ), `statusText`, (中文(简体) ), `url`, (中文(简体) ), `redirected`, (中文(简体) ), `headers`, (中文(简体) ), `text()`, (中文(简体) ), `json()`,以及 `arrayBuffer()`
-   15秒后请求暂停,答复上限为 1 MB

这个桥的设计是为了避免环境页面证书和主机DOM访问. 它仍然通过浏览器网络堆栈进行路由,所以浏览器控制的元数据如 `Origin` 或者说 `User-Agent` hTTP 层可能仍然存在.

## 支持的子集

-   文本插值
-   属性插值
-   约束事件,例如 `@click`
-   嵌入元素
-   同步 `component()` 组成
-   组件通过 `component((props, emit) => ...)` 和家长听众通过 `Child(props, { eventName })`
-   自动同步 `component()` 与VM所属倒置/投降/反应处理的构成
-   `pick()` 编号 : `props()` 缩小组件道具
-   全球 `output(payload)` 主机桥
-   直接主机桥模块通过第三个 `sandbox()` 参数
-   vM 内部的反应性更新
-   限制桥接 `fetch()` 请求和JSON/文本回复处理
-   桥接计时器调用 `setTimeout` 财务报告和审定财务报表 `setInterval`
-   阵列和有条件的儿童区域
-   没有包装元素的多根模板

## 不支持或部分支持

-   按键列表 diffing
-   直接 DOM 校对或真实 DOM 节点访问
-   任意的外部进口
-   浏览器 API 访问没有明确桥段
-   硬 CPU 和内存隔离

## 目前的限制

-   这还不是对抗CPU或内存耗尽的硬边界.
-   内存限制适用于快取JS运行时间,但拒绝服务硬化仍需做更多的工作.
-   类型脚本支持用途 `typescript.transpileModule`,不完全的语义类型检查.
-   模板支持有意比标准箭头主机运行时间更窄.

## 发展

```sh
pnpm --filter @arrow-js/sandbox sync:vm
pnpm --filter @arrow-js/sandbox demo
pnpm exec vitest run packages/sandbox/src/index.spec.ts
pnpm exec playwright test -c playwright.sandbox.config.ts
```

演示内容包括从公共Open-Meteo预测API获取当前条件的气象小应用.

## 常见问题

### @arrow-js/sandbox 是什么？

在主机窗口域外执行Arrow模板的快JS/WASM后置沙盒运行时间\.

### 如何安装 @arrow-js/sandbox？

在项目目录运行 npm install @arrow-js/sandbox，或使用 pnpm add / yarn add / bun add。

### @arrow-js/sandbox 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/arrow-js\_\_sandbox 是否存在。

### @arrow-js/sandbox 支持 ESM 还是 CommonJS？

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

### @arrow-js/sandbox 可以商用吗？

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

### @arrow-js/sandbox 的下载量有多少？

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

### @arrow-js/sandbox 还在维护吗？

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