Información general del panel Acciones

  • Artículo

Un panel de acciones es un panel de tareas acciones de documento personalizable que está asociado a un documento específico de Microsoft Office Word o a un libro de Microsoft Office Excel. El panel de acciones se hospeda dentro del panel de tareas de Office junto con otros paneles de tareas integrados, como el panel de tareas Origen XML en Excel o el panel de tareas Estilos y formato de Word. Puede utilizar controles de Windows Forms o WPF para diseñar la interfaz de usuario del panel de acciones.

Se aplica a: la información de este tema se aplica a proyectos de nivel de documento para Excel y Word. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

Puede crear un panel de acciones solo en una personalización de nivel de documento para Word o Excel. No se puede crear un panel de acciones en un complemento de VSTO. Para obtener más información, consulte Características disponibles por aplicación de Office lication y tipo de proyecto.

Nota:

El panel de acciones difiere de los paneles de tareas personalizados. Los paneles de tareas personalizados están asociados a la aplicación, no a un documento específico. Puede crear paneles de tareas personalizados en complementos de VSTO para algunas aplicaciones de Microsoft Office. Para obtener más información, consulte Paneles de tareas personalizados.

Mostrar el panel de acciones

El panel de acciones se representa mediante la clase ActionsPane. Cuando crea un proyecto de nivel de documento, una instancia de esta clase está disponible para el código mediante el uso del campo ActionsPane de la clase ThisWorkbook (para Excel) o ThisDocument (para Word) en el proyecto. Para mostrar el panel de acciones, agregue un control de Windows Forms a la propiedad Controls del campo ActionsPane. En el siguiente ejemplo de código se agrega un control denominado actions al panel de acciones.

this.ActionsPane.Controls.Add(actions);

El panel de acciones se vuelve visible en tiempo de ejecución en cuanto se agrega explícitamente un control. Una vez que se muestre el panel de acciones, puede agregar o quitar controles de forma dinámica en respuesta a las acciones del usuario. Normalmente debe agregar el código para mostrar el panel de acciones en el controlador de eventos Startup de ThisDocument o ThisWorkbook para que el panel de acciones esté visible cuando el usuario abra el documento por primera vez. Sin embargo, puede que le interese mostrar el panel de acciones solo como respuesta a una acción del usuario en el documento. Por ejemplo, podría agregar código para el evento Click de un control en el documento.

Agregar varios controles al panel de acciones

Al agregar varios controles al panel de acciones, debe agrupar los controles en un control de usuario y, a continuación, agregar el control de usuario a la Controls propiedad . Este proceso incluye los siguientes pasos:

  1. Cree la interfaz de usuario (UI) del panel de acciones agregando un elemento Control de panel de acciones o Control de usuario al proyecto. Ambos elementos incluyen una clase UserControl de Windows Forms personalizada. Los elementos Control de panel de acciones y Control de usuario son equivalentes; la única diferencia es su nombre.

  2. Agregue controles de Windows Forms al UserControl mediante el diseñador o escribiendo código.

    Nota:

    También puede agregar controles WPF al panel de acciones agregando un WPF UserControl al UserControl de Windows Forms. Para obtener más información, vea Usar controles WPF en soluciones de Office.

  3. Agregue una instancia del control de usuario personalizado a los controles contenidos en el campo ActionsPane de la clase ThisWorkbook (para Excel) o ThisDocument (para Word) en el proyecto.

    Para obtener ejemplos que muestran este proceso con más detalle, vea Cómo: Agregar un panel de acciones a documentos de Word o libros de Excel.

Ocultar el panel de acciones

Aunque la clase ActionsPane tiene un método Hide y una propiedad Visible, no puede quitar el panel de acciones de la interfaz de usuario utilizando ningún miembro de la propia clase ActionsPane. Al llamar al Hide método o establecer la Visible propiedad en false , solo se ocultan los controles del panel de acciones; no oculta el panel de tareas.

Para ocultar el panel de tareas en la solución, tiene varias opciones:

  • Para Word, establezca la Visible propiedad del TaskPane objeto que representa el panel de tareas Acciones de documento en false. El siguiente ejemplo de código está diseñado para ejecutarse desde la clase ThisDocument del proyecto.

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

  • En Excel, establezca la DisplayDocumentActionTaskPane propiedad del Application objeto en false. El siguiente ejemplo de código está diseñado para ejecutarse desde la clase ThisWorkbook del proyecto.

    this.Application.DisplayDocumentActionTaskPane = false;

  • Para Word o Excel, también puede establecer la Visible propiedad de la barra de comandos que representa el panel de tareas en false. El siguiente ejemplo de código está diseñado para ejecutarse desde la clase ThisDocument o ThisWorkbook del proyecto.

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

Borrar el panel de acciones cuando se abre el documento

Cuando un usuario guarda el documento mientras el panel de acciones está visible, el panel de acciones está visible cada vez que se abre el documento, independientemente de que el panel de acciones contenga controles o no. Si desea controlar cuando se muestra, llame al método Clear del campo ActionsPane en el controlador de eventos Startup de ThisDocument o ThisWorkbook para asegurarse de que el panel de acciones no esté visible cuando se abra el documento.

Determinar cuándo se cierra el panel de acciones

No se genera ningún evento cuando se cierra el panel de acciones. Aunque la clase ActionsPane tiene un evento VisibleChanged, este evento no se genera cuando el usuario final cierra el panel de acciones. En su lugar, este evento se genera cuando los controles del panel de acciones están ocultos llamando al Hide método o estableciendo la Visible propiedad en false.

Cuando el usuario cierra el panel de acciones, el usuario puede volver a mostrarlo realizando uno de los procedimientos siguientes en la interfaz de usuario (UI) de la aplicación.

Para mostrar el panel de acciones mediante la interfaz de usuario de Word o Excel

  1. En la cinta de opciones, haga clic en la pestaña Ver .

  2. En el grupo Mostrar u ocultar, haga clic en el botón de alternancia Acciones del documento.

Eventos del panel acciones del programa

Puede agregar varios controles de usuario al panel de acciones y, a continuación, escribir código para responder a eventos en el documento mostrando y ocultando los controles de usuario. Si asigna elementos de esquema XML a su documento, puede mostrar determinados controles de usuario en el panel de acciones siempre que el punto de inserción esté dentro de uno de los elementos XML. Para obtener más información, vea Cómo: Asignar esquemas a documentos de Word dentro de Visual Studio y Cómo: Asignar esquemas a hojas de cálculo dentro de Visual Studio.

También puede escribir código para responder a los eventos de cualquier objeto, incluyendo eventos de control host, aplicación o documento. Para obtener más información, vea Tutorial: Programa con eventos de un control NamedRange.

Enlace de datos a controles en el panel de acciones

Los controles del panel de acciones tienen las mismas capacidades de enlace de datos que los controles de Windows Forms. Puede enlazar los controles a orígenes de datos, como conjuntos de datos, conjuntos de datos con tipo y XML. Para obtener más información, consulte Enlace de datos y Formularios Windows Forms.

Puede enlazar controles en el panel de acciones y controles en el documento al mismo conjunto de datos. Por ejemplo, puede crear una relación maestro y detalles entre los controles del panel de acciones y los controles de la hoja de cálculo. Para obtener más información, vea Tutorial: Enlazar datos a controles en un panel de acciones de Excel.

Validar datos en controles de panel de acciones

Si se muestra un cuadro de mensaje en el controlador de eventos Validating de un control en el panel de acciones, el evento podría generarse una segunda vez al pasar el foco del control al cuadro de mensaje. Para evitar este problema, utilice un control ErrorProvider para mostrar cualquier mensaje de error de validación.

Orden de apilamiento de control de usuario

Si está utilizando varios controles de usuario, puede escribir código para apilar correctamente los controles de usuario en el panel de acciones, independientemente de que esté acoplado vertical u horizontalmente. Puede establecer el orden de apilamiento de los controles de usuario en el panel de acciones mediante la enumeración StackStyle de la propiedad StackOrder. Para obtener más información, vea How to: Manage control layout on actions panes .How to: Manage control layout on actions panes.

La propiedad StackOrder puede tomar los siguientes StackStyle valores de enumeración.

Estilo de apilamiento Definición
FromBottom Apilar desde la parte inferior del panel de acciones.
FromLeft Apilar desde la parte izquierda del panel de acciones.
FromRight Apilar desde la parte derecha del panel de acciones.
FromTop Apilar desde la parte superior del panel de acciones.
None Sin orden de apilamiento definido; el desarrollador controla el orden.

El código siguiente establece la propiedad StackOrder para que apile los controles de usuario desde la parte superior del panel de acciones.

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

Controles de anclaje

Si el usuario cambia el tamaño del panel de acciones en tiempo de ejecución, los controles pueden cambiar el tamaño con el panel de acciones. Puede utilizar la propiedad Anchor de un control de Windows Forms para anclar los controles al panel de acciones. También puede anclar de la misma manera los controles de Windows Forms al control de usuario. Para obtener más información, vea Cómo: Delimitar controles en formularios Windows Forms.

Cambiar el tamaño del panel de acciones

No puede cambiar directamente el tamaño de un ActionsPane porque ActionsPane está incrustado en el panel de tareas. Sin embargo, puede cambiar el ancho del panel de tareas mediante programación estableciendo la propiedad Width de la CommandBar que representa el panel de tareas. Puede cambiar la altura del panel de tareas si está acoplado horizontalmente o si está flotando.

No se recomienda cambiar el tamaño del panel de tareas mediante programación porque el usuario debe poder seleccionar el tamaño del panel de tareas que mejor se adapte a sus necesidades. Sin embargo, si tiene que cambiar el ancho del panel de tareas, podría utilizar el siguiente código para hacerlo.

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

Cambiar la posición del panel de acciones

No puede cambiar directamente la posición del ActionsPane porque está incrustado en el panel de tareas. Sin embargo, puede mover el panel de tareas mediante programación estableciendo la propiedad Position de la CommandBar que representa el panel de tareas.

No se recomienda cambiar la posición del panel de tareas mediante programación porque el usuario debe poder elegir la posición del panel de tareas en la pantalla que mejor se adapte a sus necesidades. Sin embargo, si tiene que mover el panel de tareas hasta una posición concreta, podría utilizar el siguiente código para hacerlo.

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

Nota:

Los usuarios finales pueden cambiar manualmente la posición del panel de tareas en cualquier momento. No hay ninguna manera de garantizar que el panel de tareas permanezca acoplado en la posición que indique mediante programación. Sin embargo, puede comprobar los cambios de orientación y asegurarse de que los controles del panel de acciones se apilen en la dirección correcta. Para obtener más información, vea How to: Manage control layout on actions panes .How to: Manage control layout on actions panes.

Establecer las Top propiedades y Left de ActionsPane no cambia su posición porque el ActionsPane objeto está incrustado en el panel de tareas.

Si el panel de tareas no está acoplado, puede establecer las propiedades Top y Left de CommandBar que representa el panel de tareas. El siguiente código mueve un panel de tareas desacoplado a la esquina superior izquierda del documento.

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

Contenido relacionado