Getting Started

Instalar

Puede utilizar nuestra configuración asistida por inteligencia artificial para instalar el complemento. Agregue las Capgo habilidades a su herramienta de inteligencia artificial utilizando el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego utilice el siguiente prompt:

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

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas del plataforma a continuación:

bun add @capgo/capacitor-compass
bunx cap sync

Importar

import { CapgoCompass } from '@capgo/capacitor-compass';

API Resumen

getCurrentHeading

Obtenga la dirección actual del compás en grados. En iOS, la dirección se actualiza en segundo plano, y el último valor se devuelve. En Android, la dirección se calcula cuando se llama al método utilizando sensores de acelerómetro y magnetómetro. No implementado en Web.

import { CapgoCompass } from '@capgo/capacitor-compass';

const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');

startListening

Inicie la escucha de cambios en la dirección del compás mediante eventos. Esto inicia los sensores del compás y emite eventos ‘headingChange’.

import { CapgoCompass } from '@capgo/capacitor-compass';

// With default throttling (100ms interval, 2° minimum change)
await CapgoCompass.startListening();

// With custom throttling for high-frequency updates
await CapgoCompass.startListening({
  minInterval: 50,      // 50ms between events
  minHeadingChange: 1.0 // 1° minimum change
});

CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value);
});

stopListening

Detener la escucha de cambios en la dirección del compás. Esto detiene los sensores del compás y detiene la emisión de eventos.

import { CapgoCompass } from '@capgo/capacitor-compass';

await CapgoCompass.stopListening();

checkPermissions

Verificar el estado de permiso actual para acceder a datos del compás. En iOS, esto verifica el estado de permiso de ubicación. En Android, esto siempre devuelve ‘concedido’ ya que no se requieren permisos.

import { CapgoCompass } from '@capgo/capacitor-compass';

const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);

requestPermissions

Solicitar permiso para acceder a datos del compás. En iOS, esto solicita permiso de ubicación (requerido para datos de dirección). En Android, esto resuelve inmediatamente ya que no se requieren permisos.

import { CapgoCompass } from '@capgo/capacitor-compass';

const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
  // Can now use compass
}

watchAccuracy

Iniciar la monitorización de la precisión del compás. En Android, esto monitorea la precisión del magnetómetro y emite eventos de cambio de precisión. Los desarrolladores pueden escuchar estos eventos y implementar su propia interfaz de usuario para solicitudes de calibración. En iOS y Web, este método no hace nada ya que la monitorización de precisión del compás no está disponible.

import { CapgoCompass } from '@capgo/capacitor-compass';

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

// Listen for accuracy changes and implement custom UI
CapgoCompass.addListener('accuracyChange', (event) => {
  console.log('Accuracy changed to:', event.accuracy);
  if (event.accuracy < CompassAccuracy.MEDIUM) {
    // Show your custom calibration UI
  }
});

unwatchAccuracy

Detener la monitorización de precisión del compás. Esto detiene la monitorización de precisión.

import { CapgoCompass } from '@capgo/capacitor-compass';

await CapgoCompass.unwatchAccuracy();

getAccuracy

Obtenga el nivel actual de precisión del compás. En Android, devuelve la precisión actual del sensor del magnetómetro. En iOS y Web, siempre devuelve CompassAccuracy.UNKNOWN ya que la monitorización de precisión no está disponible.

import { CapgoCompass } from '@capgo/capacitor-compass';

const { accuracy } = await CapgoCompass.getAccuracy();
if (accuracy < CompassAccuracy.MEDIUM) {
  console.log('Compass needs calibration');
}

Referencia de tipos

CompassHeading

Resultado que contiene el valor del encabezado del compás.

export interface CompassHeading {
  /** Compass heading in degrees (0-360) */
  value: number;
}

ListeningOptions

Opciones para configurar el comportamiento de escucha del compás.

export interface ListeningOptions {
  /**
   * Minimum interval between heading change events in milliseconds.
   * Lower values = more frequent updates but higher CPU/battery usage.
   *
   * @default 100
   * @since 8.1.4
   */
  minInterval?: number;

  /**
   * Minimum heading change in degrees required to trigger an event.
   * Lower values = more sensitive but more events.
   * Handles wraparound (e.g., 359° to 1° = 2° change).
   *
   * @default 2.0
   * @since 8.1.4
   */
  minHeadingChange?: number;
}

HeadingChangeEvent

Datos del evento para cambios en la dirección de la cabeza.

export interface HeadingChangeEvent {
  /** Compass heading in degrees (0-360) */
  value: number;
}

AccuracyChangeEvent

Datos del evento para cambios en la precisión.

export interface AccuracyChangeEvent {
  /** Current accuracy level of the compass */
  accuracy: CompassAccuracy;
}

PermissionStatus

Estado de permiso para plugin de brújula.

export interface PermissionStatus {
  /**
   * Permission state for accessing compass/location data.
   * On iOS, this requires location permission to access heading.
   * On Android, no special permissions are required for compass sensors.
   *
   * @since 7.0.0
   */
  compass: PermissionState;
}

CompassAccuracy

Niveles constantes de precisión de brújula.

export enum CompassAccuracy {
  /** High accuracy - approximates to less than 5 degrees of error */
  HIGH = 3,
  /** Medium accuracy - approximates to less than 10 degrees of error */
  MEDIUM = 2,
  /** Low accuracy - approximates to less than 15 degrees of error */
  LOW = 1,
  /** Unreliable accuracy - approximates to more than 15 degrees of error */
  UNRELIABLE = 0,
  /** Unknown accuracy value */
  UNKNOWN = -1,
}

PermissionState

Estado de permiso para acceso al compás.

export type PermissionState = 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied';

Fuente de Verdad

Esta página se genera desde el plugin’s src/definitions.tsRe-ejecutar la sincronización cuando el público API cambie en la fuente.

Seguir adelante desde Inicio

Si estás utilizando Inicio para planificar la consola y las operaciones API, conectarlo con Usando @capgo/capacitor-compass para la capacidad nativa en Usando @capgo/capacitor-compass, Resumen de API para el detalle de implementación en Resumen de API, Introducción para el detalle de implementación en Introducción, Claves de API para el detalle de implementación en Claves de API, y Dispositivos para el detalle de implementación en Dispositivos.