PathView QML Type
Coloca los elementos proporcionados por el modelo a lo largo de una ruta. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- cacheItemCount : int
- count : int
- currentIndex : int
- currentItem : Item
- delegate : Component
- dragMargin : real
- dragging : bool
- flickDeceleration : real
- flicking : bool
- highlight : Component
- highlightItem : Item
- highlightMoveDuration : int
- highlightRangeMode : enumeration
- interactive : bool
- maximumFlickVelocity : real
- model : model
- movementDirection : enumeration
- moving : bool
- offset : real
- path : Path
- pathItemCount : int
- preferredHighlightBegin : real
- preferredHighlightEnd : real
- snapMode : enumeration
Propiedades adjuntas
- isCurrentItem : bool
- onPath : bool
- view : PathView
Señales
Métodos
- void decrementCurrentIndex()
- void incrementCurrentIndex()
- int indexAt(real x, real y)
- Item itemAt(real x, real y)
- Item itemAtIndex(int index)
- void positionViewAtIndex(int index, PositionMode mode)
Descripción detallada
Un PathView muestra datos de modelos creados a partir de tipos QML integrados, como ListModel y XmlListModel, o de clases de modelo personalizadas definidas en C++ que heredan de QAbstractListModel.
La vista cuenta con un ` model`, que define los datos que se van a mostrar, y un ` delegate`, que define cómo deben mostrarse dichos datos. Se crea una instancia de ` delegate ` para cada elemento de la ` path`. Los elementos pueden desplazarse con un movimiento rápido para moverlos a lo largo de la ruta.
Por ejemplo, si hay un modelo de lista simple definido en un archivo ContactModel.qml como este:
import QtQuick
ListModel {
ListElement {
name: "Bill Jones"
icon: "pics/qtlogo.png"
}
ListElement {
name: "Jane Doe"
icon: "pics/qtlogo.png"
}
ListElement {
name: "John Smith"
icon: "pics/qtlogo.png"
}
}Estos datos se pueden representar como un PathView, de la siguiente manera:
import QtQuick
Rectangle {
width: 240; height: 200
Component {
id: delegate
Column {
id: wrapper
required property url icon
required property string name
opacity: PathView.isCurrentItem ? 1 : 0.5
Image {
anchors.horizontalCenter: nameText.horizontalCenter
width: 64; height: 64
source: wrapper.icon
}
Text {
id: nameText
text: wrapper.name
font.pointSize: 16
}
}
}
PathView {
anchors.fill: parent
model: ContactModel {}
delegate: delegate
path: Path {
startX: 120; startY: 100
PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
}
}
}(Ten en cuenta que el ejemplo anterior utiliza PathAttribute para escalar y modificar la opacidad de los elementos a medida que giran. Este código adicional se puede consultar en la documentación de PathAttribute ).
PathView no gestiona automáticamente la navegación mediante el teclado. Esto se debe a que las teclas que se deben utilizar para la navegación dependerán de la forma de la ruta. La navegación se puede añadir de forma muy sencilla configurando focus como true y llamando a decrementCurrentIndex() o incrementCurrentIndex(), por ejemplo, para navegar utilizando las teclas de flecha izquierda y derecha:
PathView {
// ...
focus: true
Keys.onLeftPressed: decrementCurrentIndex()
Keys.onRightPressed: incrementCurrentIndex()
}La propia vista de ruta es un ámbito de foco (véase «Foco del teclado» en Qt Quick para obtener más detalles).
Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Nunca debe almacenarse el estado en un delegado.
PathView adjunta una serie de propiedades al elemento raíz del delegado, por ejemplo, PathView.isCurrentItem. En el siguiente ejemplo, el elemento raíz del delegado puede acceder a esta propiedad adjunta directamente como PathView.isCurrentItem, mientras que el objeto hijo nameText debe hacer referencia a esta propiedad como wrapper.PathView.isCurrentItem.
Component {
id: delegate
Column {
id: wrapper
required property url icon
required property string name
opacity: PathView.isCurrentItem ? 1 : 0.5
Image {
anchors.horizontalCenter: nameText.horizontalCenter
width: 64; height: 64
source: wrapper.icon
}
Text {
id: nameText
text: wrapper.name
font.pointSize: 16
}
}
}Ten en cuenta que las vistas no activan el recorte automáticamente. Si la vista no está recortada por otro elemento o por la pantalla, será necesario establecer `clip: true ` para que los elementos que quedan fuera de la vista se recorten correctamente.
Véase también Path, Modelos de datos de QML, ListView, GridView y Qt Quick Ejemplos: vistas.
Documentación de propiedades
cacheItemCount : int
Esta propiedad establece el número máximo de elementos que se pueden almacenar en caché fuera de la ruta.
Por ejemplo, un ` PathView ` con un modelo que contenga 20 elementos, un ` pathItemCount ` de 10 y un `cacheItemCount` de 4 creará hasta 14 elementos, de los cuales 10 serán visibles en la ruta y 4 serán elementos almacenados en caché invisibles.
Los delegados almacenados en caché se crean de forma asíncrona, lo que permite que la creación se produzca a lo largo de varios fotogramas y reduce la probabilidad de que se salten fotogramas.
Nota: Establecer esta propiedad no sustituye a la creación de delegados eficientes. Puede mejorar la fluidez del comportamiento de desplazamiento a costa de un mayor consumo de memoria. Cuantos menos objetos y enlaces haya en un delegado, más rápido se podrá desplazar una vista. Es importante tener en cuenta que establecer `cacheItemCount` solo pospondrá los problemas causados por delegados de carga lenta; no es una solución para este caso.
Véase también pathItemCount.
count : int [read-only]
Esta propiedad contiene el número de elementos del modelo.
currentIndex : int
Esta propiedad contiene el índice del elemento actual.
currentItem : Item [read-only]
Esta propiedad contiene el elemento actual de la vista.
delegate : Component
El delegado proporciona una plantilla que define cada elemento instanciado por la vista. El índice se expone como una propiedad accesible de tipo « index ». Las propiedades del modelo también están disponibles en función del tipo de modelo de datos.
El número de objetos y enlaces en el delegado tiene un efecto directo en el rendimiento del desplazamiento rápido de la vista cuando se especifica ` pathItemCount `. Si es posible, coloca la funcionalidad que no sea necesaria para la visualización normal del delegado en un ` Loader `, que puede cargar componentes adicionales cuando sea necesario.
Tenga en cuenta que el ` PathView ` distribuirá los elementos en función del tamaño del elemento raíz del delegado.
A continuación se muestra un ejemplo de delegado:
Component {
id: delegate
Column {
id: wrapper
required property url icon
required property string name
opacity: PathView.isCurrentItem ? 1 : 0.5
Image {
anchors.horizontalCenter: nameText.horizontalCenter
width: 64; height: 64
source: wrapper.icon
}
Text {
id: nameText
text: wrapper.name
font.pointSize: 16
}
}
}dragMargin : real
Esta propiedad indica la distancia máxima respecto a la ruta a partir de la cual se inicia el arrastre con el ratón.
Por defecto, la ruta solo se puede arrastrar haciendo clic en un elemento. Si dragMargin es mayor que cero, se puede iniciar el arrastre haciendo clic dentro de un margen de dragMargin píxeles respecto a la ruta.
dragging : bool [read-only]
Esta propiedad indica si la vista se está desplazando en ese momento porque el usuario la está arrastrando.
flickDeceleration : real
Esta propiedad determina la velocidad a la que se desacelerará un movimiento rápido.
El valor por defecto es 100.
flicking : bool [read-only]
Esta propiedad indica si la vista se está desplazando en ese momento debido a que el usuario ha deslizado el dedo sobre ella.
highlight : Component
Esta propiedad contiene el componente que se utilizará como resaltado.
Se creará una instancia del componente de resaltado para cada vista. La geometría de la instancia del componente resultante será gestionada por la vista para que permanezca junto al elemento actual.
El siguiente ejemplo muestra cómo crear un resaltado sencillo. Fíjate en el uso de la propiedad adjunta ` PathView.onPath ` para garantizar que el resaltado quede oculto cuando se deslice fuera de la ruta.
Véase también « highlightItem » y « highlightRangeMode ».
highlightItem : Item [read-only]
highlightItem contiene el elemento destacado, que se ha creado a partir del componente highlight.
Véase también highlight.
highlightMoveDuration : int
Esta propiedad define la duración de la animación de movimiento del delegado de resaltado.
Si la propiedad « highlightRangeMode » tiene el valor «StrictlyEnforceRange», esta propiedad determina la velocidad a la que los elementos se desplazan a lo largo de la ruta.
El valor predeterminado de la duración es 300 ms.
Estas propiedades establecen el rango preferido de la selección (elemento actual) dentro de la vista. Los valores preferidos deben estar comprendidos entre 0 y 1.
Los valores válidos para highlightRangeMode son:
| Constante | Descripción |
|---|---|
PathView.NoHighlightRange | no se aplica ningún rango: el elemento resaltado se moverá libremente dentro de la vista. |
PathView.ApplyRange | La vista intentará mantener el resaltado dentro del rango; sin embargo, este puede salirse del rango en los extremos de la ruta o debido a una interacción con el ratón. |
PathView.StrictlyEnforceRange | El resaltado nunca se moverá fuera del rango. Esto significa que el elemento actual cambiará si una acción del teclado o del ratón provoca que el resaltado se mueva fuera del rango. |
El valor por defecto es PathView.StrictlyEnforceRange.
Definir un rango de resaltado es la forma correcta de influir en la posición en la que queda el elemento actual cuando se desplaza la vista. Por ejemplo, si quieres que el elemento seleccionado actualmente se encuentre en el centro de la ruta, establece el rango de resaltado en 0,5;0,5 y « highlightRangeMode » en PathView.StrictlyEnforceRange. De este modo, cuando la ruta se desplace, el elemento seleccionado actualmente será el que se encuentre en esa posición. Esto también se aplica cuando cambia el elemento seleccionado actualmente: se desplazará hasta situarse dentro del rango de resaltado preferido. Además, el comportamiento del índice del elemento actual se producirá independientemente de si existe o no un resaltado.
Nota: Para queun rango sea válido, « preferredHighlightEnd » debe ser mayor o igual que « preferredHighlightBegin ».
interactive : bool
Un usuario no puede arrastrar ni deslizar con un movimiento rápido un elemento « PathView » que no sea interactivo.
Esta propiedad resulta útil para desactivar temporalmente el deslizamiento. Esto permite una interacción especial con los elementos secundarios de « PathView ».
maximumFlickVelocity : real
Esta propiedad indica la velocidad máxima aproximada, en píxeles por segundo, a la que el usuario puede desplazar rápidamente la vista.
El valor por defecto depende de la plataforma.
model : model
Esta propiedad contiene el modelo que proporciona datos a la vista.
El modelo proporciona un conjunto de datos que se utiliza para crear los elementos de la vista. En el caso de conjuntos de datos grandes o dinámicos, el modelo suele proporcionarse mediante un objeto de modelo en C++. Los modelos también se pueden crear directamente en QML, utilizando el tipo ` ListModel `.
Nota: al modificar el modelo, el desplazamiento y el ` currentIndex ` se restablecerán a 0.
Véase también Modelos de datos.
movementDirection : enumeration
Esta propiedad determina la dirección en la que se desplazan los elementos al establecer el índice actual. Los valores posibles son:
| Constante | Descripción |
|---|---|
PathView.Shortest | (por defecto) los elementos se desplazan en la dirección que requiere el menor movimiento, que puede ser « Negative » o « Positive ». |
PathView.Negative | Los elementos se desplazan hacia atrás, en dirección a su destino. |
PathView.Positive | Los elementos se desplazan hacia delante, en dirección a su destino. |
Por ejemplo, supongamos que hay 5 elementos en el modelo y que currentIndex es 0. Si currentIndex se establece en 2,
- una dirección de movimiento de «
Positive» dará como resultado el siguiente orden: 0, 1, 2 - una dirección de movimiento «
Negative» dará como resultado el siguiente orden: 0, 5, 4, 3, 2 - una dirección de movimiento «
Shortest» dará como resultado el mismo orden que «Positive».
Nota: esta propiedad no afecta al movimiento de « incrementCurrentIndex()» ni de « decrementCurrentIndex()».
moving : bool [read-only]
Esta propiedad indica si la vista se está desplazando en ese momento debido a que el usuario la está arrastrando o deslizando con un movimiento rápido.
offset : real
El desplazamiento especifica la distancia a la que se encuentran los elementos a lo largo de la trayectoria respecto a sus posiciones iniciales. Se trata de un número real que oscila entre 0 y el número de elementos del modelo.
path : Path
Esta propiedad contiene la ruta utilizada para organizar los elementos. Para obtener más información, consulta la documentación de « Path ».
pathItemCount : int
Esta propiedad almacena el número de elementos visibles en la ruta en un momento dado.
Si se establece «pathItemCount» en «undefined», se mostrarán todos los elementos de la ruta.
snapMode : enumeration
Esta propiedad determina cómo se colocarán los elementos tras un arrastre o un movimiento rápido. Los valores posibles son:
| Constante | Descripción |
|---|---|
PathView.NoSnap | (por defecto) los elementos se detienen en cualquier punto de la trayectoria. |
PathView.SnapToItem | Los elementos se colocan de forma que uno de ellos quede alineado con el « preferredHighlightBegin ». |
PathView.SnapOneItem | Los elementos se colocan a una distancia máxima de un elemento respecto al elemento más cercano a la « preferredHighlightBegin » en el momento en que se suelta la pulsación. Este modo resulta especialmente útil para desplazarse página a página. |
snapMode No afecta a la « currentIndex ». Para actualizar la « currentIndex » a medida que se desplaza la vista, establezca « highlightRangeMode » en « PathView.StrictlyEnforceRange » (valor por defecto para « PathView »).
Véase también highlightRangeMode.
Documentación sobre propiedades adjuntas
PathView.isCurrentItem : bool [read-only attached]
Esta propiedad adjunta devuelve «true» si este delegado es el elemento actual; en caso contrario, devuelve «false».
Se asocia a cada instancia del delegado.
Esta propiedad se puede utilizar para ajustar la apariencia del elemento actual.
Component {
id: delegate
Column {
id: wrapper
required property url icon
required property string name
opacity: PathView.isCurrentItem ? 1 : 0.5
Image {
anchors.horizontalCenter: nameText.horizontalCenter
width: 64; height: 64
source: wrapper.icon
}
Text {
id: nameText
text: wrapper.name
font.pointSize: 16
}
}
}PathView.onPath : bool [read-only attached]
Esta propiedad adjunta indica si el elemento se encuentra actualmente en la ruta.
Si se ha establecido un « pathItemCount », es posible que algunos elementos estén instanciados, pero no se consideren que se encuentren actualmente en la ruta. Por lo general, estos elementos se marcarían como invisibles, por ejemplo:
Se adjunta a cada instancia del delegado.
PathView.view : PathView [read-only attached]
Esta propiedad asociada contiene la vista que gestiona esta instancia del delegado.
Se adjunta a cada instancia del delegado.
Documentación de Signal
dragEnded()
Esta señal se emite cuando el usuario deja de arrastrar la vista.
Si la velocidad del arrastre es suficiente en el momento en que se suelta el toque o el botón del ratón, se iniciará un movimiento rápido.
Nota: El controlador correspondiente es onDragEnded.
dragStarted()
Esta señal se emite cuando la vista comienza a arrastrarse debido a la interacción del usuario.
Nota: El controlador correspondiente es onDragStarted.
flickEnded()
Esta señal se emite cuando la vista deja de moverse debido a un movimiento rápido.
Nota: El controlador correspondiente es onFlickEnded.
flickStarted()
Esta señal se emite cuando se realiza un movimiento rápido con el ratón o el dedo sobre la vista. Un movimiento rápido comienza en el momento en que se suelta el ratón o se retira el dedo, mientras aún se encuentra en movimiento.
Nota: El controlador correspondiente es onFlickStarted.
movementEnded()
Esta señal se emite cuando la vista deja de moverse debido a la interacción del usuario. Si se ha generado un «flick», esta señal se emitirá una vez que el «flick» se detenga. Si no se ha generado ningún «flick», esta señal se emitirá cuando el usuario deje de arrastrar, es decir, al soltar el ratón o el dedo.
Nota: El controlador correspondiente es onMovementEnded.
movementStarted()
Esta señal se emite cuando la vista comienza a moverse como consecuencia de la interacción del usuario.
Nota: El controlador correspondiente es onMovementStarted.
Documentación del método
void decrementCurrentIndex()
Disminuye el índice actual.
Nota: los métodos solo deben invocarse una vez que el componente haya finalizado.
void incrementCurrentIndex()
Aumenta el índice actual.
Nota: los métodos solo deben invocarse una vez que el componente haya finalizado.
int indexAt(real x, real y)
Devuelve el índice del elemento que contiene el punto x, y en coordenadas de contenido. Si no hay ningún elemento en el punto especificado, se devuelve -1.
Nota: los métodos solo deben invocarse una vez que el componente se haya completado.
Item itemAt(real x, real y)
Devuelve el elemento que contiene el punto x, y en coordenadas de contenido. Si no hay ningún elemento en el punto especificado, se devuelve «null».
Nota: los métodos solo deben invocarse una vez que el componente se haya completado.
Item itemAtIndex(int index)
Devuelve el elemento correspondiente a index. Si no existe ningún elemento para ese índice —por ejemplo, porque aún no se ha creado o porque se ha desplazado fuera del área visible y se ha eliminado de la caché—, se devuelve null.
Nota: este método solo debe invocarse una vez que el componente haya finalizado su ejecución. Tampoco debe almacenarse el valor devuelto, ya que puede pasar a ser `null` en cuanto el control salga del ámbito de la llamada, si la vista libera dicho elemento.
void positionViewAtIndex(int index, PositionMode mode)
Coloca la vista de tal forma que el punto de vista ( index ) se sitúe en la posición especificada por el punto de vista ( mode):
| Constante | Descripción |
|---|---|
PathView.Beginning | elemento de posición al inicio de la ruta. |
PathView.Center | elemento de posición en el centro de la ruta. |
PathView.End | elemento de posición al final de la ruta. |
PathView.Contain | Asegura que el elemento se sitúe en la ruta. |
PathView.SnapPosition | Coloca el elemento en preferredHighlightBegin. Este modo solo es válido si highlightRangeMode es StrictlyEnforceRange o si el ajuste está habilitado mediante snapMode. |
Nota: los métodos solo deben llamarse una vez que el componente haya finalizado. Para colocar la vista al inicio, este método debe ser llamado por `Component.onCompleted`. Por ejemplo, para colocar la vista al final:
Component.onCompleted: positionViewAtIndex(count - 1, PathView.End)© 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.