網頁適用的 Permissions API

Matt Gaunt

如果您曾使用過 Geolocation API,那麼您可能會想確認自己是否有權使用 Geolocation,且不會出現提示。這根本不可能。您必須要求目前的位置,這會指出權限狀態,或向使用者顯示提示。

但並非所有 API 都以這種方式運作。Notifications API 有自己的方式,可讓您透過 Notification.permission 檢查目前的權限狀態。

隨著網路平台的 API 數量增加,開發人員需要有單一標準方式來檢查權限狀態,而不需要記住每個 API 的運作方式。Permission API 可在 Chrome 43 版中使用,這是檢查 API 權限狀態的唯一標準方式。

permissions.query()

使用 permissions.query() 方法查看權限狀態。這會傳回狀態,可能是已授予 (您有權限)、已拒絕 (您無法存取 API) 或提示 (需要向使用者顯示提示)。例如:

// Check for Geolocation API permissions
navigator.permissions.query({name:'geolocation'})
    .then(function(permissionStatus) {
    console.log('geolocation permission state is ', permissionStatus.state);

    permissionStatus.onchange = function() {
        console.log('geolocation permission state has changed to ', this.state);
    };
    });

查詢方法會採用 PermissionDescriptor 物件,您可以在其中定義權限名稱。回應是解析為 PermissionStatus 物件的承諾。您可以透過這個物件,使用 permissionStatus.state 檢查狀態是否為「已授予」、「已拒絕」或「提示」。您也可以為 permissionStatus.onchange 實作事件處理常式,並處理權限狀態的變更。

支援的 PermissionDescriptor

在上述範例中,我們會強調如何使用以下權限描述項 {name:'geolocation'} 查詢地理位置權限狀態。

通知權限描述元件與之類似,只需要名稱屬性:{name:'notifications'}

Pushmidi 各自都有專屬於該 API 的額外參數。

針對推播權限,您可以提供 userVisibleOnly 參數。這會指出您是否希望為每則推播訊息顯示通知,或是能夠傳送靜默推播通知 (目前 Chrome 僅支援含有通知的推播訊息)。使用方式如下:

navigator.permissions.query({name:'push', userVisibleOnly:true})

Midi 允許使用 sysex 參數。這會指出您是否需要和/或接收系統專屬訊息。對於 MIDI,這會是:

navigator.permissions.query({name:'midi', sysex:true})

要求權限

向使用者要求權限的方式取決於特定 API。舉例來說,當您呼叫 getCurrentPosition() 時,地理位置會顯示權限提示。

navigator.geolocation.getCurrentPosition(function(position) {
    console.log('Geolocation permissions granted');
    console.log('Latitude:' + position.coords.latitude);
    console.log('Longitude:' + position.coords.longitude);
});

而通知會在您呼叫 requestPermission() 時提示使用者。

Notification.requestPermission(function(result) {
    if (result === 'denied') {
    console.log('Permission wasn\'t granted. Allow a retry.');
    return;
    } else if (result === 'default') {
    console.log('The permission request was dismissed.');
    return;
    }
    console.log('Permission was granted for notifications');
});

重點在於,Permission API 可讓您以一致的方式監控權限狀態,同時支援目前網站上的各種 API。

這樣做的一大優點是,您可以為使用者打造更優質的體驗,只在使用者清楚瞭解您為何需要額外特權時才顯示提示,並在您知道已獲得授權時充分利用這些 API。

您可以在這裡找到完整的範例

瀏覽器支援

Chrome 是第一個實作這項功能的瀏覽器,Mozilla 也打算推出這項功能,而 Microsoft 也對 API 表示出興趣。

已知問題

  • 如果使用者關閉權限要求,地理位置就不會再次顯示提示。不過,權限狀態仍為「提示」。[bugs.chromium.org]