# @capgo/capacitor-compass 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-compass/

版本：8\.1\.24
npm 元数据更新时间：2026-10-15T04:16:35.387Z
中文译文更新时间：2026-11-09T03:34:44.962Z
软件包许可：MPL-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-compass
原文对照：https://npmcn.com/package/%40capgo/capacitor-compass/?lang=original
项目主页：https://capgo.app/docs/plugins/compass/
源码仓库：https://github.com/Cap-go/capacitor-compass

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

- 包体积（解压后）：125 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-28T20:38:10.065Z
- 最新版本发布：2026-10-15T04:16:35.014Z
- 近 30 天下载量：45704（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

Capacitor 本地指南针标题插件

## 安装

```sh
npm install @capgo/capacitor-compass
```

也可以使用：`pnpm add @capgo/capacitor-compass`、`yarn add @capgo/capacitor-compass`、`bun add @capgo/capacitor-compass`

## README

# @ capgo/ 电容器- compass

让设备指南针在iOS和Android上以度向行走,作为一次性读取或活流. 将用户指向某地,旋转地图或建立qibla查找器.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-compass)](https://capgo.app/?ref=plugin_compass)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_compass)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_compass) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-compass` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/capor-compass到我的 Capacitor app 并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_compass) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_compass)

![@capgo/capacitor-compass for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-compass/main/assets/github-social-preview.png)

## 主要特点

-   **当前标题**数字 : `getCurrentHeading()` 返回以度为单位的标题.
-   **实时更新**数字 : `startListening()` 发射 `headingChange` 事件, `stopListening()` 拦住他们.
-   **准确性**数字 : `watchAccuracy()`, (中文(简体) ), `getAccuracy()` 编辑 `accuracyChange` 事件可以要求用户校正.
-   **权限**数字 : `checkPermissions()` 财务报告和审定财务报表 `requestPermissions()`。 。 。 .
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-22. iOS使用Core Location标题,Android使用设备传感器. 在网上不可用.

## 为什么是Capacitor Compass?

官方电容 [API 动议](https://capacitorjs.com/docs/apis/motion) 依靠网络API来获取指南针/标题数据,这提供了一个次最佳开发者的经验:

-   **行为不一致** 跨平台
-   **其他权限处理** 通过网络 API
-   **准确性有限** 与本地执行相比
-   **业绩不佳** 在一些设备上
-   **无准确性监测** 确保可靠的指南针读取

此插件提供 **真实的本地指南针功能** 使用:

-   **iOS系统**数字 : `CLLocationManager` 通过 CoreLocation 获取准确的标题数据
-   **机器人**: 硬件传感器(加速计+磁力计),用于精确的轴承计算
-   **准确性监测**: 监测Android上的指南针准确性并促使用户在需要时校正
-   **基于事件的 API**: 现代 `addListener` 实时标题更新模式

对于导航应用,增强现实,基于位置的游戏,以及任何需要精确的指南针航向的应用都是必不可少的.

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-compass` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-compass
npx cap sync
```

## 所需资源

### iOS系统

在您的 `Info.plist`数字 :

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need access to your location to determine compass heading</string>
```

### 机器人

不需要额外设置。 该插件使用设备的加速计和磁强计传感器.

## 使用量

```typescript
import { CapgoCompass, CompassAccuracy } from '@capgo/capacitor-compass';

// Get current heading once
const { value } = await CapgoCompass.getCurrentHeading();
console.log('Current heading:', value, 'degrees');

// Listen for continuous heading updates
const handle = await CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value, 'degrees');
});

// Start the compass sensor
await CapgoCompass.startListening();

// Monitor compass accuracy (Android only)
const accuracyHandle = await CapgoCompass.addListener('accuracyChange', (event) => {
  console.log('Compass accuracy:', event.accuracy);
  if (event.accuracy < CompassAccuracy.MEDIUM) {
    console.log('Compass needs calibration');
    // Show your own custom UI to prompt user to calibrate
  }
});

// Start accuracy monitoring
await CapgoCompass.watchAccuracy();

// Get current accuracy
const { accuracy } = await CapgoCompass.getAccuracy();
console.log('Current accuracy:', accuracy);

// Later: stop listening
await CapgoCompass.stopListening();
await CapgoCompass.unwatchAccuracy();
await handle.remove();
await accuracyHandle.remove();
```

## API 密码

-   [`getCurrentHeading()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-getcurrentheading)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-getpluginversion)
-   [`startListening(...)`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-startlistening)
-   [`stopListening()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-stoplistening)
-   [`addListener('headingChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-addlistenerheadingchange-)
-   [`addListener('accuracyChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-addlisteneraccuracychange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-removealllisteners)
-   [`checkPermissions()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-checkpermissions)
-   [`requestPermissions()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-requestpermissions)
-   [`watchAccuracy()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-watchaccuracy)
-   [`unwatchAccuracy()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-unwatchaccuracy)
-   [`getAccuracy()`](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-getaccuracy)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-type-aliases)
-   [数字](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-enums)

用于读取设备指南针方向的 Capacitor Compass 插件接口 .

### 获取当前标题( C)

```typescript
getCurrentHeading() => Promise<CompassHeading>
```

让现在的指南针以度向上. 在iOS上,标题在背景中更新,并返回最新值. 在Android上,当使用加速计和磁强计传感器调用该方法时会计算出这个标题. 未在网络上执行 .

**回返情况:** `Promise<[CompassHeading](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-compassheading)>`

**自:** 7.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 .

**回返情况:** `Promise<{ version: string; }>`

**自:** 7.0.0 (单位:千美元)

* * *

### 开始聆听(...)

```typescript
startListening(options?: ListeningOptions | undefined) => Promise<void>
```

开始通过事件聆听指南针标题变化 . 这开始罗盘传感器 并发出"头变"事件.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ListeningOptions](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-listeningoptions)` | \- 节奏行为的可选配置 |

**自:** 7.0.0 (单位:千美元)

* * *

### 停止听( )

```typescript
stopListening() => Promise<void>
```

停止监听指南针标题更改 . 这停止了罗盘传感器 并停止了排放事件.

**自:** 7.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 标题变化 ” ,...)

```typescript
addListener(eventName: 'headingChange', listenerFunc: (event: HeadingChangeEvent) => void) => Promise<{ remove: () => Promise<void>; }>
```

为引导更改事件添加一个收听器 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'headingChange'` | \- 要听的活('heading Change') |
| **`listenerFunc`** | `(event: [HeadingChangeEvent](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-headingchangeevent)) => void` | \- 事件发射时调用功能 |

**回返情况:** `Promise<{ remove: () => Promise<void>; }>`

**自:** 7.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 准确切换 ” ,...)

```typescript
addListener(eventName: 'accuracyChange', listenerFunc: (event: AccuracyChangeEvent) => void) => Promise<{ remove: () => Promise<void>; }>
```

为指南针精确度变化事件添加一个收听器. 只支持在Android上. 在iOS和Web上,这永远不会出现事件.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'accuracyChange'` | \- 要听的活动('准确 Change') |
| **`listenerFunc`** | `(event: [AccuracyChangeEvent](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-accuracychangeevent)) => void` | \- 事件发射时调用功能 |

**回返情况:** `Promise<{ remove: () => Promise<void>; }>`

**自:** 8.2.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 7.0.0 (单位:千美元)

* * *

### 检查( )

```typescript
checkPermissions() => Promise<PermissionStatus>
```

检查当前访问罗盘数据的许可状态 . 在iOS上,此检查位置许可状态. 在Android上,它总是返回"被授予",因为不需要权限.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-permissionstatus)>`

**自:** 7.0.0 (单位:千美元)

* * *

### 请求( )

```typescript
requestPermissions() => Promise<PermissionStatus>
```

请求访问罗盘数据的许可 . 在iOS上,这请求位置权限(对标题数据的要求). 在Android上,这立即解决,因为不需要权限.

**回返情况:** `Promise<[PermissionStatus](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-permissionstatus)>`

**自:** 7.0.0 (单位:千美元)

* * *

### 精确度( )

```typescript
watchAccuracy() => Promise<void>
```

开始监控罗盘精确度. 在Android上,这个监测磁强计的精度和发射精度 变化事件. 开发者可以收听这些事件,执行自己的UI校正提示. 在iOS和Web上,这种方法没有任何作用,因为没有罗盘准确性监测.

**自:** 8.2.0 (中文(简体) )

* * *

### 准确性( )

```typescript
unwatchAccuracy() => Promise<void>
```

停止监控罗盘精确度. 这停止了准确性监测.

**自:** 8.2.0 (中文(简体) )

* * *

### 获取准确性( )

```typescript
getAccuracy() => Promise<{ accuracy: CompassAccuracy; }>
```

获取当前指南针精确度 . 在Android上,返回当前磁强计传感器的精度. 在 iOS 和 Web 上, 总是返回 [指南准确性](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-compassaccuracy) 由于没有准确性监测.

**回返情况:** `Promise<{ accuracy: [CompassAccuracy](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-compassaccuracy); }>`

**自:** 8.2.0 (中文(简体) )

* * *

### 接口

#### 指南标题

包含指南针标题值的结果 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`value`** | `number` | 坐标为度(0-360) |

#### 监听选项

配置罗盘监听行为的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`minInterval`** | `number` | 以毫秒计的标题变化事件之间的最小间隔 。 下值 = 更新频率较高,但CPU/电池使用率较高. | `100` | 8.1.4 (中文(简体) ) |
| **`minHeadingChange`** | `number` | 触发事件所需的最小方向变化 。 下值 = 更敏感但事件更多. 手接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相. | `2.0` | 8.1.4 (中文(简体) ) |

#### 标题 更改事件

变化事件标题的事件数据 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`value`** | `number` | 坐标为度(0-360) |

#### 精确变化事件

准确性变化事件的事件数据.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`accuracy`** | `[CompassAccuracy](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-compassaccuracy)` | 指南针的当前精确度 |

#### 权限状态

指南针插件的授权状态 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`compass`** | `[PermissionState](https://npmcn.com/package/%40capgo/capacitor-compass/#readme-permissionstate)` | 访问罗盘/位置数据的许可状态 。 在iOS上,这需要位置许可才能访问标题. 在Android上,指南针传感器不需要特殊许可. | 7.0.0 (单位:千美元) |

### 类型异名

#### 权限状态

`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`

### 数字

#### 指南精确度

| 成员 | 数值 | 说明 |
| --- | --- | --- |
| **`HIGH`** | `3` | 高度精度 - 大约为5度以下的错误 |
| **`MEDIUM`** | `2` | 中度精确度 - 大约为10度以下的错误 |
| **`LOW`** | `1` | 低精度 - 大约为15度以下的错误 |
| **`UNRELIABLE`** | `0` | 不可靠的精确度 - 大约为15度以上的误差 |
| **`UNKNOWN`** | `-1` | 未知的精确值 |

## 贷项

此插件的灵感来自 [电容-内在-辅助材料](https://github.com/HeyItsBATMAN/capacitor-native-compass) 嘿,这是蝙蝠侠.

## 常见问题

### @capgo/capacitor-compass 是什么？

Capacitor 本地指南针标题插件

### 如何安装 @capgo/capacitor-compass？

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

### @capgo/capacitor-compass 支持 TypeScript 吗？

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

### @capgo/capacitor-compass 支持 ESM 还是 CommonJS？

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

### @capgo/capacitor-compass 可以商用吗？

@capgo/capacitor-compass 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-compass 的下载量有多少？

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

### @capgo/capacitor-compass 还在维护吗？

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