База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

Element.setPointerCapture — прихващане на показалец

Методът setPointerCapture(pointerId) насочва следващите събития от даден показалец към избран елемент, дори когато показалецът напусне границите му. Това улеснява плъзгането с мишка, докосване или писалка.

Версия: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Синтаксис

element.setPointerCapture(pointerId)

Извикайте Element.setPointerCapture върху елемент, обикновено в обработчик pointerdown, като подадете event.pointerId. Прихващането заменя обичайния избор на цел според позицията, така че елементът продължава да получава например събития pointermove и извън границите си. Методът връща undefined; не премества и не заключва курсора.

Извикването задава чакащо прихващане: hasPointerCapture(pointerId) може веднага да върне true, преди събитието gotpointercapture. releasePointerCapture(pointerId) освобождава прихващането изрично; след pointerup или pointercancel браузърът го освобождава автоматично. Използвайте lostpointercapture, за да изчистите състоянието на взаимодействието. При въвеждане с докосване може вече да има неявно прихващане.

Идентификатор, който не съответства на активен показалец, причинява NotFoundError. Несвързан елемент или активен Pointer Lock в неговия документ причинява InvalidStateError. Едва след успешна проверка на идентификатора на показалеца, свързаността на елемента и състоянието на Pointer Lock методът проверява останалите условия: ако няма нито натиснат бутон, нито контакт или ако документът на елемента не е активният документ на показалеца, методът не задава прихващане и не предизвиква грешка.

Прихващането не изключва превъртането или увеличаването чрез докосване; примерът използва touch-action: none само в демонстрационната област. Това е браузърен API, описан в Pointer Events, а не функция на конкретно издание на ECMAScript. Наличието на Node 24 не доказва, че API е достъпен: проверете метода и тествайте целевите браузъри.

Примери

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';
    }
  });
}

Резултат

released

Показаният код и заявеният резултат са проверени в изолирана среда по метода, записан в доказателството за проверка на тази точна версия.

Източници