Добавление быстрых комментариев непосредственно в документы Word является распространённым требованием для совместных рабочих процессов рецензирования. GroupDocs.Annotation Cloud SDK for Node.JS позволяет программно добавлять насыщенные аннотации, не покидая серверную среду. В этом руководстве мы покажем, как создавать стикер‑заметки на страницах Word в Node.JS, охватывая настройку, подробный пошаговый процесс, полный пример кода и эквивалентные вызовы cURL.

Настройка GroupDocs.Annotation Cloud SDK для Node.JS

Прежде чем начать, убедитесь, что у вас есть:

  • Node.js 14+ и npm установлен
  • Учётная запись GroupDocs cloud с clientId и clientSecret
  • Доступ к исходному файлу DOCX, который вы хотите аннотировать

Установите SDK через npm:

npm install groupdocs-annotation-cloud

Скачайте последнюю версию пакета со страницы официального релиза, если вы предпочитаете ручную установку: GroupDocs.Annotation Cloud SDK for Node.JS Скачать.

Создайте объект конфигурации с вашими учётными данными (выдержка из полного примера):

const { Configuration } = require("@groupdocs.annotation-cloud");

const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

С установленным SDK и готовыми учётными данными мы можем перейти к реализации.

Создание стикеров на страницах Word в Node.JS: пошаговое руководство

В этом руководстве мы создадим Sticky Notes на страницах Word в Node.JS, используя классы аннотаций SDK.

Шаг 1: Инициализация API аннотаций

Сначала импортируйте необходимые классы и создайте экземпляр AnnotateApi.

const { AnnotateApi, models } = require("@groupdocs.annotation-cloud");
const annotateApi = new AnnotateApi(config);

Шаг 2: Определите исходный и целевой файлы

Укажите входной DOCX и путь для аннотированного вывода.

const inputFilePath = "sample.docx";
const outputFilePath = "sample_annotated.docx";

const fileInfo = new models.FileInfo();
fileInfo.filePath = inputFilePath;

Шаг 3: Настройка положения липкой заметки

Создайте Rectangle, который определяет, где будет отображаться липкая заметка на странице 1.

const rect = new models.Rectangle();
rect.x = 100;      // distance from left edge (points)
rect.y = 100;      // distance from top edge (points)
rect.width = 200;  // width of the sticky note
rect.height = 100; // height of the sticky note

Шаг 4: Создание объекта аннотации Sticky Note

Настройте тип аннотации, номер страницы, прямоугольник, текст и цвет фона.

const stickyNote = new models.AnnotationInfo();
stickyNote.annotationType = "StickyNote";
stickyNote.pageNumber = 1;
stickyNote.rect = rect;
stickyNote.text = "This is a sticky note added via GroupDocs.Annotation Cloud SDK.";
stickyNote.color = "FFFF00"; // Yellow background

Шаг 5: Выполнение запроса аннотации

Соберите параметры запроса и вызовите метод annotate.

const annotateOptions = new models.AnnotateOptions();
annotateOptions.fileInfo = fileInfo;
annotateOptions.annotations = [stickyNote];
annotateOptions.outputPath = outputFilePath;

(async () => {
    try {
        const request = new models.AnnotateRequest(annotateOptions);
        const response = await annotateApi.annotate(request);
        console.log("Sticky note created successfully. Output saved to:", response.path);
    } catch (err) {
        console.error("Failed to create sticky note:", err);
    }
})();

Полный рабочий пример создания стикеров на страницах Word в Node.JS

Следующий пример демонстрирует полную реализацию создания Sticky Notes на страницах Word в Node.JS с использованием GroupDocs.Annotation Cloud SDK.

const { AnnotateApi, Configuration, models } = require("@groupdocs.annotation-cloud");

// -----------------------------------------------------------------------------
// Configuration – replace with your actual GroupDocs credentials
// -----------------------------------------------------------------------------
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

const annotateApi = new AnnotateApi(config);

// -----------------------------------------------------------------------------
// Define input and output files
// -----------------------------------------------------------------------------
const inputFilePath = "sample.docx";
const outputFilePath = "sample_annotated.docx";

// -----------------------------------------------------------------------------
// Build FileInfo object for the source document
// -----------------------------------------------------------------------------
const fileInfo = new models.FileInfo();
fileInfo.filePath = inputFilePath;

// -----------------------------------------------------------------------------
// Define rectangle (position & size) for the sticky note on page 1
// -----------------------------------------------------------------------------
const rect = new models.Rectangle();
rect.x = 100;      // distance from left edge (points)
rect.y = 100;      // distance from top edge (points)
rect.width = 200;  // width of the sticky note
rect.height = 100; // height of the sticky note

// -----------------------------------------------------------------------------
// Create the sticky‑note annotation
// -----------------------------------------------------------------------------
const stickyNote = new models.AnnotationInfo();
stickyNote.annotationType = "StickyNote";
stickyNote.pageNumber = 1;
stickyNote.rect = rect;
stickyNote.text = "This is a sticky note added via GroupDocs.Annotation Cloud SDK.";
stickyNote.color = "FFFF00"; // Yellow background

// -----------------------------------------------------------------------------
// Assemble the annotate request options
// -----------------------------------------------------------------------------
const annotateOptions = new models.AnnotateOptions();
annotateOptions.fileInfo = fileInfo;
annotateOptions.annotations = [stickyNote];
annotateOptions.outputPath = outputFilePath;

// -----------------------------------------------------------------------------
// Execute the request
// -----------------------------------------------------------------------------
(async () => {
    try {
        const request = new models.AnnotateRequest(annotateOptions);
        const response = await annotateApi.annotate(request);
        console.log("Sticky note created successfully. Output saved to:", response.path);
    } catch (err) {
        console.error("Failed to create sticky note:", err);
    }
})();

Примечание: Этот пример кода демонстрирует базовый функционал. Прежде чем использовать его в вашем проекте, убедитесь, что обновили все пути к файлам и значения конфигурации в соответствии с вашей реальной средой, проверьте, что все необходимые зависимости правильно установлены, и тщательно протестируйте в вашей среде разработки. Если вы столкнётесь с какими‑либо проблемами, обратитесь к официальной документации или свяжитесь с командой поддержки для получения помощи.

Добавление аннотаций Sticky Note с помощью cURL и REST API

REST API предоставляет те же возможности без написания кода. Ниже приведены необходимые вызовы cURL.

Сначала получите токен доступа:

curl -X POST "https://api.groupdocs.cloud/v2.0.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

Загрузите исходный файл DOCX (замените YOUR_ACCESS_TOKEN токеном из предыдущего шага):

curl -X PUT "https://api.groupdocs.cloud/v2.0.0/storage/file/sample.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary @sample.docx

Создайте аннотацию с липкой заметкой:

curl -X POST "https://api.groupdocs.cloud/v2.0.0/annotation/annotate" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfo": { "filePath": "sample.docx" },
           "annotations": [
               {
                   "annotationType": "StickyNote",
                   "pageNumber": 1,
                   "rect": { "x": 100, "y": 100, "width": 200, "height": 100 },
                   "text": "This is a sticky note added via GroupDocs.Annotation Cloud SDK.",
                   "color": "FFFF00"
               }
           ],
           "outputPath": "sample_annotated.docx"
         }'

Скачать аннотированный документ:

curl -X GET "https://api.groupdocs.cloud/v2.0.0/storage/file/sample_annotated.docx?download=true" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o sample_annotated.docx

Для получения более подробной информации о полезных нагрузках запросов см. справку API.

Настройка параметров аннотации для стик‑нотов

SDK предоставляет несколько свойств, позволяющих точно настроить внешний вид и поведение стикер‑заметки:

  • annotationType - должно быть установлено в "StickyNote" (обязательно).
  • pageNumber - страница, на которой появится заметка.
  • rect - определяет позицию (x, y) и размер (width, height). Отрегулируйте эти значения для управления размещением.
  • text - содержание заметки.
  • color - цвет фона в HEX (например, "FFFF00" для желтого).

Вы также можете установить необязательные поля, такие как author, fontFamily или opacity, через модель AnnotationInfo. Обратитесь к справке API для полного списка настраиваемых свойств.

Заключение

Следуя приведённым выше шагам, вы теперь знаете, как создавать Sticky Notes на страницах Word в Node.JS с помощью GroupDocs.Annotation Cloud SDK. Независимо от того, предпочитаете ли вы нативную реализацию на Node.js или рабочий процесс на основе REST‑based cURL, SDK предоставляет последовательный и надёжный способ программно аннотировать файлы DOCX. Не забудьте применить действующую лицензию для использования в продакшене; временную лицензию можно получить на license page или ознакомиться с вариантами ценообразования на странице продукта. Happy annotating!

Часто задаваемые вопросы

  • Как создать Sticky Notes на страницах Word в Node.JS, используя GroupDocs.Annotation Cloud SDK?
    Используйте AnnotateApi, как показано в примере кода. SDK автоматически обрабатывает доступ к файлам, создание аннотаций и генерацию вывода.

  • Какие форматы файлов поддерживаются для аннотирования с помощью SDK?
    SDK работает с DOCX, PDF, PPTX, XLSX, а также со многими другими популярными форматами. Смотрите полный список в официальной документации.

  • Как аутентифицироваться при использовании REST API для стикеров?
    Получите токен доступа через endpoint /auth/token, используя ваши клиентские учётные данные, затем включите токен в заголовок Authorization: Bearer для всех последующих вызовов. Подробные шаги находятся в справке API.

  • Могу ли я настроить цвет или размер стикер‑заметки?
    Да. Установите свойство color в значение HEX и отрегулируйте размеры rect (width, height), чтобы контролировать размер и расположение заметки.

Читать далее