# @appium/css-locator-to-native 中文文档

规范地址：https://npmcn.com/package/%40appium/css-locator-to-native/

版本：1\.0\.7
npm 元数据更新时间：2026-10-08T09:03:55.759Z
中文译文更新时间：2026-11-06T11:32:35.641Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40appium/css-locator-to-native
原文对照：https://npmcn.com/package/%40appium/css-locator-to-native/?lang=original
项目主页：https://github.com/appium/css-locator-to-native#readme
源码仓库：https://github.com/appium/css-locator-to-native

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

- 包体积（解压后）：86.3 kB，54 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.12\.0 \|\| \>=24\.0\.0
- 运行依赖：1 个
- 首次发布：2026-06-07T18:33:13.204Z
- 最新版本发布：2026-09-01T12:56:36.813Z
- 近 30 天下载量：770639（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

用于本地定位器转换的平台不可知CSS选择器解析和正常化

## 安装

```sh
npm install @appium/css-locator-to-native
```

也可以使用：`pnpm add @appium/css-locator-to-native`、`yarn add @appium/css-locator-to-native`、`bun add @appium/css-locator-to-native`

## README

# @ appium/ css- 定位器对本地

平台-不可知 CSS 选取器解析并规范本地定位器转换.

## 安装

```bash
npm install @appium/css-locator-to-native
```

## 快开始

```typescript
import {
  createCssTransformer,
  type AttributeSchema,
  type ParsedSelector,
  type StrategyKey,
} from '@appium/css-locator-to-native';

const schema: AttributeSchema = {
  attributes: {
    visible: {type: 'boolean'},
    name: {type: 'string', aliases: ['id']},
    index: {type: 'numeric', aliases: ['nth-child']},
  },
  booleanFormat: 'zero-one',
};

const emitters = {
  native: {
    strategy: 'my-native-strategy',
    emit(parsed: ParsedSelector) {
      // Map ParsedSelector IR to your platform's selector syntax
      return parsed.rule.tag ?? '*';
    },
  },
};

const transformCss = createCssTransformer({
  schema,
  emitters,
  resolveStrategy(): StrategyKey<typeof emitters> {
    return 'native';
  },
});

const {strategy, selector} = transformCss('window#foo[visible]');
// => { strategy: 'my-native-strategy', selector: '...' }
```

## API 密码

所有东西都从一个入口出口:

| 导出 | 说明 |
| --- | --- |
| `normalizeCssSelector(css, schema)` | 将 CSS 选择器解析并规范化为 `ParsedSelector` 爱尔兰语 |
| `createCssTransformer(config)` | 返回用于剖析 CSS 并生成一个函数 `NativeLocator` |
| `InvalidSelectorError` | CSS 语法无法解析 |
| `UnsupportedSelectorError` | 解析的 CSS 使用不支持的特性或未知属性 |
| `UnresolvedStrategyError` | 解析策略密钥没有匹配的发射器 |

### 解析选择器 IR

常态化产生平台-不可知中间代表. IR捕获 CSS 结构——标记,类, `#id`属性 假象 组合器 与你的计划相对应 没错 **没有** 编码为iOS类链,UiAutomator,或任何其他本土语法.

```typescript
interface ParsedSelector {
  rule: ParsedRule; // first comma-separated rule only
}

interface ParsedRule {
  combinator?: 'descendant' | 'child';
  tag?: string;           // raw CSS tag (may be '*')
  classes: string[];      // raw class tokens
  id?: string;            // raw #id value
  attributes: ParsedAttribute[];
  pseudos: ParsedAttribute[];
  nested?: ParsedRule;
}
```

### 属性计划

驱动程序声明哪些 CSS 属性是有效的, 以及布林是如何被胁迫的 :

```typescript
interface AttributeSchema {
  attributes: Record<string, {type: 'boolean' | 'string' | 'numeric'; aliases?: string[]}>;
  booleanFormat?: 'zero-one' | 'true-false' | 'literal';
}
```

-   **`zero-one`** —— 说 `true`编号 :`1`(空虚) `'1'`, (中文(简体) ), `false`编号 :`0` → `'0'`
-   **`true-false`** —— 说 `true`(空虚) `'true'`, (中文(简体) ), `false` → `'false'`
-   **`literal`** (默认) —— 原始属性值保持不变; 隐含布尔( 无值) 保持不变

标签,类,和 `#id` 测绘(如:. `XCUIElementType*` 前缀, `resourceId` 前缀)完全是驱动器在发件人中的责任.

### 多战略路线

`createCssTransformer` 需要登记 `StrategyEmitter`页:1 `resolveStrategy` 调用。 解析器会选择根据选择器外形进行排放使用; 变压器既返回目标策略名称, 也返回本地选择器字符串 .

```typescript
interface NativeLocator {
  strategy: string;
  selector: string;
}
```

具有单一目标策略的驱动程序使用一入式登记器和小解析器.

## 驱动器集成模式

平台逻辑留在驱动器中. 典型布局 :

```
lib/css/
  schema.ts          # AttributeSchema for the platform
  *-emitter.ts       # StrategyEmitter implementations
  resolve-helpers.ts # isSimpleIdSelector, etc.
  index.ts           # createCssTransformer wrapper
```

单位 `find` 命令,使用变换结果中的策略而不是硬编码:

```typescript
if (strategy === 'css selector') {
  ({strategy, selector} = cssToNativeLocator(selector));
}
```

## 支持的 CSS 子集

匹配现有 Appium 驱动程序接受的子集 :

-   标记(包括 `*`, (中文(简体) ), `#id`,类,属性选择器(`=`, (中文(简体) ), `*=`, (中文(简体) ), `^=`, (中文(简体) ), `$=`, (中文(简体) ), `~=`(中文(简体) )
-   儿童(`>`)和后人(空间)组合器
-   被接受为按照chema(如:. `:visible`, (中文(简体) ), `:nth-child(2)`(中文(简体) )
-   仅以逗号分隔的第一条规则( 其他规则被忽略)
-   不支持 : `+` 编号 : `~` 组合器、假元素、筑巢(`&`),命名空间

## 发展

```bash
npm install --no-package-lock
npm run typecheck   # type-check lib + test
npm run build       # compile to build/
npm test            # unit tests (compiled ESM)
npm run lint
npm run format:check
```

## 所需资源

-   节点.js `^20.19.0 || ^22.12.0 || >=24.0.0`
-   无 `>=10`

## 许可证

[阿帕奇 - 2.0](https://npmcn.com/package/%40appium/css-locator-to-native/LICENSE)

## 常见问题

### @appium/css-locator-to-native 是什么？

用于本地定位器转换的平台不可知CSS选择器解析和正常化

### 如何安装 @appium/css-locator-to-native？

在项目目录运行 npm install @appium/css-locator-to-native，或使用 pnpm add / yarn add / bun add。

### @appium/css-locator-to-native 支持 TypeScript 吗？

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

### @appium/css-locator-to-native 支持 ESM 还是 CommonJS？

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

### @appium/css-locator-to-native 需要什么版本的 Node\.js？

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

### @appium/css-locator-to-native 可以商用吗？

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

### @appium/css-locator-to-native 的下载量有多少？

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

### @appium/css-locator-to-native 还在维护吗？

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