テーマ設定のサポート対象タイプに、新しい type: objects を導入します。これは、近日中に廃止予定の既存の json_schema タイプを置き換えるために使用できます。
objects タイプのテーマ設定の定義
objects タイプのテーマ設定を作成するには、まず他のテーマ設定と同様に、設定名として使用するトップレベルのキーを定義します。
links: ...
次に、設定に type、default、および schema キーワードを追加します。
links:
type: objects
default: []
schema: ...
type: objects は、これが objects タイプの設定であることを示します。また、default: [] 注釈は、設定のデフォルト値を空の配列に設定します。デフォルト値は、schema が定義された後で示すように、オブジェクトの配列にも設定できることに注意してください。
スキーマを定義するには、まず以下のようにスキーマの name を定義します。
links:
type: objects
default: []
schema:
name: link
次に、各オブジェクトの外観を定義および検証できるように、スキーマに properties キーワードを追加します。
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
上記の例では、link オブジェクトが name プロパティを持つことを示しています。期待されるデータの種類を定義するために、各プロパティは type キーワードを定義する必要があります。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
上記のスキーマ定義は、link オブジェクトが string 型の name プロパティを持つことを示しており、これはプロパティに対して文字列値のみが受け入れられることを意味します。現在、以下のタイプがサポートされています。
-
string: プロパティの値は文字列として保存されます。拡張テキストエリアを使用するにはtextarea: trueを設定します。description: type: string textarea: true validations: max_length: 500 -
integer: プロパティの値は整数として保存されます。 -
float: プロパティの値は浮動小数点数として保存されます。 -
boolean: プロパティの値はtrueまたはfalseです。 -
upload: プロパティの値は添付ファイルのURLです。 -
enum: プロパティの値は、choicesキーワードで定義された値のいずれかである必要があります。links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: プロパティの値は、有効なカテゴリIDの配列です。 -
groups: プロパティの値は、有効なグループIDの配列です。 -
tags: プロパティの値は、有効なタグ名の配列です。 -
icon: プロパティの値は、Discourseアイコンセットからの単一のアイコン名です。選択したアイコンはスプライトシートに自動的に追加されるため、個別に登録しなくてもレンダリングできます。
APIを通じて objects テーマ設定を更新する場合、tags 配列にはソースタグ名、整数のタグID、またはその両方を含めることができます。IDは検証と保存の前にソース名に解決されます。テーマには引き続きソース名の配列が届きます。数値文字列はIDではなく名前として扱われ、デフォルトでは名前を使用する必要があります。
フロントエンドのデフォルトのタグレンダラーには、IDを持つタグオブジェクト、または tagId オプションとともにレンダリングされるタグ名に対して data-tag-id が含まれます。既存の data-tag-name 属性は変更されません。表示名が変更されても、IDはロケール間で同じままです。IDなしの名前のみのレンダリング呼び出しでは、data-tag-id は省略されます。
直接的な tags プロパティを持つオブジェクトは、フロントエンドの設定で自動的に tag_objects 配列を受け取ります。
{
tags: ["support"],
tag_objects: [
{ id: 42, name: "support" }
]
}
既存のタグ名配列は変更されません。各コンパニオンオブジェクトには、タグIDと、大文字と小文字の区別を含む、設定からの元のソース名文字列が正確に含まれます。翻訳された表示名に置き換わることはありません。コンポーネントは、IDを使用して選択したタグを参照できます。例えば、CSSで data-tag-id をターゲットする場合などです。コアはこのコンパニオン配列をUIとしてレンダリングせず、これ用の管理設定を追加しません。
コンパニオンは、オブジェクトの直接的な tags の選択を元の順序で結合し、繰り返しの選択を保持します。ネストされたオブジェクトには独自のコンパニオンが付与されます。訪問者に表示されるタグのみが含まれます。見つからない、削除された、または非表示の選択は省略されます。タグが解決されない場合でも、コンパニオンは [] として存在します。そのインデックスが元の文字列配列と一致すると仮定しないでください。
オプトインや追加のブラウザAPIリクエストは不要です。作成者定義のスキーマプロパティ名が tag_objects の場合、そちらが優先されます。コアはそのフィールドを保持し、そのレベルではコンパニオンを生成しません。この名前の既存のカスタムフィールドを宣言してください。宣言されていない tag_objects 値は生成されたメタデータとして扱われ、削除されます。直接的な tags プロパティを持たないオブジェクトや、レガシーなトップレベルのタグリスト設定は変更されません。
コンパニオンは、フロントエンドのページデータに対してのみ生成されます。保存された設定と管理編集値は、既存の形状を維持します。設定APIを通じて送信された生成されたメタデータは破棄されます。コンテキストをサポートするコンポーネントや、このデータのない古いDiscourseバージョンでは、Array.isArray(style.tag_objects) をチェックし、利用できない場合は既存の名前ベースの動作にフォールバックできます。
スキーマが定義されると、以下のようにyamlで配列を定義することで、設定のデフォルト値を設定できます。
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
必須プロパティ
定義されたすべてのプロパティはデフォルトでオプションです。プロパティを必須としてマークするには、単に required: true でプロパティに注釈を付けます。プロパティは required: false で注釈を付けることでもオプションとしてマークできます。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
空白の string、datetime、icon 値、および空の categories、groups、tags リストは欠落と見なされます。必須プロパティはそれらを拒否し、オプションプロパティはそれらの検証をスキップします。false は設定済みと見なされます。
カスタム検証
特定のプロパティタイプでは、プロパティに validations キーワードで注釈を付けることで宣言できるカスタム検証の組み込みサポートがあります。
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
string タイプの検証
min_length: プロパティの最小文字数。キーワードの値は整数である必要があります。max_length: プロパティの最大文字数。キーワードの値は整数である必要があります。url: プロパティが有効なURLであることを検証します。キーワードの値はtrue/falseにできます。
integer および float タイプの検証
min: プロパティの最小値。キーワードの値は整数である必要があります。max: プロパティの最大値。キーワードの値は整数である必要があります。
tags、groups、および categories タイプの検証
min: プロパティの最小レコード数。キーワードの値は整数である必要があります。max: プロパティの最大レコード数。キーワードの値は整数である必要があります。
グループメンバーシップの解決
オブジェクト設定は、type: groups プロパティを現在のユーザーに対するブール値に解決できます。これは、テーマコードが現在のユーザーが設定されたグループのいずれかに属しているかだけを知る必要がある場合に有用です。なぜなら、currentUser.groups にはユーザーに表示されるグループのみが含まれるためです。
groups プロパティに resolve_group_membership: true を追加します。
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
管理UIと保存された設定値は、元の groups 配列を使用し続けます。フロントエンドの実行時 settings オブジェクトでは、Discourseは各オブジェクトからグループIDを削除し、同じプロパティ名に user_in_ をプレフィックスとして付けたブール値を追加します。
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// このセクションでは、ユーザーは少なくとも1つの選択されたグループに属しています。
}
}
このオプションは、type: groups を持つオブジェクトスキーマプロパティでのみ有効です。これは、ネストされたオブジェクトスキーマでも、logged_in_users や anonymous_users などの自動グループでも機能します。
ネストされたオブジェクト構造
オブジェクトは、オブジェクトの配列を含むプロパティを持つこともできます。ネストされたオブジェクト構造を作成するには、プロパティに type: objects と関連する schema 定義を注釈として付けることもできます。
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 ロケールで設定の説明を追加するには、以下のフォーマットでファイル locales/en.yml を作成します。
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: これは sections テーマ設定の説明です
schema:
properties:
name:
label: 名前
description: プロパティの説明
links:
name:
label: 名前
description: プロパティの説明
url:
label: URL
description: プロパティの説明
翻訳可能なオブジェクトテキスト
translation_key という名前の必須の文字列プロパティを宣言し、テキストプロパティに translatable: true をマークして、それらを サイトテキスト で公開します。コアは保存されたオブジェクト設定からデフォルトを読み取り、通常のテーマ翻訳アセットにそれらを含めます。テーマコンポーネントにはバックエンドコードは不要です。
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
これにより、js.theme_translations.<theme_id>.links.guidelines.label がデフォルトテキスト「Community guidelines」およびデフォルトテキスト言語 en とともに公開されます。フロントエンドは引き続き、設定内の各リンクに対して i18n(themePrefix(`links.${link.translation_key}.label`), { defaultValue: link.label }) を使用します。
エディタは、themePrefix に渡すための相対キーと、コンポーネントにフィルタされたサイトテキストへのリンクをプレビューします。翻訳を管理する前に変更を保存してください。
コアは、インストール済みテーマIDとオブジェクト設定名にキーをスコープします。デフォルトのテキスト言語は en です。変更するには、ルートスキーマに translations: { default_locale: fr } を任意で設定します。それ以外に translations ブロックは必要ありません。ネストされたスキーマは、それぞれ独自の必須文字列 translation_key プロパティを宣言し、翻訳可能なプロパティをマークします。祖先オブジェクトキーとコレクションプロパティ名は、各ネストされたキーに含まれます。例えば、キー getting_started を持つセクションにキー guidelines を持つリンクが含まれている場合、resource_sections 設定に対して theme_translations.<theme_id>.resource_sections.getting_started.links.guidelines.label が生成されます。
翻訳可能なフィールドを持つスキーマ(その祖先オブジェクトスキーマを含む)は、type: string と required: true で translation_key を宣言する必要があります。スキーマ検証は、デフォルトのオブジェクトリストが空の場合でもこれを確認します。別個の schema.identifier: label オプションは、エディタの表示ラベルを選択しますが、翻訳識別子を選択するものではありません。
小文字で始まり、小文字、数字、アンダースコアのみを含む、安定した手動で割り当てられた識別子を使用します。識別子は最大80文字で、各コレクション内で一意である必要があります。翻訳可能な設定名、フィールド名、およびネストされたコレクション名も、小文字で始まり、小文字、数字、アンダースコアのみを含みます。並べ替えは翻訳を保持します。識別子を変更すると、新しい翻訳キーが作成されます。オブジェクトを複製するには、別のキーが必要です。個別のコンポーネントインストールは、独立した名前空間を持ちます。
既存のコンポーネントに翻訳可能なフィールドを追加する際は、カスタマイズされたオブジェクトに有効な translation_key 値を追加する設定マイグレーションを提供してください。コンポーネントのアップデートは、最終的なオブジェクト翻訳キーを検証し、設定マイグレーションが完了した後に翻訳を再構築します。無効な最終キーはアップデートをロールバックします。通常のオブジェクトエディタの保存はすぐに検証されます。保存されたオブジェクト識別子が無効な場合、読み取りパスはオブジェクトのデフォルトを省略するため、ロケールファイルの翻訳とアセットは利用可能のままです。オブジェクト設定の保存とマイグレーションの適用は、引き続き厳密に検証されます。
translatable: true でマークされた文字列フィールドのみが参加します。マークされていないフィールドと translatable: false のフィールドは除外されます。空のオプションフィールドは、そのキーと既存の翻訳を保持します。デフォルトテキストをクリアしても翻訳は削除されません。ネストされたコレクションは、キーにそのプロパティ名を含めるため、個別のコレクションで同じオブジェクト識別子を再利用できます。
デフォルトには、テーマのデフォルトとインポートされた設定が含まれます。デフォルトテキストを変更すると、翻訳が古いとマークされます。デフォルトはオブジェクト設定に残ります。翻訳は、ロケールファイルフィールドと同様に、既存の ThemeTranslationOverride モデルを使用します。別個のテキストレジストリはありません。
オブジェクト、翻訳可能なフィールド宣言、またはロケールファイルキーを削除しても、その保存された翻訳オーバーライドは削除されません。現在のソースを持たないオーバーライドには deprecated ステータスがあり、設定の保存、マイグレーション、およびコンポーネントのアップデートを通じて保持されます。同じ翻訳キーを復元すると、コンポーネントのロールバック後も、保存されたカスタマイズが再利用されます。これにより、オブジェクト翻訳にオプトインしないコンポーネントの既存のロケールファイル翻訳動作が保持されます。削除されたキーは、そのソース宣言が戻るまでサイトテキストにリストされません。
スキーマ変更により、保持されたキーが現在のキーのネスト構造と競合する場合、現在の宣言がランタイム形状を決定します。両方の保存されたオーバーライドは、スキーマがロールバックされた場合に復元のために利用可能のままです。
翻訳を明示的に元に戻すと、そのオーバーライドが削除され、選択されたロケールの出荷時デフォルトが復元されます。コンポーネントを削除すると、そのすべての翻訳オーバーライドが削除されます。
サイトテキストは、編集可能な翻訳と一緒にデフォルトテキストとその言語を表示します。オブジェクトエディタフィールドとロケールファイルに出荷された文字列の両方が、サイトテキストで js.theme_translations.<theme_id>.<key> を使用します。デフォルト追跡が利用可能になる前に保存された翻訳には、不明なベースラインがあり、古いフィルターから除外されます。現在のデフォルトを確認すると、翻訳を変更せずにベースラインが確立されます。オブジェクトフィールドの補間プレースホルダーは、宣言されたソーステキストに対してチェックされ、カスタムソースオーバーライドに対してはチェックされません。複数形は、兄弟の other フォームで宣言されたプレースホルダーを使用できます。ロケールファイルのオーバーライドは、コンポーネントが出荷テキストで使用していないランタイム引数を供給できる可能性があるため、既存の無制限のプレースホルダー動作を保持します。サイトテキストはこれらの引数を無効としてマークしません。
デフォルト追跡は、保存されたオブジェクトフィールドまたは出荷された英語テキストを使用し、英語キーが存在しない場合は選択されたロケールの出荷テキストにフォールバックします。ソースロケールのオーバーライドはこのベースラインを置き換えません。デフォルトの言語が明示的に表示され、ロケールファイルのオーバーライドを元に戻すと、選択されたロケールに出荷されたテキストが復元されます。
設定名は、テーマ内で名前空間を予約します。ロケールファイルはその設定のルートキーをさらに定義することはできません。オブジェクト設定の保存またはテーマの更新は、その競合を拒否します。テキストは、アクティブなテーマとそのコンポーネント(プレビューを含む)に対してのみ、既存のキャッシュされたテーマ翻訳アセットを通じて配信されます。
このドキュメントはバージョン管理されています - 変更は github で提案してください。



