# @bisonsoftware/canvas-grid-playwright 中文文档

规范地址：https://npmcn.com/package/%40bisonsoftware/canvas-grid-playwright/

版本：0\.3\.0
npm 元数据更新时间：2025-10-07T17:50:49.336Z
中文译文更新时间：2026-11-08T03:48:27.296Z
软件包许可：GPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40bisonsoftware/canvas-grid-playwright
原文对照：https://npmcn.com/package/%40bisonsoftware/canvas-grid-playwright/?lang=original
项目主页：https://github.com/Bison-Software/CanvasGrid#readme
源码仓库：https://github.com/Bison-Software/CanvasGrid

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

- 包体积（解压后）：776 kB，46 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@playwright/test \>=1\.44\.0
- 首次发布：2025-10-03T21:49:46.497Z
- 最新版本发布：2025-10-07T17:50:49.115Z
- 近 30 天下载量：4988（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

通过网格覆盖的Canvas测试(Playwright-First).

## 安装

```sh
npm install @bisonsoftware/canvas-grid-playwright
```

也可以使用：`pnpm add @bisonsoftware/canvas-grid-playwright`、`yarn add @bisonsoftware/canvas-grid-playwright`、`bun add @bisonsoftware/canvas-grid-playwright`

## README

# Canvas 网格库

一个Playwright-First库,用于使用基于网格的方法测试HTML5 Canvas元素.

## 依赖关系

这个图书馆需要 [剧作家](https://playwright.dev/) 作为同伴依赖:

```bash
npm install @playwright/test
```

您必须安装 Playwright 在您的项目中使用 CanvasGrid .

## 请注意,整个图书馆仍然是实验性的.

## 基本用途

```typescript
import { test, expect } from '@playwright/test';
import {CanvasGrid} from "@bisonsoftware/canvas-grid-playwright";

test('canvas testing example', async ({ page }) => {
  await page.goto('https://your-canvas-app.com');
  
  // Create grid overlay
  const grid = new CanvasGrid(page)
    .locator('canvas')
    .gridSize(10, 8);  // 10 cols, 8 rows
  
  await grid.attach();
  
  // Interact with canvas
  await grid.clickCell(5, 4);
  await grid.hoverCell(3, 2);
});
```

## API 参考

### 核心方法

#### 设置

-   `new CanvasGrid(page)` - 以 Playwright 页面初始化
-   `.locator(selector)` - 选择画布元素
-   `.nth(index)` - 多次匹配时选择特定的画布
-   `.gridSize(cols, rows)` - 设置网格尺寸(默认情况下可选、自动大小)
-   `.attach()` - 创建和附加网格覆盖

#### 鼠标交互

-   `.clickCell(col, row)` - 左键单元格中心
-   `.hoverCell(col, row)` - 躲过牢房中心
-   `.doubleClickCell(col, row)` - 双击单元格中心
-   `.rightClickCell(col, row)` - 右击单元格中心
-   `.dragFromCellToCell(fromCol, fromRow, toCol, toRow)` - 在单元格间拖动

#### 工具提示检测

-   `.hoverCellAndCaptureTooltip(col, row, options?)` - 抓住DOM工具提示
-   `.waitForTooltip(options?)` - 等待工具提示出现
-   `.getVisibleTooltips(selectors?)` - 获取所有当前可见的工具提示
-   `.scanAllCellsForTooltips(options?)` - 为 DOM 工具提示扫描整个网格
-   `.hasAnyTooltips(options?)` - 快速检查是否有 DOM 工具提示
-   `.scanWithTextExtraction(options?)` - DOM工具提示强化扫描

#### 重叠控制

-   `.interactive(boolean)` - 启用/禁用覆盖鼠标事件
-   `.toggleOverlay(boolean)` - 显示/隐藏可视性

## 自动图像大小

未指定网格大小时,库会根据画布大小自动选择:

-   **小画布** ( < 400px): 6×4 网格
-   **中画布** (400-900px): 10x8网格
-   **大画布** ( > 900px): 14x10 网格

```typescript
// Auto-sizing based on canvas dimensions
const grid = new CanvasGrid(page).locator('#my-canvas');
await grid.attach(); // Grid size determined automatically
```

## 常见问题

### @bisonsoftware/canvas-grid-playwright 是什么？

通过网格覆盖的Canvas测试\(Playwright-First\)\.

### 如何安装 @bisonsoftware/canvas-grid-playwright？

在项目目录运行 npm install @bisonsoftware/canvas-grid-playwright，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@playwright/test（\>=1\.44\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bisonsoftware/canvas-grid-playwright 支持 TypeScript 吗？

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

### @bisonsoftware/canvas-grid-playwright 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bisonsoftware/canvas-grid-playwright 可以商用吗？

@bisonsoftware/canvas-grid-playwright 使用 GPL-3\.0-only 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @bisonsoftware/canvas-grid-playwright 的下载量有多少？

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

### @bisonsoftware/canvas-grid-playwright 还在维护吗？

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