Zum Hauptinhalt springen
Die <ribaunt-widget>-Web-Komponente und ihr React-Wrapper teilen sich dieselbe Konfigurationsoberfläche. HTML verwendet Attribute in Kebab-Case; React verwendet Props in CamelCase. Du kannst beide je nach Stack austauschbar nutzen — alles hier Beschriebene gilt für beide, sofern nicht anders angegeben.

​
Kurzbeispiel

Das folgende Snippet zeigt jedes verfügbare Attribut, gesetzt am HTML-Element: 
<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  auto-verify="true"
  show-warning="false"
  warning-message="Verification may take longer on this device."
  solve-timeout="15000"
  disabled="false"
></ribaunt-widget>

​
Referenz für Attribute und Props

HTML-AttributReact-PropTypStandardBeschreibung
challenge-endpointchallengeEndpointstringundefinedURL-Endpunkt, der { challenges: string[] } zurückgibt. Ist er undefiniert, kann das Widget nicht automatisch abrufen.
verify-endpointverifyEndpointstringundefinedURL-Endpunkt, an den die Lösungen per POST gesendet werden. Ist er undefiniert, musst du die Verifizierung manuell mit dem Solver direkt durchführen.
auto-verifyautoVerify`booleanstring`falseStartet die Verifizierung automatisch, sobald das Widget geladen ist. Setze auf "false" oder lasse es weg, um eine Benutzerinteraktion oder startVerification() zu erfordern.
show-warningshowWarning`booleanstring`falseZeigt ein rotes Warn-Banner über dem Widget an. Wird häufig verwendet, um Benutzer zu warnen, falls WebAssembly für zukünftige Fast-Solver fehlt.
warning-messagewarningMessagestring"Enable WASM..."Benutzerdefinierter Nachrichtentext für das Warn-Banner.
solve-timeoutsolveTimeout`numberstring`undefinedOptionaler Timeout in Millisekunden für das Lösen. Wird er weggelassen, gibt es kein automatisches Timeout.
disableddisabled`booleanstring`falseDeaktiviert Benutzerinteraktion und programmatische Verifizierung, solange gesetzt.

​
Antwortformat des Challenge-Endpunkts

Dein challenge-endpoint sollte einen JSON-Body zurückgeben, der die Challenge-Tokens enthält, die das Widget lösen wird. Das empfohlene Antwortformat ist { challenges: string[] }.
Das Widget akzeptiert drei Antwortformate vom challenge-endpoint:
  1. { challenges: string[] } — empfohlener Vertrag
  2. { tokens: string[] } — Legacy-Kompatibilität
  3. rohes string[] — Legacy-Kompatibilität
Ungültige oder gemischte Token-Arrays schlagen frühzeitig mit einem klaren Fehler-Ereignis des Widgets fehl.

​
Verhalten im Disabled-Zustand

Wenn du disabled setzt (oder einen beliebigen Wert außer "false"), wechselt das Widget in einen vollständig inerten Zustand. Konkret bedeutet das:
  • Klick-Interaktionen werden blockiert
  • Tastaturaktivierungen werden blockiert
  • startVerification() wird zu einem No-Op
  • auto-verify wird am Starten gehindert
  • Das Widget wird aus der Tab-Reihenfolge entfernt
  • aria-disabled="true" wird für Barrierefreiheit gesetzt
Verwende disabled, um Nutzer am erneuten Absenden zu hindern, während dein Server ein Formular verarbeitet, und entferne es, sobald die Antwort eintrifft. Hier ist ein React-Beispiel, das die Disabled-Prop basierend auf einem Lade-Flag umschaltet: 
<RibauntWidget
  disabled={isProcessing}
  challengeEndpoint="/api/captcha/challenge"
  verifyEndpoint="/api/captcha/verify"
/>

​
Imperative Methoden (über ref)

Du kannst Methoden direkt am Widget-Element aufrufen, um es programmatisch zu steuern. In React erhältst du eine typisierte Ref über RibauntWidgetHandle:
MethodeBeschreibung
startVerification()Startet den Lösungsablauf programmatisch
reset()Setzt das Widget in den Anfangszustand zurück
getState()Gibt die aktuelle Widget-Zustands-Zeichenkette zurück
import { useRef } from 'react';
import RibauntWidget, { type RibauntWidgetHandle } from 'ribaunt/widget-react';

const ref = useRef<RibauntWidgetHandle>(null);
// ...
ref.current?.startVerification();
ref.current?.reset();
const state = ref.current?.getState();

​
Nur in React verfügbare Props

Zusätzlich zu den oben genannten Attributen akzeptiert der React-Wrapper typisierte Callback-Props und eine ref. Diese haben kein HTML-Attribut-Äquivalent und werden vollständig innerhalb des React-Wrappers behandelt:
  • onVerify — wird ausgelöst, wenn die Verifizierung erfolgreich ist
  • onError — wird ausgelöst, wenn ein Fehler auftritt
  • onStateChange — wird ausgelöst, wenn das Widget zwischen Zuständen wechselt
  • onReady — wird einmal ausgelöst, nachdem das Widget gemountet wurde
  • onLoad — Alias für onReady, zur Abwärtskompatibilität bereitgestellt
  • onEvent — Sammel-Handler für alle Ereignistypen
  • ref — imperativer Handle, der reset(), getState() und startVerification() bereitstellt
Siehe die Ereignis-Referenz für vollständige Details zu jedem Callback, dessen Payload-Typen und Anwendungsbeispielen.
Das Lösen im Browser erfordert HTTPS oder http://localhost. Das Laden von einer einfachen LAN-URL (z. B. http://192.168.x.x) wird fehlschlagen, da die Web Crypto API nicht verfügbar ist.