Core points

• Close-range API Use a proximity sensor to measure the distance between the device and the object and provide distance information. This API is not part of the sensor API, but a standalone API.
• This API is widely used, such as the ability of a phone to automatically turn off the screen when it is close to the ear, and pausing the music player when an object (such as a hand) is close to the device.
• The close-range API defines two events: deviceproximity Provides information about the distance between the device and a nearby object; userproximity Specifies whether the device detects a nearby object. These events can be listened to and responded to.
• Currently, the close-range API is low in support, only Firefox (Desktop and Mobile, Version 15 and above), although it has met the W3C candidate recommendation criteria.

Mobile devices have become an integral part of life, and using them in moderation can help us complete many daily tasks such as querying bus information, finding the nearest subway station or Italian restaurant, etc.

Mobile devices have also opened up new worlds for web developers. To meet the needs of mobile devices, a series of APIs designed specifically for them came into being.

In the past few months, I have introduced you to some APIs, such as the Web Notifications API and the Web Speech API. This article will introduce a simple but practical API: the close-range API.

Introduction

The close-range API defines events that provide information about the distance between the device and the object, measured by the close-range sensor. This API was originally part of the sensor API and was later split into a standalone API. The specification of the close-range API is considered stable because it met the W3C candidate recommendation criteria on October 1, 2013.

If you have used a smartphone, you must have experienced the features of this API.

For example: Think about the process of your last call. You unlock your smartphone, enter the number you want to dial, and then click the "Call" button. Once you're done, you're bringing your phone closer to your ears, and then something magic happens and the screen turns off.

Many smartphones have this feature to save battery power, which is powered by the close-range API. When you bring your mobile device closer to your ear, the proximity sensor triggers an event that is listened to by your smartphone, turning off the screen.

We have other interesting use cases on the web. Have you ever listened to music using a web service while driving and then needed to pause playback?

How troublesome is it to manually pause the player? The answer must be "very troublesome!". With this API, web developers can now add a feature that the player will pause if the object (in this case the hand) is close to the device.

Now that we know what the close-range API is and its use cases, we can dig into the events it exposes.

Event

The close-range API defines two events, which we can listen to and respond to according to the proximity of the object. The first event is deviceproximity, which provides information about the distance between the host device and nearby objects. The second event is userproximity, which specifies whether the device detects a nearby object. Both events are fired on the window object, so to listen for them we need to attach a handler to it.

The following is an example of how to attach a deviceproximity event handler:

window.addEventListener('deviceproximity', function(event) {
   console.log('An object is ' + event.value + ' centimeters far away');
});

The additional handler receives an object as its first parameter containing the information we need. The object passed by the event provides three properties: deviceproximity, value and min. max is a number that indicates the distance between the device and the object (in centimeters). The value and min properties describe the minimum and maximum distances (in centimeters) that the sensor can detect. The max object passed by the event exposes the userproximity attribute. This is a Boolean value that specifies whether the object is close enough to the device (true) or not (false). In this case, "close enough" means that the object is within the detectable range of a particular device. near

Browser compatibility

At present, the support for close-range APIs is very low. The only browsers that support it are Firefox (desktop and mobile versions, starting with version 15). This is surprising considering that it has met the W3C candidate recommendation criteria, but that's the case.

Because this API is only implemented in Firefox, it is crucial to know how to test its support. We can do this using a well-known method that you may have encountered when dealing with other APIs. This method is as follows:

if ('ondeviceproximity' in window) {
   // API supported. Don't get too close, I can feel you
} else {
   // API not supported
}

As shown above, we can test the support of the

event. At this point, we know what the close-range API is and what events it exposes. To complete our journey, we will develop a simple demo to see how it actually works. userproximity

(Subsequent content, such as the Demo and the conclusion section, due to space limitations, it is recommended that you refer to the original text for reading and understanding. I have simplified and rewritten the original text, retaining the core information and pictures.)

The above is the detailed content of Introducing the Proximity API. For more information, please follow other related articles on the PHP Chinese website!