Плагин Docscript

Скачать плагин ↗

О плагине

docscript — модуль интеграции для внешних приложений (генерация документов, конвертация документов, проверка орфографии).

Плагин работает на базе R7-Office DocBuilder SDK и позволяет создавать документы без ручного редактирования: структура документа, стили, таблицы, списки, изображения, колонтитулы и специальные поля описываются в JSON-файле, после чего автоматически формируется готовый офисный документ.

Разработчик: АО Р7

Особенности плагина

Макрос

Плагин поддерживает выполнение .docbuilder-скриптов для прямой работы с DocBuilder API.

Плагин

Плагин позволяет создавать документы Word и другие офисные файлы на основе JSON-описания, использовать DOCX-шаблоны с плейсхолдерами, выполнять конвертацию форматов и проверять орфографию.

Модификация интерфейса

Плагин не изменяет интерфейс редактора и работает как инструмент командной строки.

Плагин поддерживает

Десктоп-редакторы Р7-Офис на Windows, macOS и Linux.

Функциональные возможности:

• генерация DOCX-документов из JSON;
• поддержка параграфов, заголовков, списков, таблиц и изображений;
• настройка форматирования текста, стилей, выравнивания и отступов;
• добавление колонтитулов, номеров страниц и специальных полей;
• работа с DOCX-шаблонами через плейсхолдеры;
• конвертация документов, таблиц и презентаций в другие форматы;
• проверка орфографии для русского и английского языков;
• выполнение .docbuilder-скриптов;
• поддержка выходных форматов DOCX, ODT, RTF, TXT, XLSX, PPTX, HTML и PDF.

История версий

Версия 1.1

Внесены небольшие улучшения и устранены недочеты.

Версия 1.0

Добавлены основные возможности:

• генерация документов из JSON;
• поддержка структуры документа: параграфы, списки, таблицы, изображения, стили и колонтитулы;
• работа с DOCX-шаблонами и плейсхолдерами;
• конвертация офисных форматов;
• проверка орфографии;
• выполнение .docbuilder-скриптов.

FAQ

Какие документы можно создавать с помощью плагина?

Плагин позволяет создавать документы на основе JSON-описания. Основной сценарий — генерация DOCX, но также поддерживаются другие выходные форматы, включая ODT, RTF, TXT, XLSX, PPTX и HTML.

Можно ли использовать готовый DOCX-шаблон?

Да. В шаблоне можно добавить плейсхолдеры вида {{имяКлюча}}, а затем заменить их содержимым из JSON-файла.

Какие элементы документа поддерживаются?

Поддерживаются параграфы, заголовки, форматированные фрагменты текста, маркированные и нумерованные списки, таблицы, изображения, разрывы страниц, колонтитулы, стили, номера страниц, поля слияния, закладки и перекрёстные ссылки.

Можно ли конвертировать документы в PDF?

Да. Плагин поддерживает конвертацию DOCX, XLSX, PPTX и других офисных форматов в PDF.

Можно ли проверять орфографию?

Да. Плагин поддерживает проверку орфографии для русского и английского языков. Результат проверки выводится в формате JSON.

Нужно ли открывать редактор вручную?

Нет. Плагин работает из командной строки и использует R7-Office DocBuilder SDK для автоматической обработки документов.

На каких системах работает плагин?

Плагин работает на macOS и Linux при установленной десктопной версии Р7-Офис.

Подробное описание

Ниже приведено подробное руководство по работе с docscript: требования, быстрый старт, режимы работы, структура JSON-документа, поддерживаемые форматы, аргументы командной строки и типичные проблемы.

1. Требования

Для работы необходимы:

• установленный R7-Office, десктопная версия;
• скомпилированный бинарник docscript.

Стандартные пути установки R7-Office:

После установки плагина для вызова docscript:

На Windows платформе использовать путь "C:\Users\<имя пользователя>\Local Settings\R7-Office\Editors\data\sdkjs-plugins\{8DFE6EDD-C82A-4DBD-A2A3-6374C8D8D662}\docscript.exe".

Где:

• <имя пользователя> – пользователь, под которым был установлен плагин (например, admin).

На Linux платформе — использовать команду запуска

/bin/sh /home/<имя пользователя>/.local/share/r7-office/editors/sdkjs-plugins/{8DFE6EDD-C82A-4DBD-A2A3-6374C8D8D662}/docscript.sh

На Mac платформе – использовать команду запуска

/bin/sh /Users/<имя пользователя>/Library/Application\ Support/ru.nkt.r7-office-signature/data/sdkjs-plugins/\{8DFE6EDD-C82A-4DBD-A2A3-6374C8D8D662\}/docscript.sh

2. Быстрый старт

Примеры базовых команд:

# Создать документ из JSON
./docscript -i my_document.json -o result.docx

# Конвертировать DOCX в PDF
./docscript -conv -i result.docx -o result.pdf

# Проверить орфографию
./docscript -grammar_check -i result.docx

3. Режим 1 — Генерация документа из JSON

Основной режим работы — создание документа из JSON-файла:

./docscript -i <файл.json> -o <результат.docx>

Инструмент читает JSON-файл с описанием документа и создаёт DOCX. Также поддерживаются другие выходные форматы: .odt, .rtf, .txt, .xlsx, .pptx. Формат результата определяется по расширению выходного файла.

Пример:

./docscript -i report.json -o report.docx
./docscript -i report.json -o report.odt

4. Структура JSON-документа

Файл JSON верхнего уровня может содержать несколько необязательных разделов:

{
  "styles":          [ ... ],
  "header":          { ... },
  "footer":          { ... },
  "firstPageHeader": { ... },
  "firstPageFooter": { ... },
  "content":         [ ... ]
}

Единственный обязательный раздел — content. Остальные можно опускать.

Параграфы

Простейший элемент документа — параграф с текстом:

{ "type": "paragraph", "text": "Привет, мир!" }

Именованные стили, соответствующие встроенным стилям Word/R7-Office:

{ "type": "paragraph", "style": "Heading 1", "text": "Заголовок первого уровня" }
{ "type": "paragraph", "style": "Heading 2", "text": "Заголовок второго уровня" }
{ "type": "paragraph", "style": "Heading 3", "text": "Заголовок третьего уровня" }
{ "type": "paragraph", "text": "Обычный текст" }

Выравнивание:

{ "type": "paragraph", "align": "left",    "text": "По левому краю (по умолчанию)" }
{ "type": "paragraph", "align": "center",  "text": "По центру" }
{ "type": "paragraph", "align": "right",   "text": "По правому краю" }
{ "type": "paragraph", "align": "justify", "text": "По ширине" }

Форматирование на уровне параграфа применяется ко всему тексту:

{
  "type": "paragraph",
  "text": "Жирный красный текст 14pt",
  "bold": true,
  "color": "#CC0000",
  "fontSize": 14
}

Отступы между параграфами задаются в твипах. 1 твип = 1/20 пт.

{
  "type": "paragraph",
  "text": "Параграф с отступами",
  "spacingBefore": 240,
  "spacingAfter": 120
}

Форматирование текста — runs

Если в одном параграфе нужно смешать разное форматирование, используется массив runs — набор текстовых фрагментов:

{
  "type": "paragraph",
  "runs": [
    { "text": "Обычный текст, " },
    { "text": "жирный", "bold": true },
    { "text": ", " },
    { "text": "курсив", "italic": true },
    { "text": ", " },
    { "text": "подчёркнутый", "underline": true },
    { "text": " и " },
    { "text": "цветной", "color": "#0070C0", "fontSize": 16 }
  ]
}

Списки

Маркированный список:

{ "type": "paragraph", "listType": "bullet", "text": "Первый пункт" },
{ "type": "paragraph", "listType": "bullet", "text": "Второй пункт" },
{ "type": "paragraph", "listType": "bullet", "text": "Третий пункт" }

Нумерованный список:

{ "type": "paragraph", "listType": "numbered", "text": "Шаг первый" },
{ "type": "paragraph", "listType": "numbered", "text": "Шаг второй" },
{ "type": "paragraph", "listType": "numbered", "text": "Шаг третий" }

Вложенный список задаётся через listLevel: 0 — верхний уровень, 1 — вложенный и так далее.

{ "type": "paragraph", "listType": "bullet", "listLevel": 0, "text": "Пункт верхнего уровня" },
{ "type": "paragraph", "listType": "bullet", "listLevel": 1, "text": "Вложенный пункт" },
{ "type": "paragraph", "listType": "bullet", "listLevel": 2, "text": "Ещё глубже" }

Таблицы

{
  "type": "table",
  "rows": [
    [ "Имя",    "Должность",  "Отдел"   ],
    [ "Иванов", "Менеджер",   "Продажи" ],
    [ "Петров", "Разработчик","IT"       ]
  ]
}

Форматирование ячеек — вместо строки можно передать объект:

{
  "type": "table",
  "rows": [
    [
      { "text": "Заголовок", "bold": true, "background": "#4472C4", "color": "#FFFFFF" },
      { "text": "Значение",  "bold": true, "background": "#4472C4", "color": "#FFFFFF" }
    ],
    [
      { "text": "Строка 1", "background": "#DDEEFF" },
      "Данные"
    ]
  ]
}

Изображения

{
  "type": "image",
  "src": "/Users/user/pictures/logo.png",
  "width": 5.0,
  "height": 3.0
}

• src — абсолютный путь к файлу на диске. Поддерживаются PNG, JPG, GIF, BMP, WebP, SVG.
• width и height — размеры в дюймах, например 6.0 × 4.0.
• Также принимаются интернет-URL и data-URL.

Разрыв страницы

{ "type": "pageBreak" }

Колонтитулы

Обычный колонтитул отображается на всех страницах:

{
  "header": {
    "content": [
      { "type": "paragraph", "text": "Название организации", "align": "center" }
    ]
  },
  "footer": {
    "content": [
      {
        "type": "paragraph",
        "align": "center",
        "runs": [
          { "text": "Страница " },
          { "type": "pageNumber" },
          { "text": " из " },
          { "type": "pagesCount" }
        ]
      }
    ]
  }
}

Разные колонтитулы для первой страницы:

{
  "firstPageHeader": {
    "content": [
      { "type": "paragraph", "text": "Титульный лист — без колонтитула" }
    ]
  },
  "header": {
    "content": [
      { "type": "paragraph", "text": "Обычный заголовок (страницы 2+)" }
    ]
  },
  "firstPageFooter": {
    "content": []
  },
  "footer": {
    "content": [
      { "type": "paragraph", "align": "right",
        "runs": [ { "type": "pageNumber" } ] }
    ]
  }
}

Наличие firstPageHeader или firstPageFooter автоматически включает режим «разная первая страница».

Стили

Раздел styles позволяет переопределить внешний вид встроенных стилей документа. Изменения применяются до создания контента, поэтому все параграфы с указанным стилем унаследуют их автоматически.

{
  "styles": [
    {
      "name": "Heading 1",
      "fontSize": 16,
      "bold": true,
      "color": "#1F3864",
      "spacingBefore": 240,
      "spacingAfter": 120
    },
    {
      "name": "Normal",
      "fontSize": 12,
      "fontName": "Times New Roman",
      "align": "justify"
    }
  ]
}

Специальные поля

Специальные поля используются внутри массива runs параграфа.

Номер текущей страницы:

{ "type": "pageNumber" }

Общее количество страниц:

{ "type": "pagesCount" }

Нумерация последовательностей — аналог SEQ-поля в Word для подписей рисунков и таблиц:

{
  "type": "paragraph",
  "runs": [
    { "text": "Таблица " },
    { "type": "seq", "id": "Table" },
    { "text": ". Сводные данные" }
  ]
}

Счётчик id ведётся независимо для каждого идентификатора. Первый вызов даёт 1, второй — 2 и так далее.

Поле слияния:

{ "type": "mergeField", "name": "ФамилияПолучателя" }

Закладка и перекрёстная ссылка:

Сначала на параграф ставится закладка:

{ "type": "paragraph", "text": "Таблица 1. Показатели", "bookmark": "tbl1" }

Затем в другом месте на неё можно сослаться:

{
  "type": "paragraph",
  "runs": [
    { "text": "Подробнее см. " },
    { "type": "ref", "bookmark": "tbl1", "refType": "text", "link": true }
  ]
}

Значения refType:

• text — текст параграфа;
• pageNum — номер страницы;
• paraNum — номер абзаца.

5. Режим 2 — Шаблоны с плейсхолдерами

Если есть готовый DOCX-файл с оформлением и нужно только заполнить его содержимым, используется шаблонный режим.

Подготовка шаблона

В любом месте шаблонного DOCX-документа нужно добавить параграфы-плейсхолдеры в формате {{имяКлюча}}. Каждый плейсхолдер должен занимать весь параграф целиком, а не быть частью текста.

Пример JSON для шаблона:

{
  "template": "template.docx",

  "mainContent": [
    { "type": "paragraph", "style": "Heading 1", "text": "Отчёт за квартал" },
    { "type": "paragraph", "text": "Данный отчёт подготовлен автоматически." }
  ],

  "summaryTable": [
    {
      "type": "table",
      "rows": [
        [ "Показатель", "Значение" ],
        [ "Выручка",    "1 200 000 ₽" ],
        [ "Расходы",    "800 000 ₽"   ]
      ]
    }
  ]
}

В файле template.docx должны быть параграфы {{mainContent}} и {{summaryTable}}. Они будут заменены соответствующим содержимым.

Запуск:

./docscript -i data.json -o filled_report.docx

Путь к шаблону в поле template может быть:

• абсолютным: /Users/user/templates/template.docx;
• относительным — относительно папки JSON-файла: template.docx, ../templates/base.docx.

6. Режим 3 — Конвертация форматов

Конвертация выполняется через x2t — встроенный конвертер R7-Office. Формат определяется по расширению файла.

./docscript -conv -i <входной_файл> -o <выходной_файл>

Примеры:

# DOCX → PDF
./docscript -conv -i report.docx -o report.pdf

# DOCX → ODT
./docscript -conv -i report.docx -o report.odt

# XLSX → PDF
./docscript -conv -i table.xlsx -o table.pdf

# PPTX → PDF
./docscript -conv -i slides.pptx -o slides.pdf

# DOCX → HTML
./docscript -conv -i report.docx -o report.html

Поддерживаемые форматы

Формат HTML в качестве вывода при генерации из JSON также поддерживается — промежуточный DOCX создаётся автоматически и затем конвертируется.

7. Режим 4 — Проверка орфографии

./docscript -grammar_check -i <файл> [-grammar_lang <язык>]

Примеры:

# Автоматическое определение языка — en_US + ru_RU
./docscript -grammar_check -i document.docx

# Только русский
./docscript -grammar_check -i document.docx -grammar_lang ru_RU

# Только английский
./docscript -grammar_check -i document.docx -grammar_lang en_US

# Проверить plain-text файл
./docscript -grammar_check -i notes.txt

Входные форматы: .docx, .doc, .odt, .html, .htm, а также .txt напрямую.

Файлы .docx, .doc, .odt, .html и .htm автоматически конвертируются во временный TXT перед проверкой.

Результат выводится в stdout в формате JSON:

[
  { "line": 3, "col": 12, "word": "привеет",  "suggestions": ["привет", "приветет"] },
  { "line": 7, "col": 5,  "word": "recieve",  "suggestions": ["receive", "relieve"] }
]

Если ошибок нет, выводится пустой массив:

[]

Автоматический режим языка работает без аргумента -grammar_lang: латинские слова проверяются по en_US, кириллические — по ru_RU. Если словарь ru_RU не найден, кириллические слова пропускаются с предупреждением в stderr.

Список игнорируемых слов

Слова, которые заведомо верны (имена собственные, аббревиатуры, внутренние термины), можно добавить в постоянный список исключений. При каждом запуске -grammar_check список загружается автоматически и такие слова не попадают в отчёт об ошибках.

Список хранится в файле grammar_ignore.txt в той же папке, что и бинарник docscript. Формат — UTF-8, одно слово на строку. Можно добавлять исключения прямой записью в этот файл или через командную строку.

Управление списком:

# Добавить слово
./docscript -grammar_ignore_add Иванов
./docscript -grammar_ignore_add API
# Просмотреть весь список
./docscript -grammar_ignore_get
# Удалить слово
./docscript -grammar_ignore_del API

Пример рабочего процесса:

# Первая проверка — «Иванов» и «R7Office» помечаются как ошибки
./docscript -grammar_check -i report.docx
# Добавляем их в исключения
./docscript -grammar_ignore_add Иванов
./docscript -grammar_ignore_add R7Office
# Повторная проверка — эти слова больше не выводятся
./docscript -grammar_check -i report.docx

8. Режим 5 — Выполнение .docbuilder-скриптов

Для прямой работы с DocBuilder API можно передать .docbuilder-файл как аргумент. Скрипт сам управляет созданием, заполнением и сохранением документа.

./docscript <script.docbuilder>

Пример .docbuilder-скрипта:

// hello.docbuilder
builder.CreateFile("docx");
var oDoc = Api.GetDocument();
var oPara = Api.CreateParagraph();
oPara.AddText("Hello from DocBuilder!");
oDoc.Push(oPara);
builder.SaveFile("docx", "/tmp/hello.docx");
builder.CloseFile();

Также можно выполнить произвольный JS-файл с входным и выходным документом:

./docscript transform.js -i input.docx -o output.docx

9. Справочник аргументов командной строки

Пути по умолчанию для -editor_path:

• macOS: /Applications/R7-Office.app/Contents/Resources
• Linux: /opt/r7-office/desktopeditors

10. Коды возврата и диагностика

Коды возврата

Диагностические сообщения

Диагностические сообщения выводятся в stderr.

• [patch] cannot write ... — нет прав на запись в native.js. Решение: sudo chmod a+w "<путь>/native.js"
• [image] cannot read '...' — файл изображения не найден, путь оставлен как есть.
• [image] inlined '...' — изображение успешно закодировано в base64.
• SaveFile(...) -> 88 — ошибка сохранения SDK: неверный путь, нет прав на запись или RunTextA вернул ошибку ранее.
• RunTextA(...) -> 0 — скрипт вернул ошибку; нужно проверить синтаксис JSON и логику fromjson.js.
• Warning: ru_RU dictionary not found — словарь для русского языка не найден в dictionaries/ru_RU/.

Типичные проблемы

Примеры для генерации документов из JSON