Přidání ovládacích prvků do dokumentů Office za běhu

  • Článek

Ovládací prvky můžete přidat do systém Microsoft Office wordového dokumentu a systém Microsoft Office excelového sešitu za běhu. Můžete je také odebrat za běhu. Ovládací prvky, které přidáte nebo odeberete za běhu, se nazývají dynamické ovládací prvky.

Platí pro: Informace v tomto tématu platí pro projekty na úrovni dokumentu a projekty doplňků VSTO pro Excel a Word. Další informace naleznete v tématu Funkce dostupné aplikace Office lication a typu projektu.

Toto téma popisuje následující:

Správa ovládacích prvků za běhu pomocí kolekcí ovládacích prvků

Pokud chcete přidat, získat nebo odebrat ovládací prvky za běhu, použijte pomocné metody ControlCollection a ControlCollection objekty.

Způsob přístupu k těmto objektům závisí na typu projektu, který vyvíjíte:

Přidání ovládacích prvků

ControlCollection Mezi tyto ControlCollection typy patří pomocné metody, které můžete použít k přidání hostitelských ovládacích prvků a běžných ovládacích prvků model Windows Forms do dokumentů a listů. Každý název metody má třídu ovládacích prvků formátuAdd, kde třída ovládacího prvku je název třídy ovládacího prvku, který chcete přidat. Pokud chcete například přidat NamedRange ovládací prvek do dokumentu, použijte metodu AddNamedRange .

Následující příklad kódu přidá NamedRange do Sheet1 projektu na úrovni dokumentu pro Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Přístup k ovládacím prvkům a jejich odstranění

Vlastnost objektu ControlsWorksheet a nebo Document můžete iterovat všemi ovládacími prvky v dokumentu, včetně ovládacích prvků, které jste přidali v době návrhu. Ovládací prvky, které přidáte v době návrhu, se také označují jako statické ovládací prvky.

Dynamické ovládací prvky můžete odebrat voláním Delete metody ovládacího prvku nebo voláním Remove metody každé kolekce Controls. Následující příklad kódu používá metodu RemoveNamedRange k odebrání z Sheet1 projektu na úrovni dokumentu pro Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

Statické ovládací prvky nelze odebrat za běhu. Pokud se pokusíte použít metodu Delete nebo Remove odebrat statický ovládací prvek, CannotRemoveControlException vyvolá se vyvolá.

Poznámka:

Ovládací prvky v Shutdown obslužné rutině události dokumentu neodebídejte programově. Prvky uživatelského rozhraní dokumentu už nejsou při vyvolání události k dispozici Shutdown . Pokud chcete ovládací prvky před ukončením dokumentu odebrat, přidejte kód do obslužné rutiny události pro jinou událost, například BeforeClose pro BeforeSave Word nebo BeforeClosenebo BeforeSave pro Excel.

Přidání hostitelských ovládacích prvků do dokumentů

Když do dokumentů přidáte ovládací prvky hostitele prostřednictvím kódu programu, musíte zadat název, který ovládací prvek jednoznačně identifikuje, a musíte určit, kam chcete ovládací prvek přidat do dokumentu. Konkrétní pokyny najdete v následujících tématech:

Další informace o hostitelských ovládacích prvcích naleznete v tématu Přehled položek hostitele a hostitelských ovládacích prvků.

Při uložení a zavření dokumentu se všechny dynamicky vytvořené hostitelské ovládací prvky odpojí od událostí a ztratí funkce datové vazby. Do řešení můžete přidat kód pro opětovné vytvoření hostitelských ovládacích prvků při opětovném otevření dokumentu. Další informace naleznete v tématu Zachování dynamických ovládacích prvků v dokumentech Office.

Poznámka:

Pomocné metody nejsou k dispozici pro následující ovládací prvky hostitele, protože tyto ovládací prvky nelze přidat programově do dokumentů: XmlMappedRange, XMLNodea XMLNodes.

Přidání ovládacích prvků model Windows Forms do dokumentů

Když do dokumentu přidáte ovládací prvek model Windows Forms programově, musíte zadat umístění ovládacího prvku a název, který ovládací prvek jednoznačně identifikuje. Visual Studio Tools for Office runtime poskytuje pomocné metody pro každý ovládací prvek. Tyto metody jsou přetížené, takže můžete předat buď rozsah, nebo konkrétní souřadnice pro umístění ovládacího prvku.

Při uložení a zavření dokumentu se z dokumentu odeberou všechny dynamicky vytvořené ovládací prvky model Windows Forms. Do řešení můžete přidat kód pro opětovné vytvoření ovládacích prvků při opětovném otevření dokumentu. Pokud vytváříte dynamické model Windows Forms ovládací prvky pomocí doplňku VSTO, zůstanou v dokumentu technologie ActiveX obálky ovládacích prvků. Další informace naleznete v tématu Zachování dynamických ovládacích prvků v dokumentech Office.

Poznámka:

model Windows Forms ovládací prvky nelze do chráněných dokumentů přidávat prostřednictvím kódu programu. Pokud programově zrušíte ochranu wordového dokumentu nebo excelového listu a přidáte ovládací prvek, musíte napsat další kód, který odebere obálku technologie ActiveX ovládacího prvku při zavření dokumentu. Obálka technologie ActiveX ovládacího prvku se automaticky neodstraní z chráněných dokumentů.

Přidání vlastních ovládacích prvků

Pokud chcete přidat metodu Control , která není podporována dostupnými pomocnými metodami, jako je například vlastní uživatelský ovládací prvek, použijte následující metody:

  • Pro Excel použijte jednu z AddControl metod objektu ControlCollection .

  • Ve Wordu AddControl použijte jednu z metod objektu ControlCollection .

    Chcete-li přidat ovládací prvek, předejte Control, umístění ovládacího prvku a název, který jednoznačně identifikuje ovládací prvek do AddControl metody. Metoda AddControl vrátí objekt, který definuje, jak ovládací prvek komunikuje s listem nebo dokumentem. Metoda AddControl vrátí ControlSite (pro Excel) nebo ControlSite objekt (pro Word).

    Následující příklad kódu ukazuje, jak použít metodu AddControl k dynamickému přidání vlastního uživatelského ovládacího prvku do listu v projektu aplikace Excel na úrovni dokumentu. V tomto příkladu je uživatelský ovládací prvek pojmenován UserControl1a Range má název range1. Pokud chcete tento příklad použít, spusťte ho Sheetz n třídy v projektu.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Použití členů vlastních ovládacích prvků

Po použití jedné z AddControl metod přidání ovládacího prvku do listu nebo dokumentu teď máte dva různé řídicí objekty:

  • Představuje Control vlastní ovládací prvek.

  • , ControlSiteOLEObjectnebo OLEControl objekt, který představuje ovládací prvek po jeho přidání do listu nebo dokumentu.

    Mezi těmito ovládacími prvky se sdílí mnoho vlastností a metod. Je důležité, abyste k těmto členům přistupovali prostřednictvím příslušného ovládacího prvku:

  • Chcete-li získat přístup k členům, které patří pouze do vlastního ovládacího prvku, použijte tlačítko Control.

  • Chcete-li získat přístup k členům sdíleným ovládacími prvky, použijte ControlSiteobjekt , OLEObjectnebo OLEControl objekt.

    Pokud ke sdílenému členu přistupujete ze sdíleného člena Control, může selhat bez upozornění nebo oznámení nebo může vést k neplatným výsledkům. Vždy používejte metody nebo vlastnosti objektu ControlSite, OLEObjectpokud OLEControl není metoda nebo vlastnost potřebná k dispozici; pouze pak byste měli odkazovat na Control.

    Například třída ControlSite i Control třída mají Top vlastnost. Chcete-li získat nebo nastavit vzdálenost mezi horní částí ovládacího prvku a horní částí dokumentu, použijte Top vlastnost ControlSite, nikoli Top vlastnost Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Související obsah