افزودن نظرات سریع مستقیماً به اسناد Word یک نیاز رایج برای جریان‌های کاری بررسی مشترک است. GroupDocs.Annotation Cloud SDK for Node.JS به شما امکان می‌دهد تا به‌صورت برنامه‌نویسی حاشیه‌نویسی‌های غنی را بدون ترک محیط سرور خود اضافه کنید. در این راهنما نشان خواهیم داد که چگونه Sticky Notes را بر روی صفحات 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: راهنمای گام‌به‌گام

در این راهنما، با استفاده از کلاس‌های حاشیه‌نویسی SDK، یادداشت‌های چسبان را بر روی صفحات Word در Node.JS ایجاد خواهیم کرد.

مرحله 1: مقداردهی اولیه API حاشیه‌نویسی

ابتدا کلاس‌های مورد نیاز را وارد کنید و یک نمونه از AnnotateApi ایجاد کنید.

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

مرحله ۲: تعریف فایل‌های منبع و مقصد

ورودی DOCX را مشخص کنید و مسیر خروجی حاشیه‌دار را تعیین کنید.

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

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

مرحله ۳: تنظیم موقعیت یادداشت چسبان

یک Rectangle ایجاد کنید که تعیین می‌کند یادداشت چسبان در صفحه ۱ کجا ظاهر شود.

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: ساخت شیء حاشیه‌نویسی یادداشت چسبان

نوع حاشیه‌نویسی، شماره صفحه، مستطیل، متن و رنگ پس‌زمینه را پیکربندی کنید.

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);
    }
})();

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید که مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روزرسانی کنید که با محیط واقعی شما مطابقت داشته باشد، اطمینان حاصل کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.

افزودن حاشیه‌نویسی‌های یادداشت چسبان با cURL و REST API

API REST همان قابلیت را بدون نوشتن کد ارائه می‌دهد. در زیر فراخوانی‌های 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‑cURL را استفاده کنید، SDK روشی ثابت و قابل اعتماد برای حاشیه‌نویسی برنامه‌نویسی فایل‌های DOCX فراهم می‌کند. به‌خاطر داشته باشید برای استفاده در محیط تولید یک لایسنس معتبر اعمال کنید؛ می‌توانید یک لایسنس موقت را از صفحه لایسنس دریافت کنید یا گزینه‌های قیمت‌گذاری را در صفحه محصول بررسی کنید. حاشیه‌نویسی خوشایند!

سوالات متداول

  • چگونه می‌توانم Sticky Notes را روی صفحات Word در Node.JS با استفاده از GroupDocs.Annotation Cloud SDK ایجاد کنم؟
    از AnnotateApi همان‌طور که در مثال کد نشان داده شده است استفاده کنید. SDK به‌صورت خودکار دسترسی به فایل، ایجاد حاشیه‌نویسی و تولید خروجی را مدیریت می‌کند.

  • کدام فرمت‌های فایل برای حاشیه‌نویسی با SDK پشتیبانی می‌شوند؟
    SDK با فرمت‌های DOCX، PDF، PPTX، XLSX، و بسیاری از فرمت‌های محبوب دیگر کار می‌کند. فهرست کامل را در مستندات رسمی ببینید.

  • چگونه هنگام استفاده از REST API برای یادداشت‌های چسبان احراز هویت کنم؟
    یک توکن دسترسی را از طریق نقطه انتهایی /auth/token با استفاده از اعتبارهای کلاینت خود دریافت کنید، سپس توکن را در هدر Authorization: Bearer برای تمام درخواست‌های بعدی گنجانید. مراحل دقیق در مرجع API موجود است.

  • آیا می‌توانم رنگ یا اندازهٔ یادداشت چسبان را سفارشی کنم؟
    بله. ویژگی color را به مقدار HEX تنظیم کنید و ابعاد rect (width، height) را تنظیم کنید تا اندازه و مکان یادداشت را کنترل کنید.

بیشتر بخوانید