Wir führen einen neuen type: objects für die unterstützten Typen für Theme-Einstellungen ein, der verwendet werden kann, um den bestehenden json_schema-Typ zu ersetzen, den wir bald als veraltet (deprecated) kennzeichnen möchten.
Definieren einer objects-Theme-Einstellung
Um eine Theme-Einstellung vom Typ objects zu erstellen, definieren Sie zunächst einen Top-Level-Schlüssel, genau wie bei jeder anderen Theme-Einstellung, der als Name der Einstellung verwendet wird.
links: ...
Fügen Sie anschließend die Schlüsselwörter type, default und schema zur Einstellung hinzu.
links:
type: objects
default: []
schema: ...
type: objects gibt an, dass es sich um eine Einstellung vom Typ objects handelt, während die Annotation default: [] den Standardwert der Einstellung auf ein leeres Array setzt. Beachten Sie, dass der Standardwert auch auf ein Array von Objekten gesetzt werden kann, was wir demonstrieren werden, sobald das schema definiert ist.
Um das Schema zu definieren, definieren Sie zunächst den name des Schemas wie folgt:
links:
type: objects
default: []
schema:
name: link
Als Nächstes fügen wir das Schlüsselwort properties zum Schema hinzu, mit dem wir festlegen und validieren können, wie jedes Objekt aussehen soll.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
Im obigen Beispiel geben wir an, dass das link-Objekt eine name-Eigenschaft besitzt. Um den erwarteten Datentyp festzulegen, muss jede Eigenschaft das type-Schlüsselwort definieren.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
Die obige Schemadefinition besagt, dass das link-Objekt eine name-Eigenschaft vom Typ string besitzt, was bedeutet, dass für diese Eigenschaft nur Zeichenfolgenwerte akzeptiert werden. Derzeit werden folgende Typen unterstützt:
-
string: Der Wert der Eigenschaft wird als Zeichenfolge gespeichert. Setzen Sietextarea: true, um ein sich erweiterndes Textfeld zu verwenden:description: type: string textarea: true validations: max_length: 500 -
integer: Der Wert der Eigenschaft wird als Ganzzahl gespeichert. -
float: Der Wert der Eigenschaft wird als Fließkommazahl gespeichert. -
boolean: Der Wert der Eigenschaft isttrueoderfalse. -
upload: Der Wert der Eigenschaft ist die Anhang-URL. -
enum: Der Wert der Eigenschaft muss einer der im Schlüsselwortchoicesdefinierten Werte sein.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: Der Wert der Eigenschaft ist ein Array mit gültigen Kategorie-IDs. -
groups: Der Wert der Eigenschaft ist ein Array mit gültigen Gruppen-IDs. -
tags: Der Wert der Eigenschaft ist ein Array mit gültigen Tag-Namen. -
icon: Der Wert der Eigenschaft ist der Name eines einzelnen Symbols aus dem Discourse-Symbolset. Ausgewählte Symbole werden automatisch zum Sprite-Sheet hinzugefügt, sodass sie ohne separate Registrierung gerendert werden können.
Bei der Aktualisierung einer objects-Theme-Einstellung über die API können tags-Arrays Quell-Tag-Namen, ganzzahlige Tag-IDs oder beides enthalten. IDs werden vor der Validierung und Speicherung in Quell-Namen aufgelöst. Themes erhalten weiterhin Arrays von Quell-Namen. Numerische Zeichenfolgen werden als Namen, nicht als IDs behandelt, und Standardwerte müssen Namen verwenden.
Der Standard-Frontend-Tag-Renderer umfasst data-tag-id für Tag-Objekte mit einer ID oder für Tag-Namen, die mit der Option tagId gerendert werden. Das vorhandene Attribut data-tag-name bleibt unverändert. Die ID bleibt über alle Locales hinweg gleich, auch wenn der angezeigte Name geändert wird. Render-Aufrufe, die nur Namen enthalten und keine ID angeben, lassen data-tag-id weg.
Objekte mit direkten tags-Eigenschaften erhalten automatisch ein zugehöriges tag_objects-Array in den Frontend-Einstellungen:
{
tags: ["support"],
tag_objects: [
{ id: 42, name: "support" }
]
}
Die vorhandenen Arrays mit Tag-Namen bleiben unverändert. Jedes zugehörige Objekt enthält die Tag-ID und die exakte ursprüngliche Quell-Namenszeichenfolge aus der Einstellung, einschließlich der Groß-/Kleinschreibung. Es wird kein übersetzter Anzeigename eingesetzt. Komponenten können die IDs verwenden, um auf die ausgewählten Tags zu verweisen, beispielsweise wenn in CSS data-tag-id als Ziel verwendet wird. Core rendert das zugehörige Array nicht als UI und fügt keine Admin-Einstellung dafür hinzu.
Die Zuordnung kombiniert die direkten tags-Auswahlen des Objekts in ihrer ursprünglichen Reihenfolge und erhält doppelte Auswahlen. Verschachtelte Objekte erhalten ihre eigenen Zuordnungen. Nur Tags, die für den Besucher sichtbar sind, werden aufgenommen; fehlende, gelöschte oder ausgeblendete Auswahlen werden weggelassen. Die Zuordnung ist weiterhin als [] vorhanden, wenn keine Tags aufgelöst werden. Gehen Sie nicht davon aus, dass ihre Indizes mit dem ursprünglichen String-Array übereinstimmen.
Kein Opt-in oder zusätzliche Browser-API-Anfrage ist erforderlich. Eine vom Autor definierte Schema-Eigenschaft namens tag_objects hat Vorrang: Core behält dieses Feld bei und generiert auf dieser Ebene keine Zuordnung. Deklarieren Sie jedes vorhandene benutzerdefinierte Feld mit diesem Namen; nicht deklarierte tag_objects-Werte werden als generierte Metadaten behandelt und entfernt. Objekte ohne direkte tags-Eigenschaften und veraltete Top-Level-Tag-Listeneinstellungen bleiben unverändert.
Die Zuordnung wird nur für die Frontend-Seitendaten generiert. Gespeicherte Einstellungen und Admin-Bearbeitungswerte behalten ihre bestehende Form; über die Settings-API zurückgesendete generierte Metadaten werden verworfen. Komponenten, die Kontexte oder ältere Discourse-Versionen ohne diese Daten unterstützen, können Array.isArray(style.tag_objects) prüfen und auf ihr bestehendes namenbasiertes Verhalten zurückfallen, wenn dies nicht verfügbar ist.
Nachdem das Schema definiert ist, kann der Standardwert der Einstellung nun durch Definieren eines Arrays in YAML wie folgt gesetzt werden:
links:
type: objects
default:
- name: link 1
title: link 1 title
- name: link 2
title: link 2 title
schema:
name: link
properties:
name:
type: string
title:
type: string
Erforderliche Eigenschaften
Alle definierten Eigenschaften sind standardmäßig optional. Um eine Eigenschaft als erforderlich zu markieren, annotieren Sie die Eigenschaft einfach mit required: true. Eine Eigenschaft kann auch als optional markiert werden, indem Sie die Eigenschaft mit required: false annotieren.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
Leere string-, datetime- und icon-Werte sowie leere categories-, groups- und tags-Listen werden als fehlend betrachtet: Erforderliche Eigenschaften lehnen sie ab, optionale Eigenschaften überspringen ihre Validierungen. false zählt als gesetzt.
Benutzerdefinierte Validierungen
Für bestimmte Eigenschaftstypen gibt es integrierte Unterstützung für benutzerdefinierte Validierungen, die durch Annotieren der Eigenschaft mit dem Schlüsselwort validations deklariert werden können.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
Validierungen für string-Typen
min_length: Minimale Länge der Eigenschaft. Der Wert des Schlüsselworts muss eine Ganzzahl sein.max_length: Maximale Länge der Eigenschaft. Der Wert des Schlüsselworts muss eine Ganzzahl sein.url: Validiert, dass die Eigenschaft eine gültige URL ist. Der Wert des Schlüsselworts kanntrue/falsesein.
Validierungen für integer- und float-Typen
min: Minimaler Wert der Eigenschaft. Der Wert des Schlüsselworts muss eine Ganzzahl sein.max: Maximaler Wert der Eigenschaft. Der Wert des Schlüsselworts muss eine Ganzzahl sein.
Validierungen für tags-, groups- und categories-Typen
min: Mindestanzahl der Datensätze für die Eigenschaft. Der Wert des Schlüsselworts muss eine Ganzzahl sein.max: Maximale Anzahl der Datensätze für die Eigenschaft. Der Wert des Schlüsselworts muss eine Ganzzahl sein.
Auflösung der Gruppenmitgliedschaft
Objekteinstellungen können type: groups-Eigenschaften in einen booleschen Wert für den aktuellen Benutzer auflösen. Dies ist nützlich, wenn der Theme-Code nur wissen muss, ob der aktuelle Benutzer in einer der konfigurierten Gruppen ist, da currentUser.groups nur Gruppen enthält, die für den Benutzer sichtbar sind.
Fügen Sie resolve_group_membership: true zur groups-Eigenschaft hinzu:
menu_sections:
type: objects
default:
- name: section 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
Die Admin-UI und der gespeicherte Einstellungswert verwenden weiterhin das ursprüngliche groups-Array. Im Frontend-Runtime-settings-Objekt entfernt Discourse die Gruppen-IDs aus jedem Objekt und fügt einen booleschen Wert mit demselben Eigenschaftsnamen hinzu, der mit user_in_ vorangestellt ist:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// Benutzer ist in mindestens einer ausgewählten Gruppe für diesen Abschnitt.
}
}
Diese Option ist nur für Objekt-Schema-Eigenschaften mit type: groups gültig. Sie funktioniert auch bei verschachtelten Objekt-Schemas und automatischen Gruppen wie logged_in_users und anonymous_users.
Struktur verschachtelter Objekte
Ein Objekt kann auch eine Eigenschaft enthalten, die ein Array von Objekten enthält. Um eine verschachtelte Objektstruktur zu erstellen, kann eine Eigenschaft auch mit type: objects und der zugehörigen schema-Definition annotiert werden.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
Beschreibung und Lokalisierung der Einstellung
Um eine Beschreibung für die Einstellung in der en-Locale hinzuzufügen, erstellen Sie eine Datei locales/en.yml mit dem folgenden Format, gegeben die folgende Theme-Einstellung vom Typ objects.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
en:
theme_metadata:
settings:
sections:
description: This is a description for the sections theme setting
schema:
properties:
name:
label: Name
description: The description for the property
links:
name:
label: Name
description: The description for the property
url:
label: URL
description: The description for the property
Übersetzbarer Objekttext
Deklarieren Sie eine erforderliche Zeichenfolgen-Eigenschaft namens translation_key und markieren Sie Text-Eigenschaften mit translatable: true, um sie in den Site-Texten bereitzustellen. Core liest die Standardwerte aus den gespeicherten Objekteinstellungen und nimmt sie in die normalen Theme-Übersetzungs-Assets auf. Theme-Komponenten benötigen keinen Backend-Code.
links:
type: objects
default:
- translation_key: guidelines
label: Community guidelines
schema:
name: link
identifier: label
properties:
translation_key:
type: string
required: true
label:
type: string
translatable: true
Dies stellt js.theme_translations.<theme_id>.links.guidelines.label mit dem Standardtext „Community guidelines“ und der Standardsprache en bereit. Das Frontend verwendet weiterhin i18n(themePrefix(`links.${link.translation_key}.label`), { defaultValue: link.label }) für jeden Link in der Einstellung.
Der Editor zeigt relative Schlüssel an, die an themePrefix übergeben werden, und Links zu Site-Texten, die auf die Komponente gefiltert sind. Speichern Sie Änderungen, bevor Sie Übersetzungen verwalten.
Core beschränkt Schlüssel auf die installierte Theme-ID und den Namen der Objekteinstellung. Die Standardsprache ist en; optional können Sie translations: { default_locale: fr } auf dem Wurzel-Schema setzen, um dies zu ändern. Ein translations-Block ist ansonsten nicht erforderlich. Verschachtelte Schemas deklarieren ihre eigene erforderliche Zeichenfolgen-Eigenschaft translation_key und markieren ihre übersetzbaren Eigenschaften; Vorfahr-Objektschlüssel und Namen der Sammel-Eigenschaften werden in jeden verschachtelten Schlüssel einbezogen. Zum Beispiel erzeugt ein Abschnitt mit dem Schlüssel getting_started, der einen Link mit dem Schlüssel guidelines enthält, theme_translations.<theme_id>.resource_sections.getting_started.links.guidelines.label für die Einstellung resource_sections.
Schemas mit übersetzbaren Feldern, einschließlich ihrer Vorfahr-Objekt-Schemas, müssen translation_key mit type: string und required: true deklarieren. Die Schema-Validierung prüft dies auch dann, wenn die Standard-Objektliste leer ist. Die separate Option schema.identifier: label wählt die Anzeigebeschriftung des Editors; sie wählt nicht den Übersetzungsidentifikator.
Verwenden Sie stabile, manuell zugewiesene Identifikatoren, die mit einem Kleinbuchstaben beginnen und nur Kleinbuchstaben, Ziffern und Unterstriche enthalten. Identifikatoren müssen höchstens 80 Zeichen lang und innerhalb jeder Sammlung eindeutig sein. Namen von übersetzbaren Einstellungen, Feldnamen und Namen verschachtelter Sammlungen beginnen ebenfalls mit einem Kleinbuchstaben und enthalten nur Kleinbuchstaben, Ziffern und Unterstriche. Umsortieren erhält Übersetzungen. Das Umbenennen eines Identifikators erzeugt neue Übersetzungsschlüssel; das Duplizieren eines Objekts erfordert einen anderen Schlüssel. Separate Komponenteninstallationen haben unabhängige Namensräume.
Beim Hinzufügen übersetzbarer Felder zu einer bestehenden Komponente stellen Sie eine Einstellungs-Migration bereit, die gültige translation_key-Werte zu angepassten Objekten hinzufügt. Komponenten-Updates validieren die endgültigen Objekt-Übersetzungsschlüssel und bauen ihre Übersetzungen neu auf, nachdem die Einstellungs-Migrationen abgeschlossen sind. Ungültige endgültige Schlüssel rollen das Update zurück. Gewöhnliche Speichervorgänge im Objekt-Editor validieren sofort. Wenn gespeicherte Objekt-Identifikatoren ungültig sind, lassen Lesepfade Objekt-Standards weg, sodass Locale-Datei-Übersetzungen und Assets verfügbar bleiben; das Speichern von Objekteinstellungen und das Anwenden von Migrationen validieren weiterhin streng.
Nur Zeichenfolgenfelder, die mit translatable: true markiert sind, nehmen teil. Nicht markierte Felder und Felder mit translatable: false werden ausgeschlossen. Leere optionale Felder behalten ihre Schlüssel und bestehenden Übersetzungen. Das Löschen von Standardtexten löscht keine Übersetzungen. Verschachtelte Sammlungen enthalten ihren Eigenschaftsnamen im Schlüssel, sodass separate Sammlungen dieselben Objekt-Identifikatoren wiederverwenden können.
Standardwerte umfassen Theme-Standardwerte und importierte Einstellungen. Ändern von Standardtexten markiert Übersetzungen als veraltet. Standardwerte bleiben in der Objekteinstellung; Übersetzungen verwenden das bestehende ThemeTranslationOverride-Modell, genau wie Locale-Datei-Felder. Es gibt keine separate Text-Registrierung.
Das Entfernen eines Objekts, einer übersetzbaren Felddeklaration oder eines Locale-Datei-Schlüssels löscht nicht dessen gespeicherte Übersetzungsoverrides. Overrides ohne aktuelle Quelle haben den Status deprecated und bleiben beim Speichern von Einstellungen, bei Migrationen und bei Komponenten-Updates erhalten. Das Wiederherstellen desselben Übersetzungsschlüssels verwendet die gespeicherte Anpassung wieder, auch nach einem Komponenten-Rollback. Dies erhält das bestehende Locale-Datei-Übersetzungsverhalten für Komponenten, die sich nicht für Objekt-Übersetzungen entscheiden. Entfernte Schlüssel werden nicht in den Site-Texten aufgeführt, bis ihre Quell-Deklarationen zurückkehren.
Wenn Schema-Änderungen dazu führen, dass ein beibehaltener Schlüssel mit der verschachtelten Struktur eines aktuellen Schlüssels in Konflikt steht, bestimmt die aktuelle Deklaration die Laufzeitform. Beide gespeicherten Overrides bleiben für die Wiederherstellung verfügbar, falls das Schema zurückgerollt wird.
Das explizite Zurücksetzen einer Übersetzung entfernt weiterhin diesen Override und stellt den ausgelieferten Standardwert für die ausgewählte Locale wieder her. Das Löschen der Komponente entfernt alle ihre Übersetzungsoverrides.
Site-Texte zeigen den Standardtext und dessen Sprache neben der bearbeitbaren Übersetzung. Sowohl Objekt-Editor-Felder als auch in Locale-Dateien ausgelieferte Zeichenfolgen verwenden in den Site-Texten js.theme_translations.<theme_id>.<key>. Übersetzungen, die gespeichert wurden, bevor die Standardverfolgung verfügbar war, haben eine unbekannte Baseline und werden vom veralteten Filter ausgeschlossen. Das Bestätigen des aktuellen Standardwerts etabliert eine Baseline, ohne die Übersetzung zu ändern. Interpolations-Platzhalter in Objekt-Feldern werden gegen den deklarierten Quelltext geprüft, nicht gegen benutzerdefinierte Quell-Overrides. Pluralformen können Platzhalter verwenden, die von ihrem Geschwister-other-Formularteil deklariert werden. Locale-Datei-Overrides behalten ihr bestehendes uneingeschränktes Platzhalterverhalten bei, da die Komponente Laufzeitargumente bereitstellen kann, die ihr ausgelieferter Text nicht verwendet. Site-Texte markieren diese Argumente nicht als ungültig.
Die Standardverfolgung verwendet das gespeicherte Objekt-Feld oder den ausgelieferten englischen Text und fällt auf den ausgelieferten Text der ausgewählten Locale zurück, wenn kein englischer Schlüssel existiert. Quell-Locale-Overrides ersetzen diese Baseline nicht. Die Sprache des Standardwerts wird explizit angezeigt; das Zurücksetzen eines Locale-Datei-Overrides stellt weiterhin den Text wieder her, der für die ausgewählte Locale ausgeliefert wurde.
Der Einstellungsname reserviert einen Namensraum innerhalb des Themes. Eine Locale-Datei kann den Wurzel-Schlüssel dieser Einstellung nicht auch definieren: Das Speichern der Objekteinstellung oder das Aktualisieren des Themes lehnt den Konflikt ab. Text wird nur für das aktive Theme und seine Komponenten, einschließlich Vorschauen, über die bestehenden zwischengespeicherten Theme-Übersetzungs-Assets bereitgestellt.
Dieses Dokument wird versionskontrolliert – schlagen Sie Änderungen auf GitHub vor.



