# @domscribe/overlay 中文文档

规范地址：https://npmcn.com/package/%40domscribe/overlay/

版本：0\.7\.0
npm 元数据更新时间：2026-10-27T19:41:30.267Z
中文译文更新时间：2026-11-12T15:49:31.416Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：185 kB，76 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：5 个
- 首次发布：2026-03-18T01:16:52.770Z
- 最新版本发布：2026-10-27T19:41:29.855Z
- 近 30 天下载量：140638（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

DOMLIS 像素到代码工作流程的框架不可知覆盖 UI

## 安装

```sh
npm install @domscribe/overlay
```

也可以使用：`pnpm add @domscribe/overlay`、`yarn add @domscribe/overlay`、`bun add @domscribe/overlay`

## README

# @ domains/ 覆盖

DOMLATS in-applay UI 的Lit网络组件. 使用阴影DOM进行CSS/JS隔离.

`@domscribe/overlay` 使元素拾取器、注释面板和可拖动标签在运行中的应用程序中。 它通过WebSocket连接到中继器,并查询直播组件上下文的运行时间. 由于它使用影子DOM,因此它不会干扰主机应用程序的风格或JavaScript.

## 安装

```bash
npm install @domscribe/overlay
```

此软件包通常由框架适配器自动安装( S)`@domscribe/next`, (中文(简体) ), `@domscribe/nuxt`而不是直接添加.

## 配置

```ts
interface OverlayOptions {
  initialMode?: 'collapsed' | 'expanded' | 'capturing';
  debug?: boolean;
  sidebarWidth?: number;
}
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `initialMode` | `OverlayMode` | `'collapsed'` | 初始显示模式 . `collapsed` 只显示标签, `expanded` 显示侧边栏, `capturing` 激活元素拾取器 |
| `debug` | `boolean` | `false` | 启用调试日志 |
| `sidebarWidth` | `number` | `360` | 边栏宽度( 像素) |

## 显示模式

-   **崩溃** – 只有可拖放标签可见于视图端口右边缘
-   **扩大** —侧边栏面板已打开,显示说明和元素细节
-   **捕获** —— 元素拾取器活动; 单击任意元素选择并抓取其运行时上下文

## 标签持久性

倒塌的标签的垂直位置存储于 `localStorage` 作为 `domscribe:tabOffsetY` (0-100%,默认) `50` =中间。 标签可沿右侧边缘拖曳并带有4px拖曳阈值,以区分单击和拖曳.

## 阴影DOM

覆盖会使阴影根内部防止CSS和JavaScript与主机应用程序相冲突. 这意味着:

-   主机应用程序样式不会流血到覆盖层中
-   重叠样式不会流入主机应用程序
-   剧作家定位器和 `.click()` 电话不要穿透阴影 DOM — 使用 `page.evaluate()` 用于自动测试覆盖本身

## 链接

部分 [多写](https://github.com/patchorbit/domscribe)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @domscribe/overlay 是什么？

DOMLIS 像素到代码工作流程的框架不可知覆盖 UI

### 如何安装 @domscribe/overlay？

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

### @domscribe/overlay 支持 TypeScript 吗？

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

### @domscribe/overlay 支持 ESM 还是 CommonJS？

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

### @domscribe/overlay 需要什么版本的 Node\.js？

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

### @domscribe/overlay 可以商用吗？

@domscribe/overlay 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @domscribe/overlay 的下载量有多少？

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

### @domscribe/overlay 还在维护吗？

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