Поделиться через

Расширение документов Word и книг Excel в надстройках VSTO во время выполнения

  • Статья

Надстройку VSTO можно использовать для настройки документов Word и книг Excel одним из описанных ниже способов.

  • Добавление управляемых элементов управления в любой открытый документ или лист.

  • Преобразование существующего объекта списка на листе Excel в расширенный объект ListObject , который предоставляет события и позволяет выполнить привязку данных с помощью модели привязки данных Windows Forms.

  • Получение доступа к событиям на уровне приложения, которые предоставляются Word и Excel для определенных документов, книг и листов.

    Для использования данных функциональных возможностей необходимо в среде выполнения создать объект, расширяющий документ или книгу.

    Область применения: сведения в этой статье относятся к проектам надстроек VSTO для следующих приложений: Excel и Word. Дополнительные сведения см. в разделе "Функции", доступные по Приложение Office ликации и типу проекта.

Создание расширенных объектов в надстройках VSTO

Расширенные объекты — это экземпляры типов, предоставляемых средой выполнения Visual Studio Tools для Office, и расширяющие функциональные возможности объектов, существующих в объектных моделях Word или Excel (так называемых собственных объектов Office). Чтобы создать расширенный объект для объекта Word или Excel, используйте метод GetVstoObject. При первом вызове GetVstoObject метода для указанного объекта Word или Excel он возвращает новый объект, расширяющий указанный объект. С каждым последующим вызовом этого метода для одного и того же объекта Word или Excel возвращается один и тот же расширенный объект.

Тип расширенного объекта имеет такое же имя, как тип собственного объекта Office, но этот тип определен в пространстве имен Microsoft.Office.Tools.Excel или Microsoft.Office.Tools.Word . Например, если метод GetVstoObject вызывается для расширения объекта Document, он возвращает объект Document.

Методы GetVstoObject предназначены для использования преимущественно в проектах надстроек VSTO. Кроме того, их можно использовать в проектах уровня документа, но в этом случае они ведут себя иначе и имеют меньшее число применений.

Чтобы определить, создан ли уже расширенный объект для определенного собственного объекта Office, воспользуйтесь методом HasVstoObject. Дополнительные сведения см. в статье "Определение того, был ли расширен объект Office".

Создание элементов узла

При использовании GetVstoObject расширения объекта уровня документа (т. е. объекта WorkbookDocumentWorksheetили) возвращенный объект называется элементом узла. Ведущий элемент — это тип, который может содержать другие объекты, включая другие расширенные объекты и элементы управления. Ведущий элемент похож на соответствующий тип в основной сборке взаимодействия Word или Excel, но обладает дополнительными функциональными возможностями. Дополнительные сведения о элементах узла см. в обзоре элементов узла и элементов управления узлами.

Созданный ведущий документ можно использовать для добавления управляемых элементов управления в документ, книгу или лист. Дополнительные сведения см. в разделе "Добавление управляемых элементов управления в документы и листы".

Создание ведущего элемента для документа Word

  • В следующем примере кода показано, как создать ведущий элемент для активного документа.

    if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

Создание ведущего элемента для книги Excel

  • В следующем примере кода показано, как создать ведущий элемент для активной книги.

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

Создание ведущего элемента для листа Excel

  • В следующем примере кода показано, как создать ведущий элемент для активного листа проекта.

    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

Создание элементов управления узлом ListObject

Если метод GetVstoObject используется для расширения объекта ListObject, возвращается объект ListObject. Имеет ListObject все функции исходного ListObject. Он также имеет дополнительные функциональные возможности и может быть привязан к данным с помощью модели привязки данных Windows Forms. Дополнительные сведения см. в элементе управления ListObject.

Создание элемента управления ведущего приложения для ListObject

  • В следующем примере кода показано, как создать объект ListObject для первого объекта ListObject в активном листе проекта.

    Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

Добавление управляемых элементов управления в документы и листы

После создания объекта Document или Worksheetв документ или на лист можно добавить элементы управления, которым соответствуют эти расширенные объекты. Чтобы добавить элементы управления, используйте Controls свойство объекта Document или Worksheet. Дополнительные сведения см. в разделе "Добавление элементов управления в документы Office во время выполнения".

Добавлять можно элементы управления Windows Forms или элементы управления ведущего приложения. Элемент управления узлом — это элемент управления, предоставляемый средой выполнения набор средств Visual Studio для Office, которая упаковывает соответствующий элемент управления в основную сборку взаимодействия Word или Excel. Элемент управления узла предоставляет все поведение базового собственного объекта Office. Он также вызывает события и может быть привязан к данным с помощью модели привязки данных Windows Forms. Дополнительные сведения см. в обзоре элементов узла и элементов управления узлами.

Примечание.

Надстройка VSTO не позволяет добавить элемент управления XmlMappedRange на лист либо элемент управления XMLNode или XMLNodes в документ. Эти элементы управления ведущего приложения невозможно добавить программными средствами. Дополнительные сведения см. в разделе "Программные ограничения" элементов узла и элементов управления узлами.

Сохранение и удаление элементов управления

Управляемые элементы управления, добавленные в документ или на лист, не сохраняются при сохранении и последующем закрытии документа. Все элементы управления удаляются; остаются только собственные объекты Office. Например, объект ListObject становится объектом ListObject. Все элементы управления Windows Forms также удаляются, но оболочки ActiveX для элементов управления в документе остаются. Для очистки элементов управления или повторного создания элементов управления при последующем открытии документа необходимо включить в надстройку соответствующий код. Дополнительные сведения см. в статье "Сохранение динамических элементов управления в документах Office".

Доступ к событиям уровня приложения в документах и книгах

Некоторые события документа, книги и листа в собственных объектных моделях Word и Excel вызываются только на уровне приложения. Например, событие DocumentBeforeSave вызывается при открытии документа в Word, но определяется в классе Application , а не в классе Document .

Если в надстройке VSTO используются только собственные объекты Office, необходимо обработать эти события уровня приложения, а затем написать дополнительный код, определяющий, является ли документ, который вызвал событие, одним из настроенных. Ведущие элементы предоставляют такие события на уровне документа; это упрощает обработку событий для конкретного документа. Также можно создать ведущий элемент, а затем обработать для него событие.

Пример использования собственных объектов Word

В следующем примере кода показано, как обрабатывать событие уровня приложения для документов Word. Метод CreateDocument создает новый документ, а затем определяет обработчик событий DocumentBeforeSave , который предотвращает сохранение этого документа. Это событие уровня приложения, которое вызывается для Application объекта, и обработчик событий должен сравнить Doc параметр с document1 объектом, чтобы определить, представляет ли document1 сохраненный документ.

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Примеры использования элемента узла

В следующем примере кода данная процедура упрощена за счет обработки события BeforeSave ведущего документа Document . Метод CreateDocument2 в этих примерах создает объект Document , который расширяет document2 объект, а затем определяет BeforeSave обработчик событий, который предотвращает сохранение документа. Обработчик событий вызывается только при document2 сохранении и может отменить действие сохранения, не выполняя никаких дополнительных действий, чтобы проверить, какой документ сохранен.

Следующий пример кода демонстрирует эту задачу.

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Определение того, был ли расширен объект Office

Чтобы определить, создан ли уже расширенный объект для определенного собственного объекта Office, воспользуйтесь методом HasVstoObject. Этот метод возвращает значение true , если расширенный объект уже создан.

Используйте метод Globals.Factory.HasVstoObject. Передайте собственный объект Word или Excel (например, Document или Worksheet), который необходимо протестировать для расширенного объекта.

Метод HasVstoObject полезен в ситуации, когда код необходимо запускать только при условии, что заданный объект Office имеет расширенный объект. Например, если у вас есть надстройка VSTO Word, которая обрабатывает DocumentBeforeSave событие для удаления управляемых элементов управления из документа до его сохранения, используйте HasVstoObject метод, чтобы определить, был ли документ расширен. Если документ не был расширен, он не может иметь управляемые элементы управления, и обработчик событий может вернуться, не пытаясь очистить элементы управления в документе.

Связанный контент