Мы представляем новый 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
```\n
Далее мы добавим ключевое слово `properties` к схеме, которое позволит нам определить и проверить, как должен выглядеть каждый объект.
```yaml
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
В приведенном выше примере мы указываем, что объект link имеет свойство name. Чтобы определить тип ожидаемых данных, каждое свойство должно определять ключевое слово type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
Приведенное выше определение схемы указывает, что объект link имеет свойство name типа string, что означает, что для свойства будут приниматься только строковые значения. В настоящее время поддерживаются следующие типы:
string: Значение свойства хранится как строка.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 3categories: Значение свойства — это массив действительных идентификаторов категорий.groups: Значение свойства — это массив действительных идентификаторов групп.tags: Значение свойства — это массив действительных имен тегов.
После определения схемы значение настройки по умолчанию теперь можно установить, определив массив в 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
Пользовательская валидация
Для определенных типов свойств есть встроенная поддержка пользовательской валидации, которую можно объявить, добавив к свойству ключевое слово validations.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min: 1
max: 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 включает только группы, видимые пользователю.
Добавьте resolve_group_membership: true к свойству groups:
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
Интерфейс администратора и хранимое значение настройки по-прежнему используют исходный массив groups. В объекте settings во время выполнения на стороне клиента Discourse удаляет идентификаторы групп из каждого объекта и добавляет логическое значение с тем же именем свойства с префиксом 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.
Вложенная структура объектов
n
Объект также может иметь свойство, которое содержит массив объектов. Чтобы создать вложенную структуру объектов, свойство также можно пометить 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 со следующим форматом, учитывая следующую настройку темы типа 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
Этот документ находится под контролем версий — предложите изменения на github.
. Это была скорее попытка проверить, возможно ли это, но не разумный подход. Я согласен с вами; было бы здорово иметь прямой способ! 