cc-1c-skills/docs/1c-spreadsheet-spec.md

Спецификация XML-формата табличного документа (SpreadsheetDocument)

Формат файла Template.xml для макетов типа SpreadsheetDocument (табличный документ / MXL).

Namespace

<document xmlns="http://v8.1c.ru/8.2/data/spreadsheet"
          xmlns:style="http://v8.1c.ru/8.1/data/ui/style"
          xmlns:v8="http://v8.1c.ru/8.1/data/core"
          xmlns:v8ui="http://v8.1c.ru/8.1/data/ui"
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

Структура документа

Элементы внутри <document> идут в фиксированном порядке:

<document>
    <languageSettings>          — языковые настройки
    <columns> ...               — наборы колонок (один или несколько)
    <rowsItem> ...              — строки с данными (повторяются)
    <drawing> ...               — рисунки (опционально, повторяются)
    <templateMode>true          — признак макета
    <defaultFormatIndex>        — индекс формата по умолчанию
    <height>                    — общее количество строк
    <vgRows>                    — видимых строк (обычно = height)
    <merge> ...                 — объединения ячеек (повторяются)
    <verticalUnmerge> ...       — отмена объединений (опционально)
    <namedItem> ...             — именованные области (повторяются)
    <line> ...                  — стили линий (повторяются)
    <font> ...                  — шрифты (опционально, повторяются)
    <format> ...                — форматы (повторяются)
    <picture> ...               — ресурсы картинок (опционально)
</document>

Индексация

Все палитры (линии, шрифты, форматы) — плоские массивы, на элементы которых ссылаются по индексу.

Палитра	Индексация	Индекс 0 означает
<line>	0-based	Первый элемент <line>
<font>	0-based	Первый элемент <font>
<format>	1-based	0 = «формат по умолчанию» (не задан)

Формат с индексом N — это N-й элемент <format> в документе (считая от 1).

Языковые настройки

<languageSettings>
    <currentLanguage>ru</currentLanguage>
    <defaultLanguage>ru</defaultLanguage>
    <languageInfo>
        <id>ru</id>
        <code>Русский</code>
        <description>Русский</description>
    </languageInfo>
</languageSettings>

Языков бывает несколько, и объявленный набор НЕ выводится из того, на каких языках лежит текст ячеек: на корпусе ERP объявлен один ru у 10 753 макетов, при том что текст в них лежит и под ru, и под en. Наборы: [ru] — 10 753, [ru,en] — 148, [en,ru] — 20.

id и code всегда со значением; description бывает пустым и тогда пишется самозакрывающимся тегом <description/> (77 записей из 11 094). Из id эти поля не выводятся: у en описание бывает «Английский», пустым и «English».

currentLanguage иногда отсутствует вовсе (3 макета), иногда указывает на необъявленный язык (8 макетов с en при объявленном одном ru). defaultLanguage во всех четырёх русских типовых равен ru, но это свойство конфигурации, а не формата.

Колонки

Основной набор

<columns>
    <size>33</size>              <!-- общее количество колонок -->
    <columnsItem>
        <index>1</index>         <!-- индекс колонки (0-based) -->
        <column>
            <formatIndex>1</formatIndex>  <!-- ссылка на format[] -->
        </column>
    </columnsItem>
    ...
</columns>

Перечисляются колонки, у которых есть собственный формат. Обычно это ширина (<width> в палитре форматов), но формат колонки несёт и оформление: шрифт (3 006 форматов на корпусе), выравнивания, рамки, hidden.

Два случая, которые легко упустить:

• <formatIndex>0</formatIndex> — колонка перечислена, а формата у неё нет (ноль здесь не индекс записи). Встречается у 4% макетов;
• индекс колонки бывает больше или равен <size> — платформа описывает колонки за пределами объявленной ширины сетки (25% макетов).

Дополнительные наборы колонок

Некоторые строки документа могут использовать собственную сетку колонок, отличную от основной. Каждый дополнительный набор имеет UUID:

<columns>
    <id>f01e015f-de4c-4f97-9fbe-a244c4c30c6c</id>
    <size>17</size>
    <columnsItem>
        <index>0</index>
        <column>
            <formatIndex>12</formatIndex>
        </column>
    </columnsItem>
    ...
</columns>

• Первый <columns> — основной набор (без <id>)
• Дополнительные наборы — с <id> (UUID), могут иметь другое количество и ширину колонок
• Строки, merge и namedItem ссылаются на набор через <columnsID>

Типичное применение: сложные печатные формы (УПД, УКД), где шапка/подвал/табличная часть имеют разную разбивку на колонки.

Строки и ячейки

Строка

<rowsItem>
    <index>3</index>               <!-- индекс строки (0-based) -->
    <indexTo>5</indexTo>            <!-- опц.: диапазон [index..indexTo] с одинаковым содержимым -->
    <row>
        <columnsID>f01e015f-...</columnsID>  <!-- опц.: набор колонок (UUID) -->
        <formatIndex>5</formatIndex>  <!-- опц.: формат строки (определяет высоту) -->
        <empty>true</empty>           <!-- опц.: пустая строка -->
        <c>...</c>                    <!-- ячейки (повторяются) -->
    </row>
</rowsItem>

• <indexTo> объединяет подряд идущие пустые строки. Одинаковые НЕпустые строки платформа не схлопывает никогда: на корпусе ERP (10 924 макета) схлопнутых непустых нет ни одной, несхлопнутых одинаковых непустых — 98 153; несхлопнутых одинаковых пустых — тоже ни одной
• <columnsID> привязывает строку к дополнительному набору колонок. Без него — используется основной набор
• <formatIndex> строки несёт не только высоту: в корпусе там hidden (17 423 вхождения), font (9 216), backColor, выравнивания, protection, рамки

Ячейка

Ячейки внутри <row> — элементы <c> (cell group), каждый содержит <c> (cell content):

<c>                                <!-- cell group -->
    <i>6</i>                       <!-- индекс колонки (0-based), опционален -->
    <c>                            <!-- cell content -->
        <f>9</f>                   <!-- индекс формата -->
        <parameter>Имя</parameter>           <!-- параметр для заполнения -->
        <detailParameter>Расш</detailParameter>  <!-- параметр расшифровки -->
        <tl>                       <!-- текст (локализованная строка) -->
            <v8:item>
                <v8:lang>ru</v8:lang>
                <v8:content>Итого:</v8:content>
            </v8:item>
        </tl>
    </c>
</c>

Правила позиционирования <i>:

• Если <i> указан — ячейка в этой колонке
• Если <i> не указан — колонка = предыдущая + 1
• Первая ячейка без <i> идёт в колонку 0

Платформа пишет <i> только при разрыве последовательности: у подряд идущей ячейки его нет. На корпусе ERP из 1 212 023 записанных номеров ни один не избыточен (счётчик начинается с −1, поэтому у ячейки в колонке 0 номера тоже нет).

У текста ячейки ТРИ состояния, а не два:

запись	смысл
<tl> отсутствует	текста нет
<tl> с элементами	текст по элементу на язык (содержимое бывает пустым)
<tl/>	тег есть, языков в нём нет

Третье — не редкость: 38 075 ячеек на 1200 макетов, встречается в 57% макетов корпуса.

<f>0</f> означает, что формата у ячейки нет вовсе — это не индекс записи. Так записана ячейка без собственного оформления: 170 710 таких ячеек против 50 635, ссылающихся на формат по умолчанию; <f>0</f> встречается в 71% макетов.

Типы заполнения ячеек

Тип заполнения определяется свойством fillType в формате ячейки:

fillType	Данные ячейки	Описание
Parameter	<parameter>Имя</parameter>	Значение подставляется программно
Template	<tl>Текст [Параметр]</tl>	Шаблон — [Имя] заменяется на значение
Text	<tl>Текст</tl>	Статический текст
(нет)	—	Пустая ячейка или ячейка с форматированием

<detailParameter> — имя параметра расшифровки (для навигации при клике на ячейку).

Рисунки

<drawing>
    <drawingType>Picture</drawingType>
    <id>1</id>
    <formatIndex>11</formatIndex>
    <beginRow>3</beginRow>
    <beginRowOffset>6</beginRowOffset>
    <endRow>4</endRow>
    <endRowOffset>33</endRowOffset>
    <beginColumn>2</beginColumn>
    <beginColumnOffset>0</beginColumnOffset>
    <endColumn>4</endColumn>
    <endColumnOffset>183</endColumnOffset>
    <autoSize>false</autoSize>
    <pictureSize>Proportionally</pictureSize>
    <zOrder>1</zOrder>
    <pictureIndex>1</pictureIndex>
</drawing>

Позиция задаётся через начальную/конечную строку и колонку + смещения в пикселях. pictureIndex ссылается на ресурс из палитры <picture>.

Объединения ячеек

<merge>
    <r>3</r>      <!-- строка (0-based), -1 = все строки -->
    <c>1</c>      <!-- колонка (0-based) -->
    <h>1</h>      <!-- доп. строк (опц., по умолчанию 0 = одна строка) -->
    <w>30</w>     <!-- доп. колонок -->
    <columnsID>f01e015f-...</columnsID>  <!-- опц.: набор колонок -->
</merge>

Размер объединения: (h + 1) строк × (w + 1) колонок. Если <h> не указан — объединение в пределах одной строки.

<r>-1</r> — объединение действует для всех строк, использующих данный набор колонок (аналог объединения колонок на уровне всего документа).

Отмена объединений

<verticalUnmerge> отменяет вертикальное объединение для конкретной строки:

<verticalUnmerge>
    <r>10</r>     <!-- строка (0-based) -->
    <c>7</c>      <!-- колонка (0-based) -->
    <w>12</w>     <!-- доп. колонок -->
</verticalUnmerge>

Используется в сложных макетах, когда глобальное объединение колонок (<r>-1</r>) нужно разорвать в отдельных строках.

Именованные области

Именованные области — аналог «имён» в табличном документе 1С. Используются для программного вывода секций.

Получение области:

// Горизонтальная область (диапазон строк)
Область = Макет.ПолучитьОбласть("Заголовок");

// Пересечение горизонтальной и вертикальной областей
Область = Макет.ПолучитьОбласть("ВысотаЭтикетки|ШиринаЭтикетки");

Пересечение через | типично для этикеток и ценников, где нужна область фиксированного размера (высота × ширина).

Тип Rows — горизонтальная область

<namedItem xsi:type="NamedItemCells">
    <name>Заголовок</name>
    <area>
        <type>Rows</type>
        <beginRow>1</beginRow>        <!-- 0-based -->
        <endRow>4</endRow>
        <beginColumn>-1</beginColumn> <!-- -1 = все колонки -->
        <endColumn>-1</endColumn>
    </area>
</namedItem>

Порядок элементов namedItem — по имени. Платформа хранит их отсортированными, регистронезависимо: на выборке 541 макета ERP 8.3.24 с несколькими именованными элементами иного порядка не встретилось ни разу. Сортировка ординальная (латиница раньше кириллицы); случай с «ё» в выборке не встретился и не проверен.

Тип Columns — вертикальная область

<namedItem xsi:type="NamedItemCells">
    <name>ШиринаЭтикетки</name>
    <area>
        <type>Columns</type>
        <beginRow>-1</beginRow>       <!-- -1 = все строки -->
        <endRow>-1</endRow>
        <beginColumn>1</beginColumn>  <!-- 0-based -->
        <endColumn>5</endColumn>
    </area>
</namedItem>

Тип Rectangle — прямоугольная область

Область, ограниченная и по строкам, и по колонкам. Используется с дополнительными наборами колонок:

<namedItem xsi:type="NamedItemCells">
    <name>ОбластьЗаписьДо</name>
    <area>
        <type>Rectangle</type>
        <beginRow>22</beginRow>         <!-- 0-based -->
        <endRow>22</endRow>
        <beginColumn>5</beginColumn>    <!-- 0-based -->
        <endColumn>17</endColumn>
        <columnsID>c6cb0794-...</columnsID>  <!-- набор колонок -->
    </area>
</namedItem>

Привязка к набору колонок

Именованные области могут ссылаться на дополнительный набор колонок через <columnsID>:

<namedItem xsi:type="NamedItemCells">
    <name>НумерацияЛистов</name>
    <area>
        <type>Rows</type>
        <beginRow>59</beginRow>
        <endRow>59</endRow>
        <beginColumn>-1</beginColumn>
        <endColumn>-1</endColumn>
        <columnsID>0adf41ed-...</columnsID>
    </area>
</namedItem>

Тип Drawing — именованный рисунок

<namedItem xsi:type="NamedItemDrawing">
    <name>Штрихкод</name>
    <drawingID>1</drawingID>          <!-- ссылка на drawing/id -->
</namedItem>

Стили линий

Палитра линий для границ ячеек и рисунков. Индексация 0-based.

<!-- Для границ ячеек -->
<line width="2" gap="false">
    <v8ui:style xsi:type="v8ui:SpreadsheetDocumentCellLineType">Solid</v8ui:style>
</line>

<!-- Для границ рисунков -->
<line width="1" gap="false">
    <v8ui:style xsi:type="v8ui:SpreadsheetDocumentDrawingLineType">None</v8ui:style>
</line>

xsi:type	Значения
v8ui:SpreadsheetDocumentCellLineType	Solid, None, Dotted, ThinDashed, LargeDashed, ThickDashed, Double
v8ui:SpreadsheetDocumentDrawingLineType	те же

Атрибут width — толщина линии; в корпусе встречаются 0, 1, 2, 3. Атрибут gap на корпусе всегда false, но пишется всегда.

Шрифты

Палитра шрифтов. Индексация 0-based.

<!-- Абсолютный шрифт -->
<font faceName="Arial" height="14" bold="true" italic="false"
      underline="false" strikeout="false" kind="Absolute" scale="100"/>

<!-- Ссылка на элемент стиля конфигурации -->
<font ref="style:TextFont" kind="StyleItem"/>

<!-- Ссылка на системный шрифт: префикс sys в корне НЕ объявлен, поэтому объявление
     дописывается прямо на узел — тот же приём, что у цветов из web-палитры -->
<font xmlns:sys="http://v8.1c.ru/8.1/data/ui/fonts/system"
      ref="sys:ANSIVariableFont" kind="WindowsFont"/>

kind выводится из префикса ссылки: style: → StyleItem, sys: → WindowsFont. На корпусе ERP таких шрифтов 272 в 213 макетах из 10 924 (StyleItem 209, WindowsFont 63).

Шрифт, на который не ссылается ни один формат, в палитру не попадает: у макета без оформления элемента <font> нет вовсе.

Устройство палитр

Три правила, общие для всех палитр. Все проверены на корпусе ERP (10 924 макета) и на макетах, собранных вручную в Конфигураторе.

Порядок — документный. Записи идут в том порядке, в каком встречаются при обходе документа сверху вниз: сначала форматы колонок (в порядке колонок), затем форматы строк и ячеек. Порядок НЕ зависит от того, в какой последовательности автор оформлял макет: контрольный опыт с оформлением снизу вверх дал палитру в порядке строк.

Формат по умолчанию — последняя запись. На корпусе он последний в 8285 макетах из 10 863, первым — в 25.

Палитра форматов дедуплицирована по содержимому: двух одинаковых записей в ней нет (10 804 макета из 10 924). Остальные 120 — накопленный мусор редактирования, там доходит до 583 записей при 130 уникальных.

Форматы

Палитра форматов — центральный элемент. Индексация 1-based (индекс 0 = формат не задан).

<format>
    <font>0</font>                          <!-- индекс шрифта (0-based) -->
    <leftBorder>0</leftBorder>              <!-- индекс линии левой границы -->
    <topBorder>1</topBorder>                <!-- индекс линии верхней границы -->
    <rightBorder>0</rightBorder>            <!-- индекс линии правой границы -->
    <bottomBorder>1</bottomBorder>          <!-- индекс линии нижней границы -->
    <width>24</width>                       <!-- ширина (для колонок) -->
    <height>84</height>                     <!-- высота (для строк) -->
    <horizontalAlignment>Center</horizontalAlignment>   <!-- Left | Center | Right -->
    <verticalAlignment>Center</verticalAlignment>       <!-- Top | Center -->
    <textPlacement>Wrap</textPlacement>     <!-- Wrap = перенос по словам -->
    <fillType>Parameter</fillType>          <!-- Parameter | Template | Text -->
    <format>                                <!-- строка формата (опционально) -->
        <v8:item>
            <v8:lang>ru</v8:lang>
            <v8:content>ЧЦ=15; ЧДЦ=2</v8:content>
        </v8:item>
    </format>
    <drawingBorder>1</drawingBorder>        <!-- индекс линии для рисунка -->
</format>

Все свойства опциональны. Формат может содержать только <width> (для колонки) или только <height> (для строки).

Порядок тегов

Внутри <format> теги идут в строгой последовательности — от неё зависит побайтовое совпадение с выгрузкой. Порядок снят с корпуса ERP: 766 960 форматов, ни один его не нарушает.

print · drawingBorder · drawingHaveLeftBorder · drawingHaveTopBorder ·
drawingHaveRightBorder · drawingHaveBottomBorder · font · leftBorder · topBorder ·
rightBorder · bottomBorder · border · height · borderColor · width ·
autoWidthCalculation · widthWeightFactor · horizontalAlignment · verticalAlignment ·
textColor · backColor · patternColor · pattern · textPlacement · fillType · protection ·
hidden · textOrientation · detailsUse · bySelectedColumns · markNegatives ·
containsValue · valueType · format · controlType · hyperLink · autoMarkIncomplete ·
indent · autoIndent · editFormat · columnSizeChange · mask · picIndex ·
pictureSizeMode · picHorizontalAlignment · picVerticalAlignment · textPosition

Обрати внимание: height идёт РАНЬШЕ width, а format — после valueType.

Ширина и высота

Единица — 1/8 символа: 72 = стандартные 9 символов, 240 = 30, 80 = 10.

Рамка

Четыре стороны и свёрнутый <border> взаимоисключающи. Если все четыре стороны одинаковы, платформа пишет один <border>; иначе — по сторонам. На корпусе: 70 265 свёрнутых форматов против 36 783 записанных по сторонам, и среди вторых нет ни одного с четырьмя совпадающими значениями; смешения border с посторонними тегами нет ни разу.

Цвет

Значение цвета (backColor, textColor, borderColor, patternColor) — строка с префиксом пространства имён, а не свободный текст:

Запись в XML	Смысл
#RRGGBB	RGB-hex
style:ИмяСтиля	элемент стиля; префикс style объявлен в корне документа
d3p1:Имя + xmlns:d3p1=".../ui/colors/web" на самом узле	цвет web-палитры
d3p1:Имя + xmlns:d3p1=".../ui/colors/windows" на самом узле	системный цвет Windows

Корень <document> объявляет только style, поэтому для web- и windows-палитр платформа дописывает объявление прямо на узел. Префикс всегда d3p1 (1264 вхождения на корпусе без отклонений). В Form.xml те же цвета выглядят как web:Имя и win:Имя — там эти префиксы объявлены в корне.

Связь формата с контекстом

Один формат обслуживает всех: колонка, строка и ячейка ссылаются в одну палитру, и набор свойств у них общий (hidden встречается у ячеек 30 175 раз, у строк 17 423, у колонок 57; protection — 84 442 / 1 492 / 1 017).

Контекст	Ссылка	Свойства, специфичные для контекста
Колонка	<formatIndex>	width
Строка	<formatIndex>	height, hidden
Ячейка	<f>	fillType, containsValue
Рисунок	<formatIndex>	drawingBorder, drawing*
По умолчанию	<defaultFormatIndex>	width

Оформление, применённое к строке целиком, платформа записывает И в формат строки, И в формат каждой ячейки (backColor: 13 899 ячеек повторяют против 96). Исключение — hidden: оно остаётся только у строки (24 026 против 62 856).

Ловушка: width в формате ЯЧЕЙКИ не описывает ячейку. Ссылка ячейки на запись палитры не обновляется при изменении ширины колонки, поэтому там остаётся ширина от прежнего состояния документа. Проверено на контролируемом стенде: в макете, где ширины колонок поменяли на обратные, ячейки продолжают ссылаться на записи со старыми ширинами. Из итогового XML это значение не выводится — воспроизводить его не нужно.

Ресурсы картинок

<picture>
    <index>0</index>
    <picture ref="v8ui:Штрихкод"/>    <!-- ссылка на предопределённую картинку -->
</picture>

Типичная структура макета печатной формы

Печатная форма обычно состоит из именованных горизонтальных областей:

Заголовок      — шапка документа (название, номер, дата)
Поставщик      — реквизиты поставщика
Покупатель     — реквизиты покупателя
ШапкаТаблицы   — заголовок таблицы товаров
Строка         — строка товара (выводится в цикле)
Итого          — итоговая строка
СуммаПрописью  — сумма прописью
Подписи        — блок подписей

Каждая область — диапазон строк, получаемый через ПолучитьОбласть("Имя") и выводимый через Вывести().

Параметры в ячейках (<parameter>) заполняются программно:

Область = Макет.ПолучитьОбласть("Строка");
Область.Параметры.НомерСтроки = НомерСтроки;
Область.Параметры.Товар = СтрокаТЧ.Номенклатура;
ТабДок.Вывести(Область);

Совместимость версий платформы

Проведено сравнение выгрузок конфигурации «Бухгалтерия предприятия 3.0» на трёх версиях платформы: 8.3.20, 8.3.24, 8.3.27.

Template.xml (табличный документ)

Содержимое Template.xml побайтно идентично на всех трёх версиях. Формат табличного документа стабилен — пространства имён, набор тегов и структура не менялись между 8.3.20 и 8.3.27.

Метаданные (version в MetaDataObject)

Атрибут version корневого элемента <MetaDataObject> в XML-файлах метаданных (.xml объектов, форм, макетов):

Платформа	version
8.3.20	2.17
8.3.24	2.17
8.3.25	2.18
8.3.26	2.19
8.3.27	2.20

Form.xml (управляемая форма)

Содержимое Form.xml идентично между 8.3.20 и 8.3.24. Дальше различается только атрибут version в корневом элементе <Form> (2.17 → 2.18 → 2.19 → 2.20 по платформам). Пространства имён и структура не изменились.

BSL-модули

Модули на встроенном языке (ObjectModule.bsl) полностью идентичны на всех трёх версиях.

Обратная совместимость

Навыки генерируют XML с version="2.17". Сборка EPF через 1cv8.exe версии 8.3.27 проходит успешно — платформа принимает файлы с более старым номером версии без ошибок. Повышать version до "2.20" не требуется.