En esta página

Explorador del sistema de archivos

Una aplicación de escritorio en QML que utiliza controles personalizados de Qt Quick para mostrar archivos de texto de un sistema de archivos.

Una interfaz de usuario de explorador de sistemas de archivos

El ejemplo del Explorador del sistema de archivos utiliza un diseño moderno que consta de tres componentes principales: una barra lateral basada en iconos a la izquierda, un « TreeView » redimensionable que muestra el sistema de archivos desde un « QFileSystemModel », y el « TextArea » que muestra los archivos de texto seleccionados. Los controles rápidos personalizados y las ventanas sin marcos, con decoraciones de ventana especializadas, garantizan una apariencia y un comportamiento uniformes en todos los sistemas operativos. Al iniciar esta aplicación desde la línea de comandos, se puede especificar un directorio inicial como parámetro. Este directorio inicial será utilizado por el « TreeView » para establecer el punto de partida para mostrar la estructura de directorios.

Ejecución del ejemplo

Puede ejecutar el ejemplo desde:

Diseño y estructura modernos

Para empezar, el ejemplo proporciona los colores a través de un objeto QML de tipo singleton. El objetivo es garantizar un control estructurado sobre la apariencia de la aplicación.

pragma Singleton

QtObject {
    readonly property color background: "#292828"
    readonly property color surface1: "#171819"
    readonly property color surface2: "#090A0C"
    readonly property color text: "#D4BE98"
    readonly property color textFile: "#E1D2B7"
    readonly property color disabledText: "#2C313A"
    readonly property color selection: "#4B4A4A"
    readonly property color active: "#292828"
    readonly property color inactive: "#383737"
    readonly property color folder: "#383737"
    readonly property color icon: "#383737"
    readonly property color iconIndicator: "#D5B35D"
    readonly property color color1: "#A7B464"
    readonly property color color2: "#D3869B"
}

El ejemplo utiliza el indicador « FramelessWindowHint » dentro de ` ApplicationWindow ` para crear una decoración personalizada, en lugar de basarse en la decoración de ventanas del sistema operativo. Para lograr una interacción equivalente con la ventana, el ejemplo sobrescribe la propiedad ` contentItem ` del ` MenuBar ` personalizado y muestra texto informativo y opciones de interacción para arrastrar o cerrar la aplicación. Los componentes en línea simplifican este proceso.

            component InteractionButton: Rectangle {
                id: interactionButton

                signal action()
                property alias hovered: hoverHandler.hovered

                Layout.fillHeight: true
                Layout.preferredWidth: height

                color: hovered ? Colors.background : "transparent"
                HoverHandler {
                    id: hoverHandler
                }
                TapHandler {
                    id: tapHandler
                    onTapped: interactionButton.action()
                }
            }

            InteractionButton {
                id: minimize

                onAction: root.dragWindow.showMinimized()
                Rectangle {
                    anchors.centerIn: parent
                    color: parent.hovered ? Colors.iconIndicator : Colors.icon
                    height: 2
                    width: parent.height - 14
                }
            }

            InteractionButton {
                id: maximize
    ...

La barra lateral de la izquierda incluye botones de navegación marcables en la parte superior y botones de acción única en la parte inferior. Se utilizan un « ButtonGroup » y un contenedor para garantizar que solo haya una entrada activa en un momento dado. De este modo, es posible ofrecer diferentes vistas utilizando un alias de propiedad para la posición actual, junto con un « StackLayout ».

Esta técnica permite ampliar la funcionalidad añadiendo otro botón y el elemento correspondiente dentro del « StackLayout ».

                StackLayout {
                    anchors.fill: parent
                    currentIndex: sidebar.currentTabIndex

                    // Shows the help text.
                    Text {
                        text: qsTr("This example shows how to use and visualize the file system.\n\n"
                                 + "Customized Qt Quick Components have been used to achieve this look.\n\n"
                                 + "You can edit the files but they won't be changed on the file system.\n\n"
                                 + "Click on the folder icon to the left to get started.")
                        wrapMode: TextArea.Wrap
                        color: Colors.text
                    }

                    // Shows the files on the file system.
                    FileSystemView {
                        id: fileSystemView
                        color: Colors.surface1
                        onFileClicked: path => root.currentFilePath = path
                    }
                }

El « StackLayout » incluye, además de un texto informativo, el «FileSystemView». Este componente personalizado muestra archivos y carpetas y se rellena con datos procedentes de un modelo C++. A continuación, puedes seleccionar los archivos y leerlos según corresponda.

QString FileSystemModel::readFile(const QString &filePath)
{
    // Don't issue errors for an empty path, as the initial binding
    // will result in an empty path, and that's OK.
    if (filePath.isEmpty())
        return {};

    QFile file(filePath);

    if (file.size() >= 2'000'000)
        return tr("File size is too big.\nYou can read files up to %1 MB.").arg(2);

    static const QMimeDatabase db;
    const QMimeType mime = db.mimeTypeForFile(QFileInfo(file));

    // Check if the mimetype is supported and return the content.
    const auto mimeTypesForFile = mime.parentMimeTypes();
    for (const auto &m : mimeTypesForFile) {
        if (m.contains("text", Qt::CaseInsensitive)
                || mime.comment().contains("text", Qt::CaseInsensitive)) {
            if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
                return tr("Error opening the File!");

            QTextStream stream(&file);
            return stream.readAll();
        }
    }
    return tr("Filetype not supported!");
}

Al hacer clic con el botón derecho sobre una carpeta en el « TreeView », se abre una ventana emergente « Menu », que permite controlar la propiedad « rootIndex » del « TreeView ».

            MyMenu {
                id: contextMenu
                Action {
                    text: qsTr("Set as root index")
                    onTriggered: {
                        fileSystemTreeView.rootIndex = fileSystemTreeView.index(treeDelegate.row, 0)
                    }
                }
                Action {
                    text: qsTr("Reset root index")
                    onTriggered: fileSystemTreeView.rootIndex = undefined
                }
            }
        }

SplitView te permite compartir dinámicamente el espacio entre el « StackLayout » y el editor. El editor contiene el « TextArea », que muestra el archivo abierto y proporciona toda la funcionalidad necesaria para editar archivos de texto. Además, el editor muestra números de línea, que se pueden activar y desactivar en la opción « Menu ».

            Editor {
                id: editor
                showLineNumbers: root.showLineNumbers
                currentFilePath: root.currentFilePath
                SplitView.fillWidth: true
                SplitView.fillHeight: true
            }

Componentes personalizados

Para comprender mejor el proceso de personalización, consulta primero el artículo «Personalización de un control ». Este ejemplo utiliza componentes reutilizables y personalizados.

Por ejemplo, el componente MyMenu personaliza la propiedad background del Menú, la propiedad contentItem de su delegado y la propiedad background.

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

import QtQuick
import QtQuick.Controls.Basic
import FileSystemModule

Menu {
    id: root

    delegate: MenuItem {
        id: menuItem
        contentItem: Item {
            Text {
                anchors.verticalCenter: parent.verticalCenter
                anchors.left: parent.left
                anchors.leftMargin: 5

                text: menuItem.text
                color: enabled ? Colors.text : Colors.disabledText
            }
            Rectangle {
                id: indicator

                anchors.verticalCenter: parent.verticalCenter
                anchors.right: parent.right
                width: 6
                height: parent.height

                visible: menuItem.highlighted
                color: Colors.color2
            }
        }
        background: Rectangle {
            implicitWidth: 210
            implicitHeight: 35
            color: menuItem.highlighted ? Colors.active : "transparent"
        }
    }
    background: Rectangle {
        implicitWidth: 210
        implicitHeight: 35
        color: Colors.surface2
    }
}

Otro ejemplo es la personalización de ScrollIndicator dentro de FileSystemView, que utiliza animaciones personalizadas. En este caso, el ejemplo sobrescribe contentItem.

        ScrollIndicator.vertical: ScrollIndicator {
            active: true
            implicitWidth: 15

            contentItem: Rectangle {
                implicitWidth: 6
                implicitHeight: 6

                color: Colors.color1
                opacity: fileSystemTreeView.movingVertically ? 0.5 : 0.0

                Behavior on opacity {
                    OpacityAnimator {
                        duration: 500
                    }
                }
            }
        }

Versión en Python

Si te interesa la versión en Python de este ejemplo, puedes encontrarla aquí. En ella se muestra el uso de ` Qt for Python ` y se explica cómo se puede utilizar para crear la misma aplicación.

Además, hay disponible un tutorial detallado que ofrece instrucciones paso a paso sobre cómo ampliar este ejemplo con funciones adicionales. Este tutorial puede resultarte útil si deseas explorar y aprender más sobre cómo ampliar la funcionalidad existente del Explorador del sistema de archivos.

Archivos fuente

Proyecto de ejemplo en code.qt.io

Véase también Todos los ejemplos de Qt XML y Ejemplos de controles deQt Quick .

© 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.