本页内容

Q3DTheme Class

Q3DTheme 类为图表提供了一种视觉样式。更多内容...

标题: #include <Q3DTheme>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
自: QtDataVisualization 1.0
在 QML 中: Theme3D
继承自: QObject
状态: 已弃用

该类已弃用。我们强烈建议不要在新代码中使用它。

公共类型

enum ColorStyle { ColorStyleUniform, ColorStyleObjectGradient, ColorStyleRangeGradient }
enum Theme { ThemeQt, ThemePrimaryColors, ThemeDigia, ThemeStoneMoss, ThemeArmyBlue, …, ThemeUserDefined }

属性

公共函数

Q3DTheme(QObject *parent = nullptr)
Q3DTheme(Q3DTheme::Theme themeType, QObject *parent = nullptr)
virtual ~Q3DTheme()
float ambientLightStrength() const
QColor backgroundColor() const
QList<QColor> baseColors() const
QList<QLinearGradient> baseGradients() const
Q3DTheme::ColorStyle colorStyle() const
QFont font() const
QColor gridLineColor() const
float highlightLightStrength() const
bool isBackgroundEnabled() const
bool isGridEnabled() const
bool isLabelBackgroundEnabled() const
bool isLabelBorderEnabled() const
QColor labelBackgroundColor() const
QColor labelTextColor() const
QColor lightColor() const
float lightStrength() const
QColor multiHighlightColor() const
QLinearGradient multiHighlightGradient() const
void setAmbientLightStrength(float strength)
void setBackgroundColor(const QColor &color)
void setBackgroundEnabled(bool enabled)
void setBaseColors(const QList<QColor> &colors)
void setBaseGradients(const QList<QLinearGradient> &gradients)
void setColorStyle(Q3DTheme::ColorStyle style)
void setFont(const QFont &font)
void setGridEnabled(bool enabled)
void setGridLineColor(const QColor &color)
void setHighlightLightStrength(float strength)
void setLabelBackgroundColor(const QColor &color)
void setLabelBackgroundEnabled(bool enabled)
void setLabelBorderEnabled(bool enabled)
void setLabelTextColor(const QColor &color)
void setLightColor(const QColor &color)
void setLightStrength(float strength)
void setMultiHighlightColor(const QColor &color)
void setMultiHighlightGradient(const QLinearGradient &gradient)
void setSingleHighlightColor(const QColor &color)
void setSingleHighlightGradient(const QLinearGradient &gradient)
void setType(Q3DTheme::Theme themeType)
void setWindowColor(const QColor &color)
QColor singleHighlightColor() const
QLinearGradient singleHighlightGradient() const
Q3DTheme::Theme type() const
QColor windowColor() const

信号

void ambientLightStrengthChanged(float strength)
void backgroundColorChanged(const QColor &color)
void backgroundEnabledChanged(bool enabled)
void baseColorsChanged(const QList<QColor> &colors)
void baseGradientsChanged(const QList<QLinearGradient> &gradients)
void colorStyleChanged(Q3DTheme::ColorStyle style)
void fontChanged(const QFont &font)
void gridEnabledChanged(bool enabled)
void gridLineColorChanged(const QColor &color)
void highlightLightStrengthChanged(float strength)
void labelBackgroundColorChanged(const QColor &color)
void labelBackgroundEnabledChanged(bool enabled)
void labelBorderEnabledChanged(bool enabled)
void labelTextColorChanged(const QColor &color)
void lightColorChanged(const QColor &color)
void lightStrengthChanged(float strength)
void multiHighlightColorChanged(const QColor &color)
void multiHighlightGradientChanged(const QLinearGradient &gradient)
void singleHighlightColorChanged(const QColor &color)
void singleHighlightGradientChanged(const QLinearGradient &gradient)
void typeChanged(Q3DTheme::Theme themeType)
void windowColorChanged(const QColor &color)

详细说明

指定影响整个图形的视觉属性。有几种内置主题,既可以直接使用,也可以自由修改。

以下属性可通过在数据系列中使用QAbstract3DSeries 属性进行显式设置来覆盖:baseColors 、baseGradients 和colorStyle 。

可以使用ThemeUserDefined 枚举值从头开始创建主题。使用默认构造函数创建主题将生成一个新的用户自定义主题。

默认主题

下表列出了由主题控制的属性以及ThemeUserDefined 的默认值。

使用示例

创建一个无需任何修改的内置主题:

Q3DTheme *theme = new Q3DTheme(Q3DTheme::ThemeQt);

创建内置主题并修改部分属性:

Q3DTheme *theme = new Q3DTheme(Q3DTheme::ThemeQt);
theme->setBackgroundEnabled(false);
theme->setLabelBackgroundEnabled(false);

创建自定义主题:

Q3DTheme *theme = new Q3DTheme();
theme->setAmbientLightStrength(0.3f);
theme->setBackgroundColor(QColor(QRgb(0x99ca53)));
theme->setBackgroundEnabled(true);
theme->setBaseColor(QColor(QRgb(0x209fdf)));
theme->setColorStyle(Q3DTheme::ColorStyleUniform);
theme->setFont(QFont(QStringLiteral("Impact"), 35));
theme->setGridEnabled(true);
theme->setGridLineColor(QColor(QRgb(0x99ca53)));
theme->setHighlightLightStrength(7.0f);
theme->setLabelBackgroundColor(QColor(0xf6, 0xa6, 0x25, 0xa0));
theme->setLabelBackgroundEnabled(true);
theme->setLabelBorderEnabled(true);
theme->setLabelTextColor(QColor(QRgb(0x404044)));
theme->setLightColor(Qt::white);
theme->setLightStrength(6.0f);
theme->setMultiHighlightColor(QColor(QRgb(0x6d5fd5)));
theme->setSingleHighlightColor(QColor(QRgb(0xf6a625)));
theme->setWindowColor(QColor(QRgb(0xffffff)));

创建内置主题并在设置后修改某些属性:

Q3DBars *graph = new Q3DBars();
graph->activeTheme()->setType(Q3DTheme::ThemePrimaryColors);
graph->activeTheme()->setBaseColor(Qt::red);
graph->activeTheme()->setSingleHighlightColor(Qt::yellow);

成员类型文档

enum Q3DTheme::ColorStyle

颜色样式。

常量值描述
Q3DTheme::ColorStyleUniform0对象以单一颜色渲染。所用的颜色在baseColors 、singleHighlightColor 和multiHighlightColor 属性中指定。
Q3DTheme::ColorStyleObjectGradient1无论对象高度如何,每个对象均使用完整的渐变进行着色。所用的渐变由baseGradients 、singleHighlightGradient 和multiHighlightGradient 属性指定。
Q3DTheme::ColorStyleRangeGradient2对象的着色使用完整渐变色谱中的一部分,该部分由对象的高度及其在 Y 轴上的位置决定。所使用的渐变由baseGradients 、singleHighlightGradient 和multiHighlightGradient 属性指定。

enum Q3DTheme::Theme

内置主题。

常量值描述
Q3DTheme::ThemeQt0以绿色为基色的浅色主题。
Q3DTheme::ThemePrimaryColors1以黄色为基色的浅色主题。
Q3DTheme::ThemeDigia2以灰色为基色的浅色主题。
Q3DTheme::ThemeStoneMoss3以黄色为基色的中等深色主题。
Q3DTheme::ThemeArmyBlue4以蓝色为基色的中等浅色主题。
Q3DTheme::ThemeRetro5以棕色为基色的中等浅色主题。
Q3DTheme::ThemeEbony6以白色为基色的深色主题。
Q3DTheme::ThemeIsabelle7以黄色为基色的深色主题。
Q3DTheme::ThemeUserDefined8自定义主题。有关详细信息,请参阅Default Theme 。

属性文档

ambientLightStrength : float

该属性控制整个图表的环境光强度。

该值决定了无论光源位置如何,颜色在整个图表中显示的均匀度和亮度。

该值必须介于0.0f 和1.0f 之间。

访问函数:

float ambientLightStrength() const
void setAmbientLightStrength(float strength)

通知信号:

void ambientLightStrengthChanged(float strength)

backgroundColor : QColor

该属性用于设置图表背景的颜色。

访问函数:

QColor backgroundColor() const
void setBackgroundColor(const QColor &color)

通知器信号:

void backgroundColorChanged(const QColor &color)

backgroundEnabled : bool

该属性与背景是否可见无关。

背景的绘制基于backgroundColor 的值。

访问函数:

bool isBackgroundEnabled() const
void setBackgroundEnabled(bool enabled)

通知器信号:

void backgroundEnabledChanged(bool enabled)

baseColors : QList<QColor>

该属性按系列存储了图中所有对象将使用的基色列表。

如果系列数量多于颜色数量,颜色列表将循环显示,并从列表中的第一个颜色开始重新显示。

如果 `colorStyle ` 不是 `ColorStyleUniform`,则此属性不会立即生效。

可以通过在系列中显式设置baseColor 来覆盖此值。

访问函数:

QList<QColor> baseColors() const
void setBaseColors(const QList<QColor> &colors)

通知信号:

void baseColorsChanged(const QList<QColor> &colors)

baseGradients : QList<QLinearGradient>

该属性存储了将用于图中所有对象(按系列分组)的基础渐变列表。

如果系列数量多于渐变数量,渐变列表将循环,并从列表中的第一个渐变开始重新开始

如果 `colorStyle ` 的值为 `ColorStyleUniform`,则此属性不会立即生效。

如果baseGradient 的值为 ,则此值不会立即生效。可以通过在系列中显式设置 来覆盖此值。

访问函数:

QList<QLinearGradient> baseGradients() const
void setBaseGradients(const QList<QLinearGradient> &gradients)

通知信号:

void baseGradientsChanged(const QList<QLinearGradient> &gradients)

colorStyle : ColorStyle

该属性用于设置图表颜色的样式。

ColorStyle 枚举值之一。

可以通过在系列中显式设置colorStyle 来覆盖此值。

访问函数:

Q3DTheme::ColorStyle colorStyle() const
void setColorStyle(Q3DTheme::ColorStyle style)

通知器信号:

void colorStyleChanged(Q3DTheme::ColorStyle style)

font : QFont

此属性用于指定标签所使用的字体。

访问函数:

QFont font() const
void setFont(const QFont &font)

通知信号:

void fontChanged(const QFont &font)

gridEnabled : bool

该属性控制是否绘制网格线。

该值影响所有网格线。

访问函数:

bool isGridEnabled() const
void setGridEnabled(bool enabled)

通知信号:

void gridEnabledChanged(bool enabled)

gridLineColor : QColor

该属性用于设置网格线的颜色。

注意: 不支持透明度 ,否则将导致未定义行为。

访问函数:

QColor gridLineColor() const
void setGridLineColor(const QColor &color)

通知器信号:

void gridLineColorChanged(const QColor &color)

highlightLightStrength : float

该属性存储所选对象的镜面光强度。

该值必须在0.0f 和10.0f 之间。

访问函数:

float highlightLightStrength() const
void setHighlightLightStrength(float strength)

通知信号:

void highlightLightStrengthChanged(float strength)

labelBackgroundColor : QColor

该属性用于设置标签背景的颜色。

如果labelBackgroundEnabled 的值为false ,则此属性无效。

访问函数:

QColor labelBackgroundColor() const
void setLabelBackgroundColor(const QColor &color)

通知器信号:

void labelBackgroundColorChanged(const QColor &color)

labelBackgroundEnabled : bool

无论标签是绘制在彩色背景上还是完全透明的背景上,此属性均适用。

绘制背景时将使用labelBackgroundColor 的值(包括透明度)。

带有背景的标签会根据最长的标签,按各坐标轴绘制为相同大小,且文本在其中居中显示。没有背景的标签则按原样绘制,并根据其在图表中的位置向左或向右对齐。

访问函数:

bool isLabelBackgroundEnabled() const
void setLabelBackgroundEnabled(bool enabled)

通知信号:

void labelBackgroundEnabledChanged(bool enabled)

labelBorderEnabled : bool

此属性决定是否为带有背景的标签绘制边框。

如果labelBackgroundEnabled 的值为false ,则此属性无效。

访问函数:

bool isLabelBorderEnabled() const
void setLabelBorderEnabled(bool enabled)

通知信号:

void labelBorderEnabledChanged(bool enabled)

labelTextColor : QColor

该属性存储标签所用字体的颜色。

访问函数:

QColor labelTextColor() const
void setLabelTextColor(const QColor &color)

通知信号:

void labelTextColorChanged(const QColor &color)

lightColor : QColor

该属性用于存储环境光和镜面光の色。

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

访问函数:

QColor lightColor() const
void setLightColor(const QColor &color)

通知器信号:

void lightColorChanged(const QColor &color)

lightStrength : float

该属性存储整个图的镜面光强度。

该值必须介于0.0f 和10.0f 之间。

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

访问函数:

float lightStrength() const
void setLightStrength(float strength)

通知信号:

void lightStrengthChanged(float strength)

multiHighlightColor : QColor

该属性用于存储所选对象的高亮颜色。

当selectionMode 设置了QAbstract3DGraph::SelectionRow 或QAbstract3DGraph::SelectionColumn 标志时,该属性才会生效。

访问函数:

QColor multiHighlightColor() const
void setMultiHighlightColor(const QColor &color)

通知器信号:

void multiHighlightColorChanged(const QColor &color)

multiHighlightGradient : QLinearGradient

该属性存储所选对象的高亮渐变。

当selectionMode 设置了QAbstract3DGraph::SelectionRow 或QAbstract3DGraph::SelectionColumn 标志时使用。

访问函数:

QLinearGradient multiHighlightGradient() const
void setMultiHighlightGradient(const QLinearGradient &gradient)

通知器信号:

void multiHighlightGradientChanged(const QLinearGradient &gradient)

singleHighlightColor : QColor

该属性存储所选对象的高亮颜色。

当selectionMode 设置了QAbstract3DGraph::SelectionItem 标志时,该属性才生效。

访问函数:

QColor singleHighlightColor() const
void setSingleHighlightColor(const QColor &color)

通知器信号:

void singleHighlightColorChanged(const QColor &color)

singleHighlightGradient : QLinearGradient

该属性存储所选对象的高亮渐变。

当selectionMode 设置了QAbstract3DGraph::SelectionItem 标志时使用。

访问函数:

QLinearGradient singleHighlightGradient() const
void setSingleHighlightGradient(const QLinearGradient &gradient)

通知信号:

void singleHighlightGradientChanged(const QLinearGradient &gradient)

type : Theme

该属性存储主题的类型。

该类型在构建主题时会自动设置,但之后也可以更改。更改主题类型会将该主题的所有其他属性更改为预定义主题所指定的值。更改图表中当前活动主题的类型,也会重置所有关联的系列,使其使用新的主题。

访问函数:

Q3DTheme::Theme type() const
void setType(Q3DTheme::Theme themeType)

通知信号:

void typeChanged(Q3DTheme::Theme themeType)

windowColor : QColor

该属性保存了绘制图表的应用程序窗口的颜色。

访问函数:

QColor windowColor() const
void setWindowColor(const QColor &color)

通知信号:

void windowColorChanged(const QColor &color)

成员函数文档

[explicit] Q3DTheme::Q3DTheme(QObject *parent = nullptr)

创建一个类型为ThemeUserDefined 的新主题。可以提供可选的parent 参数,该参数随后将传递给QObject 构造函数。

[explicit] Q3DTheme::Q3DTheme(Q3DTheme::Theme themeType, QObject *parent = nullptr)

使用themeType 构建一个新主题,该主题可以是Theme 中列出的内置主题之一。可以提供可选的parent 参数,该参数随后将传递给QObject 构造函数。

[virtual noexcept] Q3DTheme::~Q3DTheme()

破坏了主题。

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