Objetos OLE e Controles ActiveX

Aspose.Words FOSS para .NET fornece acesso de leitura a objetos OLE incorporados e controles ActiveX do Forms 2.0 através do ponto de entrada OleFormat e suas classes relacionadas em Aspose.Words.Drawing e Aspose.Words.Drawing.Ole.

Acessando Dados de Objetos OLE Incorporados

OleFormat é exposto por um Shape incorporado e fornece acesso aos dados brutos e metadados do objeto incorporado. SuggestedFileName e SuggestedExtension descrevem como o objeto incorporado seria salvo, ProgId identifica a aplicação servidor OLE que o criou, e IsLink distingue um objeto vinculado (SourceFullName/SourceItem apontam para a fonte externa) de um totalmente incorporado. GetOleEntry(oleEntryName) lê um fluxo nomeado específico da estrutura de arquivo composto OLE, GetRawData() retorna os dados brutos completos do objeto, e Save(fileName) / Save(stream) gravam os dados nativos do objeto incorporado em disco ou em um fluxo — útil para extrair o arquivo original incorporado (por exemplo, uma planilha ou apresentação incorporada) sem abri-lo em sua aplicação nativa. OlePackage, alcançado via OleFormat.OlePackage, expõe FileName e DisplayName para objetos incorporados como um Pacote OLE.

Trabalhando com Controles ActiveX do Forms 2.0

Quando o objeto incorporado é um controle ActiveX do Microsoft Forms 2.0 (caixas de seleção, caixas de texto, caixas de combinação e controles interativos semelhantes em vez de documentos incorporados), OleFormat.OleControl retorna um OleControl. Verifique sua propriedade IsForms2OleControl e, se true, faça cast para Forms2OleControl (a classe base abstrata para todos os controles do Forms 2.0) para acessar propriedades específicas do controle: Caption, Value, Enabled, Type (um valor Forms2OleControlType — CheckBox, Textbox, ComboBox, OptionButton, ListBox, CommandButton e outros), além das propriedades visuais ForeColor, BackColor, Width e Height. Controles contêiner, como frames, expõem seus controles aninhados através de ChildNodes, um Forms2OleControlCollection.

Dicas e Melhores Práticas

Verifique OleFormat.IsLink antes de supor que os dados do objeto incorporado estejam presentes localmente — objetos vinculados referenciam um arquivo externo via SourceFullName em vez de incorporar seu conteúdo.
Use SuggestedExtension junto com Save() para reconstruir um nome de arquivo de saída sensato ao extrair objetos incorporados em lote.
Sempre verifique OleControl.IsForms2OleControl antes de converter para Forms2OleControl — nem todo OleControl é um controle Forms 2.0.
Forms2OleControlCollection.Count e enumeração via GetEnumerator() permitem percorrer controles aninhados dentro de um quadro ou controle de contêiner multipágina.

Problemas Comuns

Problema	Causa	Correção
`GetRawData()` retorna dados inesperados/vazios	Objeto é um link (`IsLink == true`), não incorporado	Verifique `IsLink` primeiro; resolva `SourceFullName` para objetos vinculados
`InvalidCastException` convertendo `OleControl` para `Forms2OleControl`	O controle não é um controle Forms 2.0	Verifique `IsForms2OleControl` antes de fazer o cast
`GetOleEntry()` retorna null para um fluxo nomeado	O nome do fluxo não existe na estrutura de arquivo composto deste objeto	Enumere os nomes reais das entradas em vez de assumir um nome fixo
Controles aninhados dentro de um frame não encontrados	Apenas verificou o `OleControl` de nível superior, não `ChildNodes`	Recursar em `Forms2OleControl.ChildNodes` para controles de contêiner

FAQ

Como extraio um objeto incorporado do Excel ou PowerPoint de um documento do Word?

Acesse o OleFormat da forma, então chame Save(fileName) ou GetRawData() para recuperar os bytes nativos do objeto incorporado; use SuggestedExtension para nomear o arquivo de saída adequadamente.

Qual é a diferença entre um objeto OLE incorporado e um controle Forms 2.0?

Um objeto OLE incorporado (acessado via OleFormat diretamente) é normalmente outro documento (planilha, apresentação); um controle Forms 2.0 (OleFormat.OleControl → Forms2OleControl) é um elemento de interface interativo como uma caixa de seleção ou caixa de texto.

Como saber se um objeto OLE está vinculado em vez de incorporado?

Verifique OleFormat.IsLink — quando true, SourceFullName e SourceItem descrevem a fonte externa em vez de o objeto conter seus próprios dados.

Posso ler a legenda ou o valor de um controle de caixa de seleção?

Sim — converta o OleControl para Forms2OleControl (após confirmar IsForms2OleControl) e leia Caption e Value.

API Reference Resumo

Classe / Método	Descrição
`OleFormat`	Ponto de entrada para os dados e metadados de um objeto OLE incorporado
`OleFormat.GetRawData()`	Recuperar os bytes brutos do objeto incorporado
`OleFormat.Save()`	Salvar os dados nativos do objeto incorporado em um arquivo ou fluxo
`OlePackage`	Nome de arquivo/nome de exibição para um objeto OLE Package
`OleControl`	Representação base de um controle ActiveX incorporado
`Forms2OleControl`	Controle Microsoft Forms 2.0 (caixa de seleção, caixa de texto, caixa de combinação, etc.)
`Forms2OleControlCollection`	Coleção de nós `Forms2OleControl` filhos (por exemplo, dentro de um quadro)
`Forms2OleControlType`	Enumeração dos tipos de controle Forms 2.0

Ver também

Aspose.Words for .NET — Enterprise Documentation