Space Station 14 Вики

Песочница/Pok/3: различия между версиями

Интерактивная навигация по истории
← Предыдущая правка
ВизуальныйВики-текст
Нет описания правки
Нет описания правки
 
(не показаны 302 промежуточные версии 4 участников)
Строка 1: Строка 1:
<div class="slide__container mw-collapsible mw-collapsed new-collapsed"
{{docpage}}{{TOC hidden}}
style="
{{OnLua|Сущность|module1=Сущность|module2=Сущность/поля|module3=GetField}}
text-align: {{{text-align|center}}};
 
border: {{{border-size|3px}}} solid {{{border-color|#4c4c61}}};
Модульный набор {{tl|Модуль:Сущность}} + {{tl|Модуль:Сущность/поля}} + {{tl|Модуль:GetField}} предназначен для:
border-radius: {{{border-radius|0.3em}}};
* автоматической сборки карточек сущностей (компонентов и прототипов) по их ID;
margin-bottom: {{{margin-bottom|6px}}};
* описания полей в шаблонах компонентов (какие поля идут в карточку, как подписаны);
">
* удобного доступа к данным из JSON (как простыми значениями, так и готовыми вызовами шаблонов).
<div class="slide__title"
 
style="
Ниже описан общий принцип работы и отдельные режимы.
color: {{{color|lightgrey}}};
 
font-size: {{{font-size|1.1em}}};
== Общий принцип работы ==
">{{{title}}}</div>
* В шаблонах компонентов/прототипов (<code>Template:Component/...</code>, <code>Template:prototype/...</code>) через {{tl|Модуль:Сущность/поля}} описываются поля:
<div class="slide__content mw-collapsible-content">{{{content}}}</div>
** '''лейблы''' (<code>cardLabel_*</code>) и '''содержимое''' (<code>cardContent_*</code>), заголовки (<code>title_*</code>) и т. п.;
</div>
** '''мета‑информация''' о том, какие ключи доступны для <code>card</code> / <code>title</code> и в каком порядке.
<!-- Не изменяемый CSS -->
* {{tl|Модуль:Сущность}} по ID сущности:
<div class="customCSS" style="display:none">
** находит связанные с ней компоненты и прототипы по JSON‑данным;
.slide__container {
** для каждого компонента/прототипа читает шаблоны и метаданные;
background: #27272f;
** собирает все поля в единую структуру;
position: relative;
** формирует один вызов карточки <code><nowiki>{{карточка/сущность|...}}</nowiki></code> (и блоки заголовков).
padding: 16px;
* Внутри полей можно писать вики‑параметры <code>{{{...}}}</code> и вызывать дополнительные модули.
text-wrap: pretty;
* {{tl|Модуль:GetField}} даёт доступ к JSON‑данным на низком уровне:
** как «расплющенный» набор параметров (<code>flattenField</code>);
** как отдельные значения (<code>get</code>);
** как готовые вызовы шаблонов с нужными параметрами (<code>getTpl</code>, <code>getTplProto</code>).
 
== Модуль: Сущность/поля ==
Шаблоны компонентов используют модуль <code>Сущность/поля</code> для объявления полей, которые будут собираться в карточку.
 
Пример шаблона компонента:
 
<pre>
{{#invoke:Сущность/поля|main
|cardLabel_Стоимость  = [[Стоимость]]
|cardContent_Стоимость = '''{{{price}}}'''
}}
</pre>
 
Другой компонент может добавлять тот же ключ:
 
<pre>
{{#invoke:Сущность/поля|main
|cardContent_Стоимость  = '''{{{superPrice}}}'''
}}
</pre>
 
Особенности:
* Пара <code>cardLabel_<Ключ></code> / <code>cardContent_<Ключ></code> описывает одну строку карточки (лейбл и содержимое).
* Если несколько шаблонов дают один и тот же <code>cardContent_Ключ</code>, содержимое '''объединяется''', а лейбл берётся первый непустой.
* То же относится к другим режимам, перечисленным в мета‑JSON шаблона (разделы <code>card</code>, <code>title</code> и т. п.), которые читает {{tl|Модуль:Сущность}}.
 
== Модуль: Сущность ==
 
=== p.get: основная сборка карточки ===
Вызов:
 
<pre>
{{#invoke:Сущность|get
| <ID или список ID>
| blacklist=...
| whitelist=...
| ignoreComponents=...
| ignorePrototypes=...
}}
</pre>
 
* '''1‑й параметр''' — <code>id</code> или список <code>id</code> через запятую.
* По этому ID модуль находит:
** '''компоненты''' из <code>component.json</code>;
** '''прототипы''' из <code>prototype.json</code>;
и для каждого — соответствующие шаблоны <code>Template:component/...</code> / <code>Template:prototype/...</code>.
* Шаблоны описывают свои поля через <code>Сущность/поля</code>.
 
После сборки модуль:
* формирует один вызов <code><nowiki>{{карточка/сущность|...}}</nowiki></code> со всеми разделами и полями;
* дополняет выход при необходимости (блоки title и т. п.);
* прогоняет результат через <code>frame:preprocess</code>, чтобы отрендерить разметку.
 
Параметры фильтрации:
* {{пм|blacklist}} — список <code>режим_Ключ</code> через запятую, чтобы исключить поле:
** пример: <code>blacklist=card_Наносит повреждения,title_Что‑то</code>;
* {{пм|whitelist}} — наоборот, список разрешённых <code>режим_Ключ</code>, остальные игнорируются;
* {{пм|ignoreComponents}} / {{пм|ignoreComponent}} — список имён компонентов через запятую, которые полностью игнорируются для этого вызова;
* {{пм|ignorePrototypes}} / {{пм|ignorePrototype}} — аналогично для прототипов.
 
Пример простой сборки (через шаблон‑обёртку):
 
<pre>
{{Сущность/карточка|MyEntityId}}
</pre>
 
где в шаблоне <code>Сущность/карточка</code> внутри:
 
<pre>
{{#invoke:Сущность|get|{{{1}}}}}
</pre>
 
=== p.preview: предпросмотр полей конкретного шаблона ===
Используется для проверки, что компонент/прототип правильно описал свои поля.
 
<pre>
{{#invoke:Сущность|preview
| Component/meleeWeapon
}}
</pre>
 
* Показывает, какие <code>card</code> / <code>title</code>‑поля объявлены в <code>Template:Component/meleeWeapon</code>.
* Удобно при разработке шаблонов компонентов.
 
=== p.jsonList: вывод JSON в виде списка ===
Режим похож на стандартный <code>arraymap</code>, но работает с JSON.
 
<pre>
{{#invoke:Сущность|jsonList
| <json или {{{...}}}>
| type = list / enum
| prefix = *
| sep = :  
| key_pattern = (.*)
| key_replace = \1
| value_pattern = (.*)
| value_replace = \1
}}
</pre>
 
Примеры JSON:
 
<pre> <!-- <syntaxhighlight lang=json> -->
{
  "Blunt": 10,
  "Slash": 5
}
}
.slide__title {
</pre> <!-- </syntaxhighlight> -->
position: relative;
 
z-index: 2;
или
display: inline-block;
 
margin: 0;
<pre> <!-- <syntaxhighlight lang=json> -->
font-family: 'Arial', sans-serif;
["Knife", "Sword", "Bat"]
font-weight: bold;
</pre> <!-- </syntaxhighlight> -->
pointer-events: none;
 
Основные опции:
* {{пм|type}}:
** <code>list</code> — список строк (с префиксом, например <code>* </code>);
** <code>enum</code> — перечисление через запятую (<code>A, B, C</code> без префикса).
* {{пм|prefix}} — префикс строки списка (по умолчанию <code>* </code>).
* {{пм|sep}} — разделитель для <code>ключ: значение</code> (по умолчанию <code>: </code>).
* {{пм|key_pattern}} / {{пм|key_replace}} — regex и замена для ключей.
* {{пм|value_pattern}} / {{пм|value_replace}} — regex и замена для значений.
 
Дополнительно:
* в шаблоне замены поддерживаются:
** <code>\1</code> — собственное значение (ключ или значение);
** <code>\2</code> в <code>value_replace</code> — '''сырой ключ''' (после <code>key_pattern</code>, но до <code>key_replace</code>);
** <code>\2</code> в <code>key_replace</code> — итоговое отформатированное значение (после <code>value_replace</code>).
 
Пример, где сначала форматируем тип урона, а затем подставляем его в описание:
 
<pre>
{{#invoke:Сущность|jsonList
| {{{damage.types}}}
| type = enum
| key_replace = <nowiki>\1</nowiki>              <!-- "Blunt" -->
| value_replace = <nowiki>'''\1''' \2</nowiki>  <!-- "'''10''' Blunt" -->
}}
</pre>
 
=== p.json: превращение JSON в вызовы шаблонов ===
Режим для случаев, когда в JSON лежит список эффектов/объектов, и нужно по каждому вызвать отдельный шаблон.
 
<pre>
{{#invoke:Сущность|json
| <json или {{{...}}}>
| <путь_к_шаблону>
}}
</pre>
 
* '''1‑й параметр / <code>json=</code>''' — строка JSON.
* '''2‑й параметр / <code>template=</code>''' — путь к шаблону, например <code>Component/adjustPlant</code>.
 
Ожидаемый формат JSON‑массива:
 
<pre> <!-- <syntaxhighlight lang=json> -->
[
  {
    "!type:PlantAdjustNutrition": {
      "amount": 0.1
    }
  },
  {
    "!type:PlantAdjustWeeds": {
      "amount": 2
    }
  },
  {
    "!type:PlantAdjustPests": {
      "amount": 2
    }
  }
]
</pre> <!-- </syntaxhighlight> -->
 
Для каждого элемента создаётся вызов:
 
<pre>
{{Component/adjustPlant
|id=!type:PlantAdjustNutrition
|amount=0.1
}}
{{Component/adjustPlant
|id=!type:PlantAdjustWeeds
|amount=2
}}
{{Component/adjustPlant
|id=!type:PlantAdjustPests
|amount=2
}}
</pre>
 
Особенности:
* Если JSON — объект вида <code>{ "id1": {...}, "id2": {...} }</code>, происходит аналогичный проход по парам <code>ключ → объект</code>.
* Все вызовы склеиваются через перевод строки и прогоняются через <code>frame:preprocess</code>, поэтому внутри шаблона можно использовать любую вики‑разметку.
 
== Модуль: GetField ==
Модуль <code>GetField</code> используется для доступа к тем же JSON‑данным <code>.../data</code>, но на более низком уровне.
 
=== p.flattenField: расплющивание записи в параметры ===
<pre>
{{#invoke:GetField|flattenField
| <id>
| <путь_к_json_странице>
}}
</pre>
 
Например:
 
<pre>
{{#invoke:GetField|flattenField
| MyEntityId
| component/item.json
}}
</pre>
 
Возвращает строку вида:
 
<pre>
damage.types={"Blunt":10}|wieldSound=someSound|...
</pre>
 
Особенности:
* Вложенные объекты кодируются в JSON и заворачиваются в <code><nowiki><nowiki></nowiki></code>, чтобы их можно было безопасно передавать как параметр.
* Массивы кодируются в JSON без <code><nowiki><nowiki></nowiki></code>, чтобы удобно обрабатывать их модулями вроде <code>Сущность.jsonList</code>.
 
Этот режим используется внутри <code>GetField.getTpl</code> и других обёрток.
 
=== p.get: получение значения по пути ===
<pre>
{{#invoke:GetField|get
| <id или пусто для "default">
| <путь_к_json_странице>
| <ключ.с.точками>
}}
</pre>
 
Примеры:
 
<pre>
{{#invoke:GetField|get
| MyEntityId
| component/item.json
| damage.types
}}
</pre>
 
Если в JSON:
 
<pre> <!-- <syntaxhighlight lang=json> -->
"damage": {
  "types": {
    "Blunt": 10
  }
}
}
.slide__content {
</pre> <!-- </syntaxhighlight> -->
padding-top: 32px;
 
text-align: left;
то результатом будет:
}
 
.new-collapsed .mw-collapsible-toggle {
<pre>
position: absolute;
{"Blunt":10}
top: 0;
</pre>
left: 0;
 
bottom: 0;
то есть:
right: 0;
* для таблиц модуль пытается сделать <code>mw.text.jsonEncode(v)</code> и вернуть JSON‑строку;
width: 100%;
* для простых значений возвращается строка <code>tostring(v)</code>.
height: 100%;
 
padding: 16px !important;
Если <code>keyPath</code> пуст, возвращается весь объект (как JSON).
text-align: center;
 
box-sizing: border-box;
=== p.getTpl: вызов шаблона по данным JSON ===
display: flex;
<pre>
align-content: center;
{{#invoke:GetField|getTpl
justify-content: flex-end;
| <id>
align-items: center;
| <путь_к_json_странице>
transition: background-color 0.2s;
| <путь_к_шаблону>
line-height: 40px;
}}
}
</pre>
.new-collapsed .mw-collapsible-toggle:hover {
 
background-color: #23232b;
Пример:
}
 
.new-collapsed .mw-collapsible-text {
<pre>
display: none;
{{#invoke:GetField|getTpl
}
| MyEntityId
.new-collapsed .mw-collapsible-title {
| component/item.json
| Component/meleeWeapon
}}
</pre>
 
Работа:
* внутри вызывает <code>flattenField</code>, получая строку <code>key=value|...</code>;
* формирует строку вида:
 
<pre>
{{Component/meleeWeapon
|id=MyEntityId
|damage.types=...
|...
}}
</pre>
 
* и прогоняет её через <code>frame:preprocess</code>, возвращая итоговый рендер.
 
Это удобный способ «подключить» шаблон компонента к данным из JSON без ручного перечисления параметров.
 
=== p.getTplProto: вызов шаблона по прототипам ===
<pre>
{{#invoke:GetField|getTplProto
| <searchId>
| <protoId>
| <путь_к_шаблону>
}}
</pre>
 
* Ищет в <code>prototype.json</code> все записи, где <code>protoId</code> встречается у <code>searchId</code>.
* Для каждого найденного ID вызывает <code>getTpl</code> и возвращает все вызовы, склеенные через перевод строки и отрендеренные.
 
Используется для случаев, когда сущность использует '''несколько''' прототипов одного типа, и нужно вывести по одному шаблону на каждый прототип.


}
== Типичный рабочий поток ==
.new-collapsed .mw-collapsible-toggle:before {
# В JSON‑файлах (<code>component.json</code>, <code>prototype.json</code> и др.) описываются сущности и связи компонент/прототипов.
content: '+';
# Для каждого компонента/прототипа создаются шаблоны <code>Template:Component/...</code>, <code>Template:prototype/...</code>, которые:
color: #616bb9;
#* вызывают <code><nowiki>{{#invoke:Сущность/поля|main ...}}</nowiki></code> для описания полей карточки;
font-weight: bold;
#* при необходимости используют <code>GetField</code> / <code>Сущность.jsonList</code> / <code>Сущность.json</code> для форматирования сложных JSON‑полей.
font-size: 40px;
# Для вывода карточки на странице сущности используется:
margin-bottom: 8px;
#* либо прямой <code><nowiki>{{#invoke:Сущность|get|MyEntityId}}</nowiki></code>,
text-decoration: none !important;
#* либо шаблон‑обёртка <code><nowiki>{{Сущность/карточка|MyEntityId}}</nowiki></code>.
border: none !important;
# Для специализированных списков/таблиц:
}
#* <code>Сущность.jsonList</code> — если нужно красиво показать массив/словарь из JSON;
.new-collapsed .mw-collapsible-toggle:hover:before {
#* <code>Сущность.json</code> — если нужно превратить список эффектов в набор вызовов шаблона;
color: #727dcb;
#* <code>GetField.get</code> — если нужно точечно вытащить одно поле;
}
#* <code>GetField.getTpl</code> / <code>getTplProto</code> — если нужно строить шаблоны по данным JSON автоматически.
.mw-collapsible:not(.mw-collapsed) .mw-collapsible-toggle:before {
content: '-';
}
.new-collapsed .mw-collapsible-title:hover + .mw-collapsible-content {
display: block;
}
.new-collapsed .mw-collapsible.mw-collapsed .mw-collapsible-content {
display: none;
}
.new-collapsed .mw-collapsible:not(.mw-collapsed) .mw-collapsible-content {
display: block;
}
.new-collapsed.mw-collapsible:not(.mw-collapsed) .mw-collapsible-toggle {
background-color: #22222b;
}
.new-collapsed.mw-collapsible:not(.mw-collapsed) .mw-collapsible-toggle {
height: 58px !important;
box-shadow: 0px 2px 4px 0px rgba(0, 0, 0, 0.5) !important;
}
.new-collapsed .mw-collapsible:not(.mw-collapsed) .mw-collapsible-toggle:after {
display: none;
}
.new-collapsed .mw-collapsible-toggle:after {
display: none;
}
.new-collapsed .mw-collapsed .mw-collapsible-toggle:after {
display: none;
}
.new-collapsed .mw-collapsible:not(.mw-collapsed) .mw-collapsible-toggle:after {
display: none;
}
</div>
Источник — https://station14.ru/wiki/Песочница/Pok/3