Compartilhar via

Visão geral do painel Ações

Importante

O recurso Ações foi desativado do Microsoft Word a partir do Office 2024. Esse recurso só está disponível no Microsoft Word com as seguintes versões do Office:

  • Microsoft 365
  • Office LTSC Professional Plus 2021
  • Padrão Office LTSC 2021
  • Office Professional Plus 2016, 2019
  • Padrão do Office 2016, 2019

Um painel de ações é um painel de tarefas Document Actions personalizável anexado a um documento específico do Microsoft Office Word ou a uma pasta de trabalho específica do Microsoft Office Excel. O painel ações é hospedado dentro do painel de tarefas do Office juntamente com outros painéis de tarefas internos, como o painel de tarefas Origem 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 projetar 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 pelo aplicativo do Office e pelo tipo de projeto.

Você pode criar um painel de ações somente em uma personalização no nível do 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 pelo aplicativo do Office e pelo tipo de projeto.

Observação

O painel ações difere 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 ações

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

this.ActionsPane.Controls.Add(actions);

O painel de ações fica visível durante a execução assim que você adiciona explicitamente um controle a ele. Depois que o painel ações for exibido, você poderá adicionar ou remover controles dinamicamente 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 ou ThisDocument para que o painel de ThisWorkbook ações fique visível quando o usuário abrir o documento pela primeira vez. No entanto, talvez você queira exibir o painel de ações apenas em resposta à ação de um usuário no documento. Por exemplo, você pode adicionar o código ao evento Click de um controle no documento.

Adicionar vários controles ao painel 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 (interface do usuário) do painel ações adicionando um item controle de painel de ações ou controle de usuário ao seu projeto. Ambos os itens incluem uma classe personalizada do Windows Forms UserControl . Os itens controle de painel ações e controle de usuário são equivalentes; a única diferença é o nome deles.

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

    Observação

    Você também pode adicionar controles WPF ao painel 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 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 Hide método ou definir a Visible propriedade como false oculta apenas os controles no painel de ações; ele não oculta o painel de tarefas.

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

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

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

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

    this.Application.DisplayDocumentActionTaskPane = false;

  • Para o Word ou Excel, você pode, como alternativa, 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 classe ThisDocument ou ThisWorkbook no 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 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 o método Clear do campo ActionsPane no manipulador de eventos Startup de ThisDocument ou ThisWorkbook para garantir que o painel de ações não esteja visível quando o documento for aberto.

Determinar quando o painel ações é 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 ações, o usuário pode exibi-lo novamente executando um dos procedimentos a seguir na interface do usuário (interface do usuário) do aplicativo.

Para exibir o painel 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 Desativar Ações do Documento .

Eventos do painel Ações do programa

Você pode adicionar vários controles de usuário ao painel ações e, em seguida, escrever código para responder a eventos no documento mostrando e ocultando os controles do usuário. Se você mapear elementos de esquema XML para o documento, poderá mostrar determinados controles de usuário no painel 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, veja Passo a passo: Programa em eventos de um controle NamedRange.

Associar dados a controles no painel ações

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

Você pode associar 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 Passo a passo: associar dados a controles em um painel de ações do Excel.

Validar dados em controles de painel de ações

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

Ordem de empilhamento do controle de usuário

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

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

Estilo de empilhamento Definição
De baixo Empilhamento com início na parte inferior do painel Ações.
Da esquerda Empilhamento com início à esquerda do painel Ações.
Da direita Empilhamento com início à direita do painel Ações.
De cima Empilhamento com início na parte superior do painel 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 do 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 podem se redimensionar 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 do usuário da mesma maneira. Para obter mais informações, consulte Como ancorar controles no Windows Forms.

Redimensionar o painel ações

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

Não é recomendável redimensionar programaticamente o painel de tarefas 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 ações

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

Não é recomendável reposicionar programaticamente o painel de tarefas porque o usuário deve ser capaz de 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 que você indicar 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.

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

Se o painel de tarefas não estiver encaixado, defina as propriedades Top e Left da CommandBar que representa o 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