Visão geral do painel de ações

  • Artigo

Um painel de ações é um painel de tarefas Ações do Documento personalizável anexado a um documento específico do Microsoft Office Word ou pasta de trabalho do Microsoft Office Excel. O painel de ações é hospedado dentro do painel de tarefas do Office junto com outros painéis de tarefas internos, como o painel de tarefas Código-fonte XML no Excel ou o painel de tarefas Estilos e Formatação no Word. Você pode usar controles do Windows Forms ou controles WPF para criar a interface do usuário do painel de ações.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento para Excel e Word. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Você pode criar um painel de ações somente em uma personalização em nível de documento para Word ou Excel. Não é possível criar um painel de ações em um suplemento VSTO. Para obter mais informações, consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Observação

O painel de ações é diferente dos painéis de tarefas personalizados. Os painéis de tarefas personalizados estão associados ao aplicativo, não a um documento específico. Você pode criar painéis de tarefas personalizados em Suplementos VSTO para alguns aplicativos do Microsoft Office. Para obter mais informações, consulte Painéis de tarefas personalizados.

Exibir o painel de ações

O painel de ações é representado pela ActionsPane classe. Quando você cria um projeto de nível de documento, uma instância dessa classe está disponível para seu código usando o ActionsPaneThisWorkbook campo da classe (para Excel) ou ThisDocument (para Word) em seu projeto. Para exibir o painel de ações, adicione um controle Windows Forms à Controls propriedade do ActionsPane campo. O exemplo de código a seguir adiciona um controle nomeado actions ao painel de ações.

this.ActionsPane.Controls.Add(actions);

O painel de ações torna-se visível em tempo de execução assim que você adiciona explicitamente um controle a ele. Depois que o painel de ações for exibido, você poderá adicionar ou remover dinamicamente controles em resposta às ações do usuário. Normalmente, você adiciona o código para exibir o painel de ações no Startup manipulador de eventos de ou ThisWorkbook para que o painel de ThisDocument ações fique visível quando o usuário abrir o documento pela primeira vez. No entanto, convém exibir o painel de ações somente em resposta à ação de um usuário no documento. Por exemplo, você pode adicionar o código ao Click evento de um controle no documento.

Adicionar vários controles ao painel de ações

Ao adicionar vários controles ao painel de ações, você deve agrupar os controles em um controle de usuário e, em seguida, adicionar o controle de usuário à Controls propriedade. Esse processo inclui as seguintes etapas:

  1. Crie a interface do usuário (UI) do painel de ações adicionando um controle do painel de ações ou um item de controle de usuário ao seu projeto. Ambos os itens incluem uma classe personalizada do Windows Forms UserControl . Os itens Controle do Painel de Ações e Controle de Usuário são equivalentes, a única diferença é o nome.

  2. Adicione controles do UserControl Windows Forms ao usando o designer ou escrevendo código.

    Observação

    Você também pode adicionar controles WPF ao painel de ações adicionando um WPF UserControl ao Windows Forms UserControl. Para obter mais informações, consulte Usar controles WPF em soluções do Office.

  3. Adicione uma instância do controle de usuário personalizado aos controles contidos no ActionsPane campo da ThisWorkbook classe (para Excel) ou ThisDocument (para Word) em seu projeto.

    Para obter exemplos que demonstram esse processo com mais detalhes, consulte Como adicionar um painel de ações a documentos do Word ou pastas de trabalho do Excel.

Ocultar o painel de ações

Embora a ActionsPane classe tenha um Hide método e uma Visible propriedade, você não pode remover o painel de ações da interface do usuário usando qualquer membro da ActionsPane própria classe. Chamar o método ou definir a Visible propriedade como false oculta apenas os controles no painel de ações, não oculta o Hide painel de tarefas.

Para ocultar o painel de tarefas em sua solução, você tem várias opções:

  • Para o Word, defina a propriedade do objeto que representa o Visible painel de tarefas Ações do Documento como false.TaskPane O exemplo de código a seguir destina-se a ser executado a ThisDocument partir da classe em seu projeto.

    this.Application.TaskPanes[Word.WdTaskPanes.wdTaskPaneDocumentActions].Visible = false;

  • Para o Excel, defina a DisplayDocumentActionTaskPaneApplication propriedade do objeto como false. O exemplo de código a seguir destina-se a ser executado a ThisWorkbook partir da classe em seu projeto.

    this.Application.DisplayDocumentActionTaskPane = false;

  • Para o Word ou Excel, você pode alternativamente definir a Visible propriedade da barra de comandos que representa o painel de tarefas como false. O exemplo de código a seguir destina-se a ser executado a partir da ThisDocument classe ou ThisWorkbook em seu projeto.

    this.Application.CommandBars["Task Pane"].Visible = false;

Limpar o painel de ações quando o documento for aberto

Quando um usuário salva o documento enquanto o painel de ações está visível, o painel de ações fica visível sempre que o documento é aberto, independentemente de o painel de ações conter ou não controles. Se você quiser controlar quando ele aparecer, chame Startup o método do campo no manipulador de eventos de ou ThisWorkbook para garantir que o painel de ActionsPaneThisDocument ações não fique visível quando o Clear documento for aberto.

Determinar quando o painel de ações está fechado

Não há nenhum evento gerado quando o painel de ações é fechado. Embora a ActionsPane classe tenha um VisibleChanged evento, esse evento não é gerado quando o usuário final fecha o painel de ações. Em vez disso, esse evento é gerado quando os controles no painel de ações são ocultos chamando o Hide método ou definindo a Visible propriedade como false.

Quando o usuário fecha o painel de ações, o usuário pode exibi-lo novamente executando um dos procedimentos a seguir na interface do usuário (UI) do aplicativo.

Para exibir o painel de ações usando a interface do usuário do Word ou do Excel

  1. Na Faixa de Opções, clique na guia Exibir .

  2. No grupo Mostrar/Ocultar, clique no botão de alternância Ações doDocumento.

Eventos do painel de ações do programa

Você pode adicionar vários controles de usuário ao painel de ações e, em seguida, escrever código para responder a eventos no documento mostrando e ocultando os controles de usuário. Se você mapear elementos do esquema XML para o documento, poderá mostrar determinados controles de usuário no painel de ações sempre que o ponto de inserção estiver dentro de um dos elementos XML. Para obter mais informações, consulte Como: mapear esquemas para documentos do Word dentro do Visual Studio e Como: mapear esquemas para planilhas dentro do Visual Studio.

Você também pode escrever código para responder aos eventos de qualquer objeto, incluindo controle de host, aplicativo ou eventos de documento. Para obter mais informações, consulte Demonstra Passo a passo: programa em relação a eventos de um controle NamedRange.

Vincular dados a controles no painel de ações

Os controles no painel de ações têm os mesmos recursos de vinculação de dados que os controles no Windows Forms. Você pode vincular os controles a fontes de dados, como conjuntos de dados, conjuntos de dados digitados e XML. Para obter mais informações, consulte Vinculação de dados e Windows Forms.

Você pode vincular controles no painel de ações e controles no documento ao mesmo conjunto de dados. Por exemplo, você pode criar uma relação mestre/detalhe entre os controles no painel de ações e os controles na planilha. Para obter mais informações, consulte Demonstra Passo a passo: vincular dados a controles em um painel de ações do Excel.

Validar dados em controles do painel de ações

Se você exibir uma caixa de mensagem no manipulador de eventos de um controle no Validating painel de ações, o evento poderá ser gerado uma segunda vez quando o foco for movido do controle para a caixa de mensagem. Para evitar esse problema, use um controle para exibir quaisquer mensagens de erro de ErrorProvider validação.

Ordem de empilhamento de controle de usuário

Se você estiver usando vários controles de usuário, poderá escrever código para empilhar corretamente os controles de usuário no painel de ações, esteja ele encaixado vertical ou horizontalmente. Você pode definir a ordem de empilhamento dos controles de usuário no painel de ações usando a StackStyle enumeração da StackOrder propriedade. Para obter mais informações, consulte Como gerenciar o layout de controle em painéis de ações.

A StackOrder propriedade pode usar os seguintes StackStyle valores de enumeração.

Estilo de empilhamento Definição
FromBottom Empilhar na parte inferior do painel de ações.
Da esquerda Empilhar na parte esquerda do painel de ações.
Da direita Empilhar na parte direita do painel de ações.
Do topo Empilhar na parte superior do painel de ações.
Nenhum Nenhuma ordem de empilhamento definida, a ordem é controlada pelo desenvolvedor.

O código a seguir define a StackOrder propriedade para empilhar os controles de usuário na parte superior do painel de ações.

this.ActionsPane.StackOrder = Microsoft.Office.Tools.StackStyle.FromTop;

Controles de âncora

Se o usuário redimensionar o painel de ações em tempo de execução, os controles poderão ser redimensionados com o painel de ações. Você pode usar a Anchor propriedade de um controle do Windows Forms para ancorar controles no painel de ações. Você também pode ancorar os controles do Windows Forms no controle de usuário da mesma maneira. Para obter mais informações, consulte Como: Anchor controles no Windows Forms.

Redimensionar o painel de ações

Não é possível alterar diretamente o tamanho de um ActionsPane porque o ActionsPane está incorporado no painel de tarefas. No entanto, você pode alterar programaticamente a largura do painel de tarefas definindo a Width propriedade do que representa o CommandBar painel de tarefas. Você pode alterar a altura do painel de tarefas se ele estiver encaixado horizontalmente ou estiver flutuando.

O redimensionamento programaticamente do painel de tarefas não é recomendado porque o usuário deve ser capaz de selecionar o tamanho do painel de tarefas que melhor atenda às suas necessidades. No entanto, se você precisar redimensionar a largura do painel de tarefas, poderá usar o código a seguir para realizar essa tarefa.

this.CommandBars["Task Pane"].Width = 200;

Reposicionar o painel de ações

Não é possível reposicionar diretamente o ActionsPane porque ele está incorporado no painel de tarefas. No entanto, você pode mover programaticamente o painel de tarefas definindo a Position propriedade do que representa o CommandBar painel de tarefas.

O reposicionamento programaticamente do painel de tarefas não é recomendado porque o usuário deve poder escolher a posição do painel de tarefas na tela que melhor atenda às suas necessidades. No entanto, se você precisar mover o painel de tarefas para uma posição específica, poderá usar o código a seguir para realizar essa tarefa.

this.CommandBars["Task Pane"].Position =
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft;

Observação

Os usuários finais podem reposicionar manualmente o painel de tarefas a qualquer momento. Não há como garantir que o painel de tarefas permaneça encaixado na posição indicada programaticamente. No entanto, você pode verificar se há alterações de orientação e garantir que os controles no painel de ações estejam empilhados na direção correta. Para obter mais informações, consulte Como gerenciar o layout de controle em painéis de ações.

A definição Top das propriedades e Left do não altera sua posição porque o ActionsPane objeto está incorporado no painel de ActionsPane tarefas.

Se o painel de tarefas não estiver encaixado, você poderá definir as Top propriedades e Left do que representa o CommandBar painel de tarefas. O código a seguir move um painel de tarefas desencaixado para o canto superior esquerdo do documento.

if (this.CommandBars["Task Pane"].Position == 
    Microsoft.Office.Core.MsoBarPosition.msoBarFloating)
{
    this.CommandBars["Task Pane"].Top = 0;
    this.CommandBars["Task Pane"].Left = 0;
}

Conteúdo relacionado