用于主题设置的对象类型

我们引入了一种新的 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 上建议更改。

16 个赞

我仍然不相信弃用 json schema 风格是个好主意。

虽然这些可能变得相当复杂,而且不是最“开发者友好”的格式(所以在这方面这是一个巨大的改变),但有在线工具可以验证 json schema,这是一种非常有用的方式来验证 schema 本身以及针对任何默认数据。

例如 https://www.jsonschemavalidator.net/

在这个新世界里,那将如何运作?

2 个赞

上传主题时,我们将根据定义的模式验证默认数据。话虽如此,我们现在不验证模式定义是否有效,但要做到这一点并不难。即使是现在的 json 模式设置,我认为我们也没有根据定义的模式验证默认数据。

我们目前 json 模式类型设置的实现方式在很多方面都有些问题,最明显的是管理界面中的编辑器。我们内部讨论过,并决定我们维护一个由我们定义的有限模式格式比允许 json 模式带来的所有可能性要容易得多。

2 个赞

这里有一些很酷的功能:

  • 您可以摆脱 JSON.parse 并直接访问设置以获取对象,这真的很棒。

  • URL 验证器!

:chefs_kiss: :chefs_kiss:

5 个赞

编辑器是否可以保留多行?

默认 可以:

- name: markdown
  value: > 
    ## Heading
      * first bullet
      * second bullet

但一旦你编辑了它,回车符就会丢失

此外,最好有一个“text”类型,可以存储更长格式的数据,并可能暴露一个更大的“textarea”编辑器。

5 个赞

以下是一些反馈:

2 个赞

我注意到了这一点,它已在以下位置修复:

1 个赞

我们能否在界面上重新排序项目?

例如,这是 easy footer 主题组件上的对象设置编辑器。我现在无法重新排列任何项目:

4 个赞

我也想请求此功能!:+1:


另外,首帖包含有关 identifier 属性的信息会很有帮助。

在查看上面 Nolo 的图片之前,我认为无法用属性值替换默认的子标签。查看代码后,我找到了 identifier 属性。

4 个赞

重新排序当然是我们内部也提出过的一个功能。我本周会尝试实现它。

知道了。我将更新首帖关于 identifier 属性的信息。

5 个赞

是的,要替换(即将成为遗留的?)json 系统,它需要匹配或超过旧接口:

包括排序。

1 个赞

您好,有计划很快支持其他字段类型吗?

例如:

  • 支持 markdown 格式的 long_string;也许带有可自定义的工具栏,
  • date 字段(带验证规则),
  • color 字段(带验证规则)?
1 个赞

目前还没有计划,尽管我同意这会很有用。我个人想要一个 icon 字段。

8 个赞

根据我的经验,这似乎就像保存的预设一样工作。在此示例中,前 2 个条目可以受益于这些预设,但之后的所有新条目最初都会显示为空白。

这意味着我们也无法为每个字段设置默认值。例如,如果我希望一个复选框一开始就处于选中状态,这是无法实现的。

links:
  type: objects
  default:
    - name: link 1
      title: link 1 title
    - name: link 2
      title: link 2 title
  schema:
    name: link
    properties:
      is_active:
        type: boolean
        default: true

default: true 在那里无法按预期工作。

是否有办法为每个创建的条目设置每个字段的默认值?

在 Sass 中有办法将对象属性导入变量吗?

你可以随时解析字符串,但这听起来不是一个好主意。:sweat_smile:

1 个赞

谢谢分享示例!不过是的……它看起来并不那么诱人 :upside_down_face:

1 个赞

顺便问一下,不用花太多时间看,我们在这方面进展如何?

2 个赞

是的,这不太好,不要这样做。 :smile: 这更多是尝试看看是否可行,而不是一个合理的方法。
我同意你;有一个直接的方法会很好! :+1:

我也想知道!
另外,如果我没记错的话,这将是与 json_schema 唯一缺失的功能奇偶校验。

2 个赞

我一直在寻找上传类型可用,但它不可用。
快速查看核心,发现主题、帖子和上传类型已在服务器端实现,但未在前台实现。有什么特别的原因吗?:thinking: