إنشاء إضافة لبرنامج Office لقد أصبحت طريقة فعالة للغاية لتوسيع نطاق استخدام برامج Word و Excel و Outlook و PowerPoint وغيرها من التطبيقات. مايكروسوفت 365 دون الحاجة إلى تطوير إضافات سطح المكتب التقليدية. تعتمد هذه الإضافات الجديدة على تقنيات الويب القياسية وواجهة برمجة تطبيقات جافا سكريبت لبرامج أوفيس، مما يتيح إنشاء تجارب حديثة وآمنة وسهلة النشر في جميع أنحاء المؤسسة.
في السطور التالية ستجد دليلًا كاملاً للغاية حول أدوات التطوير، وأنواع البيانات الوصفية، وواجهات برمجة التطبيقات المتاحة، وخيارات النشريتضمن ذلك دمج وثائق مايكروسوفت الرسمية. الفكرة هي أنه يمكنك البدء من الصفر والحصول على إضافة فعّالة، مع فهم وظيفة كل جزء والقرارات التقنية التي تحتاج إلى اتخاذها في كل خطوة.
ما هي الإضافة الحديثة لبرنامج Office وكيف يتم تنظيمها؟
إضافات المكتب الحديث تعتمد هذه البرامج على منصة إضافات Office، وهي منصة مشتركة بين Word وExcel وPowerPoint وOneNote وOutlook وProject، على أجهزة سطح المكتب والويب، وفي بعض الحالات على الأجهزة المحمولة. وتشترك جميعها في نفس البنية الأساسية المكونة من جزأين متميزين بوضوح.
الجزء الأول هو بيان المكمليعمل هذا الملف كـ "بطاقة هوية" للملحق. فهو يعلن عن البيانات الوصفية (المعرف، الاسم، الإصدار، اللغات)، وتطبيقات Office التي يمكن استخدامه معها، والأذونات التي يحتاجها، والأوامر التي يضيفها إلى الشريط، والرموز التي يستخدمها، ومكان استضافة تطبيق الويب، وفي أي سياقات يجب تنشيطه (على سبيل المثال، في Outlook، فقط للرسائل أو المواعيد التي تستوفي قواعد معينة).
الجزء الثاني هو تطبيق ويب يُوفّر هذا التطبيق واجهة المستخدم ومنطق العمل. ويتكوّن من HTML وCSS وJavaScript (أو TypeScript)، ويعمل ضمن حاوية Office HTML (لوحة مهام، أو إضافة محتوى، أو مربع حوار). ومن ثمّ، يستخدم مكتبة office.js لقراءة المستند والكتابة إليه، واستدعاء الخدمات الخارجية، وإدارة المصادقة، وعرض مربعات الحوار، وأداء أي مهام أخرى نموذجية لتطبيق ويب حديث.
أدوات لإنشاء إضافات Office
لا توجد طريقة واحدة لبدء مشروع إضافة. تقدم مايكروسوفت العديد من الأدوات الرسميةتُلبي هذه الأدوات احتياجات فئات المستخدمين المختلفة: من أولئك الذين يُفضلون قوالب Visual Studio إلى أولئك الذين يعملون يوميًا مع Node.js وVisual Studio Code. كما توجد أدوات أخرى من جهات خارجية أو أدوات أكثر تخصصًا، مثل محررات واجهة المستخدم لـ VBA.
مولد Yeoman لإضافات Office
من المحتمل أن يكون مولد Yeoman لبرنامج Office الخيار الأكثر مرونة لمطوري الويب. يتيح لك إنشاء مشاريع مبنية على Node.js يمكنك تعديلها باستخدام كود الاستوديو المرئي أو الناشر الذي تفضله. يرشدك المعالج خلال سلسلة من الأسئلة لاختيار نوع الإضافة (جزء المهام، إضافة المحتوى، الوظائف المخصصة، Outlook، إلخ) والتطبيق المستهدف.
مع هذا المولد يمكنك إنشاء مشاريع لـ إكسل، ون نوت، أوتلوك، باوربوينت، بروجكت، وورد، ووظائف إكسل المخصصة. علاوة على ذلك، يتيح لك الاختيار بين مجموعة بسيطة من HTML وCSS وJavaScript/TypeScript أو بنية قائمة على React، أيضًا في JavaScript أو TypeScript، مع إعداد هيكل المشروع بالكامل مسبقًا.
مشاريع Visual Studio لـ Office
إذا تحركت براحة أكبر في بيئات .NETيتضمن Visual Studio قوالب محددة لإضافات Office. تغطي هذه القوالب بشكل أساسي Excel وOutlook وWord وPowerPoint، مما يخلق حلاً كاملاً يشمل بيان الإضافة وتطبيق الويب، ومشاريع الواجهة الخلفية المرتبطة بها اختيارياً.
مشروع Visual Studio كما أنه يعتمد على HTML وCSS وJavaScript، ولكنه يتكامل مع النظام البيئي الكلاسيكي لشركة مايكروسوفت.التصحيح المتكامل، والنشر، والتغليف، وما إلى ذلك. إنه خيار جيد عندما تعمل بالفعل مع حلول المؤسسات في Visual Studio وتريد الحفاظ على كل شيء مركزيًا في نفس بيئة التطوير المتكاملة.
مجموعة أدوات وكلاء Microsoft 365 ومجموعة أدوات تطوير إضافات Office
مجموعة أدوات وكلاء Microsoft 365 صُممت هذه الأداة لتتجاوز الإضافات التقليدية، وتتيح إنشاء أي نوع من الإضافات تقريبًا لنظام Microsoft 365، حيث تجمع بين برامج الروبوت، وإضافات Teams، والإضافات الأخرى. باستخدام هذه الأداة، يمكنك إنشاء مشاريع إضافات Office التي تتناسب مع تطبيقات Microsoft 365 الأوسع نطاقًا.
مجموعة أدوات تطوير إضافات Office إنها إضافة لبرنامج Visual Studio Code تُسهّل العمل اليومي بشكل كبير. فمن داخل VS Code، يمكنك إنشاء مشاريع إضافات جديدة، وتحميل نماذج برمجية جاهزة للاختبار، وإدارة دورة التطوير بأكملها دون مغادرة المحرر. صُممت هذه الإضافة للعمل مع كلٍ من ملفات البيان الموحدة وملفات البيان الخاصة بالإضافات فقط.
البيان: جوهر تكوين الإضافة
يتم وصف كل إضافة من إضافات Office بواسطة ملف البيان يُحدد هذا كيفية تحميل التطبيق، وخيارات واجهة المستخدم التي يجب عرضها، والأذونات المطلوبة. يوجد نموذجان رئيسيان لملفات البيان، ويُحدد اختيار أحدهما كيفية دمج الإضافة مع ملحقات Microsoft 365 الأخرى.
أنواع البيانات: بيانات تكميلية فقط وبيانات موحدة
- بيانٌ يُعنى بالتكامل فقط. هذا هو التنسيق الكلاسيكي لإضافات Office الإنتاجية في Excel وOneNote وOutlook وPowerPoint وProject وWord. وهو مكتوب بلغة XML ويركز فقط على وصف الإضافة، دون دمجها مع أنواع أخرى من التطبيقات.
- البيان الموحد لمايكروسوفت 365. تطور نموذج البيان بتنسيق JSON، المستخدم تاريخيًا في تطبيقات Teams. يتيح هذا التنسيق تجميع أنواع مختلفة من ملحقات Microsoft 365 - إضافات Office، وملحقات Teams، وما إلى ذلك - في تطبيق واحد.
منطق التكوين متشابه في كلتا الحالتينتُحدد مُعرّفًا فريدًا (عادةً ما يكون GUID)، والإصدار، واسم العرض، والوصف، واللغات المدعومة، والأيقونات، وأنواع الأذونات (على سبيل المثال، قراءة المستندات أو قراءة/كتابة المستندات)، وبنية واجهة المستخدم (علامات التبويب، والمجموعات، وأزرار الشريط). كما تُحدد عنوان URL لتشغيل تطبيق الويب وأي إعدادات إضافية، مثل اختصارات لوحة المفاتيح في Excel أو Word، وقواعد التشغيل في Outlook، أو أبعاد اللوحات والإضافات الخاصة بالمحتوى.
العناصر الرئيسية المعلنة في البيان
إضافة البيانات الوصفية الأساسيةيجب أن يوضح بيان التثبيت بدقة كيفية دمج الملحق في تجربة Office. يشمل ذلك صور العلامة التجارية وأيقونات أوامر الشريط، والتي يجب استضافتها على خادم يسمح بالتخزين المؤقت (رؤوس HTTP مع Cache-Control: no-cache أو ما شابه ذلك للإنتاج).
وهناك جانب حاسم آخر وهو أمنيجب أن تستخدم جميع عناوين URL التي تشير إلى تطبيق الويب أو موارد الإضافة بروتوكول HTTPS. في حين أن بعض سيناريوهات التطوير تسمح باستخدام HTTP أو الشهادات الموقعة ذاتيًا، إذا كنت ترغب في تشغيل الإضافة في Office على الويب أو نشرها على Microsoft Marketplace، فإن استخدام SSL إلزامي لتجنب تحذيرات المحتوى المختلط وضمان حماية البيانات أثناء النقل.
إذا كنت تخطط لتوزيع الإضافة الخاصة بك من خلال سوق مايكروسوفت، فيجب أن يتضمن ملف البيان ما يلي: بالإضافة إلى المعرف الفريد العالمي (GUID)، يوجد عنوان URL للدعم الفني يمكن الوصول إليه ويكون صالحًا. تطبق مايكروسوفت سلسلة من إرشادات التحقق حيث تتم مراجعة اتساق بيانات البيان، وسلوك الإضافة، والامتثال لمتطلبات الأمان وتجربة المستخدم.
النطاقات والمصادر المسموح بها لـ Office.js
كما يتحكم البيان ما هي النطاقات التي يمكن تصفحها داخل لوحة المكونات الإضافية؟في Office على الويب وOutlook الجديد لنظام Windows، يمكن لجزء المهام تحميل أي عنوان URL تقريبًا. مع ذلك، في تطبيقات سطح المكتب، يكون السلوك أكثر صرامة: إذا حاول الملحق الانتقال إلى نطاق غير نطاق الصفحة الرئيسية، فسيتم فتح عنوان URL خارج التطبيق، في نافذة متصفح منفصلة.
لتجنب تلك القفزة الخارجية على سطح المكتبيمكنك إدراج كل نطاق إضافي ترغب في ظهوره في نافذة الإضافة ضمن ملف البيان. إذا كان النطاق المستهدف مدرجًا، فسيتم فتحه داخل اللوحة في كل من Office على سطح المكتب وOffice على الويب؛ وإلا، فسيتم فتحه في متصفح خارجي على سطح المكتب.
التفاعل مع المستندات باستخدام واجهة برمجة تطبيقات جافا سكريبت الخاصة بـ Office
يتواصل تطبيق الويب الخاص بالملحق مع مستند Office. (أو مع الرسالة في حالة Outlook) عبر مكتبة Office JavaScript API، والتي يمكن الوصول إليها من خلال شبكة توصيل المحتوى الرسمية لشركة Microsoft على الرابط التالي: https://appsforoffice.microsoft.com/lib/1/hosted/office.jsما عليك سوى الإشارة إلى هذا النص البرمجي في القسم <head> من الصفحة لتتمكن من استخدام الأنواع والأساليب المتاحة.
بمجرد تحميل المكتبة، ستتمكن من الوصول إلى نموذجين متكاملين لواجهة برمجة التطبيقات (API):
- واجهات برمجة التطبيقات الخاصة بالتطبيقات.
- واجهات برمجة التطبيقات الشائعة.
تم تصميم كل نموذج لتغطية سيناريوهات مختلفة، على الرغم من إمكانية دمجها في نفس الملحق حسب الاحتياجات.
واجهات برمجة التطبيقات الخاصة بالتطبيقات
توفر واجهات برمجة التطبيقات الخاصة بالتطبيقات الكائنات ذات الأنواع القوية تمثل هذه العناصر كيانات أصلية خاصة بتطبيق Office المحدد. على سبيل المثال، في Excel، لديك كائنات لأوراق العمل والنطاقات والجداول والمخططات، والتي تتيح لك معالجة البيانات بطريقة منظمة وفعالة.
يعتمد هذا النموذج على عمليات الدفعاتيمكنك ربط الإجراءات ضمن سياق معين، وعندما تكون جاهزًا، تقوم بمزامنة التغييرات مع Office. تقلل هذه الطريقة من عدد مرات الانتقال بين الإضافة والتطبيق، مما يحسن الأداء بشكل ملحوظ، خاصةً في Office على الويب.
واجهات برمجة التطبيقات المشتركة للميزات المشتركة
واجهات برمجة التطبيقات الشائعة يركزون على الوظائف الشاملة الموجودة في العديد من التطبيقات: عناصر الواجهة، مربعات الحوار، إعدادات العميل، إلخ. يستخدم هذا النموذج ردود الاتصال بدلاً من الوعود، وبحسب التصميم، يقوم كل استدعاء بتنفيذ عملية واحدة على التطبيق.
باستخدام واجهات برمجة التطبيقات الشائعة، يمكنك على سبيل المثال، عرض مربع حوار منبثق، أو إدارة تكوين إضافة على مضيفين مختلفين، أو الوصول إلى إمكانيات معينة في Outlook أو PowerPoint أو Project التي لم يتم تغطيتها بعد بواسطة واجهات برمجة التطبيقات الخاصة بالتطبيقات، وذلك حسب حالة الاستخدام.
متطلبات النظام والتوافق عبر الأنظمة الأساسية
يتم تنظيم توافق واجهة برمجة التطبيقات (API) في مجموعات المتطلباتتُصنّف هذه المجموعات أعضاء واجهة برمجة التطبيقات (API) المحددة تحت اسم إصدار. وهناك مجموعات متطلبات خاصة بالتطبيقات، مثل: ExcelApi 1.7وغيرها من الأشياء المشتركة، مثل DialogApi 1.1والتي تعمل حيث يتم دعم وظيفة مربع الحوار.
يمكن للملحق التحقق أثناء التشغيل مما إذا كان تطبيق Office الذي يعمل ضمنه يفي بالمتطلبات اللازمة. يتيح لك هذا تخصيص تجربة المستخدم أو تعطيل الميزات المتقدمة عندما لا يفي النظام المضيف بالحد الأدنى من المتطلبات، بدلاً من التسبب في أخطاء غير متوقعة.
استكشف واجهة برمجة التطبيقات (API) باستخدام Script Lab
مختبر البرمجة النصية هو إضافة مجانية يُستخدم كبيئة اختبار لواجهة برمجة تطبيقات جافا سكريبت الخاصة بـ Office. يتم تثبيته من متجر Microsoft Marketplace ويعمل داخل تطبيقات مثل Excel أو Word، مما يسمح لك بكتابة وتنفيذ أجزاء من التعليمات البرمجية في الوقت الفعلي على المستند الحالي.
يمكنك الوصول إلى Script Lab مكتبة من الأمثلة الجاهزة للاستخدام والتي توضح إمكانيات واجهة برمجة التطبيقات المختلفةيمكنك استخدام هذه المقتطفات كأساس لرمزك الخاص، وتعديلها، ورؤية النتيجة على الفور في المستند، مما يسرع بشكل كبير مرحلة النمذجة الأولية واختبار الوظائف قبل دمجها في المكون الإضافي النهائي الخاص بك.
كيفية توسيع واجهة مستخدم Office
إحدى المزايا الكبيرة للإضافات هي أنها تسمح دمج الوظائف مباشرة في واجهة Officeبحيث لا يشعر المستخدم بأنه "يغادر" التطبيق. ويتحقق ذلك من خلال دمج أوامر الإضافات وحاويات HTML مثل لوحات المهام، وإضافات المحتوى، ومربعات الحوار.
- أوامر الإضافات تُستخدم هذه الأدوات لإضافة علامات تبويب مخصصة ومجموعات جديدة وأزرار أو قوائم إضافية إلى شريط أدوات Office.
- حاويات HTML (لوحات المهام، والإضافات الخاصة بالمحتوى، والحوارات) تعمل كسطح لعرض واجهة الإضافة الخاصة بها.
في سيناريو نموذجي، قد يكون لديك أمر يضيف مجموعة مع زر "تحليل البيانات" في Excel؛ عند الضغط عليه، يتم فتح جزء مهام على اليمين مع تطبيق الويب الخاص بك، والذي يقوم بتحليل النطاق المحدد، واستدعاء خدمة التعلم الآلي، وإرجاع النتائج عن طريق تمييز الخلايا أو إنشاء مخططات باستخدام واجهة برمجة التطبيقات الخاصة بـ Excel.
إنشاء وظيفة إضافية لجزء المهام باستخدام Yeoman (مثال من Word)
لتطبيق كل هذه المفاهيم عملياًمن المفيد الاطلاع على كيفية إنشاء إضافة لوحة مهام عمليًا باستخدام مولد Yeoman، لكل من Word وOutlook. على الرغم من اختلاف تفاصيل واجهة المستخدم بين التطبيقين، إلا أن بنية المشروع وسير العمل متشابهان للغاية.
متطلبات بيئة التطوير
قبل إنشاء المشروعيجب تثبيت أحدث إصدار LTS من Node.js، والذي يمكن تنزيله من الموقع الرسمي. بعد التثبيت، قم بتثبيت Yeoman ومولد Office عالميًا باستخدام الأمر npm install -g yo generator-officeوأخيرًا، تأكد من ربط Office باشتراك Microsoft 365 الذي يتضمن Office على الويب، حيث ستختبر الإضافة على كل من سطح المكتب والمتصفح.
إنشاء وظيفة إضافية لبرنامج Word مع جزء مهام
الخطوة الأولى هي حدد نوع البيان يعتمد اختيارك على ما إذا كنت تنوي دمج الإضافة مع ملحقات أخرى في تطبيق واحد أم لا. بمجرد اتخاذ قرارك، يمكنك تشغيلها. yo office في دليل العمل.
د مساعد تفاعلييمكنك، على سبيل المثال، اختيار نوع المشروع، وتسميته باسم مثل "إضافة مكتبي"، ثم تحديد برنامج Word كتطبيق العميل المستهدف. عند الانتهاء، يقوم المُنشئ بإنشاء مجلد المشروع، وتثبيت تبعيات Node، وتجهيز كل شيء للتشغيل.
ستجد ملف البيان ضمن الحل (manifest.json o manifest.xml) في الجذر، والذي يحدد إعدادات الملحق؛ الملف ./src/taskpane/taskpane.html باستخدام ترميز لوحة المهام؛ CSS في ./src/taskpane/taskpane.cssوالرمز الذي يستدعي واجهة برمجة تطبيقات Office في ./src/taskpane/taskpane.ts o .jsيعتمد ذلك على ما إذا اخترت TypeScript أو JavaScript.
لاختبار الإضافة في برنامج Word على سطح المكتبكل ما عليك فعله هو الانتقال إلى المجلد الرئيسي للمشروع (cd "My Office Add-in"وتنفيذ npm startيُشغّل هذا الأمر خادم الويب المحلي ويبدأ تشغيل برنامج Word مع تحميل الإضافة مسبقًا في وضع التثبيت الجانبي. إذا كنت تفضل تجربتها في Word على الويب، فيمكنك استخدام أمر كهذا: npm run start -- web --document {url}، واستبدال عنوان URL بعنوان URL الخاص بمستند مخزن في OneDrive أو SharePoint.
خادم التطوير وإدارة التبعيات
من الشائع أثناء التطوير أن npm install قد يفشل الأمر أثناء الخطوة التلقائية التي ينفذها Yeoman، خاصةً إذا كانت هناك تعارضات في إصدارات التبعيات. في هذه الحالات، ما عليك سوى الانتقال إلى مجلد المشروع وتشغيله. npm install لحلها يدوياً.
في حالة ظهور تحذيرات التبعية القديمةيمكنك الاعتماد على الأداة npm-check-updates، وتثبيته مع npm i -g npm-check-updates، جري ncu -u لتحديث نطاقات الإصدارات في package.json واستكمال العملية بجديد npm installالعديد من هذه التحذيرات ليست خطيرة، ولكن من الممارسات الجيدة مراجعتها بشكل دوري للحفاظ على سلامة المشروع.
لإيقاف خادم التطوير ثم قم بإلغاء تثبيت الملحق في وضع التثبيت الجانبي، ويمكنك تشغيله. npm stop في الدليل الجذر. إذا كنت قد قمت بتحميل الملحق يدويًا مسبقًا (على سبيل المثال، عن طريق تحميل ملف البيان إلى Office على الويب)، فستحتاج أيضًا إلى إزالته يدويًا من واجهة الإدارة المقابلة.
بدءًا من البنية الأساسية للملحق وأدوات التطوير (Yeoman، وVisual Studio، وAgents Toolkit، وScript Lab) وصولًا إلى دور ملف البيان، وواجهات برمجة تطبيقات JavaScript، وضوابط الأمان، وخيارات النشر (محليًا، أو عبر Marketplace، أو النشر المركزي، أو عبر مزودين مثل Qlik)، لديك خريطة شبه كاملة لتحديد نوع الإضافة التي تحتاجها، وكيفية بنائها، وكيفية وضعها بين أيدي المستخدمين دون مفاجآت تقنية.