Signatur
Beschreibung
Die schreibgeschützte Eigenschaft radiusX eines Touch-Objekts gibt den Radius der Kontaktellipse entlang ihrer X-Achse an. Der Wert ist eine Gleitkommazahl in CSS-Pixeln und gehört zur selben Skala wie clientX/clientY. Zusammen mit radiusY und rotationAngle beschreibt er die Form und Lage der Fläche, mit der Finger oder Stift den Bildschirm berühren.
Wichtig: radiusX bezieht sich nicht zwingend auf die horizontale Bildschirmachse. Die Ellipse wird zuerst mit radiusX und radiusY definiert und anschließend um rotationAngle Grad im Uhrzeigersinn gedreht. Erst mit allen drei Werten lässt sich der Kontaktbereich korrekt darstellen.
Typische Einsatzfälle sind Zeichen- und Mal-Anwendungen (Pinselbreite abhängig von der Fingerfläche), Unterscheidung zwischen Fingerkuppe und flach aufgelegtem Finger bzw. Handballen (Palm Rejection) sowie Visualisierungen zur Fehlersuche bei Touch-Interaktionen.
Der Wert wird ausschließlich über Touch-Events (touchstart, touchmove, touchend, touchcancel) zugänglich – über die Listen TouchEvent.touches, targetTouches oder changedTouches.
Rückgabewert
1; manche Browser/Geräte geben stattdessen 0 oder einen festen Schätzwert zurück.Beispiele
Kontaktgröße beim Berühren ausgeben
const flaeche = document.querySelector('#touch-flaeche');
flaeche.addEventListener('touchstart', (event) => {
for (const touch of event.changedTouches) {
console.log(
`Touch #${touch.identifier}: radiusX=${touch.radiusX.toFixed(1)}px, ` +
`radiusY=${touch.radiusY.toFixed(1)}px, Winkel=${touch.rotationAngle}°`
);
}
}, { passive: true });Kontaktellipse auf einem Canvas zeichnen
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const zeichneKontakt = (event) => {
event.preventDefault();
const rect = canvas.getBoundingClientRect();
for (const touch of event.changedTouches) {
const x = touch.clientX - rect.left;
const y = touch.clientY - rect.top;
// Fallback, falls das Gerät keine Radien liefert
const rx = touch.radiusX || 10;
const ry = touch.radiusY || 10;
const winkel = (touch.rotationAngle * Math.PI) / 180;
ctx.beginPath();
ctx.ellipse(x, y, rx, ry, winkel, 0, Math.PI * 2);
ctx.fillStyle = 'rgba(0, 120, 255, 0.3)';
ctx.fill();
}
};
canvas.addEventListener('touchstart', zeichneKontakt, { passive: false });
canvas.addEventListener('touchmove', zeichneKontakt, { passive: false });Handballen-Berührungen ignorieren (Palm Rejection)
const MAX_RADIUS = 25; // Schwellwert in CSS-Pixeln, gerätespezifisch justieren
const istHandballen = (touch) =>
Math.max(touch.radiusX, touch.radiusY) > MAX_RADIUS;
document.addEventListener('touchstart', (event) => {
const gueltig = [...event.changedTouches].filter((t) => !istHandballen(t));
console.log(`${gueltig.length} von ${event.changedTouches.length} Berührungen werden verarbeitet`);
}, { passive: true });// Wichtig · Fallstricke
- Hardware-abhängig: Viele Geräte (insbesondere ältere Smartphones und manche Touchpads) liefern keine echten Messwerte. Dann erhält man
1,0oder immer denselben Wert. Code sollte stets einen sinnvollen Fallback vorsehen. - Nicht horizontal:
radiusXist nicht die Breite auf dem Bildschirm, sondern eine Halbachse der Ellipse vor der Drehung umrotationAngle. - Radius, nicht Durchmesser: Die tatsächliche Ausdehnung beträgt
2 * radiusX. - Präfixe: Sehr alte WebKit-/Android-Browser kannten nur
webkitRadiusX. Moderne Browser unterstützen die unpräfixierte Eigenschaft; Desktop-Safari stellt die Touch-Events-API generell nicht bereit. - Für geräteübergreifende Eingaben (Maus, Stift, Touch) ist die Pointer-Events-API mit
PointerEvent.width/heightmeist die bessere Wahl. - Soll
preventDefault()intouchstart/touchmovewirken, muss der Listener mit{ passive: false }registriert werden.