Ograniczenia programowe elementów hosta i kontrolek hosta

  • Artykuł

Każdy element hosta i kontrolka hosta jest zaprojektowany tak, aby zachowywał się jak odpowiedni natywny obiekt programu Microsoft Office Word lub Microsoft Office Excel z dodatkowymi funkcjami. Istnieją jednak pewne podstawowe różnice między zachowaniem elementów hosta a kontrolkami hosta i natywnymi obiektami pakietu Office w czasie wykonywania.

Aby uzyskać ogólne informacje na temat elementów hosta i kontrolek hosta, zobacz Omówienie elementów hosta i kontrolek hosta.

Dotyczy: informacje w tym temacie dotyczą projektów na poziomie dokumentu i projektów dodatków VSTO dla programów Excel i Word. Aby uzyskać więcej informacji, zobacz Funkcje dostępne przez aplikacja pakietu Office lication i typ projektu.

Programowe tworzenie elementów hosta

Podczas programowego tworzenia lub otwierania dokumentu, skoroszytu lub arkusza w czasie wykonywania przy użyciu modelu obiektów programu Word lub Excel element nie jest elementem hosta. Zamiast tego nowy obiekt jest natywnym obiektem pakietu Office. Jeśli na przykład użyjesz Add metody do utworzenia nowego dokumentu programu Word w czasie wykonywania, będzie to obiekt natywny Document , a nie Document element hosta. Podobnie podczas tworzenia nowego arkusza w czasie wykonywania przy użyciu Add metody uzyskuje się obiekt macierzysty Worksheet , a nie Worksheet element hosta.

W projektach na poziomie dokumentu nie można tworzyć elementów hosta w czasie wykonywania. Elementy hosta można tworzyć tylko w czasie projektowania w projektach na poziomie dokumentu. Aby uzyskać więcej informacji, zobacz Element hosta dokumentu, Element hosta skoroszytu i Element hosta arkusza.

W projektach dodatków VSTO można tworzyć Documentelementy , Workbooklub Worksheet hostować w czasie wykonywania. Aby uzyskać więcej informacji, zobacz Rozszerzanie dokumentów programu Word i skoroszytów programu Excel w dodatku VSTO w czasie wykonywania.

Programowe tworzenie kontrolek hosta

Kontrolki hosta można dodawać programowo do Document elementu hosta lub Worksheet w czasie wykonywania. Aby uzyskać więcej informacji, zobacz Dodawanie kontrolek do dokumentów pakietu Office w czasie wykonywania.

Nie można dodać kontrolek hosta do natywnego Document lub Worksheet.

Uwaga

Nie można programowo dodać następujących kontrolek hosta do arkuszy lub dokumentów: XmlMappedRange, XMLNodei XMLNodes.

Omówienie różnic między typami między elementami hosta, kontrolkami hosta i natywnymi obiektami pakietu Office

Dla każdego elementu hosta i kontrolki hosta istnieje podstawowy natywny obiekt programu Microsoft Office Word lub Microsoft Office Excel. Dostęp do obiektu bazowego można uzyskać przy użyciu właściwości InnerObject elementu hosta lub kontrolki hosta. Nie ma jednak możliwości rzutowania natywnego obiektu pakietu Office na odpowiedni element hosta lub kontrolkę hosta. Jeśli spróbujesz rzutować natywny obiekt pakietu Office do typu elementu hosta lub kontrolki hosta, InvalidCastException zostanie zgłoszony element .

Istnieje kilka scenariuszy, w których różnice między typami elementów hosta i kontrolkami hosta a podstawowymi obiektami natywnymi pakietu Office mogą mieć wpływ na kod.

Przekazywanie kontrolek hosta do metod i właściwości

W programie Word nie można przekazać kontrolki hosta do metody lub właściwości, która wymaga natywnego obiektu programu Word jako parametru. Aby zwrócić podstawowy natywny obiekt programu Word, należy użyć właściwości InnerObject kontrolki hosta. Na przykład można przekazać Bookmark obiekt do metody, przekazując InnerObject właściwość Bookmark kontrolki hosta do metody .

W programie Excel należy użyć właściwości InnerObject kontrolki hosta, aby przekazać kontrolkę hosta do metody lub właściwości, gdy metoda lub właściwość oczekuje bazowego obiektu programu Excel.

Poniższy przykład tworzy kontrolkę NamedRange i przekazuje ją do AutoFill metody . Kod używa InnerObject właściwości nazwanego zakresu w celu zwrócenia bazowego pakietu Office Range wymaganego przez metodę AutoFill .

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

Zwraca typy natywnych metod i właściwości pakietu Office

Większość metod i właściwości elementów hosta zwraca podstawowy natywny obiekt pakietu Office, na którym bazuje element hosta. Na przykład Parent właściwość kontrolki NamedRange hosta w programie Excel zwraca Worksheet obiekt, a nie Worksheet element hosta. Parent Podobnie właściwość kontrolki RichTextContentControl hosta w programie Word zwraca Document obiekt, a nie Document element hosta.

Uzyskiwanie dostępu do kolekcji kontrolek hostów

Środowisko uruchomieniowe Visual Studio Tools dla pakietu Office nie udostępnia poszczególnych kolekcji dla każdego typu kontrolki hosta. Zamiast tego użyj właściwości Controls elementu hosta, aby iterować wszystkie kontrolki zarządzane (zarówno kontrolki hosta, jak i kontrolki formularzy systemu Windows) w dokumencie lub arkuszu, a następnie wyszukać elementy zgodne z typem kontrolki hosta, którą cię interesuje. Poniższy przykład kodu sprawdza każdą kontrolkę w dokumencie programu Word i określa, czy kontrolka Bookmarkjest .

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}

Aby uzyskać więcej informacji na temat właściwości Controls elementów hosta, zobacz Dodawanie kontrolek do dokumentów pakietu Office w czasie wykonywania.

Modele obiektów programów Word i Excel zawierają właściwości, które uwidaczniają kolekcje natywnych kontrolek w dokumentach i arkuszach. Nie można uzyskać dostępu do kontrolek zarządzanych przy użyciu tych właściwości. Na przykład nie można wyliczyć każdej Bookmark kontrolki hosta w dokumencie przy użyciu Bookmarks właściwości Document obiektu lub Bookmarks właściwości Document. Te właściwości obejmują tylko kontrolki Bookmark w dokumencie; nie zawierają Bookmark kontrolek hosta w dokumencie.

Powiązana zawartość