En esta página

Ejemplo de columna congelada

Este ejemplo muestra cómo congelar una columna dentro de una tabla de datos ( QTableView).

Aplicación en la que se muestra una columna congelada en una tabla

Utilizamos el marco de trabajo «modelo/vista» de Qt para implementar una tabla con su primera columna congelada. Esta técnica se puede aplicar a varias columnas o filas, siempre que se encuentren en los bordes de la tabla.

El marco de trabajo «modelo/vista» permite mostrar un mismo modelo de diferentes maneras utilizando múltiples vistas. Para este ejemplo, utilizamos dos vistas sobre el mismo modelo: dos « table views » que comparten un mismo modelo. La columna congelada es un elemento secundario de la «tableview» principal, y conseguimos el efecto visual deseado mediante una técnica de superposición que se describirá paso a paso en las siguientes secciones.

La disposición de la vista de tabla, los encabezados y las barras de desplazamiento

Definición de la clase `FreezeTableWidget`

La clase ` FreezeTableWidget ` tiene un constructor y un destructor. Además, cuenta con dos miembros privados: la vista de tabla que utilizaremos como superposición y el modelo compartido por ambas vistas de tabla. Se añaden dos ranuras para ayudar a mantener sincronizados los tamaños de las secciones, así como una función para reajustar la geometría de la columna congelada. Además, reimplementamos dos funciones: ` resizeEvent()` y ` moveCursor()`.

class FreezeTableWidget : public QTableView {
     Q_OBJECT

public:
      FreezeTableWidget(QAbstractItemModel * model);
      ~FreezeTableWidget();

protected:
      void resizeEvent(QResizeEvent *event) override;
      QModelIndex moveCursor(CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override;
      void scrollTo (const QModelIndex & index, ScrollHint hint = EnsureVisible) override;

private:
      QTableView *frozenTableView;
      void init();
      void updateFrozenTableGeometry();

private slots:
      void updateSectionWidth(int logicalIndex, int oldSize, int newSize);
      void updateSectionHeight(int logicalIndex, int oldSize, int newSize);

};

Nota: ` QAbstractItemView ` es el antecesor de ` QTableView`.

Implementación de la clase `FreezeTableWidget`

El constructor toma model como argumento y crea una vista de tabla que utilizaremos para mostrar la columna congelada. A continuación, dentro del constructor, invocamos la función init() para configurar la columna congelada. Por último, conectamos las señales « QHeaderView::sectionResized()» (para los encabezados horizontales y verticales) a las ranuras correspondientes. Esto garantiza que las secciones de nuestra columna congelada estén sincronizadas con los encabezados. También conectamos entre sí las barras de desplazamiento verticales para que la columna congelada se desplace verticalmente junto con el resto de nuestra tabla.

FreezeTableWidget::FreezeTableWidget(QAbstractItemModel * model)
{
      setModel(model);
      frozenTableView = new QTableView(this);

      init();

      //connect the headers and scrollbars of both tableviews together
      connect(horizontalHeader(),&QHeaderView::sectionResized, this,
              &FreezeTableWidget::updateSectionWidth);
      connect(verticalHeader(),&QHeaderView::sectionResized, this,
              &FreezeTableWidget::updateSectionHeight);

      connect(frozenTableView->verticalScrollBar(), &QAbstractSlider::valueChanged,
              verticalScrollBar(), &QAbstractSlider::setValue);
      connect(verticalScrollBar(), &QAbstractSlider::valueChanged,
              frozenTableView->verticalScrollBar(), &QAbstractSlider::setValue);

}

En la función ` init() `, nos aseguramos de que la vista de tabla superpuesta responsable de mostrar la columna congelada esté configurada correctamente. Esto significa que esta vista de tabla, ` frozenTableView`, debe tener el mismo modelo que la vista de tabla principal. Sin embargo, la diferencia aquí es que la única columna visible de ` frozenTableView` es su primera columna; ocultamos las demás utilizando ` setColumnHidden()`.

void FreezeTableWidget::init()
{
      frozenTableView->setModel(model());
      frozenTableView->setFocusPolicy(Qt::NoFocus);
      frozenTableView->verticalHeader()->hide();
      frozenTableView->horizontalHeader()->setSectionResizeMode(QHeaderView::Fixed);

      viewport()->stackUnder(frozenTableView);

En cuanto al orden Z de la columna congelada, la colocamos encima del área de visualización. Esto se consigue llamando a stackUnder() en el área de visualización. Por motivos estéticos, evitamos que la columna le quite el foco a la vista de tabla principal. Además, nos aseguramos de que ambas vistas compartan el mismo modelo de selección, de modo que solo se pueda seleccionar una celda a la vez. Se realizan algunos ajustes más para que nuestra aplicación tenga un buen aspecto y se comporte de forma coherente con la vista de tabla principal. Ten en cuenta que hemos llamado a ` updateFrozenTableGeometry() ` para que la columna ocupe la posición correcta.

      frozenTableView->setStyleSheet("QTableView { border: none;"
                                     "background-color: #8EDE21;"
                                     "selection-background-color: #999}"); //for demo purposes
      frozenTableView->setSelectionModel(selectionModel());
      for (int col = 1; col < model()->columnCount(); ++col)
            frozenTableView->setColumnHidden(col, true);

      frozenTableView->setColumnWidth(0, columnWidth(0) );

      frozenTableView->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
      frozenTableView->setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
      frozenTableView->show();

      updateFrozenTableGeometry();

      setHorizontalScrollMode(ScrollPerPixel);
      setVerticalScrollMode(ScrollPerPixel);
      frozenTableView->setVerticalScrollMode(ScrollPerPixel);
}

Al cambiar el tamaño de la columna congelada, la misma columna de la vista de tabla principal debe adaptarse en consecuencia para garantizar una integración perfecta. Esto se consigue obteniendo el nuevo tamaño de la columna a partir del valor de « newSize » de la señal « sectionResized()», emitida tanto por el encabezado horizontal como por el vertical.

void FreezeTableWidget::updateSectionWidth(int logicalIndex, int /* oldSize */, int newSize)
{
      if (logicalIndex == 0){
            frozenTableView->setColumnWidth(0, newSize);
            updateFrozenTableGeometry();
      }
}

void FreezeTableWidget::updateSectionHeight(int logicalIndex, int /* oldSize */, int newSize)
{
      frozenTableView->setRowHeight(logicalIndex, newSize);
}

Dado que se modifica el ancho de la columna congelada, ajustamos la geometría del widget en consecuencia invocando a ` updateFrozenTableGeometry()`. Esta función se explica con más detalle a continuación.

En nuestra reimplementación de ` QTableView::resizeEvent()`, llamamos a ` updateFrozenTableGeometry() ` tras invocar la implementación de la clase base.

void FreezeTableWidget::resizeEvent(QResizeEvent * event)
{
      QTableView::resizeEvent(event);
      updateFrozenTableGeometry();
 }

Al navegar por la tabla con el teclado, debemos asegurarnos de que la selección actual no desaparezca detrás de la columna congelada. Para sincronizar esto, reimplementamos QTableView::moveCursor() y ajustamos las posiciones de las barras de desplazamiento si es necesario, tras llamar a la implementación de la clase base.

QModelIndex FreezeTableWidget::moveCursor(CursorAction cursorAction,
                                          Qt::KeyboardModifiers modifiers)
{
      QModelIndex current = QTableView::moveCursor(cursorAction, modifiers);

      if (cursorAction == MoveLeft && current.column() > 0
              && visualRect(current).topLeft().x() < frozenTableView->columnWidth(0) ){
            const int newValue = horizontalScrollBar()->value() + visualRect(current).topLeft().x()
                                 - frozenTableView->columnWidth(0);
            horizontalScrollBar()->setValue(newValue);
      }
      return current;
}

El cálculo de la geometría de la columna congelada se basa en la geometría de la tabla subyacente, por lo que siempre aparece en el lugar correcto. El uso de la función QFrame::frameWidth() ayuda a calcular esta geometría correctamente, independientemente del estilo que se utilice. Nos basamos en la geometría de la ventana de visualización y de los encabezados para establecer los límites de la columna congelada.

void FreezeTableWidget::updateFrozenTableGeometry()
{
      frozenTableView->setGeometry(verticalHeader()->width() + frameWidth(),
                                   frameWidth(), columnWidth(0),
                                   viewport()->height()+horizontalHeader()->height());
}

Proyecto de ejemplo en code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.