Zum Hauptinhalt springen

Formatierter Text

rich_text speichert formatierte Notizen und Beschreibungen: Überschriften, Hervorhebungen, Listen, Zitate, Code und Links. Die kanonische Darstellung ist ein HTML-Fragment, das auf eine begrenzte Menge an Elementen beschränkt ist. Schreibvorgänge werden in diese Form normalisiert, Lesevorgänge geben sie unverändert zurück, und jeder Konsument, der kein Markup darstellen kann, erhält dieselbe deterministische Nur-Text-Projektion.

Verwenden Sie text für Kennungen, Namen und einzeilige Werte. Verwenden Sie rich_text, wenn der Wert Fließtext ist, den Personen formatieren. Ein bestehendes text-Attribut kann seinen Typ nicht ändern; migrieren Sie, indem Sie ein rich_text-Attribut anlegen und die alten Werte schreiben, die zu Absätzen werden (siehe Umstellung von Text).

Unterstütztes Markup​

FunktionElemente
Absätze und Zeilenumbrüchep, br
Überschriftenh1, h2, h3
Hervorhebungstrong, em, u, s
Codecode, pre (mit code)
Zitateblockquote
Listenul, ol, li, auch verschachtelt
Linksa mit href und den Schemata http, https, mailto oder tel

href ist das einzige Attribut, das ein Dokument tragen darf. b, i, strike und del werden akzeptiert und zu strong, em und s normalisiert. Alles andere, einschließlich img, Tabellen, style, class, Event-Handlern und anderen URL-Schemata, wird abgelehnt statt entfernt, damit der Aufrufer genau erfährt, was ein importiertes Dokument enthielt.

Grenzen​

GrenzeWertFehlertyp
Kanonische UTF-8-Größe65.536 Bytesrich-text-too-large
Verschachtelungstiefe der Elemente16rich-text-too-deep

Weitere Validierungsfehler: rich-text-unsupported-element, rich-text-unsupported-attribute, rich-text-unsafe-link sowie type-mismatch für einen Wert, der kein String ist. Alle zeigen auf das Attribut, zum Beispiel #/data/notes. Die Obergrenze für Datensatznutzdaten (413 payload-too-large) greift zuerst.

Normalisierung​

Die gespeicherte Form ist deterministisch und idempotent:

  • Alias-Elemente werden zu ihrem kanonischen Element; Kommentare entfallen.
  • Text oder Inline-Markup direkt im Fragment wird in einen Absatz gepackt; Zeilenumbrüche in solchem Text werden zu <br>.
  • Geschützte Leerzeichen werden zu Leerzeichen; &, <, > werden als &amp;, &lt;, &gt; maskiert; Linkziele werden getrimmt.
  • Leerraum zwischen Elementen und die Attributquotierung werden kompakt serialisiert.

Formatierungen innerhalb der unterstützten Menge bleiben exakt erhalten. Eine byteweise Erhaltung des übermittelten Markups wird nicht zugesichert.

Leere Dokumente​

Ein Dokument, dessen Nur-Text-Projektion leer ist (zum Beispiel <p></p>, <p><br></p> oder eine leere Liste), hat keinen Wert. Beim Schreiben leert es das Attribut genau wie null: Ein optionales Attribut wird entfernt, ein Pflichtattribut liefert 422 required-field. Lesevorgänge geben nie ein leeres Dokument zurück.

Definition​

{
"slug": "handover_notes",
"type": "rich_text",
"name": {"en": "Handover notes", "de": "Übergabenotizen"},
"config": {
"is_required": false,
"default": "<p>Check <strong>tyres</strong></p>"
}
}
KonfigurationVerhalten
is_requiredEin Dokument mit Textinhalt muss vorhanden sein.
defaultMarkup aus der unterstützten Teilmenge, normalisiert und begrenzt wie Datensatzwerte, beim Anlegen eingesetzt, wenn ein Datensatz das Attribut auslässt. Reiner Text wird zu einem Absatz.
is_uniqueNicht unterstützt; liefert 422 unique-unsupported-type.

Formatierter Text hat außer den Plattformgrenzen keine Muster- oder Längenbeschränkungen.

Datensatzschreibvorgänge​

{
"data": {
"handover_notes": "<p>Fuel card in <em>glovebox</em></p><ul><li>Check tyres</li></ul>"
}
}

Änderungen folgen dem JSON-Merge-Patch-Vertrag der Datensätze auf Attributebene: Ein ausgelassenes Attribut bleibt unverändert, ein mitgesendetes Dokument ersetzt das gespeicherte Dokument vollständig, und null oder ein leeres Dokument leert es.

Nur-Text-Projektion​

Anzeigevorlagen, die Datensatzsuche, das GraphQL-Feld text und kompakte Listenvorschauen verwenden eine gemeinsame Projektion: Blockelemente beenden eine Zeile, <br> bricht eine Zeile um, Aufzählungspunkte erhalten das Präfix - und nummerierte Punkte ihre Nummer, Inline-Markup entfällt, Entities werden dekodiert und Leerraum wird außer in pre zusammengefasst. Anzeigevorlagen und die globale Suche fassen das Ergebnis zusätzlich auf eine Zeile zusammen. Linkziele sind nicht Teil der Projektion.

Abfragefähigkeiten​

OberflächeFähigkeit
REST filter_operatorscontains und is_null (is_null nur bei optionalen Attributen)
REST is_sortablefalse
GraphQL-AusgabeRecordRichText { html: String!, text: String! }
GraphQL-FilterRichTextOperators mit _contains und _is_null
GraphQL order_byNicht verfügbar
SucheÜber die Nur-Text-Projektion enthalten; Markup und Linkziele werden nicht indexiert

contains vergleicht die Nur-Text-Projektion ohne Beachtung der Groß-/Kleinschreibung. Präfix-, Suffix-, Gleichheits- und Ordnungsoperatoren liefern 422 filter-operator-not-applicable, eine Sortierung liefert 422 unsupported-sort-field.

Umstellung von Text​

Attributtypen sind unveränderlich. Um ein bestehendes text-Attribut auf formatierten Text umzustellen, legen Sie ein rich_text-Attribut an, kopieren jeden Wert und entfernen das alte Attribut, sobald nichts mehr darauf zugreift. Das Schreiben eines reinen Strings in ein rich_text-Attribut ist eine deterministische Umwandlung: Er wird zu einem Absatz und jeder Zeilenumbruch zu einem <br>, es geht also nichts verloren. Die umgekehrte Richtung ist verlustbehaftet: Verwenden Sie die Nur-Text-Projektion und rechnen Sie damit, dass Formatierungen verschwinden.

Integrationsoberflächen​

Webhook-Nutzdaten, MCP-Datensatzwerkzeuge und Workflow-Datensatzoperationen übertragen den kanonischen HTML-String innerhalb von data, genau wie REST ihn zurückgibt. Konsumenten, die ihn darstellen, müssen ihn mit derselben Positivliste erneut bereinigen; die Tourfold-Web-App tut das.