CKTIS / JavaScript
Element.setPointerCapture — przechwytywanie wskaźnika
Metoda setPointerCapture(pointerId) kieruje kolejne zdarzenia danego wskaźnika do wybranego elementu, nawet po opuszczeniu jego granic. Ułatwia obsługę przeciągania myszą, dotykiem lub piórem.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
element.setPointerCapture(pointerId)Element.setPointerCapture wywołuje się na elemencie, zwykle w obsłudze pointerdown, przekazując event.pointerId. Przechwycenie zastępuje normalny wybór celu na podstawie położenia wskaźnika, dzięki czemu element nadal odbiera np. pointermove poza swoimi granicami. Metoda zwraca undefined; nie przesuwa ani nie blokuje kursora.
Wywołanie ustawia oczekujące przechwycenie: hasPointerCapture(pointerId) może od razu zwrócić true, jeszcze przed gotpointercapture. releasePointerCapture(pointerId) zwalnia je jawnie; po pointerup lub pointercancel przeglądarka zwalnia je automatycznie. Zdarzenie lostpointercapture służy do sprzątania stanu interakcji. Dotyk może już mieć przechwycenie niejawne.
Identyfikator, który nie odpowiada żadnemu aktywnemu wskaźnikowi, powoduje NotFoundError. Odłączony element lub aktywny Pointer Lock w jego dokumencie powoduje InvalidStateError. Dopiero po pomyślnym sprawdzeniu identyfikatora, podłączenia elementu i stanu Pointer Lock metoda sprawdza pozostałe warunki: jeśli nie ma ani wciśniętego przycisku, ani kontaktu lub jeśli dokument elementu nie jest aktywnym dokumentem wskaźnika, metoda nie ustawia przechwycenia i nie zgłasza błędu.
Przechwycenie nie wyłącza przewijania ani powiększania dotykiem; przykład używa touch-action: none tylko na obszarze demonstracyjnym. To API przeglądarki opisane w Pointer Events, nie funkcja określonej edycji ECMAScript. Obecność Node 24 nie dowodzi jego dostępności: sprawdzaj metodę i testuj docelowe przeglądarki.
Przykłady
const pad = document.createElement('div');
pad.textContent = 'Press, move outside, release';
pad.style.cssText = 'width:220px;height:100px;background:lightblue;touch-action:none;user-select:none';
const log = document.createElement('pre');
document.body.append(pad, log);
if (typeof pad.setPointerCapture !== 'function') {
log.textContent = 'unsupported';
} else {
let activeId = null;
pad.addEventListener('pointerdown', (event) => {
if (activeId !== null) return;
pad.setPointerCapture(event.pointerId);
activeId = event.pointerId;
log.textContent = `pending: ${pad.hasPointerCapture(activeId)}`;
});
pad.addEventListener('pointermove', (event) => {
if (event.pointerId === activeId) {
log.textContent = 'moving';
}
});
pad.addEventListener('lostpointercapture', (event) => {
if (event.pointerId === activeId) {
activeId = null;
log.textContent = 'released';
}
});
}Wynik
released
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.