# Добавление настроек в тему Discourse **URL:** https://meta.discourse.org/t/add-settings-to-your-discourse-theme/82557 **Category:** Developer Guides **Tags:** how-to, theme-guides **Created:** [08.Март.2018 22:28:58 UTC](https://meta.discourse.org/t/add-settings-to-your-discourse-theme/82557 "2018-03-08T22:28:58Z") **Posts on this page:** 7 **Page:** 1
### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse) #### Post date: [08.Март.2018 22:28:59 UTC](https://meta.discourse.org/t/add-settings-to-your-discourse-theme/82557/1 "2018-03-08T22:28:59Z")
Discourse позволяет темам иметь «настройки», которые разработчики тем могут добавлять, чтобы владельцы сайтов могли настраивать темы через интерфейс, не изменяя ни одной строки кода и не беспокоясь о потере изменений при будущих обновлениях темы. Темы также могут изменять определенные настраиваемые параметры сайта. Для получения дополнительной информации см. тему [Настраиваемые параметры сайта](https://meta.discourse.org/t/-/374376). ## ➕ Добавление настроек в вашу тему Добавление настроек в тему немного отличается от добавления кода CSS и JS: это невозможно сделать через интерфейс. Способ добавить настройки — создать [репозиторий для вашей темы](https://meta.discourse.org/t/how-to-develop-custom-themes/60848?u=osama) и в корневой папке вашего репозитория создать новый файл `settings.yaml` (или `settings.yml`). В этом файле вы будете использовать язык [YAML](https://en.wikipedia.org/wiki/YAML) для определения настроек вашей темы. > 📢 **Примечание:** Вам может пригодиться использование [Theme CLI](https://meta.discourse.org/t/discourse-theme-cli-console-app-to-help-you-build-themes/82950?u=osama), которое значительно упрощает процесс разработки. Если вы знакомы с разработкой плагинов, это не будет для вас новостью — в основном это работает так же, как добавление параметров сайта в ваш плагин. Просто добавьте валидный YAML в файл настроек, и всё будет готово. Валидная настройка темы должна иметь имя и значение по умолчанию. Это минимальный необходимый набор, и он выглядит так: ```yaml simple_setting: true ``` Как вы, вероятно, догадались, это создаст настройку с именем `simple_setting`, и её значением по умолчанию будет `true`. Аналогичным образом, вы можете добавить что-то вроде этого: ```yaml site_name: My Forums max_avatars: 7 ``` И у вас появится две дополнительные настройки: `site_name`, которая будет строковой настройкой со значением по умолчанию “My Forums”, и `max_avatars` как целочисленная настройка со значением по умолчанию 7. ![image](https://global.discourse-cdn.com/meta/original/4X/f/1/8/f184f8f16a50a7e3c15efc462e1f07b6dbada223.jpeg) Вы можете обращаться к своим настройкам в JS-коде так: `settings.your_setting_key`. Таким образом, до этого момента мы рассмотрели самый простой способ определения настроек. В следующем разделе мы подробнее рассмотрим различные типы настроек и то, как их можно использовать. ## 🔣 Поддерживаемые типы Существует 9 типов настроек: 1. `integer` 2. `float` 3. `string` 4. `bool` (для логических значений) 5. `list` 6. `enum` 7. `objects` (замена для `json_schema`) 8. `upload` (для изображений) 9. `icon` (для одной иконки из набора иконок Discourse) И вы можете указать тип, добавив атрибут `type` к вашей настройке, как здесь: ```yaml float_setting: type: float default: 3.14 ``` Следует отметить, что вам не всегда нужно явно устанавливать атрибут `type`, потому что Discourse достаточно умный, чтобы определить тип настройки по её значению по умолчанию. Поэтому вы можете сократить приведенный выше пример до такого: ```yaml float_setting: default: 3.14 ``` Тем не менее, вы _должны_ установить атрибут типа при работе с настройками **`list`** , **`enum`** и **`icon`** , иначе Discourse не распознает их правильно. **Настройка списка (List Setting):** ```yaml whitelisted_fruits: default: apples|oranges type: list ``` **Настройка перечисления (Enum Setting):** ```yaml favorite_fruit: default: orange type: enum choices: - apple - banana ``` ![image](https://global.discourse-cdn.com/meta/original/4X/8/f/3/8f3a9f54ad0312a9435d9559eadeeeb9978f5145.jpeg) Если разница между настройками списка и перечисления вам не ясна: настройки перечисления позволяют пользователям вашей темы выбирать только _одно_ значение из набора значений, определенных вами (см. атрибут `choices`). С другой стороны, настройки списка позволяют вашим пользователям создавать собственный _список_ (т.е. массив) значений. Они могут добавлять в список значений по умолчанию настройки или удалять из него. Вы можете установить список значений по умолчанию для настройки, соединив значения символом вертикальной черты |. См. настройку списка в примере выше. Вы можете увидеть реальный пример использования настроек списка здесь: [Auto-Linkify Words](https://meta.discourse.org/t/linkify-words-in-post-theme-component/82193?u=osama). > 📢 **Примечание** : Обращайте внимание на отступы при работе с YAML, так как YAML очень чувствителен к пробелам и выдаст ошибку синтаксиса, если отступы в вашем коде неверны. **Настройка иконки (Icon Setting):** ```yaml banner_icon: default: bullhorn type: icon ``` Настройки иконки предоставляют владельцам сайтов поисковую панель выбора иконок, а значением является имя иконки. Discourse добавляет выбранную иконку в спрайт-лист, поэтому вы можете отобразить её в своей теме, не регистрируя её отдельно. ### Тип `objects` Тип настройки `objects` — это специальный тип, который позволяет вам создавать продвинутые настройки с настраиваемой структурой и валидациями. Для этого типа есть [отдельная документация](https://meta.discourse.org/t/objects-type-for-theme-setting/305009). ## 🔠 Описание настроек и локализация Вы можете добавить текст описания к настройке темы, и он будет отображаться как метка непосредственно под настройкой. Для этого просто добавьте атрибут `description` к вашей настройке, как здесь: ```yaml whitelisted_fruits: default: apples|oranges type: list description: "Этот текст будет отображаться под этой настройкой и объяснять, что она делает!" ``` И вы получите это: ![image](https://global.discourse-cdn.com/meta/original/4X/6/3/4/634e39cb47a710b98844f08b871563f8c283a651.jpeg) ### Поддержка нескольких языков Если вы знаете более одного языка и хотите добавить поддержку этих языков в вашу тему, вы можете сделать это, при условии, что Discourse поддерживает эти языки. Прежде всего, убедитесь, что язык, который вы хотите поддерживать, есть в этом списке: > **Список языков** > > | Код | | | | Название | > | --- | --- | --- | --- | --- | > | ar | | | | اللغة العربية | > | bs\_BA | | | | bosanski jezik | > | ca | | | | català | > | cs | | | | čeština | > | da | | | | dansk | > | de | | | | Deutsch | > | el | | | | ελληνικά | > | en | | | | English | > | es | | | | Español | > | et | | | | eesti | > | fa\_IR | | | | فارسی | > | fi | | | | suomi | > | fr | | | | Français | > | gl | | | | galego | > | he | | | | עברית | > | id | | | | Indonesian | > | it | | | | Italiano | > | ja | | | | 日本語 | > | ko | | | | 한국어 | > | lv | | | | latviešu valoda | > | nb\_NO | | | | Norsk bokmål | > | nl | | | | Nederlands | > | pl\_PL | | | | język polski | > | pt | | | | Português | > | pt\_BR | | | | Português (BR) | > | ro | | | | limba română | > | ru | | | | Русский | > | sk | | | | slovenčina | > | sq | | | | Shqip | > | sr | | | | српски језик | > | sv | | | | svenska | > | te | | | | తెలుగు | > | th | | | | ไทย | > | tr\_TR | | | | Türkçe | > | uk | | | | українська мова | > | ur | | | | اردو | > | vi | | | | Việt Nam | > | zh\_CN | | | | 中文 | > | zh\_TW | | | | 中文 (TW) | (Если вы не видите свой язык в списке, возможно, вам стоит взглянуть на [How to add a new language](https://meta.discourse.org/t/how-to-add-a-new-language/14970?u=osama)) Затем вам нужно найти код вашего языка из списка выше и использовать код языка как ключ под атрибутом `description`, а перевод как значение для этого ключа, как здесь: ```yaml whitelisted_fruits: default: apples|oranges type: list description: en: English text ar: نص باللغة العربية fr: Texte français ``` И теперь у вас есть поддержка 3 языков: английского, арабского и французского. ## Дополнительные атрибуты и опции настроек ### Атрибуты Min и max Иногда вам может потребоваться указать ограничения, которые значение настройки не может превышать, чтобы предотвратить случайное разрушение темы или, возможно, всего сайта пользователями. Чтобы указать ограничения, просто добавьте атрибут `min` или `max` или оба к вашей настройке, как здесь: ```yaml integer_setting: default: 10 min: 5 max: 100 ``` Вы можете указать ограничения для настроек типа `integer`, `float` и `string`. Для настроек `integer` и `float` само значение настройки проверяется на соответствие ограничениям. А для настроек `string` длина значения проверяется на соответствие указанным ограничениям. Если ваш пользователь попытается ввести значение, выходящее за пределы допустимого диапазона, он увидит сообщение об ошибке с указанием минимального и максимального значений. ### Доступ к настройкам в вашем JS/CSS/Handlebars Настройки темы доступны глобально как переменная `settings` в файлах JavaScript темы. Например: ```gjs // {theme}/javascripts/discourse/api-initializers/init-theme.gjs import { apiInitializer } from "discourse/lib/api"; export default apiInitializer((api) => { console.log("settings are", settings); }); ``` Этот объект `settings` также можно использовать как обычный внутри тегов `