KeyboardEvent#

new KeyboardEvent()#

Interfejs KeyboardEvent może być wywoływany w roli konstruktora, dzięki czemu pozwala na bezpośrednie tworzenie nowych zdarzeń klawiatury (syntetycznych) wprost z interfejsu. Przy tworzeniu nowego zdarzenia od razu ustalany jest jego typ (pierwszy argument) oraz specyficzne cechy ustawiane za pomocą opcjonalnego słownika KeyboardEventInit (drugi argument).

Składnia#

Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:

var new_keyboardEvent = new KeyboardEvent(type [, keyboardEventInitDict]);

gdzie poszczególne człony oznaczają:

new_keyboardEvent - referencja do nowego zdarzenia.
type - typ zdarzenia w postaci łańcucha znakowego. Może to być dowolny łańcuch znakowy (nawet pusty).
keyboardEventInitDict - opcjonalny obiekt określający szczegółowe kryteria inicjalizacji zdarzenia. Oto dostępne właściwości dla obiektu:
- bubbles - boolowskie true oznacza, że zdarzenie zezwala na obsługę fazy bąbelkowania. Domyślną wartością jest boolowskie false (dziedziczone z EventInit).
- cancelable - boolowskie true oznacza, że domyślne akcje dla zdarzenia mogą zostać anulowane. Domyślną wartością jest boolowskie false (dziedziczone z EventInit).
- view - obiekt okna lub wartość null. Domyślną wartością jest wartość null (dziedziczone z UIEventInit).
- detail - szczegółowe informacje w postaci liczby całkowitej. Domyślną wartością jest 0 (dziedziczone z UIEventInit).
- key - łańcuch znakowy reprezentujący wciśnięty klawisz (po uwzględnieniu wszelkich zmian klawiaturowych). Domyślną wartością jest pusty łańcuch znakowy.
- code - łańcuch znakowy reprezentujący wciśnięty klawisz (bez uwzględnienia wszelkich zmian klawiaturowych). Domyślną wartością jest pusty łańcuch znakowy.
- location - liczba całkowita reprezentująca lokalizację klawisza na urządzeniu wejściowym. Domyślną wartością jest 0.
- altKey - boolowskie true oznacza aktywność klawisza alternatywy w chwili wysłania zdarzenia. Domyślną wartością jest boolowskie false.
- ctrlKey - boolowskie true oznacza aktywność klawisza kontrolnego w chwili wysłania zdarzenia. Domyślną wartością jest boolowskie false.
- metaKey - boolowskie true oznacza aktywność klawisza mety w chwili wysłania zdarzenia. Domyślną wartością jest boolowskie false.
- shiftKey - boolowskie true oznacza aktywność klawisza zmiany w chwili wysłania zdarzenia. Domyślną wartością jest boolowskie false.
- repeat - boolowskie true oznacza, że klawisz dla zdarzenia był wciśnięty w sposób trwały. Domyślną wartością jest boolowskie false.
- isComposing - boolowskie true oznacza, że zdarzenie jest częścią sesji kompozycji. Domyślną wartością jest boolowskie false.
- locale -łańcuch znakowy reprezentujący język z ustawień regionalnych, w którym klawiatura wygenerowała znaki. Domyślną wartością jest pusty łańcuch znakowy.

Algorytm wywołania konstruktora new KeyboardEvent(type, keyboardEventInitDict) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

Zwróć nowe zdarzenie klawiatury za pomocą algorytmu tworzenia zdarzenia z typem type i słownikiem keyboardEventInitDict (jeśli występuje).

Obiekt zwracany przez konstruktor new KeyboardEvent() implementuje interfejs KeyboardEvent, dlatego ma dostęp do wszystkich poleceń z tego interfejsu (oraz z kolejnych interfejsów w łańcuchu dziedziczenia). Warto podkreślić, że i opcjonalny słownik KeyboardEventInit dziedziczy ze słownika UIEventInit, dlatego ma dostęp do wszystkich jego członków w chwili przekazania do konstruktora.

Nowy obiekt zdarzenia będzie miał ustawiane domyślne wartości dla wszystkich swoich właściwości i dodatkowo zostanie automatycznie zainicjowany zgodnie z przekazanymi argumentami przy jego wywołaniu, w przeciwieństwie do polecenia Document.createEvent(), dlatego może być od razu wysłany za pomocą metody EventTarget.dispatchEvent().

W ramach uzupełnienia warto przeanalizować wady i zalety poszczególnych poleceń odpowiedzialnych za tworzenie niezaufanych zdarzeń.

Ze względów bezpieczeństwa zdarzenia generowane przy użyciu konstruktora new KeyboardEvent() muszą ustawiać wartość właściwości Event.isTrusted na boolowskie false.

Prosty przykład:

<script>

	// Tworzymy nowe zdarzenie
	var keyboardEvent1 = new KeyboardEvent("piesek");

	document.write(keyboardEvent1); // [object KeyboardEvent]
	document.write("<br>");
	document.write(keyboardEvent1.type); // piesek
	document.write("<br>");
	document.write(keyboardEvent1.bubbles); // false
	document.write("<br>");
	document.write(keyboardEvent1.cancelable); // false
	document.write("<br>");
	document.write(keyboardEvent1.view); // null
	document.write("<br>");
	document.write(keyboardEvent1.detail); // 0
	document.write("<br>");
	document.write(keyboardEvent1.key); // "" - pusty łańcuch
	document.write("<br>");
	document.write(keyboardEvent1.code); // "" - pusty łańcuch
	document.write("<br>");
	document.write(keyboardEvent1.location); // 0
	document.write("<br>");
	document.write(keyboardEvent1.altKey); // false
	document.write("<br>");
	document.write(keyboardEvent1.ctrlKey); // false
	document.write("<br>");
	document.write(keyboardEvent1.metaKey); // false
	document.write("<br>");
	document.write(keyboardEvent1.shiftKey); // false
	document.write("<br>");
	document.write(keyboardEvent1.repeat); // false
	document.write("<br>");
	document.write(keyboardEvent1.isComposing); // false
	document.write("<br>");
	document.write(keyboardEvent1.locale); // "" - pusty łańcuch
	document.write("<br>");
	document.write(keyboardEvent1.defaultPrevented); // false
	document.write("<br>");
	document.write(keyboardEvent1.isTrusted); // false
	document.write("<br>");
	document.write(keyboardEvent1.eventPhase); // 0
	document.write("<br>");
	document.write(keyboardEvent1.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
	document.write("<br>");
	document.write(keyboardEvent1.currentTarget); // null
	document.write("<br>");
	document.write(keyboardEvent1.target); // null

	document.write("<br><br>");

	// Tworzymy kolejne zdarzenie
	var keyboardEvent2 = new KeyboardEvent("piesek", {
		bubbles: true,
		cancelable: true,
		view: window,
		detail: 69,
		key: "HUSKY",
		code: "husky",
		location: 3,
		altKey: true,
		ctrlKey: true,
		metaKey: true,
		shiftKey: true,
		repeat: true,
		isComposing: true,
		locale: "pl"
	});

	document.write(keyboardEvent2); // [object KeyboardEvent]
	document.write("<br>");
	document.write(keyboardEvent2.type); // piesek
	document.write("<br>");
	document.write(keyboardEvent2.bubbles); // true
	document.write("<br>");
	document.write(keyboardEvent2.cancelable); // true
	document.write("<br>");
	document.write(keyboardEvent2.view); // [object Window]
	document.write("<br>");
	document.write(keyboardEvent2.detail); // 69
	document.write("<br>");
	document.write(keyboardEvent2.key); // HUSKY
	document.write("<br>");
	document.write(keyboardEvent2.code); // husky
	document.write("<br>");
	document.write(keyboardEvent2.location); // 3
	document.write("<br>");
	document.write(keyboardEvent2.altKey); // true
	document.write("<br>");
	document.write(keyboardEvent2.ctrlKey); // true
	document.write("<br>");
	document.write(keyboardEvent2.metaKey); // true
	document.write("<br>");
	document.write(keyboardEvent2.shiftKey); // true
	document.write("<br>");
	document.write(keyboardEvent2.repeat); // true
	document.write("<br>");
	document.write(keyboardEvent2.isComposing); // true
	document.write("<br>");
	document.write(keyboardEvent2.locale); // "pl"
	document.write("<br>");
	document.write(keyboardEvent2.defaultPrevented); // false
	document.write("<br>");
	document.write(keyboardEvent2.isTrusted); // false
	document.write("<br>");
	document.write(keyboardEvent2.eventPhase); // 0
	document.write("<br>");
	document.write(keyboardEvent2.timeStamp); // liczba całkowita z wartością zależną od chwili uruchomienia przykładu
	document.write("<br>");
	document.write(keyboardEvent2.currentTarget); // null
	document.write("<br>");
	document.write(keyboardEvent2.target); // null

</script>

Na chwilę obecną wszystkie aktualne przeglądarki pozwalają na wywoływanie interfejsu KeyboardEvent w roli konstruktora, oczywiście z wyjątkiem IE11.

Interfejs Web IDL#

[Constructor(DOMString typeArg, optional KeyboardEventInit keyboardEventInitDict)]
interface KeyboardEvent : UIEvent {
};

dictionary KeyboardEventInit : UIEventInit {
	DOMString key = "";
	DOMString code = "";
	unsigned long location = 0;
	boolean ctrlKey = false;
	boolean shiftKey = false;
	boolean altKey = false;
	boolean metaKey = false;
	boolean repeat = false;
	boolean isComposing = false;
	DOMString locale = "";
};

Specyfikacje i inne materiały#

DOM Level 3 Events

Pasek społecznościowy

WebRef - kursy webowe

KeyboardEvent#

new KeyboardEvent()#

Składnia#

Interfejs Web IDL#

Specyfikacje i inne materiały#