Perspectiva 3D (Spatial)
SpatialView Vista espacial
Aplica perspectiva e inclinación según el puntero a los widgets existentes. Mantén la edición de texto y los elementos emergentes en el diseño normal; no se pueden incrustar hijos de ventana nativa ni OpenGL.
Ejemplo
No se pudo cargar la vista previa de propiedades. Selecciona Vista previa de propiedades para reintentar.

Uso
Perspectiva de escena
Ajusta la cámara y el zoom, luego mueve el puntero sobre las tarjetas.
#include <FluentQt/Spatial.h>
using namespace fluent::spatial;
using namespace fluent;
// The two cards keep their own poses while the view changes the whole scene.
class SceneView final : public spatial::SpatialView {
public:
using SpatialView::SpatialView;
void arrange()
{
if (itemCount() != 2)
return;
const float spread = width() < 650 ? 24 : 100;
items().first()->setPosition(QVector3D(-spread, -44, -160));
items().last()->setPosition(QVector3D(spread, 44, 160));
}
protected:
void resizeEvent(QResizeEvent* event) override
{
SpatialView::resizeEvent(event);
arrange();
}
};
auto* panel = new SpatialPreviewPanel(parent);
auto* column = new QVBoxLayout(panel);
column->setContentsMargins(0, 0, 0, 0);
column->setSpacing(16);
auto* session = new spatial::SpatialSession(panel, panel);
const bool active = session->activate();
auto* view = new SceneView(panel);
if (!active || !session->attachView(view)) {
view->setSpatialEnabled(false);
view->setRenderMode(spatial::SpatialView::RenderMode::Raster);
}
view->setObjectName("spatialPreviewView");
view->setFixedHeight(400);
view->setCameraDistance(1200);
view->setZoom(0.9);
view->setMaximumTilt(QPointF(6, 12));
// Response time (140 ms), animation limit (60 fps), cache and Auto renderer use UILib defaults.
// See SpatialView.h for the full parameter contract.
// Both layers use the same size and data, making perspective easy to compare.
const auto makeLayer = [](const QString& title, const QString& caption) {
auto* card = new layout::Card;
card->setFixedSize(220, 150);
auto* content = new QVBoxLayout(card);
content->setContentsMargins(16, 12, 16, 12);
content->setSpacing(6);
auto* heading = new textfields::Label(title, card);
heading->setFluentTypography(Typography::FontRole::Subtitle);
heading->setTextColorRole(textfields::Label::TextColorRole::Primary);
content->addWidget(heading);
auto* chart = new charts::Sparkline(card);
chart->setAccessibleName(title + " sample chart");
auto* model = new charts::ChartModel(card);
model->setPoints({{0, 12}, {1, 24}, {2, 18}, {3, 38}, {4, 32}, {5, 54}});
chart->setModel(model);
content->addWidget(chart, 1);
auto* note = new textfields::Label(caption, card);
note->setTextColorRole(textfields::Label::TextColorRole::Secondary);
content->addWidget(note);
return card;
};
spatial::SpatialItem* back = view->addWidget(
makeLayer("Back layer", "Z -160 · sample data"), WidgetOwnership::Owned);
spatial::SpatialItem* front = view->addWidget(
makeLayer("Front layer", "Z +160 · sample data"), WidgetOwnership::Owned);
back->setRotation(QVector3D(6, 16, 0));
front->setRotation(QVector3D(-6, -16, 0));
back->setSurfaceIntensity(0.75);
front->setSurfaceIntensity(0.75);
view->arrange();
auto* toolbar = new QHBoxLayout;
auto* follow = new basicinput::ToggleSwitch(panel);
follow->setObjectName("spatialViewFollow");
follow->setAccessibleName("Follow pointer");
follow->setOnContent("Follow pointer");
follow->setOffContent("Follow pointer");
follow->setIsOn(true);
toolbar->addWidget(follow);
toolbar->addStretch();
column->addLayout(toolbar);
column->addWidget(view);
// Keep view-wide controls outside the projection so their drag targets stay still.
auto* controls = new QWidget(panel);
controls->setObjectName("spatialViewControls");
auto* grid = new QGridLayout(controls);
grid->setContentsMargins(0, 0, 0, 0);
grid->setHorizontalSpacing(24);
grid->setVerticalSpacing(12);
grid->setColumnStretch(0, 1);
grid->setColumnStretch(1, 1);
const auto addSlider = [controls, grid](const QString& name, const QString& label,
const QString& unit, int minimum, int maximum,
int initial, int row, int col) {
auto* group = new QWidget(controls);
auto* layout = new QVBoxLayout(group);
layout->setContentsMargins(0, 0, 0, 0);
layout->setSpacing(4);
auto* text = new textfields::Label(group);
text->setTextColorRole(textfields::Label::TextColorRole::Primary);
auto* slider = new basicinput::Slider(group);
slider->setObjectName(name);
slider->setAccessibleName(label);
slider->setRange(minimum, maximum);
slider->setValue(initial);
const auto updateText = [text, label, unit](int value) {
text->setText(QString("%1: %2%3").arg(label).arg(value).arg(unit));
};
updateText(initial);
QObject::connect(slider, &basicinput::Slider::valueChanged, text, updateText);
layout->addWidget(text);
layout->addWidget(slider);
grid->addWidget(group, row, col);
return slider;
};
auto* distance = addSlider("spatialViewDistance", "Camera distance", " px",
650, 2400, 1200, 0, 0);
auto* zoom = addSlider("spatialViewZoom", "Scene zoom", "%", 50, 110, 90, 0, 1);
QObject::connect(distance, &basicinput::Slider::valueChanged, view,
[view](int value) { view->setCameraDistance(value); });
QObject::connect(zoom, &basicinput::Slider::valueChanged, view,
[view](int value) { view->setZoom(value / 100.0); });
column->addWidget(controls);
QObject::connect(follow, &basicinput::ToggleSwitch::toggled,
view, &spatial::SpatialView::setPointerTrackingEnabled);
QObject::connect(view, &spatial::SpatialView::pointerTrackingEnabledChanged,
follow, &basicinput::ToggleSwitch::setIsOn);
const auto updateAvailability = [view, controls, follow] {
controls->setEnabled(view->isSpatialEnabled());
follow->setEnabled(view->isSpatialEnabled());
};
QObject::connect(view, &spatial::SpatialView::spatialEnabledChanged, controls, updateAvailability);
updateAvailability();import fluentqt
from PySide6.QtCore import QEvent, QPointF
from PySide6.QtGui import QVector3D
from PySide6.QtWidgets import QGridLayout, QHBoxLayout, QVBoxLayout, QWidget
from fluentqt.spatial import SpatialSession, SpatialView
class SpatialPreviewPanel(QWidget):
def stop_spatial(self):
session = self.findChild(SpatialSession)
if session is not None:
session.deactivate()
def event(self, event):
# Stop before deleteLater dismantles this panel's widgets.
# Also call stop_spatial before disposing an enclosing window.
if event.type() == QEvent.DeferredDelete:
self.stop_spatial()
return super().event(event)
class SceneView(SpatialView):
def arrange(self):
if self.itemCount() == 2:
spread = 24 if self.width() < 650 else 100
self.items()[0].setPosition(QVector3D(-spread, -44, -160))
self.items()[-1].setPosition(QVector3D(spread, 44, 160))
def resizeEvent(self, event):
super().resizeEvent(event)
self.arrange()
panel = SpatialPreviewPanel()
column = QVBoxLayout(panel)
column.setContentsMargins(0, 0, 0, 0)
column.setSpacing(12)
session = SpatialSession(panel, panel)
spatial_attached = session.activate()
view = SceneView(panel)
spatial_attached = spatial_attached and session.attachView(view)
if not spatial_attached:
view.setRenderMode(SpatialView.RenderMode.Raster)
view.setSpatialEnabled(False)
view.setObjectName("spatialPreviewView")
view.setFixedHeight(400)
view.setCameraDistance(1200)
view.setMaximumTilt(QPointF(4, 6))
column.addWidget(view)
def add_slider(parent, layout, name, label, unit, minimum, maximum, initial):
in_grid = isinstance(layout, QGridLayout)
group = QWidget(parent) if in_grid else parent
column = QVBoxLayout(group) if in_grid else QVBoxLayout()
column.setContentsMargins(0, 0, 0, 0)
column.setSpacing(4)
text = fluentqt.Label(f"{label}: {initial}{unit}", group)
slider = fluentqt.Slider(group)
slider.setObjectName(name)
slider.setAccessibleName(label)
slider.setRange(minimum, maximum)
slider.setValue(initial)
slider.valueChanged.connect(
lambda value: text.setText(f"{label}: {value}{unit}")
)
column.addWidget(text)
column.addWidget(slider)
if isinstance(layout, QGridLayout):
layout.addWidget(group, 0, layout.count())
else:
layout.addLayout(column)
return slider
column.setSpacing(16)
view.setZoom(0.9)
view.setMaximumTilt(QPointF(6, 12))
def make_layer(title, caption):
card = fluentqt.Card()
card.setFixedSize(220, 150)
content = QVBoxLayout(card)
content.setContentsMargins(16, 12, 16, 12)
content.setSpacing(6)
heading = fluentqt.Label(title, card)
heading.setFluentTypography(fluentqt.FontRole.Subtitle)
content.addWidget(heading)
chart = fluentqt.Sparkline(card)
chart.setAccessibleName(title + " sample chart")
model = fluentqt.ChartModel(card)
model.setPoints([QPointF(x, y) for x, y in enumerate([12, 24, 18, 38, 32, 54])])
chart.setModel(model)
content.addWidget(chart, 1)
note = fluentqt.Label(caption, card)
note.setTextColorRole(fluentqt.Label.TextColorRole.Secondary)
content.addWidget(note)
card._model = model
return card
back = view.addOwnedWidget(make_layer("Back layer", "Z -160 · sample data"))
front = view.addOwnedWidget(make_layer("Front layer", "Z +160 · sample data"))
back.setRotation(QVector3D(6, 16, 0))
front.setRotation(QVector3D(-6, -16, 0))
back.setSurfaceIntensity(0.75)
front.setSurfaceIntensity(0.75)
view.arrange()
toolbar = QHBoxLayout()
follow = fluentqt.ToggleSwitch(panel)
follow.setObjectName("spatialViewFollow")
follow.setAccessibleName("Follow pointer")
follow.setOnContent("Follow pointer")
follow.setOffContent("Follow pointer")
follow.setIsOn(True)
toolbar.addWidget(follow)
toolbar.addStretch()
column.removeWidget(view)
column.addLayout(toolbar)
column.addWidget(view)
controls = QWidget(panel)
controls.setObjectName("spatialViewControls")
sliders = QGridLayout(controls)
sliders.setContentsMargins(0, 0, 0, 0)
sliders.setHorizontalSpacing(24)
sliders.setVerticalSpacing(12)
sliders.setColumnStretch(0, 1)
sliders.setColumnStretch(1, 1)
distance = add_slider(
controls,
sliders,
"spatialViewDistance",
"Camera distance",
" px",
650,
2400,
1200
)
zoom = add_slider(
controls,
sliders,
"spatialViewZoom",
"Scene zoom",
"%",
50,
110,
90
)
distance.valueChanged.connect(view.setCameraDistance)
zoom.valueChanged.connect(lambda value: view.setZoom(value / 100.0))
column.addWidget(controls)
follow.toggled.connect(view.setPointerTrackingEnabled)
view.pointerTrackingEnabledChanged.connect(follow.setIsOn)
def update_availability():
controls.setEnabled(view.isSpatialEnabled())
follow.setEnabled(view.isSpatialEnabled())
view.spatialEnabledChanged.connect(update_availability)
update_availability()API
DeclaraciónNo hay miembros de la API que coincidan.
fluent::spatial::SpatialView
Hereda de QWidget · FluentElement · QMLPlus
Contenedor de widgets compatible con transformaciones de perspectiva 3D mediante backends de OpenGL y rasterización por CPU. Recurre a un diseño vertical plano en 2D cuando se desactiva la perspectiva o se pulsa Tab / Esc para entrada y accesibilidad.
Constructores
Destructores
Enumeraciones
enum class RenderModeAutoRasterOpenGL
enum class BackendRasterOpenGL
Métodos
SpatialItem* addWidget(QWidget* widget, WidgetOwnership ownership = WidgetOwnership::Borrowed)Añade un widget a la vista 3D y devuelve su SpatialItem; ownership controla la limpieza al eliminarlo.
QWidget* takeWidget(SpatialItem* item)Desvincula el widget, elimina item y devuelve la propiedad del widget al llamador.
void releaseItem(SpatialItem* item)Quita el elemento y administra su widget según su configuración WidgetOwnership.
int itemCount() constNúmero de elementos actualmente en la vista.
bool isSpatialEnabled() constHabilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.
void setSpatialEnabled(bool enabled)Habilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.
qreal cameraDistance() constDistancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.
void setCameraDistance(qreal distance)Distancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.
qreal zoom() constFactor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.
void setZoom(qreal zoom)Factor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.
bool isPointerTrackingEnabled() constInclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.
void setPointerTrackingEnabled(bool enabled)Inclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.
QPointF maximumTilt() constInclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).
void setMaximumTilt(const QPointF& degrees)Inclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).
int responseTime() constConstante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.
void setResponseTime(int milliseconds)Constante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.
int maximumFrameRate() constLímite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.
void setMaximumFrameRate(int framesPerSecond)Límite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.
bool isCacheEnabled() constHabilita la caché fuera de pantalla para los elementos; true de forma predeterminada.
void setCacheEnabled(bool enabled)Habilita la caché fuera de pantalla para los elementos; true de forma predeterminada.
RenderMode renderMode() constBackend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).
void setRenderMode(RenderMode mode)Backend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).
Backend activeBackend() constBackend de renderizado activo actualmente (Raster u OpenGL).
QString rendererName() constNombre del renderizador OpenGL activo, o vacío al usar rasterización por CPU.
QString fallbackReason() constMotivo por el que OpenGL recurrió al renderizado por CPU, o vacío en caso contrario.
Propiedades
bool spatialEnabledHabilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.
LecturaisSpatialEnabled()EscriturasetSpatialEnabled()NotificaciónspatialEnabledChanged()qreal cameraDistanceDistancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.
LecturacameraDistance()EscriturasetCameraDistance()NotificacióncameraDistanceChanged()qreal zoomFactor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.
Lecturazoom()EscriturasetZoom()NotificaciónzoomChanged()bool pointerTrackingEnabledInclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.
LecturaisPointerTrackingEnabled()EscriturasetPointerTrackingEnabled()NotificaciónpointerTrackingEnabledChanged()QPointF maximumTiltInclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).
LecturamaximumTilt()EscriturasetMaximumTilt()NotificaciónmaximumTiltChanged()int responseTimeConstante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.
LecturaresponseTime()EscriturasetResponseTime()NotificaciónresponseTimeChanged()int maximumFrameRateLímite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.
LecturamaximumFrameRate()EscriturasetMaximumFrameRate()NotificaciónmaximumFrameRateChanged()bool cacheEnabledHabilita la caché fuera de pantalla para los elementos; true de forma predeterminada.
LecturaisCacheEnabled()EscriturasetCacheEnabled()NotificacióncacheEnabledChanged()RenderMode renderModeBackend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).
LecturarenderMode()EscriturasetRenderMode()NotificaciónrenderModeChanged()Backend activeBackendBackend de renderizado activo actualmente (Raster u OpenGL).
LecturaactiveBackend()NotificaciónrendererChanged()QString rendererNameNombre del renderizador OpenGL activo, o vacío al usar rasterización por CPU.
LecturarendererName()NotificaciónrendererChanged()QString fallbackReasonMotivo por el que OpenGL recurrió al renderizado por CPU, o vacío en caso contrario.
LecturafallbackReason()NotificaciónrendererChanged()int itemCountNúmero de elementos actualmente en la vista.
LecturaitemCount()NotificaciónitemCountChanged()
Señales
void spatialEnabledChanged(bool enabled)Habilita la perspectiva 3D (true de forma predeterminada cuando se permite); deshabilitarlo cambia a un diseño vertical 2D.
void cameraDistanceChanged(qreal distance)Distancia de cámara en perspectiva en píxeles lógicos [100, 10000]; predeterminado: 1000.
void zoomChanged(qreal zoom)Factor de zoom de toda la escena [0.1, 4]; 1 de forma predeterminada.
void pointerTrackingEnabledChanged(bool enabled)Inclina la escena hacia el puntero en modo 3D; el valor predeterminado es true.
void maximumTiltChanged(const QPointF& degrees)Inclinación máxima del puntero en grados por eje [0, 45]; valor predeterminado (10, 16).
void responseTimeChanged(int milliseconds)Constante de tiempo de suavizado del puntero en ms [0, 1000]; valor predeterminado: 140.
void maximumFrameRateChanged(int framesPerSecond)Límite de frecuencia de actualización de inclinación del puntero [15, 120] fps; valor predeterminado: 60.
void cacheEnabledChanged(bool enabled)Habilita la caché fuera de pantalla para los elementos; true de forma predeterminada.
void renderModeChanged(RenderMode mode)Backend de renderizado: Auto (predeterminado), Raster (CPU) u OpenGL (recurre a CPU si el hardware no está disponible).
void rendererChanged()Backend de renderizado activo actualmente (Raster u OpenGL).
void itemCountChanged(int count)Número de elementos actualmente en la vista.
Adiciones de PySide6
addOwnedWidget(widget)Transfiere el contenido a la vista. Al liberar su elemento, se destruye el contenido.
addReparentedWidget(widget)Al liberar el contenido, lo devuelve a su QWidget padre original.
Miembros protegidos
Métodos
Heredado de fluent::FluentElement
Enumeraciones
enum ThemeTema visual global usado al resolver los tokens de diseño.
Light = 0Dark = 1HighContrast = 2
Métodos
static void setTheme(Theme theme)Actualiza el tema global y notifica a las instancias activas de FluentElement.
static void setThemeDeferred(Theme theme)Programa una actualización de tema por lotes dando prioridad a lo visible sin bloquear la interacción actual.
static Theme currentTheme()Devuelve el tema global activo actualmente.
static bool themeUsesDarkAppearance(Theme theme)Devuelve si un tema utiliza cromo sobre fondo oscuro y tokens de material.
static void refreshTheme()Vuelve a difundir el tema actual para repintar tras un cambio de token de diseño.
static int themeGeneration()Contador monótono incrementado en cada cambio de tema para comprobaciones de obsolescencia.
Theme effectiveTheme() constResuelve el tema usado por este elemento, respetando una invalidación heredada de QWidget.
bool effectiveThemeUsesDarkAppearance() constDevuelve si el tema efectivo de este elemento usa cromo sobre fondo oscuro.
bool setThemeOverrides(const QJsonObject& overrides)Reemplaza las invalidaciones dispersas de tokens de color, radio y fuente de este elemento.
QJsonObject themeOverrides() constDevuelve las anulaciones definidas en este elemento.
void clearThemeOverrides()Restaura todos los campos de token a los valores predeterminados del tema global.
const Colors& themeColorsRef() constAcceso sin copia al conjunto de colores activo para rutas críticas de pintado.
Material::AcrylicToken themeAcrylic() constTokens de material, elevación y diseño adaptable.
QColor themeBackdrop(bool active) constColor de fondo del chrome de la ventana para el estado de activación indicado.
virtual void onThemeUpdated()Se llama después de que cambia el tema global.
Tipos y alias
struct ColorsInstantáneas de tokens de diseño devueltas a los componentes.
Heredado de fluent::QMLPlus
Métodos
AnchorLayout::Anchors* anchors()Devuelve los anclajes mutables del host QWidget.
void setState(const QString& name)Aplica un estado registrado por nombre o restaura el estado predeterminado cuando @p name está vacío. Los nombres desconocidos se ignoran y los enlaces existentes se reanudan al salir del estado.
void addState(const QMLState& state)Registra o reemplaza una definición de estado con nombre; reemplazar el estado activo lo aplica de inmediato.
void evaluateStates()Reevalúa las condiciones de estado en orden de registro y activa la primera coincidencia, o el estado predeterminado si ninguna coincide. También se ejecuta automáticamente cuando notifican las propiedades dependientes; los estados derivados que usan extend heredan cambios de ancestros salvo que sean cíclicos o falten.
QMLPlusRuntime* runtime()Devuelve el observador de estado creado de forma diferida y propiedad de este host.
void setAnchors(const AnchorLayout::Anchors& anchors)Reemplaza todos los anclajes del host e invalida el diseño padre.
void resetAnchors()Limpia todos los anclajes del host e invalida el diseño padre.
void bind(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction dir = PropertyBinder::OneWay)Vincula @p sourceProp en @p source con @p targetProp en este host QWidget mediante PropertyBinder::bind().
BindingHandle bindManaged(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction direction = PropertyBinder::OneWay, BindingOptions options = {})Instala un enlace directo gestionado en este host QWidget.
BindingHandle bindComputed(const char* targetProp, const QVector<BindingDependency>& dependencies, std::function<QVariant()> evaluate, BindingOptions options = {})Instala una expresión C++ de dependencias explícitas en este host QWidget.
void addTransition(const StateTransition& transition)Registra una transición de estado por orden de precedencia.
void setBehavior(const char* propertyName, const PropertyAnimation& animation)Establece la animación por defecto usada al escribir @p propertyName mediante writeProperty() o un enlace. Las reglas StateTransition explícitas tienen prioridad; las llamadas directas a setters de C++ no se animan.
void clearBehavior(const char* propertyName)Quita la animación predeterminada para futuras escrituras administradas.
bool writeProperty(const char* propertyName, const QVariant& value)Escribe una propiedad del host mediante Behavior sin eliminar su enlace.
Documentación de la clase base de Qt: QWidget