إضافة تعليقات سريعة مباشرةً إلى مستندات Word هي متطلب شائع لتدفقات العمل التعاونية للمراجعة. GroupDocs.Annotation Cloud SDK for Node.JS يتيح لك إضافة تعليقات غنية برمجياً دون مغادرة بيئة الخادم الخاصة بك. في هذا الدليل سنوضح لك كيفية إنشاء ملاحظات لاصقة على صفحات Word في Node.JS، مع تغطية الإعداد، دليل تفصيلي، مثال كامل على الكود، واستدعاءات cURL المكافئة.
إعداد GroupDocs.Annotation Cloud SDK for 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 Download.
إنشاء كائن تكوين باستخدام بيانات الاعتماد الخاصة بك (مقتطف من المثال الكامل):
const { Configuration } = require("@groupdocs.annotation-cloud");
const config = new Configuration({
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
});
مع تثبيت SDK وإعداد بيانات الاعتماد، يمكننا المتابعة إلى التنفيذ.
إنشاء ملاحظات لاصقة على صفحات Word في Node.JS: دليل خطوة بخطوة
في هذا الشرح سنقوم بإنشاء ملاحظات ملصقة على صفحات Word في Node.JS باستخدام فئات التعليقات التوضيحية في SDK.
الخطوة 1: تهيئة واجهة برمجة تطبيقات التعليقات التوضيحية
أولاً، استورد الفئات المطلوبة وأنشئ مثيلاً من 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: إعداد موضع الملاحظة اللاصقة
أنشئ مستطيل يحدد المكان الذي ستظهر فيه الملاحظة اللاصقة على الصفحة 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: بناء كائن التعليق التوضيحي للملاحظة اللاصقة
قم بتكوين نوع التعليق التوضيحي، رقم الصفحة، المستطيل، النص، ولون الخلفية.
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
يوضح المثال التالي التنفيذ الكامل لإنشاء ملاحظات لاصقة على صفحات 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
توفر واجهة برمجة التطبيقات 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 للحصول على القائمة الكاملة للخصائص القابلة للتكوين.
الخلاصة
باتباع الخطوات أعلاه، أنت الآن تعرف كيفية إنشاء ملاحظات لاصقة على صفحات Word في Node.JS باستخدام GroupDocs.Annotation Cloud SDK. سواء كنت تفضل تنفيذًا أصليًا لـ Node.js أو سير عمل cURL قائم على REST، يوفر SDK طريقة متسقة وموثوقة لتوضيح ملفات DOCX برمجيًا. تذكر تطبيق ترخيص صالح للاستخدام في الإنتاج؛ يمكنك الحصول على ترخيص مؤقت من صفحة الترخيص أو مراجعة خيارات التسعير على صفحة المنتج. نتمنى لك توضيحًا سعيدًا!
الأسئلة المتكررة
كيف يمكنني إنشاء ملاحظات لاصقة على صفحات 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) للتحكم في حجم وموقع الملاحظة.
