Compass - PhoneGap 中文文档

返回介绍

Compass

发布于 2019-07-04 字数 12917 浏览 803 评论 0

Compass

Obtains the direction that the device is pointing.

Methods

  • compass.getCurrentHeading
  • compass.watchHeading
  • compass.clearWatch
  • compass.watchHeadingFilter (obsolete)
  • compass.clearWatchFilter (obsolete)

Arguments

  • compassSuccess
  • compassError
  • compassOptions
  • compassHeading

Permissions

Android

app/res/xml/config.xml

<plugin name="Compass" value="org.apache.cordova.CompassListener" />

BlackBerry WebWorks

No permissions are required.

iOS

config.xml

<plugin name="Compass" value="CDVLocation" />

Windows Phone

Properties/WPAppManifest.xml

<Capabilities>
    <Capability Name="ID_CAP_SENSORS" />
</Capabilities>

Reference: Application Manifest for Windows Phone

Tizen

No permissions are required.

compass.getCurrentHeading

Get the current compass heading.

navigator.compass.getCurrentHeading(compassSuccess, compassError, compassOptions);

Description

The compass is a sensor that detects the direction or heading that the
device is pointed, typically from the top of the device. It measures
the heading in degrees from 0 to 359.99, where 0 is north.

The compass heading information is returned via a CompassHeading
object using the compassSuccess callback function.

Supported Platforms

  • Android
  • iOS
  • Tizen
  • Windows Phone 7 and 8 ( if available in hardware )
  • Windows 8

Quick Example

function onSuccess(heading) {
    alert('Heading: ' + heading.magneticHeading);
};
function onError(error) {
    alert('CompassError: ' + error.code);
};
navigator.compass.getCurrentHeading(onSuccess, onError);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Compass Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">
    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);
    // device APIs are available
    //
    function onDeviceReady() {
navigator.compass.getCurrentHeading(onSuccess, onError);
    }
    // onSuccess: Get the current heading
    //
    function onSuccess(heading) {
alert('Heading: ' + heading.magneticHeading);
    }
    // onError: Failed to get the heading
    //
    function onError(compassError) {
alert('Compass Error: ' + compassError.code);
    }
    </script>
  </head>
  <body>
    <h2>Example</h2>
    <p>getCurrentHeading</p>
  </body>
</html>

compass.watchHeading

At a regular interval, get the compass heading in degrees.

var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);

Description

The compass is a sensor that detects the direction or heading that the
device is pointed. It measures the heading in degrees from 0 to
359.99.

The compass.watchHeading gets the device’s current heading at a
regular interval. Each time the heading is retrieved, the
headingSuccess callback function is executed. Specify the interval
in milliseconds via the frequency parameter in the compassOptions
object.

The returned watch ID references the compass watch interval. The watch
ID can be used with compass.clearWatch to stop watching the compass.

Supported Platforms

  • Android
  • iOS
  • Tizen
  • Windows Phone 7 and 8 (if available in hardware)
  • Windows 8

Quick Example

function onSuccess(heading) {
    var element = document.getElementById('heading');
    element.innerHTML = 'Heading: ' + heading.magneticHeading;
};
function onError(compassError) {
    alert('Compass error: ' + compassError.code);
};
var options = {
    frequency: 3000
}; // Update every 3 seconds
var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Compass Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">
    // The watch id references the current `watchHeading`
    var watchID = null;
    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);
    // device APIs are available
    //
    function onDeviceReady() {
startWatch();
    }
    // Start watching the compass
    //
    function startWatch() {
// Update compass every 3 seconds
var options = { frequency: 3000 };
watchID = navigator.compass.watchHeading(onSuccess, onError, options);
    }
    // Stop watching the compass
    //
    function stopWatch() {
if (watchID) {
navigator.compass.clearWatch(watchID);
watchID = null;
}
    }
    // onSuccess: Get the current heading
    //
    function onSuccess(heading) {
var element = document.getElementById('heading');
element.innerHTML = 'Heading: ' + heading.magneticHeading;
    }
    // onError: Failed to get the heading
    //
    function onError(compassError) {
alert('Compass error: ' + compassError.code);
    }
    </script>
  </head>
  <body>
    <div id="heading">Waiting for heading...</div>
    <button onclick="startWatch();">Start Watching</button>
    <button onclick="stopWatch();">Stop Watching</button>
  </body>
</html>

iOS Quirks

In iOS compass.watchHeading can also get the device’s current
heading when it changes by a specified number of degrees. Each time
the heading changes by the specified number of degrees or more, the
headingSuccess callback function executes. Specify the degrees of
change via the filter parameter in the compassOptions object.
Clear the watch as usual by passing the returned watch ID to
compass.clearWatch. This functionality replaces the previously
separate, iOS-only watchHeadingFilter and clearWatchFilter
functions, which were removed in version 1.6.

Only one watchHeading can be in effect at one time in iOS. If a
watchHeading uses a filter, calling getCurrentHeading or
watchHeading uses the existing filter value to specify heading
changes. Watching heading changes with a filter is more efficient than
with time intervals.


compass.clearWatch

Stop watching the compass referenced by the watch ID parameter.

navigator.compass.clearWatch(watchID);
  • watchID: The ID returned by compass.watchHeading.

Supported Platforms

  • Android
  • iOS
  • Tizen
  • Windows Phone 7 and 8 ( if available in hardware )
  • Windows 8

Quick Example

var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
// ... later on ...
navigator.compass.clearWatch(watchID);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Compass Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">
    // The watch id references the current `watchHeading`
    var watchID = null;
    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);
    // device APIs are available
    //
    function onDeviceReady() {
startWatch();
    }
    // Start watching the compass
    //
    function startWatch() {
// Update compass every 3 seconds
var options = { frequency: 3000 };
watchID = navigator.compass.watchHeading(onSuccess, onError, options);
    }
    // Stop watching the compass
    //
    function stopWatch() {
if (watchID) {
navigator.compass.clearWatch(watchID);
watchID = null;
}
    }
    // onSuccess: Get the current heading
    //
    function onSuccess(heading) {
var element = document.getElementById('heading');
element.innerHTML = 'Heading: ' + heading.magneticHeading;
    }
    // onError: Failed to get the heading
    //
    function onError(compassError) {
alert('Compass error: ' + compassError.code);
    }
    </script>
  </head>
  <body>
    <div id="heading">Waiting for heading...</div>
    <button onclick="startWatch();">Start Watching</button>
    <button onclick="stopWatch();">Stop Watching</button>
  </body>
</html>

compass.watchHeadingFilter

No longer supported as of 1.6, see compass.watchHeading for equivalent functionality.


compass.clearWatchFilter

No longer supported as of 1.6. See compass.clearWatch.


compassSuccess

onSuccess callback function that provides the compass heading information via a compassHeading object.

function(heading) {
    // Do something
}

Parameters

  • heading: The heading information. (compassHeading)

Example

function onSuccess(heading) {
    alert('Heading: ' + heading.magneticHeading);
};

compassError

onError callback function for compass functions.

Example

function(CompassError) {
    // Handle the error
}

compassOptions

An optional parameter to customize the retrieval of the compass.

Options

  • frequency: How often to retrieve the compass heading in milliseconds. (Number) (Default: 100)
  • filter: The change in degrees required to initiate a watchHeading success callback. (Number)

Android Quirks


  • filter is not supported.

Tizen Quirks

  • filter is not supported.

Windows Phone 7 and 8 Quirks

  • filter is not supported.

compassHeading

A CompassHeading object is returned to the compassSuccess callback function.

Properties

  • magneticHeading: The heading in degrees from 0 – 359.99 at a single moment in time. (Number)
  • trueHeading: The heading relative to the geographic North Pole in degrees 0 – 359.99 at a single moment in time. A negative value indicates that the true heading cannot be determined. (Number)
  • headingAccuracy: The deviation in degrees between the reported heading and the true heading. (Number)
  • timestamp: The time at which this heading was determined. (milliseconds)

Description

The CompassHeading object is returned to the compassSuccess callback function.

Android Quirks

  • trueHeading is not supported, but reports the same value as magneticHeading
  • headingAccuracy is always 0 because there is no difference between the magneticHeading and trueHeading.

iOS Quirks

  • trueHeading is only returned when location services are enabled via navigator.geolocation.watchLocation()
  • For iOS 4 devices and above, heading factors in the device’s current orientation, not in reference to its absolute position, for apps that supports that orientation.

CompassError

A CompassError object is returned to the compassError callback function when an error occurs.

Properties

  • code: One of the predefined error codes listed below.

Constants

  • CompassError.COMPASS_INTERNAL_ERR
  • CompassError.COMPASS_NOT_SUPPORTED

Description

When an error occurs, the CompassError object is passed as a
parameter to a compassError callback function.

上一篇:Capture

下一篇:Connection

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!