@capgo/capacitor-compass 사용하기
기기 나침반의 헤딩(heading) 값을 읽기 위한 Capacitor Compass 플러그인 인터페이스.
설치
bun add @capgo/capacitor-compass
bunx cap sync
bunx cap sync 플러그인의 네이티브 code를 네이티브 프로젝트에 복사합니다. 플러그인을 업그레이드할 때마다 다시 실행하세요.
가져오기
import { CapgoCompass } from '@capgo/capacitor-compass';
API 한눈에 보기
| 메서드 | 설명 |
|---|---|
getCurrentHeading |
현재 나침반의 방위각을 도(degree) 단위로 가져옵니다. iOS에서는 백그라운드에서 방위각이 업데이트되며 최신 값을 반환합니다. Android에서는 메서드 호출 시 가속도계와 자기계 센서를 사용하여 방위각을 계산합니다. Web에서는 지원되지 않습니다. |
startListening |
이벤트를 통해 나침반 방위각 변경 사항을 감지하기 시작합니다. 나침반 센서가 활성화되며 'headingChange' 이벤트가 발생합니다. |
stopListening |
나침반 방위각 변경 사항 감지를 중단합니다. 나침반 센서가 비활성화되며 이벤트 발생이 중단됩니다. |
checkPermissions |
나침반 데이터 접근에 대한 현재 권한 상태를 확인합니다. iOS에서는 위치 권한 상태를 확인합니다. Android에서는 별도의 권한이 필요하지 않으므로 항상 'granted'를 반환합니다. |
requestPermissions |
나침반 데이터 접근 권한을 요청합니다. iOS에서는 방위각 데이터에 필요한 위치 권한을 요청합니다. Android에서는 별도의 권한이 필요하지 않으므로 즉시 완료됩니다. |
watchAccuracy |
나침반 정확도를 모니터링하기 시작합니다. Android에서는 자기계 정확도를 모니터링하고 accuracyChange 이벤트를 발생시킵니다. 개발자는 이 이벤트를 수신하여 보정(calibration) prompt를 위한 자체 UI를 구현할 수 있습니다. iOS와 Web에서는 정확도 모니터링을 지원하지 않으므로 아무 동작도 수행하지 않습니다. |
unwatchAccuracy |
나침반 정확도 모니터링을 중단합니다. |
getAccuracy |
현재 나침반 정확도 수준을 가져옵니다. Android에서는 현재 자기계 센서의 정확도를 반환합니다. iOS와 Web에서는 정확도 모니터링을 지원하지 않으므로 항상 CompassAccuracy.UNKNOWN을 반환합니다. |
예시
getCurrentHeading()
현재 나침반의 방위각을 도(degree) 단위로 가져옵니다. iOS에서는 백그라운드에서 방위각이 업데이트되며 최신 값이 반환됩니다. Android에서는 메서드 호출 시 가속도계와 자기계 센서를 사용하여 방위각을 계산합니다. Web에서는 지원되지 않습니다.
import { CapgoCompass } from '@capgo/capacitor-compass';
const { value } = await CapgoCompass.getCurrentHeading();
console.log('Compass heading:', value, 'degrees');
startListening()
이벤트를 통해 나침반 방위각 변경 사항을 감지하기 시작합니다. 나침반 센서가 활성화되며 '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()
나침반 방위각 변경 사항 감지를 중단합니다. 나침반 센서가 비활성화되며 이벤트 발생이 중단됩니다.
import { CapgoCompass } from '@capgo/capacitor-compass';
await CapgoCompass.stopListening();
checkPermissions()
나침반 데이터 접근에 대한 현재 권한 상태를 확인합니다. iOS에서는 위치 권한 상태를 확인합니다. Android에서는 별도의 권한이 필요하지 않으므로 항상 'granted'를 반환합니다.
import { CapgoCompass } from '@capgo/capacitor-compass';
const status = await CapgoCompass.checkPermissions();
console.log('Compass permission:', status.compass);
requestPermissions()
나침반 데이터 접근 권한을 요청합니다. iOS에서는 방위각 데이터에 필요한 위치 권한을 요청합니다. Android에서는 별도의 권한이 필요하지 않으므로 즉시 완료됩니다.
import { CapgoCompass } from '@capgo/capacitor-compass';
const status = await CapgoCompass.requestPermissions();
if (status.compass === 'granted') {
// Can now use compass
}
watchAccuracy()
나침반 정확도 모니터링을 시작합니다. Android에서는 자기계 정확도를 모니터링하고 accuracyChange 이벤트를 발생시킵니다. 개발자는 이 이벤트를 수신하여 calibration prompt를 위한 자체 UI를 구현할 수 있습니다. iOS와 Web에서는 나침반 정확도 모니터링을 지원하지 않으므로 아무 동작도 수행하지 않습니다.
import { CapgoCompass, CompassAccuracy } 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
}
});
위 표는 8가지 핵심 메서드를 나열합니다. Listener와 version 헬퍼, 그리고 각 메서드의 전체 명세는 다음 문서에 정리되어 있습니다. GitHub 리포지토리.
이벤트 수신
addListener 핸들을 반환합니다. 호출하세요 handle.remove() 화면이 언마운트될 때, 또는 CapgoCompass.removeAllListeners() 모든 리스너를 해제하려면.
전체 레퍼런스
@capgo/capacitor-compass 사용법 더 알아보기
사용 중이라면 @capgo/capacitor-compass 사용하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-compass @capgo/capacitor-compass의 구현 세부 사항은 시작하기 Getting Started의 구현 상세 내용은 API 개요 구현 세부 사항은 API 개요에서 소개 Introduction의 구현 상세 내용은, 그리고 API 키 API Keys의 구현 상세 내용은