Back to Qt.io
Contact Us Blog Download Qt
本页内容

Bars3D QML Type

3D条形图。更多...

Import Statement: import QtGraphs
Inherits:

GraphsItem3D

属性

信号

方法

详细说明

此类型允许开发人员使用Qt Quick 以3D形式渲染条形图。

要使用此类型，您需要导入Qt Graphs 模块：

import QtGraphs

之后，您可以在 QML 文件中使用 Bars3D：

import QtQuick
import QtGraphs

Item {
    width: 640
    height: 480

    Bars3D {
        width: parent.width
        height: parent.height

        Bar3DSeries {
            itemLabelFormat: "@colLabel, @rowLabel: @valueLabel"

            ItemModelBarDataProxy {
                itemModel: dataModel
                // Mapping model roles to bar series rows, columns, and values.
                rowRole: "year"
                columnRole: "city"
                valueRole: "expenses"
            }
        }
    }

    ListModel {
        id: dataModel
        ListElement{ year: "2022"; city: "Oulu";     expenses: "4200"; }
        ListElement{ year: "2022"; city: "Rauma";    expenses: "2100"; }
        ListElement{ year: "2022"; city: "Helsinki"; expenses: "7040"; }
        ListElement{ year: "2022"; city: "Tampere";  expenses: "4330"; }
        ListElement{ year: "2023"; city: "Oulu";     expenses: "3960"; }
        ListElement{ year: "2023"; city: "Rauma";    expenses: "1990"; }
        ListElement{ year: "2023"; city: "Helsinki"; expenses: "7230"; }
        ListElement{ year: "2023"; city: "Tampere";  expenses: "4650"; }
    }
}

请参阅“简单条形图”以获取更详细的使用示例。

另请参阅 Bar3DSeries 、ItemModelBarDataProxy 、Scatter3D 、Surface3D 以及Qt Graphs 等用于 3D 渲染的 C++ 类。

属性文档

ambientLightStrength : real

整个图表的环境光强度。该值决定了无论光线位置如何，图表中各处的颜色显示是否均匀且明亮。该值必须介于0.0 和1.0 之间。

aspectRatio : real

图表中水平平面最长轴与 y 轴之间的缩放比例。默认值为2.0 。

注意：此设置 对Bars3D 无影响。

另请参阅 horizontalAspectRatio 。

barSeriesMargin : size

X 和 Z 维度中系列列之间的间距。默认预设值为(0.0, 0.0) 。合理的取值范围为 [0,1)。

barSpacing : size

X 和 Z 方向的条形间距。

默认预设值为(1.0, 1.0) 。间距受barSpacingRelative 属性影响。

barSpacingRelative : bool

间距是绝对的，还是相对于条形厚度而言的。

如果true ，则0.0 的值表示线条并排排列，1.0 表示线条之间留有与一条线宽相同的间距，以此类推。默认值为true 。

barThickness : real

X 轴和 Z 轴方向的棒材厚度比。数值1.0 表示棒材的宽度与深度相等，而0.5 则表示棒材的深度是宽度的两倍。

cameraPreset : Graphs3D.CameraPreset

当前激活的相机预设，该预设属于Graphs3D.CameraPreset 之一。如果未激活任何预设，则该值为Graphs3D.CameraPreset.NoPreset 。

cameraTargetPosition : vector3d

摄像机目标以 vector3d 形式表示。默认值为vector3d(0.0, 0.0, 0.0) 。

有效的坐标值范围为-1.0...1.0 ，其中边界值表示相应轴范围的边界。超出此范围的任何值都会被限制在边界值内。

cameraXRotation : real

相机以目标点为轴心的X轴旋转角度（以度为单位），以当前基准位置为起点。

cameraYRotation : real

相机以目标点为中心、以当前基准位置为起点的Y轴旋转角度（单位：度）。

cameraZoomLevel : real

摄像机的缩放级别（以百分比表示）。默认值100.0 表示摄像机未设置任何缩放比例。该值受minCameraZoomLevel 和maxCameraZoomLevel 属性的限制。

另请参阅 minCameraZoomLevel 和maxCameraZoomLevel 。

columnAxis : Category3DAxis

当前活动的列坐标轴。

如果未指定坐标轴，则会创建一个没有标签的临时默认坐标轴。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

currentFps : int

启用帧率（FPS）测量后，过去一秒的测量结果将存储在此只读属性中。在测量功能激活后，该值至少需要一秒钟才会更新。

另请参阅 measureFps 。

customItemList : list<Custom3DItem>

添加到图中的Custom3DItem 项的列表。图将接管这些已添加项的所有权。

cutoffMargin : real [since 6.11]

用于确定轴限值与图表元素被剔除的位置之间的差值的数值。

注意：不 影响柱状图。

该属性自 Qt 6.11 起引入。

dragMode : Graphs3D.DragMode [since 6.12]

确定如何解释图形上的拖动事件，取值范围为 Graphs3D.DragMode 枚举中的某个值。

默认值为Graphs3D.DragMode.Rotate 。

该属性于 Qt 6.12 中引入。

另请参阅 panEnabled 。

floorLevel : real

条形图在Y轴数据坐标系中的下限。

实际下限将受Y轴最小值和最大值的限制。默认值为零。

gridLineType : Graphs3D.GridLineType

用于指定网格线类型是Graphs3D.GridLineType.Shader 还是Graphs3D.GridLineType.Geometry 。

此值将影响所有网格线。

另请参阅 Graphs3D.GridLineType 。

horizontalAspectRatio : real

x 轴与 z 轴之间图表缩放的比例。0.0 表示根据轴范围自动缩放。默认值为0.0 。

注意：此属性 对Bars3D无效 ，后者通过barThickness 和barSpacing 属性处理水平面的缩放。极坐标图也会忽略此属性。

另请参阅 aspectRatio 、polar 、Bars3D::barThickness 和Bars3D::barSpacing 。

labelMargin : real

此属性用于指定坐标轴标签的放置边距。

负值将标签放置在绘图区域内，而正值则将其放置在绘图区域外。当值为负时，标签的自动旋转功能将被禁用。默认值为0.1

另请参阅 QAbstract3DAxis::labelAutoAngle 。

lightColor : color

在Scene3D 中定义的环境光和镜面光颜色。

lightStrength : real

整个图形的镜面光强度。该值必须在0.0 和10.0 之间。

该值会影响在Scene3D 中指定的光照。

locale : locale

设置用于格式化各种数字标签的区域设置。默认使用"C" 区域设置。

另请参阅 Value3DAxis::labelFormat 。

margin : real

用于设定可绘制图表区域边缘与图表背景边缘之间留白宽度的绝对值。

如果边距值为负数，则边距将由系统自动确定，并可能根据数据系列中数据点的大小以及图表类型而有所不同。如果图表的纵横比未从默认值进行更改，则该值将被解释为 y 轴范围的百分比。默认值为-1.0 。

注意：若 为散点图设置的 边距小于自动确定的边距，可能会导致图表边缘处的散点与图表背景重叠。

注意：在 散点图和曲面图中 ，如果边距相对于坐标轴标签的大小较小时，系统会调整坐标轴边缘标签的位置，以避免与相邻坐标轴的边缘标签发生重叠。

maxCameraXRotation : real [since 6.9]

相机围绕目标点的最大X轴旋转角度（单位：度）。默认值为180.0

该属性自 Qt 6.9 起引入。

maxCameraYRotation : real [since 6.9]

相机围绕目标点的最大Y轴旋转角度（单位：度）。默认值为90.0

该属性自 Qt 6.9 起引入。

maxCameraZoomLevel : real

设置相机允许的最大缩放级别。如果新的最大级别低于现有的最小级别，则最小级别也会调整为新的最大级别。如果当前的cameraZoomLevel 超出了新范围，它也会被调整。默认值为500.0f 。

另请参阅 cameraZoomLevel 和minCameraZoomLevel 。

measureFps : bool

如果true ，则渲染将持续进行，而非按需进行，并且currentFps 属性的值会随之更新。默认值为false 。

另请参阅 currentFps 。

minCameraXRotation : real [since 6.9]

相机围绕目标点的最小X轴旋转角度（单位：度）。默认值为-180.0

该属性自 Qt 6.9 起引入。

minCameraYRotation : real [since 6.9]

相机围绕目标点的最小Y轴旋转角度（单位：度）。默认值为0.0

该属性自 Qt 6.9 起引入。

minCameraZoomLevel : real

设置允许的最低相机缩放级别。如果新的最低级别高于现有的最高级别，则最高级别也会调整为新的最低级别。如果当前的cameraZoomLevel 超出了新范围，也会相应调整。minCameraZoomLevel不能设置为低于1.0 。默认值为10.0 。

另请参见 cameraZoomLevel 和maxCameraZoomLevel 。

msaaSamples : int

当renderingMode 为Indirect 时，多采样抗锯齿所使用的采样数。当renderingMode 为DirectToBackground 时，此属性值为只读，并返回窗口表面格式所指定的采样数。默认值为4 。

另请参阅 renderingMode 。

multiSeriesUniform : bool

指定即使显示了多个系列，条形图是否应根据单个系列的条形比例进行缩放。如果设置为“true ”，则“bar spacing ”仅会正确应用于X轴。默认预设为“false ”。

optimizationHint : Graphs3D.OptimizationHint

指定渲染优化时使用默认模式还是传统模式。

默认模式采用实例化渲染，在大多数系统上能以最佳性能提供完整的功能集。静态模式可优化图渲染，非常适合大型且数据不变的集合。但在数据动态变化和项目旋转时，其渲染速度会变慢。 选择操作未经过优化，因此不建议在海量数据集上使用静态模式。传统模式会单独渲染图中的所有项目，而不进行实例化。仅当默认模式无法正常工作时才应使用该模式，即目标系统不支持实例化时。默认值为Default 。

注意：在 某些环境下 ，使用静态优化的大型图可能无法渲染，因为所有项都通过单个渲染调用进行渲染，而不同的图形驱动程序对每次调用的最大顶点数支持各不相同。此问题主要出现在 32 位和 OpenGL ES2 平台上。 要解决此问题，请选择顶点数较少的元素网格，或使用点网格。

另请参阅 Abstract3DSeries::mesh 和Graphs3D.OptimizationHint 。

orthoProjection : bool

如果设置为true ，则将使用正射投影来显示图形。默认值为false 。

注意： 当设置为true 时，阴影 将被禁用。

panEnabled : bool [since 6.12]

该输入处理程序是否允许对图进行平移操作。

默认值为true 。

该属性自 Qt 6.12 起引入。

polar : bool

如果true ，则水平坐标轴将转换为极坐标轴。x轴变为角度轴，z轴变为半径轴。极坐标模式不适用于条形图。

默认值为false 。

另请参阅 orthoProjection 和radialLabelOffset 。

primarySeries : Bar3DSeries

图表的主系列。当未在坐标轴上显式设置标签时，该系列用于确定行轴和列轴的标签。

如果指定的数据集尚未添加到图表中，将其设置为主数据集也会将其隐式地添加到图表中。

如果主数据系列本身从图表中被移除，则此属性将重置为默认值。

如果该数据集为空，则该属性将重置为默认值。默认值为第一个添加的数据集；如果图表中未添加任何数据集，则默认值为零。

queriedGraphPosition : vector3d [read-only]

此只读属性包含通过 `Scene3D::graphPositionQuery` 查询得到的、沿各轴的最新图表位置值。这些值已被归一化为范围 `[-1, 1]`。如果查询的位置超出图表边界，则这些值不会反映实际位置，而是会显示为范围 `[-1, 1]` 之外的某个未定义位置。在进行查询之前，该值将为未定义。

由于不存在与特定屏幕位置完全对应的唯一正确 3D 坐标，因此为了保持一致性，查询始终针对包围图表的不可见矩形框的内侧进行。

注意：条形图 仅允许在图表底边高度处查询位置，因此条形图的 y 值始终为零，且仅当屏幕位置包含图表底边时，才能进行有效的查询。

另请参阅 Scene3D::graphPositionQuery 。

radialLabelOffset : real

该属性指定径向极坐标轴轴标的标准化水平偏移量。值0.0 表示应将轴标绘制在0角度的角轴网格线旁。值1.0 表示轴标应绘制在其通常位置，即图表背景的边缘。如果polar属性的值为false ，则该属性将被忽略。默认值为1.0 。

另请参阅 polar 。

renderingMode : Graphs3D.RenderingMode

图的渲染方式。默认值为Indirect 。

注意：设置 图表的antialiasing 属性不会产生任何效果。但是，如果当前的渲染模式使用了抗锯齿，则该属性会由图表本身自动设置。

另请参阅 msaaSamples 和Graphs3D.RenderingMode 。

rootNode : Node [read-only, since 6.9]

返回指向 3D 图根节点的指针。使用此属性可通过 `importScene` 将 3D 图注入到单独的 `View3D ` 中：

Bars3D {
  id: bars
}
View3D {
  importScene: bars.rootNode
}

该属性于 Qt 6.9 版本中引入。

另请参阅 View3D 。

rotationEnabled : bool

该输入处理程序是否允许图形旋转。

默认值为true 。

rowAxis : Category3DAxis

当前活动的行轴。

如果未指定坐标轴，则会创建一个没有标签的临时默认坐标轴。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

scene : Scene3D [read-only]

Scene3D 指针，可用于操作场景并访问场景元素。

该属性为只读属性。

selectedElement : Graphs3D.ElementType [read-only]

图中选中的元素。

该属性可用于查询所选元素的类型。该类型在图表中进行新选择并发出selectedElementChanged 信号之前一直有效。

该信号可用于实现自定义输入处理，如“轴处理”示例所示。

另请参阅 selectedLabelIndex()、selectedAxis()、selectedCustomItemIndex()、selectedCustomItem()、Bars3D::selectedSeries 、Scatter3D::selectedSeries 、Scene3D::selectionQueryPosition 以及Graphs3D.ElementType 。

selectedSeries : Bar3DSeries [read-only]

所选系列或null 。如果selectionMode 设置了SelectionMultiSeries 标志，则该属性将保存拥有所选柱状图的系列。

selectionEnabled : bool

该输入处理程序是否允许从图中进行选择。

默认值为true 。

selectionMode : Graphs3D.SelectionMode

图形中的活动选择模式。属于Graphs3D.SelectionFlag 枚举值之一。

seriesList : list<Bar3DSeries> [default]

图表的系列。默认情况下，该属性包含一个空列表。要设置系列，可以使用addSeries()函数，或者将其定义为图表的子元素。

shadowQuality : Graphs3D.ShadowQuality

阴影质量。Graphs3D.ShadowQuality 枚举值之一。

shadowStrength : real

整个图形的阴影强度。数值越高，阴影越深。该值必须在0.0 和100.0 之间。

该值会影响在Scene3D 中指定的光照效果。

theme : GraphsTheme

图的当前主题。

另请参阅 GraphsTheme 。

transparencyTechnique : Graphs3D.TransparencyTechnique [since 6.9]

指定要使用的透明度处理技术。默认值为Default 。在渲染透明表面图时，请使用Approximate 或Accurate 。对于其他图类型，应使用Default 。

常量描述
Default表示不使用与顺序无关的透明度技术。可提供最佳性能。当图表不包含透明度，或者条形图或散点图同时使用实例化时（即optimizationHint 为{QtGraphs3D::OptimizationHint::Default}），应使用此选项。
Approximate表示图尝试对顺序无关透明度进行近似渲染。该方法比 `Accurate ` 更快，可在较旧的硬件上运行，但可能会产生不准确的结果。当需要顺序无关透明度，但性能开销必须低于使用精确顺序无关透明度时，请使用此方法。
Accurate表示使用精确的顺序无关透明度。当需要完美的透明度渲染时使用。

该属性在 Qt 6.9 中引入。

valueAxis : ValueAxis3D

活动值轴。

如果未指定坐标轴，系统将创建一个临时默认坐标轴，该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的取向，则该临时坐标轴将被销毁。

wrapCameraXRotation : bool

X 轴旋转中最小值和最大值的处理方式。默认情况下，X 轴旋转会从最小值循环到最大值，再从最大值循环回最小值。

若设置为true ，摄像机的X轴旋转将从最小值循环到最大值，再从最大值循环回最小值。若设置为false ，摄像机的X轴旋转将限制在由最小值和最大值确定的扇区内。

wrapCameraYRotation : bool

Y 轴旋转中最小值和最大值的限制行为。默认情况下，Y 轴旋转在最小值和最大值之间受限，且不进行循环。

如果true ，则摄像机的 Y 轴旋转会从最小值循环到最大值，再从最大值循环回最小值。如果false ，则摄像机的 Y 轴旋转将限制在由最小值和最大值确定的扇形区域内。

zoomAtTargetEnabled : bool

是否应在缩放后调整摄像头目标，以便图表中被缩放的点在缩放后仍保持在原位置。

默认值为true 。

zoomEnabled : bool

该输入处理程序是否允许对图表进行缩放。

默认值为true 。

Signal 文档

barSeriesMarginChanged(size margin)

当barSeriesMargin 变为margin 时，会触发此信号。

注意： 相应的处理程序 是onBarSeriesMarginChanged 。

barSpacingChanged(size spacing)

当barSpacing 变为spacing 时，会触发此信号。

注意： 相应的处理程序 是onBarSpacingChanged 。

barSpacingRelativeChanged(bool relative)

当barSpacingRelative 变为relative 时，会触发此信号。

注意： 相应的处理程序 是onBarSpacingRelativeChanged 。

barThicknessChanged(real thicknessRatio)

当barThickness 变为thicknessRatio 时，会触发此信号。

注意： 相应的处理程序 是onBarThicknessChanged 。

columnAxisChanged(Category3DAxis axis)

当columnAxis 变为axis 时，会触发此信号。

注意： 相应的处理程序 为onColumnAxisChanged 。

doubleTapped(QEventPoint eventPoint, Qt::MouseButton button)

当在短时间内连续点击图形控件两次时，会触发此信号。eventPoint 信号参数包含来自释放事件的关于被点击点的信息，而button 是被点击的mouse button ，或在触摸屏上为NoButton 。

注意： 相应的处理程序 是onDoubleTapped 。

另请参阅 QEventPoint 、Qt::MouseButtons 和TapHandler::doubleTapped 。

dragged(QVector2D delta)

当执行捏合手势时，如果图形上点簇的平移位置发生变化，则会发出此信号。delta 向量表示平移量的变化。

注意： 相应的处理程序 为onDragged 。

另请参阅 PinchHandler::translationChanged 。

floorLevelChanged(real level)

当floorLevel 变为level 时，会触发此信号。

注意： 相应的处理程序 是onFloorLevelChanged 。

longPressed()

当“parent ”控件被按住的时间超过TapHandler::longPressThreshold 时，会发出此信号。

注意： 相应的处理程序 为onLongPressed 。

另请参阅 TapHandler::longPressed 。

mouseMove(QPoint mousePos)

当图接收到 mouseMove 事件时，会触发此信号。mousePos 的值表示鼠标移动时的位置。

注意： 相应的处理程序 为onMouseMove 。

另请参阅 QQuickItem::mouseMoveEvent 。

multiSeriesUniformChanged(bool uniform)

当multiSeriesUniform 变为uniform 时，会触发此信号。

注意： 对应的处理程序 是onMultiSeriesUniformChanged 。

pinch(qreal delta)

当执行捏合手势时，如果图表上的缩放因子发生变化，则会发出此信号。delta 值表示缩放因子的乘法变化量。

注意： 相应的处理程序 为onPinch 。

另请参阅 PinchHandler::scaleChanged 。

primarySeriesChanged(Bar3DSeries series)

当primarySeries 变为series 时，会触发此信号。

注意： 相应的处理程序 是onPrimarySeriesChanged 。

rowAxisChanged(Category3DAxis axis)

当rowAxis 变为axis 时，会触发此信号。

注意： 相应的处理程序 是onRowAxisChanged 。

selectedSeriesChanged(Bar3DSeries series)

当selectedSeries 变为series 时，会触发此信号。

注意： 相应的处理程序 是onSelectedSeriesChanged 。

tapped(QEventPoint eventPoint, Qt::MouseButton button)

当图形项被单击一次时，会发出此信号。eventPoint 信号参数包含来自释放事件的关于被点击点的信息，而button 表示被点击的mouse button ，或在触摸屏上为NoButton 。

注意： 相应的处理程序 为onTapped 。

另请参阅 QEventPoint 、Qt::MouseButtons 以及TapHandler::singleTapped 。

valueAxisChanged(ValueAxis3D axis)

当valueAxis 变为axis 时，会触发此信号。

注意： 相应的处理程序 是onValueAxisChanged 。

wheel(QQuickWheelEvent *event)

每当图表接收到类型为QWheelEvent 的event 时，都会触发此信号：也就是说，每次滚轮移动或滚动手势更新时，都会触发此信号。

注意： 相应的处理程序 是onWheel 。

另请参阅 WheelEvent 和WheelHandler::wheel 。

方法文档

qsizetype addCustomItem(Custom3DItem item)

向图中添加一个Custom3DItem item 。图将拥有该添加项的所有权。

若添加成功，则返回所添加项的索引；若尝试添加空项，则返回-1；若尝试添加已存在的项，则返回该项的索引。

另请参阅 removeCustomItems()、removeCustomItem()，以及removeCustomItemAt()。

void addSeries(Bar3DSeries series)

将series 添加到图表中。一个图表可以包含多个系列，但只能有一组坐标轴，因此所有系列的行和列必须匹配，可视化数据才有意义。 如果图表中有多个可见系列，且未在坐标轴上显式设置标签，则只有第一个添加的系列会在坐标轴上生成行或列标签。如果新添加的系列指定了选定条形，该条形将被高亮显示，且任何现有的选定状态将被清除。仅有一个添加的系列可以处于选定状态。

另请参阅 GraphsItem3D::hasSeries()。

void clearSelection()

清除所有关联系列中的选中项。

void doPicking(QPoint point)

使用point 中的视图坐标对图中的元素进行点选操作，并选择第一个被点中的项目。默认的输入处理机制会在接收到 onTapped 事件时执行此操作。

另请参阅 selectedElement 。

void doRayPicking(QVector3D origin, QVector3D direction)

从origin 开始，并按照direction 对图中的元素进行拣选，选择第一个匹配的项。

另请参阅 selectedElement 。

bool hasSeries(Abstract3DSeries series)

返回series 是否已添加到图中。

void insertSeries(int index, Bar3DSeries series)

将series 插入到序列列表中index 的位置。如果series 已添加到列表中，则将其移动到新的index 位置。

注意：当 将一个序列移动到其旧索引之后的新位置index 时 ，列表中的新位置是按照该序列仍位于其旧索引的位置来计算的，因此最终索引实际上是index 减去1。

另请参阅 GraphsItem3D::hasSeries()。

void releaseCustomItem(Custom3DItem item)

取回item 的所有权，并将item 从图中移除。

注意：如果 将同一项重新添加到图形中，则需要重新设置纹理文件。

另请参阅 Custom3DItem::textureFile 。

void removeCustomItem(Custom3DItem item)

删除自定义item 。并删除分配给它的资源。

void removeCustomItemAt(vector3d position)

删除position 下的所有自定义项目。并释放分配给这些项目的资源。

void removeCustomItems()

删除所有自定义项目。并释放分配给这些项目的资源。

void removeSeries(Bar3DSeries series)

从图中移除series 。

另请参阅 GraphsItem3D::hasSeries()。

[since 6.10] void renderSliceToImage(int requestedIndex, QtGraphs3D::SliceCaptureType sliceType, QUrl filePath)

从位于requestedIndex 的序列中导出一个 2D 切片，并将结果保存为位于指定路径filePath 的图像。导出的切片包含行或列的条形，具体由sliceType 定义。

此方法于 Qt 6.10 中引入。

Abstract3DAxis selectedAxis()

可用于在接收到selectedElementChanged 信号后获取所选轴，该信号的标签类型不限。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选轴，或返回 null。

另请参阅 selectedElement 。

Custom3DItem selectedCustomItem()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于获取所选的自定义项。该项的所有权仍归图所有。选中状态有效直至下一个selectedElementChanged 信号触发。

返回所选的自定义项，或 null。

另请参阅 selectedElement 。

qsizetype selectedCustomItemIndex()

可在接收到类型为ElementType.CustomItem 的selectedElementChanged 信号后，用于查询所选自定义项的索引。该选择在下次selectedElementChanged 信号触发前一直有效。

返回所选自定义项的索引，或 -1。

另请参阅 selectedElement 。

int selectedLabelIndex()

可在接收到selectedElementChanged 信号后，用于查询所选标签的索引，支持任何标签类型。该选择在收到下一个selectedElementChanged 信号之前一直有效。

返回所选标签的索引，或 -1。

另请参阅 selectedElement 。

void setDefaultInputHandler()

* * @brief 恢复默认的输入处理机制。 * * 此方法将重新启用内部预定义的输入处理程序。 * 若此前曾调用 *unsetDefaultInputHandler ，请使用此方法恢复默认行为。 *

另请参阅 unsetDefaultInputHandler()。

void setDragButton(Qt::MouseButtons button)

* * @brief 设置用于触发拖动事件的鼠标按钮。 * * 此方法允许将启动 * 拖动操作所需的鼠标按钮更改为button 。 * 默认值为Qt::RightButton 。

[since 6.12] void setPanButton(Qt::MouseButtons button)

* * * @brief 设置用于触发平移事件的鼠标按钮。 * * 该方法允许将启动拖动操作所需的鼠标按钮更改为 *button 。 * 默认值为Qt::MiddleButton 。

该方法在 Qt 6.12 中引入。

void unsetDefaultDragHandler()

* * @brief 禁用默认的拖拽事件处理程序。 * * 这会专门取消对拖拽手势的内置响应。 * 如果您需要实现自定义的拖拽处理程序，请使用此选项。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultInputHandler()

* * @brief 禁用默认的输入处理机制。 * * 此方法会停用所有预定义的默认输入处理程序。 * 若要覆盖默认行为，请调用此方法。 *

另请参阅 unsetDefaultTapHandler()、unsetDefaultDragHandler()、unsetDefaultWheelHandler() 以及unsetDefaultPinchHandler()。

void unsetDefaultPinchHandler()

* * @brief 禁用默认的捏合手势处理程序。 * * 这会专门取消对捏合手势的内置响应。 * 用于实现自定义捏合手势处理程序。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultTapHandler()

* * @brief 禁用默认的点击事件处理程序。 * * 这会专门取消对点击或单击事件的内置响应， * 从而支持自定义的点击处理逻辑。 *

另请参阅 unsetDefaultInputHandler()。

void unsetDefaultWheelHandler()

* * @brief 禁用默认的鼠标滚轮事件处理程序。 * * 这会专门取消对鼠标滚轮滚动操作的内置响应。 * 在实现自定义滚轮行为时请使用此选项。 *

另请参阅 unsetDefaultInputHandler()。

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