我们引入了一种新的 type: objects 作为主题设置的受支持类型之一,可用于替代我们计划不久后弃用的现有 json_schema 类型。
定义对象类型主题设置
要创建对象类型主题设置,首先像定义其他主题设置一样,定义一个顶级键,它将用作设置名称。
links: ...
接下来,为设置添加 type、default 和 schema 关键字。
links:
type: objects
default: []
schema: ...
type: 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 图标集中的单个图标名称。选定的图标会自动添加到精灵图(sprite sheet)中,因此无需单独注册即可渲染。
通过 API 更新对象主题设置时,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) {
// User is in at least one selected group for this section.
}
}
此选项仅对 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: 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
可翻译的对象文本
声明一个名为 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。
具有可翻译字段(包括其祖先对象模式)的模式,必须声明 translation_key 为 type: string 和 required: true。即使默认对象列表为空,模式验证也会检查这一点。独立的 schema.identifier: label 选项选择编辑器显示标签;它不选择翻译标识符。
使用稳定的、手动分配的标识符,以小写字母开头,仅包含小写字母、数字和下划线。标识符必须最多 80 个字符长,且在每个集合中唯一。可翻译的设置名称、字段名称和嵌套集合名称也以小写字母开头,仅包含小写字母、数字和下划线。重新排序会保留翻译。重命名标识符会创建新的翻译键;复制对象需要不同的键。独立的组件安装具有独立的命名空间。
向现有组件添加可翻译字段时,请提供设置迁移,为自定义对象添加有效的 translation_key 值。组件更新在设置迁移完成后验证最终对象翻译键并重建其翻译。无效的最终键会回滚更新。普通对象编辑器保存会立即验证。如果保存的对象标识符无效,读取路径会省略对象默认值,以便语言环境文件翻译和资源保持可用;保存对象设置和应用迁移仍严格验证。
只有标记为 translatable: true 的字符串字段参与。未标记的字段和标记为 translatable: false 的字段被排除。空的可选字段保留其键和现有翻译。清除默认文本不会删除翻译。嵌套集合在其键中包含其属性名称,因此独立的集合可以重用相同的对象标识符。
默认值包括主题默认值和导入的设置。更改默认文本会标记翻译为过期。默认值保留在对象设置中;翻译使用现有的 ThemeTranslationOverride 模型,就像语言环境文件字段一样。没有单独的文本注册表。
删除对象、可翻译字段声明或语言环境文件键不会删除其保存的翻译覆盖。没有当前源的覆盖具有 deprecated 状态,并在设置保存、迁移和组件更新中保留。恢复相同的翻译键会重用保存的自定义内容,包括在组件回滚后。这为不选择加入对象翻译的组件保留了现有的语言环境文件翻译行为。在源声明恢复之前,删除的键不会列在站点文本中。
如果模式更改使保留的键与当前键的嵌套结构冲突,当前声明决定运行时形状。如果模式回滚,两个保存的覆盖仍可用于恢复。
明确恢复翻译仍会删除该覆盖并为选定的语言环境恢复随附的默认值。删除组件会删除其所有翻译覆盖。
站点文本显示默认文本及其语言以及可编辑的翻译。对象编辑器字段和随语言环境文件打包的字符串在站点文本中都使用 js.theme_translations.<theme_id>.<key>。在默认跟踪可用之前保存的翻译具有未知基线,并被排除在过期过滤器之外。确认当前默认值会建立基线而不更改翻译。对象字段插值占位符根据声明的源文本检查,而不是自定义源覆盖。复数形式可以使用其同级 other 形式声明的占位符。语言环境文件覆盖保持其现有的不受限制的占位符行为,因为组件可以提供其随附文本未使用的运行时参数。站点文本不会将这些参数标记为无效。
默认跟踪使用保存的对象字段或随附的英文文本,当没有英文键时,回退到选定语言环境的随附文本。源语言环境覆盖不会替换此基线。默认值的语言显示为明确;恢复语言环境文件覆盖仍会恢复为选定语言环境随附的文本。
设置名称在主题中保留一个命名空间。语言环境文件不能也定义该设置的根键:保存对象设置或更新主题会拒绝冲突。文本仅通过现有的缓存主题翻译资源为活动主题及其组件(包括预览)提供。
此文档采用版本控制 - 请在 github 上建议更改。



