.CARDS

Zeigt Bot-Cards (Buttons, Bilder, iFrames, HTML, Videos, Lade-Indikator) im Chat an (RAGAI.CARDS).

Hintergrund

Cards werden - anders als RAGAI.OVERLAY - direkt in den Chatverlauf eingefügt und persistiert (als Verlaufsnachricht mit role: 'botcard'); Overlays sind modale, nicht-persistente UI-Elemente über dem Chat. Jede Card löst RAGAI.CARDS.ADD sowie RAGAI.CARDS.ADD.<type> Events aus (außer debugEvent, das bewusst keine Events feuert, um Debug-Ausgaben nicht in den regulären Event-Strom zu mischen). Für Diagramme siehe stattdessen RAGAI.CHARTS.

Methoden

.buttons(buttons, cssClass?)

Zeigt eine Button-Card mit anklickbaren Optionen an.

Parameter	Typ	Beschreibung
buttons	BUTTONCARDBUTTON[]	Die anzuzeigenden Buttons.
cssClass	string	Optionale CSS-Klasse für die Card.

Rückgabewert: Promise<void>

.iframe(url, cssClass?)

Zeigt eine iFrame-Card an.

Parameter	Typ	Beschreibung
url	string | z.input<typeof cardsIframeSchema>	URL der einzubettenden Seite, oder ein Objekt gemäß cardsIframeSchema.
cssClass	string	Optionale CSS-Klasse für die Card.

Objekt-Form (validiert über cardsIframeSchema):

Feld	Typ	Pflicht	Beschreibung
url	string	✔	URL der in der Card einzubettenden Seite.
cssClass	string	–	Optionale CSS-Klasse für die Card.

Rückgabewert: Promise<void>

Nichts.

.html(html, cssClass?, id?)

Zeigt eine HTML-Card an.

Parameter	Typ	Beschreibung
html	string | z.input<typeof cardsHtmlSchema>	Der anzuzeigende HTML-Inhalt, oder ein Objekt gemäß cardsHtmlSchema.
cssClass	string	Optionale CSS-Klasse für die Card.
id	string	Optionale Element-ID für die Card.

Objekt-Form (validiert über cardsHtmlSchema):

Feld	Typ	Pflicht	Beschreibung
html	string	✔	Der anzuzeigende HTML-Inhalt.
cssClass	string	–	Optionale CSS-Klasse für die Card.
id	string	–	Optionale Element-ID für die Card.

Rückgabewert: Promise<void>

Nichts.

.debugEvent(html, cssClass?, id?)

Wie html, löst aber keine RAGAI.CARDS.ADD-Events aus. Wird für interne Debug-Ausgaben verwendet.

Parameter	Typ	Beschreibung
html	string	Der anzuzeigende HTML-Inhalt.
cssClass	string	Optionale CSS-Klasse für die Card.
id	string	Optionale Element-ID für die Card.

Rückgabewert: Promise<void>

.loading(text?, icon?, cssClass?)

Zeigt einen Lade-Indikator im Chat an.

Parameter	Typ	Beschreibung
text	string | z.input<typeof cardsLoadingSchema>	Optionaler Ladetext, oder ein Objekt gemäß cardsLoadingSchema.
icon	string	Optionales Icon für den Indikator.
cssClass	string	Optionale CSS-Klasse für die Card.

Objekt-Form (validiert über cardsLoadingSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	–	Optionaler Ladetext.
icon	string	–	Optionales Icon für den Lade-Indikator.
cssClass	string	–	Optionale CSS-Klasse für die Card.

Rückgabewert: void

.removeLoading()

Entfernt den aktuell angezeigten Lade-Indikator.

Rückgabewert: void

.youtube(id, cssClass?)

Zeigt eine YouTube-Video-Card an.

Parameter	Typ	Beschreibung
id	string | z.input<typeof cardsYoutubeSchema>	Die YouTube-Video-ID, oder ein Objekt gemäß cardsYoutubeSchema.
cssClass	string	Optionale CSS-Klasse für die Card.

Objekt-Form (validiert über cardsYoutubeSchema):

Feld	Typ	Pflicht	Beschreibung
id	string	✔	Die YouTube-Video-ID.
cssClass	string	–	Optionale CSS-Klasse für die Card.

Rückgabewert: Promise<void>

Nichts.

.vimeo(id, hash?, cssClass?)

Zeigt eine Vimeo-Video-Card an.

Parameter	Typ	Beschreibung
id	string | z.input<typeof cardsVimeoSchema>	Die Vimeo-Video-ID, oder ein Objekt gemäß cardsVimeoSchema.
hash	string	Privater Vimeo-Hash für geschickte Videos.
cssClass	string	Optionale CSS-Klasse für die Card.

Objekt-Form (validiert über cardsVimeoSchema):

Feld	Typ	Pflicht	Beschreibung
id	string	✔	Die Vimeo-Video-ID.
hash	string	✔	Privater Vimeo-Hash für geschützte Videos.
cssClass	string	–	Optionale CSS-Klasse für die Card.

Rückgabewert: Promise<void>

Nichts.

.image(src, altText?, cssClass?)

Zeigt eine Bild-Card an. Lädt die URL bei Bedarf aus einem Skill auf.

Parameter	Typ	Beschreibung
src	string | z.input<typeof cardsImageSchema>	Bild-URL, Skill-ID, oder ein Objekt gemäß cardsImageSchema.
altText	string	Alternativtext für das Bild.
cssClass	string	Optionale CSS-Klasse für die Card.

Objekt-Form (validiert über cardsImageSchema):

Feld	Typ	Pflicht	Beschreibung
src	string	✔	Bild-URL oder Skill-ID des anzuzeigenden Bilds.
altText	string	–	Alternativtext für das Bild.
cssClass	string	–	Optionale CSS-Klasse für die Card.

Rückgabewert: Promise<void>

Nichts.

.stageListButtons()

Zeigt Navigations-Buttons für alle sichtbaren Stages an.

Rückgabewert: Promise<void>

.addBotCard(payload, triggerEvent?)

Fügt eine beliebige Bot-Card zum Chatverlauf hinzu.

Parameter	Typ	Beschreibung
payload	{ type: string, data: unknown }	Card-Payload.
triggerEvent	boolean	false, um die zugehörigen RAGAI.CARDS.ADD-Events zu unterdrücken.

Rückgabewert: Promise<any>

Die gespeicherte Verlaufsnachricht.