1. Web
  2. HTTP
  3. 參考
  4. 標頭
  5. Permissions-Policy

Permissions-Policy 頭

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

HTTP Permissions-Policy 響應頭提供了一種機制，用於允許和拒絕在文件或文件中的任何 <iframe> 元素中使用瀏覽器功能。

有關更多資訊，請參閱主要 許可權策略 文章。

頭型別 響應頭
禁止請求頭 是

語法

http
Permissions-Policy: <directive>=<allowlist>
<directive>

要應用 allowlist 的許可權策略指令。請參閱下面的指令，瞭解允許的指令名稱列表。

<allowlist>

允許列表是一個源列表，它包含以下一個或多個用括號括起來的值，並用空格分隔

* (萬用字元)

此功能將在當前文件和所有巢狀的瀏覽上下文（<iframe>）中被允許，無論其來源如何。

() (空允許列表)

此功能在頂級和巢狀瀏覽上下文中被停用。對於 <iframe> 的 allow 屬性，其等效值為 'none'。

self

此功能將在此文件和所有同源的巢狀瀏覽上下文（<iframe>）中被允許。此功能不允許在巢狀瀏覽上下文中的跨源文件中使用。self 可視為 https://your-site.example.com 的簡寫。對於 <iframe> 的 allow 屬性，其等效值為 self。

src

此功能將在該 <iframe> 中被允許，只要載入到其中的文件源自其 src 屬性中的 URL 的相同源。此值僅在 <iframe> 的 allow 屬性中使用，並且是 <iframe> 中 allowlist 的預設值。

"<origin>"

特定來源（例如，"https://a.example.com"）允許使用該功能。來源應以空格分隔。請注意，<iframe> 允許屬性中的來源不帶引號。

值 * 和 () 只能單獨使用，而 self 和 src 可以與一個或多個來源組合使用。

注意：指令有一個預設的允許列表，對於 Permissions-Policy HTTP 頭，它始終是 *、self 或 none 之一，並控制如果未在策略中明確列出時的預設行為。這些在各個指令參考頁面中指定。對於 <iframe> 的 allow 屬性，預設行為始終是 src。

在支援的情況下，你可以在許可權策略源中包含萬用字元。這意味著，你無需在允許列表中顯式指定幾個不同的子域，而是可以透過一個帶有萬用字元的源來指定它們。

所以，不是

http
("https://example.com" "https://a.example.com" "https://b.example.com" "https://c.example.com")

你可以指定

http
("https://example.com" "https://*.example.com")

注意： "https://*.example.com" 不匹配 "https://example.com"。

指令

accelerometer

控制當前文件是否允許透過 Accelerometer 介面收集裝置加速度資訊。

ambient-light-sensor

控制當前文件是否允許透過 AmbientLightSensor 介面收集裝置周圍環境光照資訊。

aria-notify

控制當前文件是否允許使用 ariaNotify() 方法觸發 螢幕閱讀器 公告。

attribution-reporting

控制當前文件是否允許使用 Attribution Reporting API。

autoplay

控制當前文件是否允許透過 HTMLMediaElement 介面請求自動播放媒體。當此策略被停用且沒有使用者手勢時，HTMLMediaElement.play() 返回的 Promise 將以 NotAllowedError DOMException 拒絕。 <audio> 和 <video> 元素上的 autoplay 屬性將被忽略。

bluetooth

控制是否允許使用 Web 藍牙 API。當此策略被停用時，Navigator.bluetooth 返回的 Bluetooth 物件的方法將返回 false 或以 SecurityError DOMException 拒絕返回的 Promise。

browsing-topics

控制對 Topics API 的訪問。如果策略明確禁止使用 Topics API，則任何呼叫 Document.browsingTopics() 方法或傳送帶有 Sec-Browsing-Topics 頭的請求都將以 NotAllowedError DOMException 失敗。

camera

控制當前文件是否允許使用影片輸入裝置。如果未允許許可權，則 getUserMedia() 返回的 Promise 將以 NotAllowedError DOMException 拒絕。

captured-surface-control

控制文件是否允許使用 捕獲表面控制 API。如果未允許許可權，API 主要方法返回的 Promise 將以 NotAllowedError DOMException 拒絕。

compute-pressure

控制對 計算壓力 API 的訪問。

cross-origin-isolated

控制當前文件是否可以被視為 跨源隔離。

deferred-fetch

控制頂級源的 fetchLater() 配額的分配。

deferred-fetch-minimal

控制共享的跨源子幀 fetchLater() 配額的分配。

display-capture

控制當前文件是否允許使用 getDisplayMedia() 方法捕獲螢幕內容。當此策略被停用時，如果未獲得捕獲顯示內容許可權，getDisplayMedia() 返回的 Promise 將以 NotAllowedError DOMException 拒絕。

encrypted-media

控制當前文件是否允許使用 加密媒體擴充套件 API (EME)。當此策略被停用時，Navigator.requestMediaKeySystemAccess() 返回的 Promise 將以 SecurityError DOMException 拒絕。

fullscreen

控制當前文件是否允許使用 Element.requestFullscreen()。當此策略被停用時，返回的 Promise 將以 TypeError 拒絕。

gamepad

控制當前文件是否允許使用 遊戲手柄 API。當此策略被停用時，呼叫 Navigator.getGamepads() 將丟擲 SecurityError DOMException，並且 gamepadconnected 和 gamepaddisconnected 事件將不會觸發。

geolocation

控制當前文件是否允許使用 Geolocation 介面。當此策略被停用時，呼叫 getCurrentPosition() 和 watchPosition() 將導致這些函式的콜back函式以 PERMISSION_DENIED 的 GeolocationPositionError 錯誤碼被呼叫。

gyroscope

控制當前文件是否允許透過 Gyroscope 介面收集裝置的姿態資訊。

hid

控制當前文件是否允許使用 WebHID API 連線到不常見或特殊的等人機介面裝置，例如替代鍵盤或遊戲手柄。

identity-credentials-get

控制當前文件是否允許使用 聯邦憑證管理 API (FedCM)。

idle-detection

控制當前文件是否允許使用 空閒檢測 API 來檢測使用者何時與他們的裝置互動，例如在聊天應用程式中報告“線上”/“離開”狀態。

language-detector

控制對 翻譯器和語言檢測器 API 的語言檢測功能的訪問。

local-fonts

控制當前文件是否允許透過 Window.queryLocalFonts() 方法收集使用者本地安裝的字型資料（另請參閱 本地字型訪問 API）。

magnetometer

控制當前文件是否允許透過 Magnetometer 介面收集裝置的姿態資訊。

microphone

控制當前文件是否允許使用音訊輸入裝置。當此策略被停用時，MediaDevices.getUserMedia() 返回的 Promise 將以 NotAllowedError DOMException 拒絕。

midi

控制當前文件是否允許使用 Web MIDI API。當此策略被停用時，Navigator.requestMIDIAccess() 返回的 Promise 將以 SecurityError DOMException 拒絕。

on-device-speech-recognition

控制對 Web Speech API 的裝置上語音識別功能的訪問。

otp-credentials

控制當前文件是否允許使用 WebOTP API 從應用伺服器傳送的特殊格式簡訊中請求一次性密碼 (OTP)，即透過 navigator.credentials.get({otp: ..., ...})。

payment

控制當前文件是否允許使用 支付請求 API。當此策略啟用時，PaymentRequest() 建構函式將丟擲 SecurityError DOMException。

picture-in-picture

控制當前文件是否允許透過相應的 API 以畫中畫模式播放影片。

publickey-credentials-create

控制當前文件是否允許使用 Web 身份驗證 API 建立新的非對稱金鑰憑證，即透過 navigator.credentials.create({publicKey: ..., ...})。

publickey-credentials-get

控制當前文件是否允許使用 Web 身份驗證 API 檢索已儲存的公鑰憑證，即透過 navigator.credentials.get({publicKey: ..., ...})。

screen-wake-lock

控制當前文件是否允許使用 螢幕喚醒鎖定 API 來指示裝置不應關閉或調暗螢幕。

serial

控制當前文件是否允許使用 Web Serial API 與序列裝置通訊，無論是透過序列埠直接連線，還是透過 USB 或藍牙裝置模擬序列埠。

speaker-selection

控制當前文件是否允許使用 音訊輸出裝置 API 列出並選擇揚聲器。

storage-access

控制在第三方上下文（即嵌入在 <iframe> 中）載入的文件是否允許使用 儲存訪問 API 請求訪問未分割槽 cookie。

translator

控制對 翻譯器和語言檢測器 API 的翻譯功能的訪問。

summarizer

控制對 摘要器 API 的訪問。

usb

控制當前文件是否允許使用 WebUSB API。

web-share

控制當前文件是否允許使用 Web Share API 的 Navigator.share() 方法將文字、連結、影像和其他內容共享到使用者選擇的任意目的地，例如移動應用程式。

window-management

控制當前文件是否允許使用 視窗管理 API 來管理多個顯示器上的視窗。

xr-spatial-tracking

控制當前文件是否允許使用 WebXR Device API 與 WebXR 會話互動。

示例

基本用法

Permissions-Policy 頭

要允許所有來源訪問地理位置，你可以這樣做

http
Permissions-Policy: geolocation=*

或者，要允許訪問部分來源，你可以這樣做

http
Permissions-Policy: geolocation=(self "https://a.example.com" "https://b.example.com")

可以透過傳送帶有逗號分隔的策略列表的頭，或者為每個策略傳送單獨的頭，同時控制多個功能。

例如，以下是等效的

http
Permissions-Policy: picture-in-picture=(), geolocation=(self https://example.com/), camera=*

Permissions-Policy: picture-in-picture=()
Permissions-Policy: geolocation=(self https://example.com/)
Permissions-Policy: camera=*

iframe

要使 <iframe> 啟用某個功能，其允許的來源也必須在父頁面的允許列表中。由於這種繼承行為，最好在 HTTP 頭中指定對某個功能最廣泛的可接受支援，然後在每個 <iframe> 中指定所需的子集支援。

要允許所有來源訪問地理位置，你可以這樣做

html
<iframe src="https://example.com" allow="geolocation *"></iframe>

要將策略應用於當前來源和其他來源，你可以這樣做

html
<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com"></iframe>

這很重要：預設情況下，如果 <iframe> 導航到另一個來源，策略不會應用於 <iframe> 導航到的來源。透過在 allow 屬性中列出 <iframe> 導航到的來源，應用於原始 <iframe> 的許可權策略將應用於 <iframe> 導航到的來源。

可以透過在 allow 屬性中包含以分號分隔的策略指令列表來同時控制多個功能。

html
<iframe
  src="https://example.com"
  allow="geolocation 'self' https://a.example.com https://b.example.com; fullscreen 'none'"></iframe>

值得特別提一下 src 值。我們上面提到，使用此允許列表值意味著只要載入到此 <iframe> 中的文件源自其 src 屬性中的 URL 的相同源，相關功能就將被允許。此值是 allow 中列出的功能的預設 allowlist 值，因此以下是等效的

html
<iframe src="https://example.com" allow="geolocation 'src'">
  <iframe src="https://example.com" allow="geolocation"></iframe
></iframe>

拒絕訪問強大功能

SecureCorp Inc. 希望在其應用程式中停用麥克風（例如 MediaDevices.getUserMedia()）和 Geolocation API。它可以使用以下響應頭來實現：

http
Permissions-Policy: microphone=(), geolocation=()

透過為來源列表指定 ()，無論其來源如何，指定的功能將對所有瀏覽上下文（包括所有 <iframe>）停用。

結合 HTTP 頭和 <iframe> 策略

例如，假設我們希望在自己的源中啟用地理位置使用，並在來自我們信任的廣告網路的嵌入內容中啟用。我們可以像這樣設定頁面範圍的許可權策略：

http
Permissions-Policy: geolocation=(self https://trusted-ad-network.com)

在我們的廣告 <iframe> 中，我們可以這樣設定對 https://trusted-ad-network.com 源的訪問許可權：

html
<iframe src="https://trusted-ad-network.com" allow="geolocation"></iframe>

如果不同的來源最終載入到 <iframe> 中，它將無法訪問地理位置

html
<iframe src="https://rogue-origin-example.com" allow="geolocation"></iframe>

規範

規範
許可權策略
# permissions-policy-http-header-field

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

本頁面最後由 MDN 貢獻者 在 修改。

在 GitHub 上檢視此頁面 • 報告此內容問題
© . Content available under a Creative Commons license.