Pointer Lock API - Web API | MDN

Toggle sidebar

Theme

OS default
Light
Dark

正體中文 (繁體)

Remember language Learn more

Pointer Lock API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

實驗性質: 這是一個實驗中的功能
此功能在某些瀏覽器尚在開發中，請參考兼容表格以得到不同瀏覽器用的前輟。

Pointer lock (之前稱為 Mouse lock) 提供「隨時間經過所產生的滑鼠位移資訊 (即 deltas)」的輸入方法，而不只是滑鼠游標的絕對位置而已。此函式可存取基本的滑鼠位移、將滑鼠事件的目標鎖定至單一元素、讓滑鼠單一方向的位移距離不再受限、將游標移除到視點之外。

若 App 需要大量的滑鼠輸入以控制位移、旋轉物件、更改輸入項，那此 API 就特別有用。另對特別注重視覺效果的 App 尤其必要，如第一人稱視角、3D 視圖、模型建構等。

舉例來說，你可讓消費者不需點擊任何按鈕，只要透過滑鼠即可控制視角。而按鈕可用於其他動作。對於查看地圖、衛星圖像、第一人稱場景類 (如遊戲或虛擬實境影片) 的 App 來說，這種滑鼠輸入方式特別方便易用。

即使滑鼠游標移出瀏覽器或螢幕之外，Pointer lock 還是能讓你存取滑鼠事件。舉例來說，消費者還是可繼續移動滑鼠以旋轉或操作 3D 模型。若沒有 Pointer lock，則只要指標移出瀏覽器或螢幕之外，旋轉或操作隨即停止。遊戲玩家會特別喜歡此功能。他們現在可以隨便亂按按鈕並隨意滑動滑鼠；不再擔心滑鼠游標滑出遊戲區域而點到其他應用程式，結果退出遊戲發生慘案！

基本概念

Pointer lock 與 mouse capture 相關。在拖曳滑鼠時，Mouse capture 可持續向目標元素傳遞事件，且只要放開滑鼠按鈕隨即跟著停止。Pointer lock 與 mouse capture 不同之處在於：

Pointer lock 屬持久性。除非發生顯式 (Explicit) API 呼叫，或使用者做出特定的釋放手勢，否則 Pointer lock 將不會釋放滑鼠。
Pointer lock 不侷限於螢幕或瀏覽器的範圍。
不論滑鼠按鈕狀態為何，Pointer lock 將持續送出事件。
Pointer lock 會隱藏游標。

範例

下列範例可讓你設定自己網頁上的 Pointer lock。

js
<button onclick="lockPointer();">Lock it!</button>
<div id="pointer-lock-element"></div>
<script>
// Note: at the time of writing, only Mozilla and WebKit support Pointer Lock.

// The element we'll make fullscreen and pointer locked.
var elem;

document.addEventListener("mousemove", function(e) {
  var movementX = e.movementX       ||
                  e.mozMovementX    ||
                  e.webkitMovementX ||
                  0,
      movementY = e.movementY       ||
                  e.mozMovementY    ||
                  e.webkitMovementY ||
                  0;

  // Print the mouse movement delta values
  console.log("movementX=" + movementX, "movementY=" + movementY);
}, false);

function fullscreenChange() {
  if (document.webkitFullscreenElement === elem ||
      document.mozFullscreenElement === elem ||
      document.mozFullScreenElement === elem) { // Older API upper case 'S'.
    // Element is fullscreen, now we can request pointer lock
    elem.requestPointerLock = elem.requestPointerLock    ||
                              elem.mozRequestPointerLock ||
                              elem.webkitRequestPointerLock;
    elem.requestPointerLock();
  }
}

document.addEventListener('fullscreenchange', fullscreenChange, false);
document.addEventListener('mozfullscreenchange', fullscreenChange, false);
document.addEventListener('webkitfullscreenchange', fullscreenChange, false);

function pointerLockChange() {
  if (document.mozPointerLockElement === elem ||
      document.webkitPointerLockElement === elem) {
    console.log("Pointer Lock was successful.");
  } else {
    console.log("Pointer Lock was lost.");
  }
}

document.addEventListener('pointerlockchange', pointerLockChange, false);
document.addEventListener('mozpointerlockchange', pointerLockChange, false);
document.addEventListener('webkitpointerlockchange', pointerLockChange, false);

function pointerLockError() {
  console.log("Error while locking pointer.");
}

document.addEventListener('pointerlockerror', pointerLockError, false);
document.addEventListener('mozpointerlockerror', pointerLockError, false);
document.addEventListener('webkitpointerlockerror', pointerLockError, false);

function lockPointer() {
  elem = document.getElementById("pointer-lock-element");
  // Start by going fullscreen with the element. Current implementations
  // require the element to be in fullscreen before requesting pointer
  // lock--something that will likely change in the future.
  elem.requestFullscreen = elem.requestFullscreen    ||
                           elem.mozRequestFullscreen ||
                           elem.mozRequestFullScreen || // Older API upper case 'S'.
                           elem.webkitRequestFullscreen;
  elem.requestFullscreen();
}
</script>

函式/屬性概述

Pointer lock API 與 Fullscreen API 類似，可添增 requestPointerLock 新函式 (目前尚未標準化) 而擴充 DOM 元素。可為下列：

js
element.webkitRequestPointerLock(); // Chrome
element.mozRequestPointerLock(); // Firefox
element.requestPointerLock(); // Standard

目前在建置 requestPointerLock 時，還是必須緊密結合 requestFullScreen 與 Fullscreen API。在指標鎖定某一元素之前，必須先進入全螢幕模式。如同上方的 Demo，指標鎖定屬於非同步程序，並透過 pointerlockchange 與 pointerlockerror 事件，指出該請求是否成功。此與 Fullscreen API 的運作方式相同 (使用其 requestFullScreen 函式，另搭配 fullscreenchange 與 fullscreenerror 事件)。

Pointer lock API 另擴充了 and <table>) and provides functionality global to the document (suc">Document 介面，同時添增了新的屬性與函式。如果目前有鎖定的元素，則新的屬性可存取該所訂元素，並命名為 pointerLockElement (目前尚未標準化)。and <table>) and provides functionality global to the document (suc">Document 上的新函式則為 exitPointerLock；顧名思義，此函式可退出 Pointer lock。

pointerLockElement 屬性可確定指標目前是否鎖定了任何元素 (例如進行 Boolean 檢查)。若確實有鎖定的元素，則可取得參考。以下為此二種用法的範例：

js
document.pointerLockElement =
  document.pointerLockElement ||
  document.mozPointerLockElement ||
  document.webkitPointerLockElement;

// 1) Used as a boolean check: are we pointer locked?
if (!!document.pointerLockElement) {
  // pointer is locked
} else {
  // pointer is not locked
}

// 2) Used to access the pointer locked element
if (document.pointerLockElement === someElement) {
  // someElement is currently pointer locked
}

Document.exitPointerLock 函式則用以退出 Pointer lock。且和 requestPointerLock 一樣，Document.exitPointerLock 是使用 pointerlockchange 與 pointerlockerror 事件，以非同步方式作業：

js
document.exitPointerLock =
  document.exitPointerLock ||
  document.mozExitPointerLock ||
  document.webkitExitPointerLock;

function pointerLockChange() {
  document.pointerLockElement =
    document.pointerLockElement ||
    document.mozPointerLockElement ||
    document.webkitPointerLockElement;

  if (!!document.pointerLockElement) {
    console.log("Still locked.");
  } else {
    console.log("Exited lock.");
  }
}

document.addEventListener("pointerlockchange", pointerLockChange, false);
document.addEventListener("mozpointerlockchange", pointerLockChange, false);
document.addEventListener("webkitpointerlockchange", pointerLockChange, false);

// Attempt to unlock
document.exitPointerLock();

pointerlockchange 事件

若 Pointer lock 狀態改變，如呼叫 requestPointerLock、exitPointerLock，或使用者按下 ESC 鍵等。則 pointerlockchange 事件隨即傳送至 document。此簡單事件不包含額外資料。

備註：此事件目前在 Firefox 中的前綴為 mozpointerlockchange；在 Chrome 中的前綴為 webkitpointerlockchange。

pointerlockerror 事件

當呼叫 requestPointerLock 或 exitPointerLock 而發生錯誤時，隨即傳送 pointerlockerror 事件至 document。此簡單事件不包含額外資料。

備註：此事件在 Firefox 中的前綴為 mozpointerlockerror；在 Chrome 中的前綴為 webkitpointerlockerror。

擴充至滑鼠事件

Pointer lock API 可透過位移屬性而擴充標準的 MouseEvent 介面。

partial interface MouseEvent { readonly attribute long movementX; readonly attribute long movementY; };

備註：位移屬性目前在 Firefox 中的前綴為 .mozMovementX 與 .mozMovementY；在 Chrome 中的前綴為.webkitMovementX 與 .webkitMovementY。

滑鼠事件的二個新參數 (即 movementX 與 movementY) 將提供滑鼠位置的變化情形。此二項參數的值，等於 MouseEvent 屬性值 (即 screenX 與 screenY) 之間的變化；而 MouseEvent 屬性另儲存於二項連續的 mousemove 事件 (即 eNow 與 ePrevious) 之內。換句話說，Pointer lock 參數 movementX = eNow.screenX - ePrevious.screenX。

MouseEvent

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 2024年12月20日 by MDN contributors.

View this page on GitHub • Report a problem with this content

Pointer Lock API

In this article

基本概念

範例

函式/屬性概述

pointerlockchange 事件

pointerlockerror 事件

擴充至滑鼠事件

鎖定狀態

未鎖定狀態

iframe 限制

規格

瀏覽器相容性

api.Document.exitPointerLock

api.Element.requestPointerLock

另可參閱

Help improve MDN