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

Surface3DSeries QML Type (Uncreatable)

表示三维曲面图中的数据序列。更多...

Import Statement: import QtGraphs
In C++: QSurface3DSeries
Inherits:

Abstract3DSeries

注意：此类型不可创建。无法在 QML 中实例化。

属性

信号

方法

详细说明

此类用于管理系列特有的视觉元素，以及系列数据（通过数据代理）。

Surface3DSeries 支持以下用于 itemLabelFormat 的格式标签：

@xTitle来自 x 轴的标题
@yTitle来自 y 轴的标题
@zTitlez轴标题
@xLabel使用 x 轴格式设置的项目值。有关详细信息，请参阅labelFormat 。
@yLabel使用 y 轴格式设置的项目值。有关详细信息，请参阅labelFormat 。
@zLabel项目值采用 z 轴的格式进行格式化。有关详细信息，请参阅labelFormat 。
@seriesName系列名称

如需更完整的说明，请参阅QSurface3DSeries 。

另请参阅 Qt Graphs 中的“3D 数据处理”。

属性文档

baseColor : color

该系列的基础色。

另请参阅 colorStyle 和GraphsTheme.seriesColors 。

baseGradient : Gradient

该系列的基数梯度。

另请参阅 colorStyle 。

colorStyle : GraphsTheme.ColorStyle

该系列的配色风格。

另请参阅 GraphsTheme.ColorStyle 。

dataArray : SurfaceDataArray

保存数据数组的引用。

dataArrayChanged 当数据数组被设置时会触发信号，除非newDataArray 与上一次设置的值完全相同。

注意： 在对 dataArray 进行任何操作之前，必须先 为相关的代理创建一个系列。

dataProxy : SurfaceDataProxy

活动数据代理。该序列会接管其上设置的任何代理，并在添加新代理时删除先前设置的代理。代理不能为空，也不能设置为另一个序列。

drawMode : DrawFlag

将绘图模式设置为Surface3DSeries.DrawFlag{QSurface3DSeries.DrawFilledSurface}中的一个。必须设置为DrawWireframe或DrawSurface之一

flatShadingSupported : bool [read-only]

指示当前系统是否支持曲面的平面着色。这需要至少 GLSL 1.2 版本，并具备 GL_EXT_gpu_shader4 扩展。

注意：此 只读属性将在首次渲染通过后被设置为正确值。在此之前，其值始终为true 。

invalidSelectionPosition : point [read-only]

一个返回无效选择位置的常量属性。该位置将被赋值给selectedPoint 属性，以清除该系列中的选择。

另请参阅 GraphsItem3D::clearSelection()。

itemLabel : string [read-only]

已格式化的项目标签。如果未选中任何项目，或者所选项目不可见，则返回一个空字符串。

另请参阅 itemLabelFormat 。

itemLabelFormat : string

该系列中数据项的标签格式。此格式用于单个数据项的标签，例如当选中某项时。该格式的解释方式取决于系列类型。

另请参阅 Bar3DSeries 、Scatter3DSeries 以及Surface3DSeries 。

itemLabelVisible : bool

如果true ，项目标签将在图中作为浮动标签绘制。否则，项目标签不会被绘制。若要在外部控件中显示项目标签，应将此属性设置为false 。默认值为true 。

另请参阅 itemLabelFormat 和itemLabel 。

lightingMode : Abstract3DSeries.LightingMode [since 6.10]

该系列中项目的照明模式。默认值为QAbstract3DSeries::LightingMode::Shaded

该属性自 Qt 6.10 起引入。

另请参阅 QAbstract3DSeries::LightingMode 。

mesh : Abstract3DSeries.Mesh

该系列中各项的网格，对于 `Surface3DSeries` 而言则是选择指针。如果网格为 `Abstract3DSeries.Mesh.UserDefined`，则必须同时设置 `userDefinedMesh ` 属性，以便各项能正确渲染。默认值取决于图形类型。

另请参阅 QAbstract3DSeries::Mesh 。

meshRotation : quaternion

应用于该系列所有项的网格旋转。该旋转应为归一化四元数。对于支持单项旋转的系列类型，各旋转值将相互乘积。Bar3DSeries 会忽略任何非绕y轴的旋转。Surface3DSeries 仅对选择指针应用旋转。默认不进行旋转。

meshSmooth : bool

如果true ，则使用通过mesh 属性设置的预定义网格的平滑版本。当网格设置为Abstract3DSeries.Mesh.UserDefined 时，此属性不会影响所使用的自定义网格。默认值为false 。

multiHighlightColor : color

该系列中多个项目的突出显示颜色。

另请参阅 colorStyle 和GraphsTheme.multiHighlightColor 。

multiHighlightGradient : Gradient

该系列中多个项目的渐变高亮效果。

另请参阅 colorStyle 和GraphsTheme.multiHighlightGradient 。

name : string

系列名称。可使用标签@seriesName 以项目标签格式显示。

另请参阅 itemLabelFormat 。

selectedPoint : point

将曲面网格点设置为系列数据数组中由行和列指定的位置，并将其选中。每次只能选中一个点。

要清除该系列中的选定内容，请将位置设为invalidSelectionPosition 。如果该系列被添加到图表中，图表会根据用户交互或选定内容失效的情况自动调整选定范围。

从该系列中删除行，或在选定点的行之前插入行，都会调整选定范围，以确保该点仍保持被选中状态。

另请参阅 GraphsItem3D::clearSelection()。

shading : Shading

将表面平铺着色设置为可见。默认预设为Surface3DSeries.Shading.Flat 。当禁用时，表面法线会被插值处理，使边缘看起来呈圆角。当启用时，三角形上的法线保持不变，使三角形的颜色呈现实心效果。这使得模型数据更易于读取。

注意：平滑着色 表面至少需要 GLSL 1.2 版本，并支持 GL_EXT_gpu_shader4 扩展。flatShadingSupported 属性的值指示运行时是否支持平滑着色。

singleHighlightColor : color

该系列的单件突出显示颜色。

另请参阅 colorStyle 和GraphsTheme.singleHighlightColor 。

singleHighlightGradient : Gradient

该系列中单件商品的渐变色亮点。

另请参阅 colorStyle 和GraphsTheme.singleHighlightGradient 。

textureFile : string

表面纹理的纹理文件名。若要清除该纹理，则设置为空文件名。

type : Abstract3DSeries.SeriesType [read-only]

序列的类型。QAbstract3DSeries::SeriesType 中的一个值。

userDefinedMesh : string

当使用mesh 时，对象的用户自定义网格文件名为Abstract3DSeries.Mesh.UserDefined 。

注意：该文件 必须采用QtQuick3D 网格格式。请使用balsam 转换工具，将其他 3D 模型格式转换为网格文件。

visible : bool

该系列的可见性。如果false ，则该系列不会被渲染。

wireframeColor : color

用于绘制曲面线框网格线的颜色。

信号文档

baseColorChanged(color color)

当baseColor 变为color 时，会触发此信号。

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

baseGradientChanged(Gradient gradient)

当baseGradient 变为gradient 时，会触发此信号。

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

colorStyleChanged(GraphsTheme.ColorStyle style)

当colorStyle 变为style 时，会触发此信号。

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

dataArrayChanged(SurfaceDataArray array)

当dataArray 变为array 时，会触发此信号。

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

dataProxyChanged(SurfaceDataProxy proxy)

当dataProxy 变为proxy 时，会触发此信号。

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

drawModeChanged(DrawFlag mode)

当drawMode 变为mode 时，会触发此信号。

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

flatShadingSupportedChanged(bool enable)

当flatShadingSupported 变为enable 时，会触发此信号。

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

itemLabelChanged(string label)

当itemLabel 变为label 时，会触发此信号。

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

itemLabelFormatChanged(string format)

当itemLabelFormat 变为format 时，会发出此信号。

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

itemLabelVisibilityChanged(bool visible)

当 itemLabelVisibility 变为visible 时，会触发此信号。

注意： 对应的处理程序 为onItemLabelVisibilityChanged 。

[since 6.10] lightingModeChanged(Abstract3DSeries.LightingMode lightingMode)

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

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

该信号在 Qt 6.10 中引入。

meshChanged(Abstract3DSeries.Mesh mesh)

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

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

meshRotationChanged(quaternion rotation)

当meshRotation 变为rotation 时，会触发此信号。

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

meshSmoothChanged(bool enabled)

当meshSmooth 变为enabled 时，会触发此信号。

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

multiHighlightColorChanged(color color)

当multiHighlightColor 变为color 时，会触发此信号。

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

multiHighlightGradientChanged(Gradient gradient)

当multiHighlightGradient 变为gradient 时，会触发此信号。

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

nameChanged(string name)

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

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

rowsSanitizedChanged(bool enabled)

当 rowsSanitized 的值变为enabled 时，会触发此信号。

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

selectedPointChanged(point position)

当selectedPoint 变为position 时，会触发此信号。

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

shadingChanged(const Shading shading)

当shading 变为shading 时，将触发此信号。

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

singleHighlightColorChanged(color color)

当singleHighlightColor 变为color 时，会触发此信号。

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

singleHighlightGradientChanged(Gradient gradient)

当singleHighlightGradient 变为gradient 时，会触发此信号。

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

textureFileChanged(string filename)

当textureFile 变为filename 时，会触发此信号。

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

userDefinedMeshChanged(string fileName)

当userDefinedMesh 变为fileName 时，会触发此信号。

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

visibilityChanged(bool visible)

当该系列的可见性变为“visible ”时，会发出此信号。

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

wireframeColorChanged(color color)

当wireframeColor 变为color 时，会触发此信号。

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

方法文档

void setMeshAxisAndAngle(vector3d axis, real angle)

一个便捷函数，用于根据axis 和angle 构建网格旋转四元数。

另请参阅 meshRotation 。

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