استدعاء تعليمات برمجية في تخصيصات على مستوى المستند من VBA

ينطبق على
تنطبق المعلومات الموجودة في هذا الموضوع فقط على أنواع المشاريع وإصدارات Microsoft Office التالية: لمزيد من المعلومات، راجع الميزات المتوفرة بواسطة تطبيقات Office و نوع المشروع. نوع المشروع مشروعات على مستوى المستند إصدار Microsoft Office Excel 2007 و Excel 2010 Word 2007 و Word 2010

يمكنك تكوين مشروع علي مستوي المستند لWord أو Excel بحيث يمكن لتعليمات Visual Basic البرمجية للتطبيقات (VBA) في المستند أن تستدعي التعليمات البرمجية في تجميع التخصيص. وهذا مفيد في السيناريوهات التالية:

• تريد توسيع تعليمات VBA البرمجية الموجودة في مستند باستخدام الميزات في تخصيص على مستوى المستند مقترن بنفس المستند.

• ترغب في توفير الخدمات التي تقوم بتطويرها في تخصيص على مستوى المستند للمستخدمين النهائيين الذين يمكنهم الوصول إلي الخدمات بكتابة تعليمات VBA البرمجية في المستند.

توفر أدوات تطوير Office في Visual Studio ميزة مشابهة للوظائف الإضافية علي مستوى التطبيق. إذا كنت تقوم بتطوير وظيفة إضافية، يمكنك استدعاء التعليمات البرمجية للوظيفة الإضافية الخاصة بك من حلول أخرى لMicrosoft Office. لمزيد من المعلومات، راجع استدعاء تعليمات برمجية في وظائف إضافية على مستوى التطبيق من حلول Office الأخرى.

ملاحظة

لا يمكن استخدام هذه الميزة في مشاريع قالب Word. يمكن استخدامها فقط في مستند Word أو مصنف Excel, أو مشاريع قالب Excel.

المتطلبات

قبل تمكين تعليمات VBA البرمجية من الاستدعاء في تجميع التخصيص، يجب أن يوفر المشروع الخاص بك المتطلبات التالية:

• يجب أن يكون للمستند علي أحد امتدادات أسماء الملفات التالية:

  • للWord: docm. أو doc.

  • للExcel: xlsm. أو xltm. أو xls. أو xlt.

• يجب أن يحتوي المستند بالفعل على مشروع VBA الذي يحتوي على تعليمات VBA البرمجية فيه.

• يجب السماح بتشغيل تعليمات VBA البرمجية في المستند دون مطالبة المستخدم من تمكين وحدات الماكرو. يمكنك الثقة في تشغيل تعليمات VBA البرمجية عن طريق إضافة موقع مشروع Office إلي قائمة المواقع الموثوق بها في إعدادات مركز التوثيق لـ Word أو Excel.

• يجب أن يحتوي مشروع Office على الأقل علي فئة عامة واحدة تحتوي على عضو عمومي واحد أو أكثر تقوم بعرضهم لـ VBA.

  يمكنك عرض أساليب و خصائص و أحداث لـ VBA. يمكن أن تكون الفئة التي قمت بعرضها فئة من عنصر مضيف (مثل ThisDocument لـ Word، أو ThisWorkbook و Sheet1 لـ Excel) أو فئة أخرى يمكنك القيام بتعريفها في المشروع. لمزيد من المعلومات حول عناصر المضيف, انظرنظرة عامة حول العناصر المضيفة و عناصر تحكم المضيف.

تمكين تعليمات VBA البرمجية من الإستدعاء إلي تجميع التخصيص

هناك طريقتان مختلفتان يمكنك من خلالهما عرض الأعضاء في تجميع التخصيص لتعليمات VBA البرمجية في المستند:

• يمكنك عرض عضو من فئة العنصر المضيف في مشروع Visual Basic لـ VBA. للقيام بذلك، قم بتعيين الخاصية EnableVbaCallers للعنصر المضيف إلي True في النافذة خصائص أثناء فتح العنصر المضيف (أي، مستند أو ورقة عمل أو مصنف) في المصمم. يقوم Visual Studio تلقائياً بإجراء كافة العمل المطلوب لتمكين تعليمات VBA البرمجية من الاتصال بأعضاء هذه الفئة.

• يمكن عرض الأعضاء في أية فئة عامة في مشروع #Visual C، أو أعضاء في فئة العنصر غير المضيف في مشروع Visual Basic لـ VBA. هذا الخيار يوفر لك المزيد من الحرية لاختيار الفئات التي تعرضها لـ VBA ولكنه يتطلب أيضًا المزيد من الخطوات اليدوية.

  للقيام بذلك، يجب عليك تنفيذ الخطوات الأساسية التالية:

  1. اعرض الفئة لـ COM.

  2. تجاوز أسلوب GetAutomationObjectمن فئة عنصر المضيف في المشروع الخاص بك لإرجاع مثيل الفئة التي تقوم بعرضه لـ VBA.

  3. قم بتعيين الخاصية ReferenceAssemblyFromVbaProject الخاصة بأي فئة للعنصر المضيف في المشروع إلي True. هذا يضمن نوع المكتبة الخاص بتجميع التخصيص إلي التجميع كما يضيف مرجعاً إلى نوع المكتبة إلى مشروع VBA في المستند.

لمعلومات مفصلة ، راجع كيفية القيام بما يلي: عرض التعليمة البرمجية إلى VBA في مشروع Visual Basic و كيفية القيام بما يلي: عرض التعليمة البرمجية إلى VBA في مشروع Visual C#‎ .

الخصائص EnableVbaCallers و ReferenceAssemblyFromVbaProject متوفرة فقط في النافذة خصائص في وقت التصميم; يتعذر استخدامهم في وقت التشغيل. لعرض الخصائص، قم بفتح المصمم للعنصر المضيف في Visual Studio. للحصول على مزيد من المعلومات حول المهام المعينة التي ينفذها Visual Studio عند تعيينك لهذه الخصائص، راجع المهام المنفذة بواسطة "خصائص العنصر المضيف".

ملاحظة

إذا كان المستند أو المصنف لا يحتوي بالفعل على تعليمات VBA البرمجية أو إذا كانت تعليمات VBA البرمجية البرمجية في المستند غير الموثوق به لتشغيله، ستظهر لك رسالة خطأ عند تعيين الخاصية EnableVbaCallers أو ReferenceAssemblyFromVbaProject لـ True. وهذا لأن Visual Studio لا يمكنه تعديل مشروع VBA في المستند في هذا الموقف.

استخدام الأعضاء في تعليمات VBA البرمجية للإستدعاء إلى تجميع التخصيص

بعد تكوين المشروع الخاص بك لتمكين تعليمات VBA البرمجية من الإستدعاء إلي تجميع التخصيص، يضيف Visual Studio الأعضاء التالية إلى مشروع VBA في المستند:

• يضيف Visual Studio أسلوب عمومي باسم GetManagedClass لكافة المشاريع .

• للحصول على المشاريع Visual Basic التي تعرض فيها أعضاء من فئة العنصر المضيف باستخدام الخاصية EnableVbaCallers، يضيف Visual Studio أيضاً خاصية باسم CallVSTOAssembly إلى الوحدة النمطية ThisDocument أو ThisWorkbook أو Sheet1 أو Sheet2 أو Sheet3 في مشروع VBA.

يمكنك استخدام الخاصية CallVSTOAssembly أو الأسلوب GetManagedClass للوصول إلي الأعضاء العامة من الفئة التي قمت بعرضها علي تعليمات VBA البرمجية في المشروع.

ملاحظة

أثناء تطويرك للحل ونشره، يوجد نسخ مختلفة متعددة من المستند حيث يمكنك إضافة تعليمات VBA البرمجية. لمزيد من المعلومات، راجع الإرشادات لإضافة تعليمات VBA البرمجية إلي المستند.

استخدام الخاصية CallVSTOAssembly في مشروع Visual Basic

استخدم الخاصية CallVSTOAssembly للوصول إلي الأعضاء العامة التي قمت بإضافتها إلى فئة العنصر المضيف. على سبيل المثال، ماكرو VBA التالي يقوم باستدعاء أسلوب يسمى MyVSTOMethod تم تعريفه في الفئة Sheet1 في مشروع مصنف Excel.

Sub MyMacro()
    Sheet1.CallVSTOAssembly.MyVSTOMethod()
End Sub

Th هو خاصية هو بطريقة أكثر ملاءمة للاتصال في تجميع التخصيص من استخدام GetManagedClassأسلوب مباشرة. CallVSTOAssemblyإرجاع كائن يمثل العنصر مضيف فئة التي تقوم بعرضها إلى VBA. الأعضاء و معلمات الأسلوب للكائن الذي تم إرجاعه تظهر في IntelliSense.

تحتوي الخاصية CallVSTOAssembly على تصريح مشابه للتعليمات البرمجية التالية. تفترض هذه التعليمات البرمجية أنك قمت بعرض فئة العنصر المضيف Sheet1 فى مشروع مصنف Excel باسم ExcelWorkbook1 لـ VBA.

Property Get CallVSTOAssembly() As ExcelWorkbook1.Sheet1
    Set CallVSTOAssembly = GetManagedClass(Me)
End Property

استخدام أسلوب GetManagedClass

لاستخدام الأسلوب العمومي GetManagedClass، قم بإدخال كائن VBA الذي يتوافق مع فئة العنصر المضيف التي تحتوي على تجاوزك للأسلوب GetAutomationObject. ثم استخدم الكائن الذي تم إرجاعه للوصول إلى الفئة التي قمت بعرضها لـ VBA.

على سبيل المثال، يقوم ماكرو VBA التالي باستدعاء أسلوب يسمى MyVSTOMethod تم تعريفه في فئة العنصر المضيف Sheet1 في مشروع مصنف Excel باسم ExcelWorkbook1.

Sub CallVSTOMethod
    Dim VSTOSheet1 As ExcelWorkbook1.Sheet1
    Set VSTOSheet1 = GetManagedClass(Sheet1)
    VSTOSheet1.MyVSTOMethod
End Sub

الأسلوب GetManagedClass له التصريح التالي.

GetManagedClass(pdispInteropObject Object) As Object

يقوم هذا الأسلوب بإرجاع كائن يمثل الفئة التي قمت بعرضها لـ VBA. الأعضاء و معلمات الأسلوب للكائن الذي تم إرجاعه تظهر في IntelliSense.

إرشادات حول إضافة تعليمات VBA البرمجية إلي المستند

هناك عدة نُسخ من المستند حيث يمكنك إضافة تعليمات VBA البرمجية التي تستدعي إلي تخصيص على مستوى المستند.

أثناء تطويرك واختبارك للحل الخاص بك، يمكنك كتابة تعليمات VBA البرمجية في المستند الذي يفتح أثناء تصحيح أو تشغيل المشروع الخاص بك في Visual Studio (أي، المستند في مجلد إخراج البناء). بالرغم من ذلك، أي تعليمات VBA برمجية تقوم بإضافتها إلى هذا المستند سيتم الكتابة فوقها في المرة التالية التي يتم فيها بناء المشروع، لأن Visual Studio يحل محل المستند في إخراج البناء بنسخة من المستند من مجلد المشروع الرئيسي.

إذا كنت تريد حفظ تعليمات VBA البرمجية التي قمت بإضافتها إلى المستند أثناء تصحيح أو تشغيل الحل، قم بنسخ تعليمات VBA البرمجية في المستند في ملف المشروع. للحصول على مزيد من المعلومات حول عملية البناء, راجع نظرة عامة حول عملية بناء حل Office.

عندما تكون جاهزاً لنشر الحل الخاص بك، هناك ثلاث مواقع للمستند الأساسي يمكن أن تضيف تعليمات VBA البرمجية إليها.

في ملف المشروع على كمبيوتر التطوير

هذا الموقع مناسب إذا كان لديك تحكم كامل لكلا من تعليمات VBA البرمجية في المستند و تعليمات التخصيص البرمجية. لأن المستند على كمبيوتر التطوير، يمكنك بسهولة تعديل تعليمات VBA البرمجية إذا قمت بتغيير تعليمات التخصيص البرمجية. تعليمات VBA البرمجية التي قمت بإضافتها إلى هذه النسخة من المستند تبقى في المستند عندما تقوم ببناء الحل الخاص بك أو تصحيحه أو نشره.

لا يمكنك إضافة تعليمات VBA البرمجية إلي المستند أثناء فتحه في المصمم. يجب أولاً إغلاق المستند في المصمم ، ومن ثم فتح المستند مباشرة في Word أو Excel.

تنبيه
إذا قمت بإضافة تعليمات VBA البرمجية التي يتم تشغيلها عند فتح المستند, في بعض الحالات النادرة هذه التعليمات البرمجية قد تتلف المستند أو تمنعه من الفتح في المصمم.

في ملف النشر أو التثبيت

في بعض الحالات، قد يكون من المناسب إضافة تعليمات VBA البرمجية إلى المستند في ملف النشر أو التثبيت. على سبيل المثال، قد تختار هذا الخيار إذا كان قد تم كتابة تعليمات VBA البرمجية و اختبارها من قبل مطور مختلف على جهاز كمبيوتر ليس عليه Visual Studio مثبتاً.

إذا قام المستخدمون بتثبيت الحل من ملف النشر مباشرة، يجب إضافة تعليمات VBA البرمجية إلي المستند كل مرة يتم فيها نشر الحل. يقوم Visual Studio بالكتابة فوق المستند في موقع النشر عند نشر الحل.

إذا قام المستخدمون بتثبيت الحل من ملف التثبيت الذي يختلف ملف النشر، يمكنك تجنب إضافة تعليمات VBA البرمجية في المستند في كل مرة يتم فيها نشر الحل. عندما يكون تحديث النشر جاهزاً ليتم نقله من ملف النشر إلى ملف التثبيت، قم بنسخ كافة الملفات إلي ملف التثبيت عدا المستند.

على كمبيوتر المستخدم النهائي

إذا كان المستخدمون النهائيون هم مطورون لـ VBA يستدعون الخدمات التي توفرها في التخصيص على مستوى المستند, يمكنك إخبارهم عن كيفية استدعاء التعليمات البرمجية الخاصة بك باستخدام الخاصية CallVSTOAssembly أو الأسلوب GetManagedClass في النسخ الخاصة بهم من المستند. عند نشر تحديثات الحل، لن يتم الكتابة فوق تعليمات VBA البرمجية في المستند على جهاز كمبيوتر المستخدم النهائي، لأنه المستند لم يتم تعديله عن طريق نشر التحديثات.

تنفيذ المهام بواسطة خصائص العنصر المضيف

عند استخدام الخاصية EnableVbaCallers و الخاصية ReferenceAssemblyFromVbaProject، يقوم Visual Studio بتنفيذ مجموعات مختلفة من المهام.

EnableVbaCallers

عند تعيين الخاصية EnableVbaCallers للعنصر المضيف لـ True في مشروع Visual Basic، يقوم Visual Studio بتنفيذ المهام التالية:

1. يقوم بإضافة السمة ComClassAttribute و السمة ComVisibleAttribute إلي فئة العنصر المضيف.

2. يتجاوز الأسلوب GetAutomationObject الخاص بفئة العنصر المضيف.

3. يقوم بتعيين الخاصية ReferenceAssemblyFromVbaProject الخاصة بالعنصر المضيف إلي True.

عند قيامك بتعيين الخاصية EnableVbaCallers مرة أخري إلى False، يقوم Visual Studio بتنفيذ المهام التالية:

1. يقوم بإزالة السمة ComClassAttribute و السمة ComVisibleAttribute من الفئة ThisDocument.

2. يقوم بإزالة الأسلوب GetAutomationObject من فئة العنصر المضيف.

   ملاحظة

   لا يقوم Visual Studio بتعيين الخاصية ReferenceAssemblyFromVbaProject مرة أخري إلى False تلقائياً. يمكنك إعداد هذه الخاصية إلى False يدوياً باستخدام النافذة خصائص .

ReferenceAssemblyFromVbaProject

عند تعيين الخاصية ReferenceAssemblyFromVbaProject الخاصة بأي عنصر مضيف في مشروع Visual Basic أو مشروع #Visual C إلي True، يقوم Visual Studio بتنفيذ المهام التالية:

1. يقوم بإنشاء مكتبة أنواع لتجميع التخصيص و تضمين مكتبة الأنواع في التجميع.

2. يقوم بإضافة مرجع لمكتبات الأنواع التالية في مشروع VBA في المستند:

   • مكتبة الأنواع لتجميع التخصيص الخاص بك.

   • أدوات Microsoft Visual Studio لمكتبة الأنواع Office Execution Engine 9.0. يتم تضمين مكتبة الأنواع هذه في Visual Studio Tools لوقت تشغيل Office.

عند تعيين الخاصية ReferenceAssemblyFromVbaProject مرة أخري إلى False، يقوم Visual Studio بتنفيذ المهام التالية:

1. إزالة مراجع مكتبة الأنوع من مشروعVBA في المستند.

2. يقوم بإزالة مكتبة الأنواع المضمنة من التجميع.

استكشاف الأخطاء وإصلاحها

يسرد الجدول التالي بعض الأخطاء الشائعة و اقتراحات حول إصلاح هذه الأخطاء.

خطأ	الاقتراح
بعد تعيين الخاصية EnableVbaCallers أو الخاصية ReferenceAssemblyFromVbaProject، توضح رسالة خطأ أن المستند لا يحتوي على مشروع VBA أو ليس لديك الإذن بالوصول إلي مشروع الـ VBA في المستند.	تأكد من أن المستند في المشروع يحتوي على الأقل على ماكرو VBA واحد و أن يكون لدي مشروع الـ VBA الثقة الكافية للتشغيل و أن يكون مشروع الـ VBA غير محمي بواسطة كلمة مرور.
بعد تعيين الخاصية EnableVbaCallers أو الخاصية ReferenceAssemblyFromVbaProject، توضح رسالة خطأ أن التصريح GuidAttributeمفقود أو معطوب.	تأكد من أن التصريح GuidAttribute موجود في الملف AssemblyInfo.cs أو AssemblyInfo.vb في المشروع الخاص بك و أن هذه السمة تم تعيينها إلي GUID صالح.
بعد تعيين الخاصية EnableVbaCallers أو الخاصية ReferenceAssemblyFromVbaProject توضح رسالة خطأ أن رقم الإصدار المحدد بواسطة AssemblyVersionAttribute غير صالح.	تأكد من أن التصريح AssemblyVersionAttribute في الملف AssemblyInfo.cs أو AssemblyInfo.vb في المشروع الخاص بك قد تم تعيينه إلى رقم إصدار تجميع صالح. للحصول على معلومات حول أرقام إصدارات تجميع صالحة، راجع الفئة AssemblyVersionAttribute.
بعد إعادة تسمية تخصيص التجميع، فإن تعليمات VBA البرمجية التي تستدعي في تخصيص التجميع تتوقف عن العمل.	إذا قمت بتغيير اسم تجميع التخصيص بعد عرضه لتعليمات VBA البرمجية، فإن الارتباط بين مشروع VBA في المستند و تجميع التخصيص الخاص بك سينقطع. لإصلاح هذه المشكلة، قم بتغيير الخاصية ReferenceFromVbaAssembly في المشروع الخاص بك إلي False ثم العودة إلى True، ثم قم باستبدال أية مراجع إلى اسم التجميع القديم في تعليمات VBA البرمجية باسم التجميع الجديد.

راجع أيضًا:

المهام

كيفية القيام بما يلي: عرض التعليمة البرمجية إلى VBA في مشروع Visual Basic

كيفية القيام بما يلي: عرض التعليمة البرمجية إلى VBA في مشروع Visual C#‎

الإرشادات التفصيلية: استدعاء تعليمات برمجية من VBA في مشروع Visual Basic

الإرشادات التفصيلية: استدعاء تعليمات برمجية من VBA في مشروع #C

المبادئ

نشر حلول Office

موارد أخرى

ضم VBA و تخصيصات من مستوى المستند

برمجة تخصيصات علي مستوي مستند