الإرشادات التفصيلية: إضافة عناصر إلى مستند ما في وقت التشغيل في وظيفة إضافية على مستوى التطبيق

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

يوضح هذا المثال كيفية إضافة أمر إلى قائمة مختصرة في الكلمة بواسطة استخدام الوظيفة الإضافية المستوى تطبيق. This walkthrough demonstrates how to use the Ribbon to enable users to add a Button or a RichTextContentControl to a document.

توضح هذه الإرشادات التفصيلية المهام التالية:

• إنشاء مشروع وظيفة Word إضافية جديد

• توفير واجهة مستخدم (UI) لإضافة عناصر تحكم إلى المستند.

• إضافة عناصر التحكم إلى المستند في وقت التشغيل.

• إزالة عناصر تحكم من المستند.

ملاحظة

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

المتطلبات الأساسية

تحتاج إلى المكونات التالية لاستكمال هذه الإرشادات التفصيلية:

-

إصدار لـ Visual Studio 2010 يشمل أدوات مطوري Microsoft Office. لمزيد من المعلومات، راجع [تكوين كمبيوتر لتطوير حلول Office](bb398242\(v=vs.100\).md).

• Word 2007 أو Word 2010.

إنشاء مشروع وظيفة Word إضافية جديد

ابدأ بانشاء مشروع وظيفة Word إضافية.

لإنشاء مشروع وظيفة إضافية Word جديد

1. إلى تشغيل هذه تعليمات برمجية، تسمى قالب الكلمة يجب أن يكون موجوداً في مجلد "مستندات" (لنظام التشغيل ‏‫نظام التشغيل Windows XP والإصدارات السابقة) أو مجلد "مستندات" (لإصدارات أحدث من Windows). لمزيد من المعلومات، راجع كيفية القيام بما يلي: إنشاء مشاريع Office في Visual Studio.

2. إذا كان مشروعك يستهدف .NET Framework 4 ، اضف مرجعاً لتجميع Microsoft.Office.Tools.Word.v4.0.Utilities.dll. هذا المرجع مطلوب لإضافة عناصر تحكم Windows Forms إلى المستند المستخدم فيما بعد في هذه الإرشادات التفصيلية.

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

اضف علامة تبويب مخصصة إلى الشريط في Word. يمكن للمستخدمين تحديد خانات الاختيار ضمن علامة التبويب لإضافة عناصر تحكم إلى مستند.

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

1. في مشروع قائمة ، انقر فوق إضافة عنصر جديد .

2. في مربع الحوار أضف عنصر جديد ، حدد الشريط (مصمم مرئى) .

3. قم بتغيير اسم الشريط الجديد إلى MyRibbonثم انقر فوق أضف‏‎ .

   ملف MyRibbon.cs أو MyRibbon.vb يفتح في "مصمم الشريط" ويعرض علامة التبويب و المجموعة الافتراضيين .

4. في "مصمم" الشريط "، انقر فوق المجموعة1 (group1) .

5. In the Properties window, change the Label property for group1 to Add Controls.

6. من التبويب عناصر تحكم شريط Office من مربع الأدوات، اسحب عنصر تحكم مربع اختيار (CheckBox) إلى group1.

7. انقر فوق CheckBox1 لتحديده .

8. في النافذة خصائص ، قم بتغيير الخصائص التالية.

   الخصائص	Value
   الاسم	addButtonComboBox
   Label	زر الإضافة

9. قم بإضافة مربع الاختيار الثاني إلى group1 ثم قم بتغيير الخصائص التالية.

   الخصائص	Value
   الاسم	addRichTextCheckBox
   Label	إضافة عنصر تحكم نص غنى

10. يضيف ‏‫Visual Studio مشروع "الخاص بي وصفه علامة ذكى" إلى من مستكشف الحل.

    Clickيوفر قوالب مشروع الوظيفة الإضافية لمعظم التطبيقات في الإصدار 2007 Microsoft المكتب الالنظام و.

11. يحتوي هذا الملف على الفئة، مما يوفر جهاز إضافة-بوصة

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

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

إضافة وإزالة عناصر تحكم في المستند النشط.

في التعليمات البرمجية الخاصة بالوظيفة الإضافية، يجب عليك تحويل المستند النشط إلى عنصر مضيف Microsoft.Office.Tools.Word.Document قبل أن يمكنك إضافة عنصر تحكم. في حلول Visual Studio Tools لـ Office, يمكن إضافة عناصر تحكم مدارة فقط للعناصر المضيفة التى تعمل كحاويات لعناصر التحكم. في المشاريع على مستوى التطبيق, يمكن إنشاء العناصر المضيفة في وقت التشغيل باستخدام الأسلوب GetVstoObject

قم بإضافة أساليب للفئة ThisAddIn التي يمكن استدعاؤها لإضافة أو إزالة Button أو RichTextContentControl على المستند النشط. فيما بعد في هذه الإرشادات التفصيلية ، سيتم استدعاء هذه الأساليب من معالجات الأحداث Click لخانات الاختيار على الشريط.

لإضافة و إزالة عناصر التحكم الموجودة في المستند النشط

1. في مستكشف الحلول ، انقر نقراً مزدوجاً فوق ThisAddIn.vb (في Visual Basic) أو ThisAddIn.cs (في C#) لفتح ملف التعليمات البرمجية.

2. قم بإضافة التعليمات البرمجية التالية إلى فئة ThisAddIn . هذه التعليمة البرمجية تقوم بالتصريح بالكائنات Button و RichTextContentControl التي تمثل عناصر التحكم التي ستتم إضافتها للمستند.

   Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
   Private richTextControl As RichTextContentControl = Nothing
   

   private Microsoft.Office.Tools.Word.Controls.Button button = null;
   private RichTextContentControl richTextControl = null;
   

3. قم بإضافة الأسلوب التالي إلى الفئة ThisAddIn . When the user clicks the Add Button check box on the Ribbon, this method adds a Button to the current selection on the document if the check box is selected, or removes the Button if the check box is cleared.

   Friend Sub ToggleButtonOnDocument()
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
   
       Dim name As String = "MyButton"
   
       If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               button = vstoDocument.Controls.AddButton( _
                   selection.Range, 100, 30, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

   internal void ToggleButtonOnDocument()
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();
   
       string name = "MyButton";
   
       if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               button = vstoDocument.Controls.AddButton(
                   selection.Range, 100, 30, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

4. قم بإضافة الأسلوب التالي إلى الفئة ThisAddIn . When the user clicks the Add Rich Text Control check box on the Ribbon, this method adds a RichTextContentControl to the current selection on the document if the check box is selected, or removes the RichTextContentControl if the check box is cleared.

   Friend Sub ToggleRichTextControlOnDocument()
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
   
       Dim name As String = "MyRichTextBoxControl"
   
       If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                       selection.Range, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

   internal void ToggleRichTextControlOnDocument()
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();
   
       string name = "MyRichTextBoxControl";
   
       if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                   selection.Range, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

إزالة عنصر تحكم الزر عند حفظ المستند.

عناصر تحكم Windows Forms لا يتم حفظها عندما يتم حفظ المستند ثم إغلاقه. ومع ذلك، برنامج تضمين ActiveX لكل عنصر تحكم يبقى في المستند، و حد برنامج التضمين هذا يمكن مشاهدته بواسطة المستخدمين عندما يتم إعادة فتح المستند. هناك عدة طرق لتنظيف عناصر تحكم Windows Forms التى تم إنشاؤها بشكل حيوي في الوظائف الإضافية. في هذه الإرشادات التفصيلية, تقوم برمجياً بإزالة Buttonعند حفظ المستند.

لإزالة عنصر تحكم الزر عند حفظ المستند.

1. في ملف التعليمات البرمجية ThisAddIn.cs أو ThisAddIn.vb، أضف الأسلوب التالي للفئة ThisAddIn. هذا الأسلوب هو معالج أحداث للحدث. DocumentBeforeSave إذا كان المستند المحفوظ فيه العنصر المضيف Document المقترن به، يأخذ معالج الأحداث العنصر المضيف و يزيل عنصر التحكم Button إذا كان موجوداً.

   Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
       ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim isExtended As Boolean = Doc.HasVstoObject()
   
       If isExtended Then
           ' Use the following line of code in projects that target the .NET Framework 4.
           Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)
   
           ' In projects that target the .NET Framework 3.5, use the following line of code.
           ' Dim vstoDocument As Document = Doc.GetVstoObject()
   
           If vstoDocument.Controls.Contains(button) Then
               vstoDocument.Controls.Remove(button)
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
           End If
       End If
   End Sub
   

   private void Application_DocumentBeforeSave(Word.Document Doc, 
       ref bool SaveAsUI, ref bool Cancel)
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       bool isExtended = Globals.Factory.HasVstoObject(Doc);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // bool isExtended = Doc.HasVstoObject();
   
       if (isExtended)
       {
           // Use the following line of code in projects that target the .NET Framework 4.
           Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
   
           // In projects that target the .NET Framework 3.5, use the following line of code.
           // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

2. فى C#، قم بإضافة التعليمات البرمجية التالية إلى معالج الحدث ThisAddIn_Startup . هذه التعليمة البرمجية مطلوبة فى C# لاستدعاء معالج الأحداث Application_DocumentBeforeSave مع الحدث DocumentBeforeSave .

   this.Application.DocumentBeforeSave += 
       new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
       Application_DocumentBeforeSave);
   

إضافة و إزالة عناصر التحكم عندما ينقر المستخدم فوق مربعات الاختيار على الشريط

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

لإضافة أو إزالة عناصر التحكم عند قيام المستخدم بالنقر فوق خانات الاختيار على "الشريط"

• في ملف التعليمات البرمجية MyRibbon.cs أو MyRibbon.vb، استبدل معالجات الأحداث addButtonCheckBox_Click و addRichTextCheckBox_Click المنشأة بالتعليمات البرمجية التالية. هذه التعليمة البرمجية تعيد تعريف معالجات الأحداث هذه لتستدعى الأساليب ToggleButtonOnDocument و ToggleRichTextControlOnDocument التي قمت بإضافتها فى الفئة ThisAddInمسبقًا في هذه الإرشادات التفصيلية.

  Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
      ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
      Globals.ThisAddIn.ToggleButtonOnDocument()
  End Sub
  
  Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
      ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
      Globals.ThisAddIn.ToggleRichTextControlOnDocument()
  End Sub
  

  private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
  {
      Globals.ThisAddIn.ToggleButtonOnDocument();
  }
  
  private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
  {
      Globals.ThisAddIn.ToggleRichTextControlOnDocument();
  }
  

اختبار الحل

قم بإضافة عناصر التحكم إلى ورقة العمل بواسطة تحديدها من علامة التبويب المخصصة على الشريط. عندما تقوم بحفظ المستند، يتم إزالة عنصر التحكم Button.

لاختبار الحل.

1. اضغط F5 لتشغيل مشروعك.

2. في المستند النشط اضغط ENTER عدة مرات لإضافة فقرات فارغة جديدة في المستند.

3. حدد الفقرة الأولى

4. انقر فوق علامة التبويب الوظائف الإضافية (Add-Ins).

5. في المجموعة إضافة عناصر تحكم، انقر فوق إضافة زر .

   سوف يظهر زر في الفقرة الأولى.

6. حدد الفقرة الأخيرة.

7. في المجموعة إضافة عناصر تحكم، انقر فوق إضافة عنصر تحكم نص غنى .

   تم إضافة عنصر تحكم نص غنى للفقرة الأخيرة.

8. احفظ المستند.

   تم إزالة الزر من المستند.

الخطوات التالية

يمكنك معرفة المزيد حول عناصر التحكم في الوظائف الإضافية على مستوى التطبيق من هذه المواضيع:

• للحصول على نموذج يوضح كيفية إضافة العديد من أنواع عناصر التحكم إلى مستند في وقت التشغيل و إعادة إنشاء عناصر التحكم عندما يتم إعادة فتح المستند, راجع نموذج عناصر التحكم الحيوية فى وظيفة Word الإضافية في نماذج تطوير Office وإرشادات تفصيلية.

• للحصول على الإرشادات التفصيلية التى توضح كيفية إضافة عناصر تحكم إلى ورقة عمل باستخدام وظيفة إضافية على مستوى تطبيق في Excel، راجع الإرشادات التفصيلية: إضافة عناصر تحكم إلى ورقة عمل في وقت التشغيل في مشروع على مستوى التطبيق.

راجع أيضًا:

المهام

كيفية القيام بما يلي: إضافة عناصر تحكم Windows Forms إلى مستندات Office

كيفية القيام بما يلي: إضافة عناصر تحكم محتويات إلى مستندات Word

المبادئ

إضافة عناصر تحكم إلى مستندات Office في وقت التشغيل

استمرارية عناصر التحكم الديناميكي في مستندات Office

توسيع مستندات Word ومصنفات Excel في وظائف إضافية على مستوى التطبيق في وقت التشغيل

موارد أخرى

حلول Word

Word الوظيفة الإضافية الديناميكي عناصر تحكم نموذج