@seafteam/seaf-archtool-core-plugin-suite 2026.32.0 → 2026.33.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/documentation/arch/aspects.yaml +0 -0
- package/documentation/arch/contexts.yaml +0 -0
- package/documentation/arch/forms.yaml +0 -0
- package/documentation/arch/namespaces.yaml +0 -0
- package/documentation/arch/root.yaml +0 -0
- package/documentation/arch/technologies.yaml +0 -0
- package/documentation/dochub.yaml +0 -0
- package/documentation/docs/conception/root.yaml +0 -0
- package/documentation/docs/manual/config/deployment.md +48 -0
- package/documentation/docs/manual/docs/docs.md +1 -0
- package/documentation/docs/manual/docs/drawio_intro.md +95 -3
- package/documentation/docs/manual/docs/editable_table/root.yaml +2 -1
- package/documentation/docs/manual/docs/editable_table/step_0_base/table.yaml +7 -0
- package/documentation/docs/manual/docs/editable_table/step_0_base/template.md +7 -0
- package/documentation/docs/manual/docs/editable_table/step_3_headers/data/markdown_preview.yaml +15 -0
- package/documentation/docs/manual/docs/editable_table/step_3_headers/root.yaml +64 -0
- package/documentation/docs/manual/docs/editable_table/step_3_headers/template.md +23 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/examples/global_search/data.yaml +58 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/examples/global_search/menu.yaml +5 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/examples/global_search/root.yaml +4 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/examples/global_search/table.yaml +48 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/examples/global_search/template.md +130 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/examples/root.yaml +2 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/menu.yaml +5 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/root.yaml +3 -0
- package/documentation/docs/manual/docs/editable_table/step_7_search/template.md +57 -0
- package/documentation/docs/manual/docs/examples/excel.yaml +41 -0
- package/documentation/docs/manual/docs/examples/object_header.md +5 -0
- package/documentation/docs/manual/docs/examples/table.yaml +27 -0
- package/documentation/docs/manual/docs/excel.md +484 -0
- package/documentation/docs/manual/docs/markaper.md +96 -0
- package/documentation/docs/manual/docs/markdown.md +28 -0
- package/documentation/docs/manual/docs/root.yaml +13 -0
- package/documentation/docs/manual/docs/seaf2drawio/seaf2drawio.md +13 -0
- package/documentation/docs/manual/docs/tables.md +104 -0
- package/documentation/docs/manual/jsonata.md +54 -0
- package/documentation/docs/manual/plugins/interface.md +7 -0
- package/documentation/docs/manual/plugins/introduction.md +35 -5
- package/documentation/docs/manual/plugins/root.yaml +0 -0
- package/documentation/docs/manual/root.yaml +0 -0
- package/documentation/docs/manual/rules/root.yaml +0 -0
- package/documentation/docs/root.yaml +0 -0
- package/documentation/entities/extentions/entity.yaml +0 -0
- package/documentation/entities/interactions/entity.yaml +0 -0
- package/documentation/root.yaml +0 -0
- package/package.json +1 -1
- package/plugin.html +1751 -4
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Поиск
|
|
2
|
+
|
|
3
|
+
Кроме фильтров в каждой колонке, в редактируемой таблице можно включить одно поле поиска сразу по всем видимым колонкам. Оно похоже на поиск в обычной таблице, но ищет по отображаемому тексту ячеек, а не по хранимым значениям.
|
|
4
|
+
|
|
5
|
+
## Как включить
|
|
6
|
+
|
|
7
|
+
Поиск выключен по умолчанию. Чтобы его включить, добавьте в корень описания таблицы флаг `global_search`:
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
global_search: true
|
|
11
|
+
# global_search - Отображение поля глобального поиска по всем видимым колонкам
|
|
12
|
+
# Дефолтное значение: false
|
|
13
|
+
# Допустимые значения: true / false
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Флаг не зависит от `filtration`: поиск работает и в таблице, где фильтры колонок отключены (`filtration: false`).
|
|
17
|
+
Поле поиска появляется в панели действий над таблицей.
|
|
18
|
+
|
|
19
|
+
## Как работает поиск
|
|
20
|
+
|
|
21
|
+
- Строка остаётся видимой, если запрос встречается как часть текста хотя бы в одной видимой колонке. Регистр букв не учитывается, «ё» и «е» не различаются: запрос `отчет` находит «Отчётность».
|
|
22
|
+
- Запрос сравнивается с **отображаемым** текстом ячейки, а не с хранимым значением:
|
|
23
|
+
- `text` — значение ячейки (для `render: markdown` — исходный текст разметки);
|
|
24
|
+
- `select` и `multiple-select` — текст варианта (`text`), а не его идентификатор (`value`). Например, значение `opt_1` с вариантом `{ value: opt_1, text: Активен }` находится по запросу `актив`, но не по запросу `opt_1`;
|
|
25
|
+
- для списка по условию (`option_id`) — текст варианта из группы этой строки, как в ячейке. Если значения нет в группе строки, ячейка его не показывает, и по этой колонке строка не находится;
|
|
26
|
+
- `link` и `upload` — текст ссылки, а если его нет — адрес (`href`);
|
|
27
|
+
- `fn` — только уже вычисленное значение. Значение колонки `fn` вычисляется, когда ячейка отрисована на экране, и для поиска отдельно не вычисляется. Поэтому строки с ещё не открытых страниц по колонке `fn` не находятся;
|
|
28
|
+
- `checkbox` в поиске не участвует;
|
|
29
|
+
- ячейка с ошибкой данных (`show_data_error: true`) в поиске не участвует: она показывает «Ошибка», а не исходное значение.
|
|
30
|
+
- Скрытые колонки (`display: false`) в поиске не участвуют. Колонки с `filterable: false` участвуют: этот флаг относится только к фильтру колонки.
|
|
31
|
+
- Поддерживается только поиск по подстроке, регулярные выражения не поддерживаются. Пустой запрос или запрос из одних пробелов поиск не включает.
|
|
32
|
+
- Результат пересчитывается с небольшой задержкой после окончания ввода. Esc, крестик в поле и кнопка «Сбросить» очищают запрос сразу; после Esc и крестика курсор остаётся в поле.
|
|
33
|
+
- Новая, ещё не сохранённая строка остаётся видимой, даже если не совпадает с запросом, — но только до следующего изменения запроса, фильтров или сортировки. После такого изменения она проверяется поиском наравне с остальными строками.
|
|
34
|
+
- Если после правки строка перестала совпадать с запросом, она исчезает с экрана, как и при фильтрах колонок.
|
|
35
|
+
|
|
36
|
+
## Поиск и фильтры колонок
|
|
37
|
+
|
|
38
|
+
Поиск сочетается с фильтрами колонок по «И»: видны только строки, которые проходят и фильтры, и поиск. Сортировка сохраняется, а пагинация считается по найденным строкам. При смене запроса открывается первая страница.
|
|
39
|
+
|
|
40
|
+
Запрос хранится вместе с фильтрами, сортировкой и текущей страницей: после перезагрузки страницы в той же сессии браузера он восстанавливается. Кнопка «Сбросить» сбрасывает и фильтры колонок, и запрос поиска. Кнопка подсвечивается, когда задан фильтр колонки или непустой запрос.
|
|
41
|
+
|
|
42
|
+
## Массовые операции и выгрузка
|
|
43
|
+
|
|
44
|
+
Массовые операции работают только по найденным строкам:
|
|
45
|
+
|
|
46
|
+
- «Выбрать все» (чекбокс в заголовке при `selection: true`) выделяет только строки, прошедшие поиск и фильтры;
|
|
47
|
+
- «Заполнить выделенное» меняет только выделенные строки;
|
|
48
|
+
- выгрузка в Excel при `excel_export_filter: true` содержит только найденные строки;
|
|
49
|
+
- выделенными остаются только видимые строки: строка, которую скрыли поиск, фильтр колонки или правка значения, снимается с выделения. Поэтому «Удалить» и «Заполнить выделенное» не действуют на невидимые строки.
|
|
50
|
+
|
|
51
|
+
## Пример
|
|
52
|
+
|
|
53
|
+
Попробуйте ввести в поле поиска `актив` (текст варианта «Активен» в колонке «Статус») или `wiki` (текст ссылки). Запрос `opt_1` — идентификатор варианта — строки не найдёт.
|
|
54
|
+
|
|
55
|
+

|
|
56
|
+
|
|
57
|
+
Описание таблицы и данных приведено в разделе «1. Глобальный поиск».
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
docs:
|
|
2
|
+
archtool.example.excel.export:
|
|
3
|
+
title: Документ с типом excel-export
|
|
4
|
+
type: excel-export
|
|
5
|
+
file_name: >
|
|
6
|
+
("Шаблон_компонентов.xlsx")
|
|
7
|
+
button_text: >
|
|
8
|
+
("Скачать шаблон")
|
|
9
|
+
options:
|
|
10
|
+
show-grid-lines: false
|
|
11
|
+
margin-left: 3.5
|
|
12
|
+
margin-top: 10.5
|
|
13
|
+
table:
|
|
14
|
+
headers:
|
|
15
|
+
height: 28.5
|
|
16
|
+
pages:
|
|
17
|
+
- name: Компоненты
|
|
18
|
+
title: Перечень компонентов
|
|
19
|
+
description: Заполните таблицу и загрузите файл через документ excel-import
|
|
20
|
+
components:
|
|
21
|
+
- type: table
|
|
22
|
+
name: components
|
|
23
|
+
headers:
|
|
24
|
+
- value: ID
|
|
25
|
+
- value: Название
|
|
26
|
+
- value: Критичность
|
|
27
|
+
type: select
|
|
28
|
+
options:
|
|
29
|
+
- Высокая
|
|
30
|
+
- Средняя
|
|
31
|
+
- Низкая
|
|
32
|
+
source: >
|
|
33
|
+
(
|
|
34
|
+
{
|
|
35
|
+
"body": [
|
|
36
|
+
["", "", ""],
|
|
37
|
+
["", "", ""],
|
|
38
|
+
["", "", ""]
|
|
39
|
+
]
|
|
40
|
+
}
|
|
41
|
+
)
|
|
@@ -44,6 +44,33 @@ docs:
|
|
|
44
44
|
payload: Значение 1 # Значение поля "id"
|
|
45
45
|
- id: 2
|
|
46
46
|
payload: Значение 2
|
|
47
|
+
archtool.table.status: # Табличный документ с колонкой статуса
|
|
48
|
+
type: table
|
|
49
|
+
headers:
|
|
50
|
+
- value: title
|
|
51
|
+
text: Система
|
|
52
|
+
align: left
|
|
53
|
+
- value: status
|
|
54
|
+
text: Статус
|
|
55
|
+
align: left
|
|
56
|
+
format: status # Выводить значение чипом статуса
|
|
57
|
+
statuses: # Значение -> оттенок чипа: ok, wip, off, bad
|
|
58
|
+
Используется: ok
|
|
59
|
+
Создается: wip
|
|
60
|
+
Выводится: off
|
|
61
|
+
Не поддерживается: bad
|
|
62
|
+
source:
|
|
63
|
+
- title: CRM
|
|
64
|
+
status: Используется
|
|
65
|
+
- title: Мобильное приложение
|
|
66
|
+
status: Создается
|
|
67
|
+
- title: Старый портал
|
|
68
|
+
status: Выводится
|
|
69
|
+
- title: Учетная система
|
|
70
|
+
status: Не поддерживается
|
|
71
|
+
- title: Аналитика
|
|
72
|
+
status: Планируется # Нет в statuses — нейтральный чип
|
|
73
|
+
|
|
47
74
|
archtool.table.select: # Табличный документ на основании запроса к данным архитектуры
|
|
48
75
|
type: table
|
|
49
76
|
headers:
|
|
@@ -0,0 +1,484 @@
|
|
|
1
|
+
# Экспорт и импорт Excel (excel-export, excel-import)
|
|
2
|
+
|
|
3
|
+
Для обмена данными архитектуры с возможностью конвертации в Microsoft Excel предусмотрены два типа документов:
|
|
4
|
+
- **excel-export** — формирует Excel-файл (книгу) по описанию в манифесте и сохраняет его на компьютер пользователя. Используется для выгрузки данных архитектуры в отчёт или для подготовки шаблона, который затем заполняется вручную;
|
|
5
|
+
- **excel-import** — загружает заполненный Excel-файл, извлекает данные из именованных таблиц, преобразует их JSONata-выражением и сохраняет результат в YAML-файл репозитория архитектуры.
|
|
6
|
+
|
|
7
|
+
Типы удобно использовать в паре: **excel-export** формирует шаблон с пустыми таблицами, пользователь заполняет его в Excel, а **excel-import** забирает данные обратно в архитектурный код.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
┌──────────────┐ Сохранить шаблон ┌────────────┐ Загрузить Excel ┌──────────────┐
|
|
11
|
+
│ excel-export │ ─────────────────► │ .xlsx файл │ ────────────────► │ excel-import │ ──► output.yaml
|
|
12
|
+
└──────────────┘ └────────────┘ └──────────────┘
|
|
13
|
+
заполнение в Excel
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Где работает
|
|
17
|
+
|
|
18
|
+
| Тип документа | Портал (браузер) | Плагин IntelliJ IDEA | Плагин VS Code |
|
|
19
|
+
|---|---|---|---|
|
|
20
|
+
| excel-export | да | да | да |
|
|
21
|
+
| excel-import | нет | да | да |
|
|
22
|
+
|
|
23
|
+
**excel-import** использует диалог выбора файла и запись в файлы репозитория, которые доступны только в плагинах для IDE. При работе через плагин файл выгрузки **excel-export** сохраняется через диалог сохранения IDE, в браузере — скачивается.
|
|
24
|
+
|
|
25
|
+
> **Важно.** На портале документ **excel-import** открывается и кнопка «Загрузить Excel» отображается, но при нажатии появляется ошибка `Ошибка рендера документа … reading 'upload'`. Не выводите документы **excel-import** в меню портала: размещайте их в манифестах, которые открываются только в плагине IDE.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
# Документ excel-export
|
|
30
|
+
|
|
31
|
+
На странице документа отображается заголовок (идентификатор документа — последний сегмент его пути) и кнопка **«Сохранить шаблон»**. При нажатии кнопки формируется Excel-книга и сохраняется на компьютер пользователя.
|
|
32
|
+
|
|
33
|
+
Если выгрузку подготовить не удалось, вместо кнопки выводится блок ошибки **«Не удалось подготовить выгрузку»** с описанием причины и, при наличии, техническими подробностями.
|
|
34
|
+
|
|
35
|
+
## Пример использования
|
|
36
|
+
|
|
37
|
+
```yaml
|
|
38
|
+
docs:
|
|
39
|
+
archtool.example.excel.export:
|
|
40
|
+
type: excel-export
|
|
41
|
+
location: SEAF.ArchTool/Руководство/Документы/Excel/Экспорт
|
|
42
|
+
file_name: >
|
|
43
|
+
("Шаблон_компонентов.xlsx")
|
|
44
|
+
button_text: >
|
|
45
|
+
("Скачать шаблон")
|
|
46
|
+
options:
|
|
47
|
+
show-grid-lines: false
|
|
48
|
+
margin-left: 3.5
|
|
49
|
+
margin-top: 10.5
|
|
50
|
+
table:
|
|
51
|
+
headers:
|
|
52
|
+
height: 28.5
|
|
53
|
+
pages:
|
|
54
|
+
- name: Компоненты
|
|
55
|
+
title: Перечень компонентов
|
|
56
|
+
description: Заполните таблицу и загрузите файл через документ excel-import
|
|
57
|
+
components:
|
|
58
|
+
- type: table
|
|
59
|
+
name: components
|
|
60
|
+
headers:
|
|
61
|
+
- value: ID
|
|
62
|
+
- value: Название
|
|
63
|
+
- value: Критичность
|
|
64
|
+
type: select
|
|
65
|
+
options:
|
|
66
|
+
- Высокая
|
|
67
|
+
- Средняя
|
|
68
|
+
- Низкая
|
|
69
|
+
source: >
|
|
70
|
+
(
|
|
71
|
+
{
|
|
72
|
+
"body": [
|
|
73
|
+
["", "", ""],
|
|
74
|
+
["", "", ""],
|
|
75
|
+
["", "", ""]
|
|
76
|
+
]
|
|
77
|
+
}
|
|
78
|
+
)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Пример рендеринга документа:
|
|
82
|
+
|
|
83
|
+

|
|
84
|
+
|
|
85
|
+
## Структура документа
|
|
86
|
+
|
|
87
|
+
Позиции в книге формируются сверху вниз: сначала ссылка, заголовки и описание страницы, затем пустая строка, затем компоненты по порядку. Перед каждым компонентом выводятся его заголовки и описание, после — пустая строка.
|
|
88
|
+
|
|
89
|
+
### Поля документа
|
|
90
|
+
|
|
91
|
+
| Поле | Обязательное | Описание |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| `type` | да | `excel-export` |
|
|
94
|
+
| `pages` | да | Список страниц (листов) книги. См. раздел «Страницы» |
|
|
95
|
+
| `file_name` | нет | JSONata-выражение, возвращающее имя сохраняемого файла (строка, не более 255 символов). Если не задано — `dh_<метка времени>` |
|
|
96
|
+
| `button_text` | нет | JSONata-выражение, возвращающее текст кнопки. По умолчанию — «Сохранить шаблон» |
|
|
97
|
+
| `options` | да | Общие настройки для всех листов. Обязательно должен быть задан `margin-left`. См. раздел «Опции» |
|
|
98
|
+
| `templates` | нет | Переиспользуемые компоненты. См. раздел «Шаблоны» |
|
|
99
|
+
| `origin` | нет | Исходные данные, доступные во всех JSONata-выражениях документа (`file_name`, `button_text`, `source` компонентов) |
|
|
100
|
+
|
|
101
|
+
> **Важно.** Значения `file_name` и `button_text` вычисляются как JSONata-выражения. Строковую константу необходимо заключать в скобки и кавычки: `("Отчёт.xlsx")`. Значение без скобок (например, `Отчёт.xlsx`) будет воспринято как ссылка на файл или источник данных. Это же относится ко всем JSONata-выражениям документа: выражение должно начинаться с `(` и заканчиваться `)`, комментарии после закрывающей скобки не допускаются.
|
|
102
|
+
|
|
103
|
+
**Расширение файла.** Если имя из `file_name` заканчивается на `.xlsx`, `.xls` или `.csv`, используется это расширение, иначе к имени добавляется `.xls`. Содержимое файла всегда формируется в формате XLSX, поэтому рекомендуется явно указывать расширение `.xlsx`.
|
|
104
|
+
|
|
105
|
+
Имя файла можно формировать динамически, например с датой выгрузки:
|
|
106
|
+
|
|
107
|
+
```yaml
|
|
108
|
+
file_name: >
|
|
109
|
+
("Реестр_компонентов_" & $substring($now(), 0, 10) & ".xlsx")
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Опции (options)
|
|
113
|
+
|
|
114
|
+
> **Важно.** Параметр `options.margin-left` обязателен, значение должно быть больше `0`, например `margin-left: 3`. Если блок `options` не указан, в нём нет `margin-left` или `margin-left: 0`, при нажатии кнопки появляется ошибка `… 0 is out of bounds. Excel supports columns from 1 to 16384`, и файл не формируется.
|
|
115
|
+
|
|
116
|
+
| Поле | Описание |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `show-grid-lines` | Отображение сетки листа: `true` (по умолчанию) / `false` |
|
|
119
|
+
| `margin-left` | **Обязательный.** Добавляет слева пустую колонку указанной ширины, например `3.5`. Содержимое листа начинается со второй колонки (B) |
|
|
120
|
+
| `margin-top` | Добавляет сверху пустую строку указанной высоты, например `10.5` |
|
|
121
|
+
| `table.headers.height` | Высота строки заголовков всех таблиц |
|
|
122
|
+
|
|
123
|
+
### Страницы (pages)
|
|
124
|
+
|
|
125
|
+
Каждый элемент списка `pages` — отдельный лист книги.
|
|
126
|
+
|
|
127
|
+
| Поле | Обязательное | Описание |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| `name` | да | Имя листа (вкладки). Должно быть уникальным в книге |
|
|
130
|
+
| `link` | нет | Ссылка на другой лист: `text` — текст ссылки, `path` — имя листа (`name`), на который ведёт ссылка. Выводится первой строкой |
|
|
131
|
+
| `title` | нет | Заголовок 1 уровня (жирный, 14 pt) |
|
|
132
|
+
| `subtitle` | нет | Заголовок 2 уровня (жирный, 12 pt) |
|
|
133
|
+
| `description` | нет | Описание (курсив, 12 pt) |
|
|
134
|
+
| `components` | нет | Список компонентов листа: `table`, `rows`, `template` |
|
|
135
|
+
| `rows` | нет | Настройки строк по номеру, например высота: `rows: { 5: { height: 40 } }` |
|
|
136
|
+
| `columns` | нет | Настройки колонок по номеру, например ширина: `columns: { 2: { width: 40 } }` |
|
|
137
|
+
|
|
138
|
+
В `rows` и `columns` ключом является номер строки/колонки (начиная с 1, с учётом отступов `margin-top`/`margin-left`), а значением — набор свойств строки/колонки библиотеки [ExcelJS](https://github.com/exceljs/exceljs#columns) (`height`, `width`, `hidden` и т.п.).
|
|
139
|
+
|
|
140
|
+
```yaml
|
|
141
|
+
pages:
|
|
142
|
+
- name: Компоненты
|
|
143
|
+
columns:
|
|
144
|
+
2:
|
|
145
|
+
width: 20
|
|
146
|
+
3:
|
|
147
|
+
width: 60
|
|
148
|
+
rows:
|
|
149
|
+
1:
|
|
150
|
+
height: 10
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Компонент table
|
|
154
|
+
|
|
155
|
+
Основной компонент — таблица Excel («умная таблица») с заголовками и данными.
|
|
156
|
+
|
|
157
|
+
| Поле | Обязательное | Описание |
|
|
158
|
+
|---|---|---|
|
|
159
|
+
| `type` | да | `table` |
|
|
160
|
+
| `name` | да | Уникальное в книге имя таблицы Excel. Используется как идентификатор таблицы при импорте через **excel-import**. Рекомендуется camelCase без пробелов: имя должно начинаться с буквы и не содержать пробелов, так требует Excel |
|
|
161
|
+
| `title`, `subtitle`, `description` | нет | Заголовки и описание над таблицей |
|
|
162
|
+
| `headers` | да* | Заголовки колонок. *Не требуется, если их возвращает `source` |
|
|
163
|
+
| `source` | да | JSONata-выражение, возвращающее данные таблицы |
|
|
164
|
+
|
|
165
|
+
**Результат `source`** должен быть объектом:
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"headers": [ { "value": "Колонка 1" }, { "value": "Колонка 2" } ],
|
|
170
|
+
"body": [
|
|
171
|
+
["R1 C1", "R1 C2"],
|
|
172
|
+
["R2 C1", "R2 C2"]
|
|
173
|
+
]
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
- `body` (обязательно) — массив строк, каждая строка — массив значений ячеек в порядке колонок;
|
|
178
|
+
- `headers` (необязательно) — если указаны, используются **вместо** `headers` из описания компонента. Это позволяет формировать колонки динамически.
|
|
179
|
+
|
|
180
|
+
Если `source` вернёт не объект или объект без `body`, на странице документа выводится блок ошибки «Не удалось подготовить выгрузку», кнопка сохранения недоступна.
|
|
181
|
+
|
|
182
|
+
**Поля заголовка колонки (headers):**
|
|
183
|
+
|
|
184
|
+
| Поле | Описание |
|
|
185
|
+
|---|---|
|
|
186
|
+
| `value` | Текст заголовка колонки (обязательно, уникален в пределах таблицы) |
|
|
187
|
+
| `type` | Тип ячеек колонки: `text` (по умолчанию), `select`, `link` |
|
|
188
|
+
| `options` | Для `type: select` — список допустимых значений. В ячейках колонки появляется выпадающий список, ввод других значений запрещён |
|
|
189
|
+
| `style` | Стиль ячеек **данных** этой колонки. См. раздел «Стили» |
|
|
190
|
+
|
|
191
|
+
Для `type: link` значение ячейки должно совпадать с именем листа книги: в ячейке создаётся ссылка на этот лист.
|
|
192
|
+
|
|
193
|
+
Строка заголовков таблицы всегда выравнивается по центру. Для всех ячеек таблицы задаётся тонкая граница (`hair`), если в `style` не указана другая.
|
|
194
|
+
|
|
195
|
+
Пример выгрузки данных архитектуры — список компонентов:
|
|
196
|
+
|
|
197
|
+
```yaml
|
|
198
|
+
- type: table
|
|
199
|
+
name: componentsList
|
|
200
|
+
title: Компоненты архитектуры
|
|
201
|
+
headers:
|
|
202
|
+
- value: Идентификатор
|
|
203
|
+
- value: Название
|
|
204
|
+
style:
|
|
205
|
+
font:
|
|
206
|
+
bold: true
|
|
207
|
+
source: >
|
|
208
|
+
(
|
|
209
|
+
{
|
|
210
|
+
"body": $reduce($keys(components), function($acc, $id) {
|
|
211
|
+
$append($acc, [[$id, $lookup(components, $id).title]])
|
|
212
|
+
}, [])
|
|
213
|
+
}
|
|
214
|
+
)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Компонент rows
|
|
218
|
+
|
|
219
|
+
Выводит произвольные строки текста — например, пояснения или инструкции по заполнению.
|
|
220
|
+
|
|
221
|
+
```yaml
|
|
222
|
+
- type: rows
|
|
223
|
+
title: Инструкция
|
|
224
|
+
rows:
|
|
225
|
+
- Строка выводится в первую ячейку # строка или число — в первую ячейку строки
|
|
226
|
+
- - Ячейка 1 # массив — по ячейкам строки
|
|
227
|
+
- Ячейка 2
|
|
228
|
+
- Ячейка 3
|
|
229
|
+
- - value: Ячейка со стилем # объект — значение и стиль ячейки
|
|
230
|
+
style:
|
|
231
|
+
font:
|
|
232
|
+
bold: true
|
|
233
|
+
- value: 20
|
|
234
|
+
- style: # только стиль, без значения
|
|
235
|
+
background: FFD145BE
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Элементы списка `rows`:
|
|
239
|
+
- строка или число — значение в первой ячейке строки;
|
|
240
|
+
- массив — значения по ячейкам строки слева направо. Элемент массива — строка или объект `{ value, style }`. Числа внутри массива задаются объектом: `- value: 20`.
|
|
241
|
+
|
|
242
|
+
### Шаблоны (templates)
|
|
243
|
+
|
|
244
|
+
Компонент, который повторяется на нескольких листах, можно описать один раз в `templates` и подключать по имени компонентом `type: template`. Сейчас в шаблонах поддерживается только компонент `rows`.
|
|
245
|
+
|
|
246
|
+
```yaml
|
|
247
|
+
templates:
|
|
248
|
+
legend:
|
|
249
|
+
type: rows
|
|
250
|
+
title: Легенда
|
|
251
|
+
rows:
|
|
252
|
+
- "* — обязательное поле"
|
|
253
|
+
|
|
254
|
+
pages:
|
|
255
|
+
- name: Лист 1
|
|
256
|
+
components:
|
|
257
|
+
- type: template
|
|
258
|
+
name: legend
|
|
259
|
+
- name: Лист 2
|
|
260
|
+
components:
|
|
261
|
+
- type: template
|
|
262
|
+
name: legend
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Если шаблон с указанным именем не найден, на странице документа выводится ошибка, файл не сохраняется.
|
|
266
|
+
|
|
267
|
+
### Стили (style)
|
|
268
|
+
|
|
269
|
+
Стиль можно задать для колонки таблицы (`headers[].style`) и для ячейки компонента `rows`.
|
|
270
|
+
|
|
271
|
+
```yaml
|
|
272
|
+
style:
|
|
273
|
+
alignment: # Выравнивание
|
|
274
|
+
horizontal: center # left | center | right | fill | justify | centerContinuous | distributed
|
|
275
|
+
vertical: middle # top | middle | bottom | distributed | justify
|
|
276
|
+
wrapText: true # Перенос текста
|
|
277
|
+
font: # Шрифт
|
|
278
|
+
name: Arial # Название шрифта
|
|
279
|
+
size: 12 # Размер
|
|
280
|
+
color: FFB80000 # Цвет (ARGB)
|
|
281
|
+
bold: true # Жирный
|
|
282
|
+
italic: true # Курсив
|
|
283
|
+
underline: single # Подчёркивание: true | single | double
|
|
284
|
+
strike: true # Зачёркивание
|
|
285
|
+
background: FFFFFF00 # Цвет заливки (ARGB)
|
|
286
|
+
border: # Граница со всех сторон ячейки
|
|
287
|
+
style: thin # thin | dotted | hair | medium | double | thick | dashed | dashDot |
|
|
288
|
+
# dashDotDot | slantDashDot | mediumDashed | mediumDashDotDot | mediumDashDot
|
|
289
|
+
color: FFB80000 # Цвет (ARGB)
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Цвета задаются в HEX-формате ARGB: `FF` (непрозрачность) + `RRGGBB`, например `FFFF0000` — красный.
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
# Документ excel-import
|
|
297
|
+
|
|
298
|
+
На странице документа отображается заголовок (идентификатор документа — последний сегмент его пути) и кнопка **«Загрузить Excel»**. При нажатии открывается диалог выбора файла. После выбора файл обрабатывается, а результат записывается в файлы, указанные в описании документа.
|
|
299
|
+
|
|
300
|
+
## Пример использования
|
|
301
|
+
|
|
302
|
+
Пример забирает данные из таблицы `components`, сформированной шаблоном из примера excel-export, и сохраняет их в файл `components.yaml` в виде объекта, где ключ — идентификатор компонента.
|
|
303
|
+
|
|
304
|
+
```yaml
|
|
305
|
+
docs:
|
|
306
|
+
archtool.example.excel.import:
|
|
307
|
+
type: excel-import
|
|
308
|
+
location: SEAF.ArchTool/Руководство/Документы/Excel/Импорт
|
|
309
|
+
tables:
|
|
310
|
+
- name: components # Имя таблицы в Excel-файле
|
|
311
|
+
output: > # Путь к файлу для сохранения результата
|
|
312
|
+
("components.yaml")
|
|
313
|
+
source: > # Преобразование данных перед сохранением
|
|
314
|
+
(
|
|
315
|
+
{
|
|
316
|
+
"components": $reduce(table, function($acc, $row) {
|
|
317
|
+
$row[0] /* строки без ID пропускаются */
|
|
318
|
+
? $merge([$acc, {
|
|
319
|
+
$string($row[0]): {
|
|
320
|
+
"title": $row[1],
|
|
321
|
+
"criticality": $row[2]
|
|
322
|
+
}
|
|
323
|
+
}])
|
|
324
|
+
: $acc
|
|
325
|
+
}, {})
|
|
326
|
+
}
|
|
327
|
+
)
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
Результат в `components.yaml`:
|
|
331
|
+
|
|
332
|
+
```yaml
|
|
333
|
+
components:
|
|
334
|
+
app.crm:
|
|
335
|
+
title: CRM
|
|
336
|
+
criticality: Высокая
|
|
337
|
+
app.billing:
|
|
338
|
+
title: Биллинг
|
|
339
|
+
criticality: Средняя
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
## Требования к Excel-файлу
|
|
343
|
+
|
|
344
|
+
- Данные читаются только из **таблиц Excel** («Форматировать как таблицу» / «Вставка → Таблица»), у которых задано имя. Обычные диапазоны ячеек не обрабатываются.
|
|
345
|
+
- Имя таблицы в Excel (вкладка «Конструктор таблиц» → «Имя таблицы») должно совпадать с `tables[].name` в документе. Таблицы, сформированные через **excel-export**, получают имя из `name` компонента `table` автоматически.
|
|
346
|
+
- Таблицы ищутся на всех листах книги.
|
|
347
|
+
- Первая строка таблицы считается заголовком и в данные не попадает.
|
|
348
|
+
- Поддерживается формат XLSX, в том числе файлы, сохранённые в Р7-Офис.
|
|
349
|
+
|
|
350
|
+
## Поля документа
|
|
351
|
+
|
|
352
|
+
| Поле | Обязательное | Описание |
|
|
353
|
+
|---|---|---|
|
|
354
|
+
| `type` | да | `excel-import` |
|
|
355
|
+
| `tables` | да | Массив правил импорта. См. ниже |
|
|
356
|
+
| `origin` | нет | Дополнительные данные, доступные в выражениях `output` и `source`. Задаётся объектом: ключ — имя переменной, значение — JSONata-запрос к данным архитектуры, ссылка на файл или константа. Через `origin` в выражения импорта передаются данные архитектуры (см. раздел «Данные в выражении source») |
|
|
357
|
+
| `yaml.null_replace_string` | нет | Строка, которой при записи в YAML заменяются пустые значения (`null`), например `""` или `"~"`. По умолчанию — `null` |
|
|
358
|
+
|
|
359
|
+
### Правило импорта (tables[])
|
|
360
|
+
|
|
361
|
+
| Поле | Обязательное | Описание |
|
|
362
|
+
|---|---|---|
|
|
363
|
+
| `name` | да | Имя таблицы в загруженном Excel-файле |
|
|
364
|
+
| `output` | да | JSONata-выражение, возвращающее путь к файлу для сохранения результата |
|
|
365
|
+
| `source` | да | JSONata-выражение, формирующее данные для сохранения |
|
|
366
|
+
|
|
367
|
+
Одну и ту же таблицу можно обработать несколькими правилами, например сохранить её в разные файлы в разном виде.
|
|
368
|
+
|
|
369
|
+
### Путь сохранения (output)
|
|
370
|
+
|
|
371
|
+
`output` — JSONata-выражение, результатом которого должна быть строка с путём к файлу:
|
|
372
|
+
- путь указывается относительно файла манифеста, в котором описан документ;
|
|
373
|
+
- расширение файла — `.yaml` или `.json`. Содержимое всегда записывается в формате YAML, поэтому рекомендуется `.yaml`;
|
|
374
|
+
- длина всего пути без расширения (включая папки) — не более 255 символов. Например, для `imported/components.yaml` учитывается строка `imported/components` (19 символов).
|
|
375
|
+
|
|
376
|
+
> **Важно.** Константный путь необходимо указывать в скобках и кавычках: `("output.yaml")`. Значение без скобок (`output.yaml`) будет воспринято как ссылка на файл данных, а не как путь.
|
|
377
|
+
|
|
378
|
+
В выражении `output` доступны данные таблицы (`table`) и ключи `origin`. Содержимое файла (`file`) здесь недоступно: путь вычисляется до чтения файла. Путь можно формировать динамически — например, раскладывать данные по файлам в зависимости от содержимого:
|
|
379
|
+
|
|
380
|
+
```yaml
|
|
381
|
+
tables:
|
|
382
|
+
- name: components
|
|
383
|
+
output: >
|
|
384
|
+
("imported/" & $string(table[0][0]) & ".yaml")
|
|
385
|
+
source: >
|
|
386
|
+
(table)
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### Данные в выражении source
|
|
390
|
+
|
|
391
|
+
В выражении `source` доступны переменные контекста:
|
|
392
|
+
|
|
393
|
+
| Имя | Описание |
|
|
394
|
+
|---|---|
|
|
395
|
+
| `table` | Данные таблицы из Excel — массив строк, каждая строка — массив значений ячеек в порядке колонок (без строки заголовков) |
|
|
396
|
+
| `file` | Текущее содержимое файла, указанного в `output`. Если файла ещё нет, `file` из файла не передаётся и файл будет создан при сохранении. При этом, если в `origin` есть ключ `file`, в выражение попадёт значение из `origin` |
|
|
397
|
+
| имена из `origin` | Данные, объявленные в `origin` документа |
|
|
398
|
+
|
|
399
|
+
Имена `table` и `file` зарезервированы. `table` всегда перекрывает одноимённый ключ из `origin`. `file` перекрывает его, только если файл `output` существует. Не используйте эти имена в `origin`.
|
|
400
|
+
|
|
401
|
+
> **Важно.** В выражениях `output` и `source` доступны только переменные импорта (`table`, а в `source` ещё и `file`) и ключи `origin`. Данные архитектуры (манифест) напрямую недоступны: например, `$exists(components)` вернёт `false`. Чтобы использовать данные архитектуры, передайте их через `origin` — значения `origin` вычисляются по манифесту.
|
|
402
|
+
|
|
403
|
+
```yaml
|
|
404
|
+
origin:
|
|
405
|
+
components: > # данные архитектуры передаются через origin
|
|
406
|
+
(components)
|
|
407
|
+
tables:
|
|
408
|
+
- name: tableForImport
|
|
409
|
+
output: >
|
|
410
|
+
("output.yaml")
|
|
411
|
+
source: >
|
|
412
|
+
($keys(components))
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
> **Совет.** Особенности обращения к `table` в JSONata:
|
|
416
|
+
>
|
|
417
|
+
> - `table[0]` — первая строка таблицы, `table[0][0]` — её первая ячейка.
|
|
418
|
+
> - `table.{ "id": $[0], "title": $[1] }` — преобразование каждой строки в объект с постоянными ключами работает построчно. Если в таблице одна строка, результатом будет объект, а не массив из одного объекта. Чтобы всегда получать массив, заключите выражение в квадратные скобки: `[table.{ ... }]`.
|
|
419
|
+
> - Ключи объекта, вычисляемые из данных строки, например `table.{ $string($[0]): ... }`, так не работают: каждая ячейка строки обрабатывается отдельно. Для объекта вида «идентификатор → данные» используйте `$reduce(table, ...)`, как в примерах на этой странице.
|
|
420
|
+
> - `table.$` объединяет все строки в один общий список значений. `table.[$[0], $[1]]` работает построчно, но при одной строке в таблице возвращает одну плоскую строку вместо массива строк. Чтобы гарантированно получить массив строк, используйте `$reduce` с `$append` (см. пример в разделе «Компонент table»).
|
|
421
|
+
> - `table[условие]` возвращает подходящие строки, но если подошла только одна, возвращается сама строка, а не массив из одной строки.
|
|
422
|
+
|
|
423
|
+
Результат выражения **полностью заменяет** содержимое файла `output`. Чтобы дополнить существующий файл, а не перезаписать его, объединяйте новые данные с `file`:
|
|
424
|
+
|
|
425
|
+
```yaml
|
|
426
|
+
docs:
|
|
427
|
+
archtool.example.excel.import.append:
|
|
428
|
+
type: excel-import
|
|
429
|
+
origin:
|
|
430
|
+
num_list: >
|
|
431
|
+
([10, 20, 30])
|
|
432
|
+
tables:
|
|
433
|
+
- name: tableForImport
|
|
434
|
+
output: >
|
|
435
|
+
("output1.yaml")
|
|
436
|
+
source: > # к массиву из файла добавляются значения из origin
|
|
437
|
+
($append(file, num_list))
|
|
438
|
+
|
|
439
|
+
- name: tableForImport
|
|
440
|
+
output: >
|
|
441
|
+
("output2.yaml")
|
|
442
|
+
source: > # файл перезаписывается данными таблицы как есть
|
|
443
|
+
(table)
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
Пример объединения объектов — добавление и обновление компонентов в существующем файле:
|
|
447
|
+
|
|
448
|
+
```yaml
|
|
449
|
+
source: >
|
|
450
|
+
(
|
|
451
|
+
$new := $reduce(table, function($acc, $row) {
|
|
452
|
+
$row[0] ? $merge([$acc, { $string($row[0]): { "title": $row[1] } }]) : $acc
|
|
453
|
+
}, {});
|
|
454
|
+
{ "components": $merge([file.components, $new]) }
|
|
455
|
+
)
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
### Значения ячеек
|
|
459
|
+
|
|
460
|
+
- Пустые ячейки, а также ячейки со значением `0` или `false`, передаются как `null`. При необходимости заменяйте `null` в `source` или используйте `yaml.null_replace_string`.
|
|
461
|
+
- Числа передаются числами. Для идентификаторов и кодов используйте `$string()`.
|
|
462
|
+
- Ячейки с формулой передаются объектом `{ "formula": ..., "result": ... }`, с гиперссылкой — `{ "text": ..., "hyperlink": ... }`. Вычисленное значение формулы находится в поле `result`.
|
|
463
|
+
- Ячейки с датой передаются **строкой** в формате ISO 8601 (UTC), например `"2026-10-09T00:00:00.000Z"`; `$type()` для такого значения вернёт `"string"`. Чтобы получить только дату, используйте, например, `$substring($row[3], 0, 10)`.
|
|
464
|
+
|
|
465
|
+
## Порядок обработки
|
|
466
|
+
|
|
467
|
+
1. Пользователь нажимает **«Загрузить Excel»** и выбирает файл.
|
|
468
|
+
2. Из файла считываются все именованные таблицы.
|
|
469
|
+
3. Правила из `tables` выполняются **последовательно** в порядке описания. Для каждого правила вычисляется `output`, читается текущее содержимое файла и выполняется `source`.
|
|
470
|
+
4. Если несколько правил пишут в один файл, каждое следующее правило получает в `file` результат предыдущего. Так можно собирать один файл из нескольких таблиц.
|
|
471
|
+
5. После обработки всех правил результаты записываются в файлы.
|
|
472
|
+
|
|
473
|
+
## Ошибки
|
|
474
|
+
|
|
475
|
+
Сообщения об ошибках выводятся в лог SEAF.ArchTool (консоль разработчика / лог плагина).
|
|
476
|
+
|
|
477
|
+
| Ситуация | Поведение |
|
|
478
|
+
|---|---|
|
|
479
|
+
| Не заполнено `name`, `output` или `source` у правила | Правило пропускается |
|
|
480
|
+
| Таблица `name` не найдена в файле | Правило пропускается |
|
|
481
|
+
| `output` вернул не строку, в пути нет расширения, расширение не `yaml`/`json`, путь без расширения длиннее 255 символов | Импорт прерывается, файлы не записываются |
|
|
482
|
+
| Ошибка выполнения JSONata в `source` | Импорт прерывается, файлы не записываются |
|
|
483
|
+
| Файл `output` не существует | `file` не передаётся, файл создаётся при сохранении |
|
|
484
|
+
| Не удалось прочитать Excel-файл | Импорт прерывается |
|