# @allwright\.dev/core 中文文档

规范地址：https://npmcn.com/package/%40allwright.dev/core/

版本：0\.2\.0
npm 元数据更新时间：2026-10-17T11:38:14.422Z
中文译文更新时间：2026-11-08T01:10:57.274Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40allwright.dev/core
原文对照：https://npmcn.com/package/%40allwright.dev/core/?lang=original
项目主页：https://allwright.dev/
源码仓库：https://github.com/allwright-dev/allwright

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

- 包体积（解压后）：193 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-08-25T17:56:11.322Z
- 最新版本发布：2026-10-17T11:38:14.060Z
- 近 30 天下载量：1945（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：76（近 12 个月 76 个）

## 中文简介

Allwright自动化引擎高级TypeScript客户端.

## 安装

```sh
npm install @allwright.dev/core
```

也可以使用：`pnpm add @allwright.dev/core`、`yarn add @allwright.dev/core`、`bun add @allwright.dev/core`

## README

# @allwright.dev/core (英语)

Allwright自动化引擎高级TypeScript客户端.

安装 :

```bash
bun add @allwright.dev/core
```

```ts
import { firefox } from "@allwright.dev/core";

const browser = await firefox.launch();
const page = browser.page();
await page.goto("https://themoderninternet.vercel.app");
await page.click(
  "xpath=//div[contains(@class,'card')][.//h2[normalize-space()='Form Inputs']]//button[normalize-space()='Visit page']",
);
await browser.close();
```

网络点击接受 `{ button: "left" | "middle" | "right", clickCount: 1 | 2 | 3 }`。 。 。 . 使用 `page.dblclick(selector)` 或者说 `locator.dblclick()` 用于常见双击大小写.

在打开标签的动作前注册一个已键入的钩子, 然后等待它 后键入结果 :

```ts
import { firefox, hooks } from "@allwright.dev/core";

const browser = await firefox.launch();
const page = browser.page();
const hook = await page.registerHook(hooks.newPage);
await page.click("a[target=_blank]");
const newPage = await hook.wait();
```

```ts
const hook = await page.registerHook(hooks.fileChooser);
await page.click("button.open-upload");
const chooser = await hook.wait();
await chooser.setFiles("fixtures/document.pdf");
```

```ts
const hook = await page.registerHook(hooks.download);
await page.click("a.download-report");
const download = await hook.wait();
await download.saveAs(`artifacts/${download.suggestedFilename}`);
```

路径传递到 `setFiles` 财务报告和审定财务报表 `saveAs` 属于测试过程,即使 allwright 服务器是远程的。 Android 应用程序支持相同的 `fileChooser` 财务报告和审定财务报表 `download` 钩子形状; Android `newPage` 钩子不适用.

可运行的例子覆盖每个已执行的表面: [网页](https://npmcn.com/package/%40allwright.dev/core/examples/web-basic.ts), (中文(简体) ), [机器人](https://npmcn.com/package/%40allwright.dev/core/examples/android-basic.ts), (中文(简体) ), [iOS系统](https://npmcn.com/package/%40allwright.dev/core/examples/ios-basic.ts), (中文(简体) ), [马科斯](https://npmcn.com/package/%40allwright.dev/core/examples/macos-basic.ts),以及 [窗口](https://npmcn.com/package/%40allwright.dev/core/examples/windows-basic.ts)。桌面示例默认为 在 MacOS 和 Windows 上的 Notepad 上的计算器并接受 `ALLWRIGHT_MAC_APP_ID` 或者说 `ALLWRIGHT_WINDOWS_APP_ID`。 。 。 .

Android、iOS、macOS和Windows应用程序执行共享 `NativeApp` 财务报告和审定财务报表 `NativeAppLocator` 接口。 平台特定类型名称,例如: `MobileAndroidApp`, (中文(简体) ), `MobileIosLocator`, (中文(简体) ), `DesktopMacLocator`,以及 `DesktopWindowsLocator` 继续导出 作为兼容性和面向平台的说明的别名.

共享配置文件是堆栈不可知的, 并且可以生活其中 `allwright.config.yaml` 或者说 `allwright.config.json`。 。 。 . 共享的策略 生活在repo根 `allwright.schema.json`。 。 。 .

```yaml
schemaVersion: 1

server:
  addr: 127.0.0.1:50051

browser:
  name: firefox
  binary: /Applications/Firefox.app/Contents/MacOS/firefox
  launchOptions:
    timeoutMs: 30000

expect:
  timeoutMs: 5000
  intervalMs: 100

suites:
  smoke:
    browser:
      name: chromium
```

TypeScript 包导出 `findConfigFile()`, (中文(简体) ), `loadConfigFile()`, (中文(简体) ), `resolveConfig()`,以及 `launchConfiguredBrowser()` 因此,跑道包可以消耗相同的配置模型而无需发明语言上特有的配置文件.

### 框架

Iframe 解决一个正常 `Page`,包括嵌入式和跨出自式框架:

```ts
const frame = await page.locator("#checkout-frame").Frame({ timeoutMs: 10_000 });
await frame.locator("input[name=email]").fill("buyer@example.com");
const nested = await frame.locator("iframe").frame({ timeoutMs: 5_000 });
```

`Frame()` 财务报告和审定财务报表 `frame()` 是别名。 超时包括找到一个Iframe, 解决其浏览上下文,并等待装满200毫秒的文件 没有DOM突变。 默认为10秒. 关闭框架页面发布 它不删除 iframe 或关闭父标签。 解决新问题 iframe 替换后的框架页面.

### 读取页面和元素状态

```ts
const url = await page.url();
const value = await page.locator('input, textarea').inputValue();
const options = await page.locator('select').selectedOptions(); // [{ value, label, index }]
const selectedText = await page.locator('textarea').selectedText();
const checked = await page.locator('input[type=checkbox]').isChecked();
const text = await page.locator('h1').innerText(); // string
const attribute = await page.locator('a').getAttribute('href');
const box = await page.locator('button').boundingBox(); // { x, y, width, height }
```

元素读取也有页面方法,例如: `page.inputValue(selector, options)` 并接受 `timeoutMs`。阅读器使用第一个定位匹配,并在帧页面中工作. `inputValue` 读取输入、文本区域或选择的活属性. `selectedOptions` 支持本地选择(包括多个选择)和标记的 ARIA 组合框/列表框选项 `aria-selected="true"`。 。 。 . `selectedText` 返回文本框中选定的子字符串,一个用于保存的空字符串,或 `null` 用于没有选择支持的输入类型. `isChecked` 支持本地复选框/收音机和ARIA检查控件;ARIA混合状态返回不实.

缺少属性返回 `null` (空属性尚存) `""`) (中文(简体) ). 相较于页面/帧视图和返回的 CSS 像素 `null` 用于隐藏或零区域元素。 缺少的元素和不兼容的控制类型会产生出错. 使用 `textContent()` 用于原始文本或 `innerText()` 用于翻译文本.

`NativeApp` 财务报告和审定财务报表 `NativeAppLocator` 曝光 `inputValue`, (中文(简体) ), `isChecked`, (中文(简体) ), `getAttribute`,以及 `boundingBox` 在Android,iOS,macOS,和Windows上进行. 原生属性为平台可访问性/UI自动化属性,原生盒使用平台屏幕坐标. 所选选项和所选文本仍然只读网络.

## 常见问题

### @allwright\.dev/core 是什么？

Allwright自动化引擎高级TypeScript客户端\.

### 如何安装 @allwright\.dev/core？

在项目目录运行 npm install @allwright\.dev/core，或使用 pnpm add / yarn add / bun add。

### @allwright\.dev/core 支持 TypeScript 吗？

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

### @allwright\.dev/core 支持 ESM 还是 CommonJS？

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

### @allwright\.dev/core 可以商用吗？

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

### @allwright\.dev/core 的下载量有多少？

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

### @allwright\.dev/core 还在维护吗？

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