# Таблицы (/docs/reference/elements/table)

Цифровой материал и сравнительные показатели в отчёте оформляются в виде таблиц. Шаблон
`modern-g7-32` автоматизирует нумерацию, выравнивание заголовков и обеспечивает корректный
перенос таблиц на стыке страниц.

<Callout type="info">
  Вам **не нужно** вручную считать количество таблиц для [реферата](../abstract.mdx) — шаблон
  сделает это автоматически.
</Callout>

## Быстрый старт

Для создания таблицы используйте функцию `table()`, обёрнутую в макрос `#figure`. Это обеспечит
правильное положение заголовка и включение в список таблиц.

<TypstRender
  code={`
#figure(
table(
  columns: (1fr, auto, auto),
  table.header([Параметр], [Значение], [Ед. изм.]),
  [Масса], [10.5], [кг],
  [Скорость], [300], [м/с],
),
caption: [Основные характеристики устройства]
) <specs-table>

Данные приведены в таблице @specs-table.
`}
  image="table-example-simple.png"
/>

## Автоматизация и логика шаблона

Шаблон настраивает таблицы в соответствии с разделом [6.6](#6.6.1):

1. **Положение заголовка**: Согласно [6.6.3](#6.6.3), наименование таблицы всегда размещается
   **над** ней, слева, без абзацного отступа.
2. **Формат подписи**: Шаблон автоматически добавляет слово «Таблица», номер и длинное тире
   («Таблица 1 — Название»).
3. **Перенос (Multipage)**: Таблицы по умолчанию являются «разбиваемыми» (`breakable: true`).
   При переносе на новую страницу шапка таблицы (`table.header`) может автоматически
   повторяться.
4. **Стили текста**: Внутри таблиц разрешается использовать шрифт меньшего размера, чем в
   основном тексте ([6.6.7](#6.6.7)). Для этого используйте функцию `#set text(size: 10pt)`
   внутри блока таблицы.
5. **Нумерация в приложениях**: В [приложениях](../appendixes.mdx) таблицы нумеруются по
   правилу «Буква.Номер» (например, Таблица Б.2).

## Параметры функций

### figure (Контейнер)

<TypeTable
  type={{
  body: {
    description: "Тело таблицы (функция table)",
    type: "content",
  },
  caption: {
    description: "Наименование таблицы",
    type: "content",
  },
  kind: {
    description: "Тип элемента (для таблиц определяется автоматически)",
    type: "string",
    default: "table"
  }
}}
/>

### table (Сетка данных)

Аргументы ниже соответствуют стандартной функции Typst
[`table`](https://typst.app/docs/reference/model/table/).

<TypeTable
  type={{
  columns: {
    description: "Размеры колонок: число колонок, auto, относительная длина, fraction или массив размеров",
    type: "auto | int | relative | fraction | array",
    default: "()"
  },
  rows: {
    description: "Размеры строк: число строк, auto, относительная длина, fraction или массив размеров",
    type: "auto | int | relative | fraction | array",
    default: "()"
  },
  gutter: {
    description: "Общий промежуток между строками и колонками; сокращение для column-gutter и row-gutter",
    type: "auto | int | relative | fraction | array",
    default: "()"
  },
  "column-gutter": {
    description: "Промежуток между колонками; имеет приоритет над gutter",
    type: "auto | int | relative | fraction | array",
    default: "()"
  },
  "row-gutter": {
    description: "Промежуток между строками; имеет приоритет над gutter",
    type: "auto | int | relative | fraction | array",
    default: "()"
  },
  inset: {
    description: "Внутренние отступы ячеек: одно значение, словарь сторон, массив по колонкам или функция от координат ячейки",
    type: "relative | array | dictionary | function",
    default: "0% + 5pt"
  },
  align: {
    description: "Выравнивание содержимого ячеек: одно значение, массив по колонкам или функция от координат ячейки",
    type: "auto | array | alignment | function",
    default: "auto"
  },
  fill: {
    description: "Заливка ячеек: цвет, градиент, массив значений, tiling, функция или none",
    type: "none | color | gradient | array | tiling | function",
    default: "none"
  },
  stroke: {
    description: "Линии таблицы: none, длина, цвет, градиент, stroke, tiling, словарь сторон или функция",
    type: "none | length | color | gradient | array | stroke | tiling | dictionary | function",
    default: "1pt + black"
  },
  children: {
    description: "Позиционные элементы таблицы в порядке строк: содержимое ячеек, table.header, table.footer, table.cell, table.hline и другие элементы table",
    type: "content",
    required: true
  }
}}
/>

Для повторяемой шапки используйте `table.header(...)` как один из позиционных элементов таблицы.
Это не именованный аргумент `table`, а вложенный элемент.

## Продвинутое использование

### Перенос длинных таблиц

Если таблица занимает несколько страниц, ГОСТ [6.6.3](#6.6.3) требует писать «Продолжение
таблицы X» над последующими частями. `modern-g7-32` делает таблицы разбиваемыми и позволяет
`table.header` повторяться, но подпись «Продолжение таблицы» остаётся ручной ответственностью.

Практичный вариант — разбить очень длинную таблицу на несколько `#figure` и явно подписать
продолжение. Это особенно полезно, если нормоконтроль требует отдельную строку «Продолжение
таблицы ...» на каждой странице:

```typst
#figure(
  table(
    columns: 3,
    table.header([Показатель], [Спринт 1], [Спринт 2]),
    [Ошибки], [12], [7],
  ),
  caption: [Метрики тестирования]
) <qa-metrics>

#figure(
  table(
    columns: 3,
    table.header([Показатель], [Спринт 3], [Спринт 4]),
    [Ошибки], [4], [2],
  ),
  caption: [Продолжение таблицы @qa-metrics]
)
```

### Лайфхаки для переносов

* Если таблица упорно не переносится, проверьте, что она находится внутри `#figure(...)`, а не
  внутри неразбиваемого `block`, `box`, `grid` или вложенной фигуры.
* Длинные текстовые ячейки лучше делать `auto`-шириной только там, где это действительно нужно.
  Для основной текстовой колонки часто удобнее `1fr`, а числовые колонки оставить `auto`.
* Если одна ячейка занимает несколько строк через `table.cell(rowspan: ...)`, задайте ей
  `breakable: true` или разбейте строку вручную: многострочные объединённые ячейки сложнее
  переносить корректно.
* Перед финальной сдачей проверьте PDF постранично: автоматический перенос таблицы не заменяет
  редакторское решение о том, где лучше разделить очень крупный материал.

### Выравнивание в ячейках

По стандарту [6.6.6](#6.6.6) заголовки граф выравниваются по центру, а заголовки строк (боковик)
— по левому краю. Шаблон устанавливает левое выравнивание по умолчанию для всех ячеек. Для
центрирования используйте `align(center)[...]`.

## Требования ГОСТ 7.32-2017

<GostQuote page={13} id="6.6.1">
  6.6.1 Цифровой материал должен оформляться в виде таблиц. Таблицы применяют для наглядности и удобства сравнения показателей.
</GostQuote>

### Размещение и ссылки

<GostQuote page={13} id="6.6.2">
  6.6.2 Таблицу следует располагать непосредственно после текста, в котором она упоминается впервые, или на следующей странице.
  На все таблицы в отчете должны быть ссылки. При ссылке следует печатать слово «таблица» с указанием ее номера.
</GostQuote>

### Оформление наименования

<GostQuote page={13} id="6.6.3">
  6.6.3 Наименование таблицы, при ее наличии, должно отражать ее содержание, быть точным, кратким. Наименование следует помещать над таблицей слева, без абзацного отступа в следующем формате: Таблица Номер таблицы — Наименование таблицы. Наименование таблицы приводят с прописной буквы без точки в конце.
  Если наименование таблицы занимает две строки и более, то его следует записывать через один межстрочный интервал.
  Таблицу с большим количеством строк допускается переносить на другую страницу. При переносе части таблицы на другую страницу слово «Таблица», ее номер и наименование указывают один раз слева над первой частью таблицы, а над другими частями также слева пишут слова «Продолжение таблицы» и указывают номер таблицы.
  При делении таблицы на части допускается ее головку или боковик заменять соответственно номерами граф и строк. При этом нумеруют арабскими цифрами графы и (или) строки первой части таблицы.
</GostQuote>

<GostQuote page={14} id="6.6.4">
  6.6.4 Таблицы, за исключением таблиц приложений, следует нумеровать арабскими цифрами сквозной нумерацией.
  Таблицы каждого приложения обозначаются отдельной нумерацией арабскими цифрами с добавлением перед цифрой обозначения приложения. Если в отчете одна таблица, она должна быть обозначена «Таблица 1» или «Таблица А.1» (если она приведена в приложении А).
  Допускается нумеровать таблицы в пределах раздела при большом объеме отчета. В этом случае номер таблицы состоит из номера раздела и порядкового номера таблицы, разделенных точкой: Таблица 2.3.
</GostQuote>

### Шапка и ячейки

<GostQuote page={14} id="6.6.5">
  6.6.5 Заголовки граф и строк таблицы следует печатать с прописной буквы, а подзаголовки граф — со строчной буквы, если они составляют одно предложение с заголовком, или с прописной буквы, если они имеют самостоятельное значение. В конце заголовков и подзаголовков таблиц точки не ставятся. Названия заголовков и подзаголовков таблиц указывают в единственном числе.
</GostQuote>

<GostQuote page={14} id="6.6.6">
  6.6.6 Таблицы слева, справа, сверху и снизу ограничивают линиями. Разделять заголовки и подзаголовки боковика и граф диагональными линиями не допускается. Заголовки граф выравнивают по центру, а заголовки строк — по левому краю.
  Горизонтальные и вертикальные линии, разграничивающие строки таблицы, допускается не проводить, если их отсутствие не затрудняет пользование таблицей.
</GostQuote>

<GostQuote page={14} id="6.6.7">
  6.6.7 Текст, повторяющийся в строках одной и той же графы и состоящий из одиночных слов, заменяют кавычками. Ставить кавычки вместо повторяющихся цифр, буквенно-цифровых обозначений, знаков и символов не допускается.
  Если текст повторяется, то при первом повторении его заменяют словами «то же», а далее кавычками.
  В таблице допускается применять размер шрифта меньше, чем в тексте отчета.
</GostQuote>