文本输入

NumberBox 数值输入框

输入数值，可以步进或拖动调整。

示例

用法

拖动调整数值

setScrubbingEnabled(true) 开启拖动调整；按住 Shift 微调，按 Esc 恢复开始时的值。

#include <FluentQt/TextFields.h>
using namespace fluent::textfields;

auto* number = new NumberBox(this);
number->setObjectName("scrubNumber");
number->setAccessibleName("Rotation angle");
number->setHeader("Rotation angle");
number->setRange(-180, 180);
number->setValue(30);
number->setScrubbingEnabled(true);
number->setScrubSensitivity(0.5);
number->setDisplayPrecision(1);
number->setFixedWidth(260);

import fluentqt

number = fluentqt.NumberBox()
number.setObjectName("scrubNumber")
number.setAccessibleName("Rotation angle")
number.setHeader("Rotation angle")
number.setRange(-180, 180)
number.setValue(30)
number.setScrubbingEnabled(True)
number.setScrubSensitivity(0.5)
number.setDisplayPrecision(1)
number.setFixedWidth(260)

API

查看声明

`fluent::textfields::NumberBox`

继承自 LineEdit

支持数值边界、表达式输入和步进按钮的数值输入框。

构造函数

explicit NumberBox(QWidget* parent = nullptr)

属性

double value: 输入框当前提交的数值。
读取 value()设置 setValue()通知 valueChanged()
double minimum: 用于限制输入值和步进值的下边界。
读取 minimum()设置 setMinimum()通知 minimumChanged()
double maximum: 用于限制输入值和步进值的上边界。
读取 maximum()设置 setMaximum()通知 maximumChanged()
double smallChange: 单次步进按钮点击或小键盘步进使用的增量。
读取 smallChange()设置 setSmallChange()通知 smallChangeChanged()
double largeChange: 大步进键盘操作使用的增量。
读取 largeChange()设置 setLargeChange()通知 largeChangeChanged()
QString header: 显示在数值输入行上方的可选标签文本。
读取 header()设置 setHeader()通知 headerChanged()
bool acceptsExpression: 输入的算术表达式是否在提交前求值。
读取 acceptsExpression()设置 setAcceptsExpression()通知 acceptsExpressionChanged()
SpinButtonPlacementMode spinButtonPlacementMode: 步进按钮的隐藏、紧凑或内联布局模式。
读取 spinButtonPlacementMode()设置 setSpinButtonPlacementMode()通知 spinButtonPlacementModeChanged()
QSize spinButtonSize: 外部步进按钮的尺寸。
读取 spinButtonSize()设置 setSpinButtonSize()通知 spinButtonSizeChanged()
QSize inlineSpinButtonSize: 内联步进按钮的尺寸。
读取 inlineSpinButtonSize()设置 setInlineSpinButtonSize()通知 inlineSpinButtonSizeChanged()
int spinButtonRightMargin: 内联步进按钮与输入框右边框之间预留的间距。
读取 spinButtonRightMargin()设置 setSpinButtonRightMargin()通知 spinButtonRightMarginChanged()
int compactSpinButtonReservedWidth: 紧凑模式下输入表面为步进按钮预留的宽度。
读取 compactSpinButtonReservedWidth()设置 setCompactSpinButtonReservedWidth()通知 compactSpinButtonReservedWidthChanged()
int spinButtonSpacing: 相邻步进按钮之间的间距。
读取 spinButtonSpacing()设置 setSpinButtonSpacing()通知 spinButtonSpacingChanged()
int spinButtonTextGap: 文本内容与内联步进按钮外观之间的间距。
读取 spinButtonTextGap()设置 setSpinButtonTextGap()通知 spinButtonTextGapChanged()
int spinButtonIconSize: 步进按钮箭头图标使用的字符尺寸。
读取 spinButtonIconSize()设置 setSpinButtonIconSize()通知 spinButtonIconSizeChanged()
int displayPrecision: 格式化数值时保留的小数位数。
读取 displayPrecision()设置 setDisplayPrecision()通知 displayPrecisionChanged()
double formatStep: 数值变化后用于规范显示舍入的步长。
读取 formatStep()设置 setFormatStep()通知 formatStepChanged()
bool scrubbingEnabled: 启用独立的水平拖拽柄，保留原有文本选择行为。
读取 isScrubbingEnabled()设置 setScrubbingEnabled()通知 scrubbingEnabledChanged()
double scrubSensitivity: 每逻辑像素对应的数值增量，必须有限且为正数。
读取 scrubSensitivity()设置 setScrubSensitivity()通知 scrubSensitivityChanged()
bool scrubbing: 当前是否正在进行拖拽编辑。
读取 isScrubbing()通知 scrubbingChanged()

方法

double value() const: 输入框当前提交的数值。
void setValue(double value): 输入框当前提交的数值。
double minimum() const: 用于限制输入值和步进值的下边界。
void setMinimum(double minimum): 用于限制输入值和步进值的下边界。
double maximum() const: 用于限制输入值和步进值的上边界。
void setMaximum(double maximum): 用于限制输入值和步进值的上边界。
void setRange(double minimum, double maximum)
double smallChange() const: 单次步进按钮点击或小键盘步进使用的增量。
void setSmallChange(double change): 单次步进按钮点击或小键盘步进使用的增量。
double largeChange() const: 大步进键盘操作使用的增量。
void setLargeChange(double change): 大步进键盘操作使用的增量。
QString header() const: 显示在数值输入行上方的可选标签文本。
void setHeader(const QString& header): 显示在数值输入行上方的可选标签文本。
bool acceptsExpression() const: 输入的算术表达式是否在提交前求值。
void setAcceptsExpression(bool accepts): 输入的算术表达式是否在提交前求值。
SpinButtonPlacementMode spinButtonPlacementMode() const: 步进按钮的隐藏、紧凑或内联布局模式。
void setSpinButtonPlacementMode(SpinButtonPlacementMode mode): 步进按钮的隐藏、紧凑或内联布局模式。
QSize spinButtonSize() const: 外部步进按钮的尺寸。
void setSpinButtonSize(const QSize& size): 外部步进按钮的尺寸。
QSize inlineSpinButtonSize() const: 内联步进按钮的尺寸。
void setInlineSpinButtonSize(const QSize& size): 内联步进按钮的尺寸。
int spinButtonRightMargin() const: 内联步进按钮与输入框右边框之间预留的间距。
void setSpinButtonRightMargin(int margin): 内联步进按钮与输入框右边框之间预留的间距。
int compactSpinButtonReservedWidth() const: 紧凑模式下输入表面为步进按钮预留的宽度。
void setCompactSpinButtonReservedWidth(int width): 紧凑模式下输入表面为步进按钮预留的宽度。
int spinButtonSpacing() const: 相邻步进按钮之间的间距。
void setSpinButtonSpacing(int spacing): 相邻步进按钮之间的间距。
int spinButtonTextGap() const: 文本内容与内联步进按钮外观之间的间距。
void setSpinButtonTextGap(int gap): 文本内容与内联步进按钮外观之间的间距。
int spinButtonIconSize() const: 步进按钮箭头图标使用的字符尺寸。
void setSpinButtonIconSize(int size): 步进按钮箭头图标使用的字符尺寸。
int displayPrecision() const: 格式化数值时保留的小数位数。
void setDisplayPrecision(int precision): 格式化数值时保留的小数位数。
double formatStep() const: 数值变化后用于规范显示舍入的步长。
void setFormatStep(double step): 数值变化后用于规范显示舍入的步长。
bool isScrubbingEnabled() const: 启用独立的水平拖拽柄，保留原有文本选择行为。
void setScrubbingEnabled(bool enabled): 启用独立的水平拖拽柄，保留原有文本选择行为。
double scrubSensitivity() const: 每逻辑像素对应的数值增量，必须有限且为正数。
void setScrubSensitivity(double sensitivity): 每逻辑像素对应的数值增量，必须有限且为正数。
bool isScrubbing() const: 当前是否正在进行拖拽编辑。
QRect scrubHandleRect() const: 拖拽柄的逻辑坐标区域，未启用时为空。
void cancelScrub(): 回滚当前拖拽，包括恢复开始时的空值。
void commitInput(): 按数值范围和表达式规则提交当前文本；无效输入保留文本并将值设为 NaN，未编辑的格式化文本保留原始精度，不修改外部模型。
QSize sizeHint() const override
QSize minimumSizeHint() const override
void onThemeUpdated() override

信号

void valueChanged(double value): 输入框当前提交的数值。
void minimumChanged(double minimum): 用于限制输入值和步进值的下边界。
void maximumChanged(double maximum): 用于限制输入值和步进值的上边界。
void smallChangeChanged(double change): 单次步进按钮点击或小键盘步进使用的增量。
void largeChangeChanged(double change): 大步进键盘操作使用的增量。
void headerChanged(): 显示在数值输入行上方的可选标签文本。
void acceptsExpressionChanged(bool accepts): 输入的算术表达式是否在提交前求值。
void spinButtonPlacementModeChanged(SpinButtonPlacementMode mode): 步进按钮的隐藏、紧凑或内联布局模式。
void spinButtonSizeChanged(const QSize& size): 外部步进按钮的尺寸。
void inlineSpinButtonSizeChanged(const QSize& size): 内联步进按钮的尺寸。
void spinButtonRightMarginChanged(int margin): 内联步进按钮与输入框右边框之间预留的间距。
void compactSpinButtonReservedWidthChanged(int width): 紧凑模式下输入表面为步进按钮预留的宽度。
void spinButtonSpacingChanged(int spacing): 相邻步进按钮之间的间距。
void spinButtonTextGapChanged(int gap): 文本内容与内联步进按钮外观之间的间距。
void spinButtonIconSizeChanged(int size): 步进按钮箭头图标使用的字符尺寸。
void displayPrecisionChanged(int precision): 格式化数值时保留的小数位数。
void formatStepChanged(double step): 数值变化后用于规范显示舍入的步长。
void scrubbingEnabledChanged(bool enabled): 启用独立的水平拖拽柄，保留原有文本选择行为。
void scrubSensitivityChanged(double sensitivity): 每逻辑像素对应的数值增量，必须有限且为正数。
void scrubbingChanged(bool scrubbing): 当前是否正在进行拖拽编辑。
void scrubStarted(double initialValue): 一次编辑开始；valueChanged 仍报告每次实时值变化。
void scrubFinished(double initialValue, double finalValue, bool canceled): 一次编辑结束；取消时在此信号之前恢复初始值。

枚举

enum class SpinButtonPlacementMode: Hidden
Compact
Inline

子类扩展接口

方法

QRect trailingContentBounds() const override
void trailingContentGeometryChanged() override
bool event(QEvent* event) override
void paintEvent(QPaintEvent* event) override
void resizeEvent(QResizeEvent* event) override
void focusInEvent(QFocusEvent* event) override
void focusOutEvent(QFocusEvent* event) override
void enterEvent(FluentEnterEvent* event) override
void leaveEvent(QEvent* event) override
void mousePressEvent(QMouseEvent* event) override
void mouseMoveEvent(QMouseEvent* event) override
void mouseReleaseEvent(QMouseEvent* event) override
void keyPressEvent(QKeyEvent* event) override
void changeEvent(QEvent* event) override
bool eventFilter(QObject* watched, QEvent* event) override
void paintFrame(QPainter& painter) override

继承自 fluent::textfields::LineEdit

属性

QMargins contentMargins: 内容边距；水平值已包含 Qt 内部文字留白，零值不会重复增加原生边距。
读取 contentMargins()设置 setContentMargins()通知 contentMarginsChanged()
Typography::FontRole fontRole: 文本绘制使用的 Fluent 排版角色。
读取 fontRole()设置 setFontRole()通知 fontRoleChanged()
bool clearButtonEnabled: 尾部清除按钮是否启用。
读取 isClearButtonEnabled()设置 setClearButtonEnabled()通知 clearButtonEnabledChanged()
int clearButtonSize: 清除按钮尺寸，默认为 24 个逻辑像素。
读取 clearButtonSize()设置 setClearButtonSize()通知 clearButtonSizeChanged()
QPoint clearButtonOffset: 清除按钮应用的像素偏移。
读取 clearButtonOffset()设置 setClearButtonOffset()通知 clearButtonOffsetChanged()
int focusedBorderWidth: 聚焦时底部边框宽度。
读取 focusedBorderWidth()设置 setFocusedBorderWidth()通知 focusedBorderWidthChanged()
int unfocusedBorderWidth: 未聚焦时底部边框宽度。
读取 unfocusedBorderWidth()设置 setUnfocusedBorderWidth()通知 unfocusedBorderWidthChanged()
bool frameVisible: LineEdit 是否绘制输入框外框和焦点下划线。
读取 isFrameVisible()设置 setFrameVisible()通知 frameVisibleChanged()
QString trailingText: 读取 trailingText()设置 setTrailingText()通知 trailingTextChanged()
QWidget* trailingWidget: 读取 trailingWidget()通知 trailingWidgetChanged()
fluent::WidgetOwnership trailingWidgetOwnership: 读取 trailingWidgetOwnership()通知 trailingWidgetOwnershipChanged()
QString clearButtonAccessibleName: 读取 clearButtonAccessibleName()设置 setClearButtonAccessibleName()通知 clearButtonAccessibleNameChanged()
Qt::FocusPolicy clearButtonFocusPolicy: 读取 clearButtonFocusPolicy()设置 setClearButtonFocusPolicy()通知 clearButtonFocusPolicyChanged()

方法

QSize sizeHint() const override
QSize minimumSizeHint() const override
void onThemeUpdated() override
QMargins contentMargins() const: 内容边距；水平值已包含 Qt 内部文字留白，零值不会重复增加原生边距。
void setContentMargins(const QMargins& margins): 内容边距；水平值已包含 Qt 内部文字留白，零值不会重复增加原生边距。
Typography::FontRole fontRole() const: 文本绘制使用的 Fluent 排版角色。
void setFontRole(Typography::FontRole role): 文本绘制使用的 Fluent 排版角色。
bool isClearButtonEnabled() const: 尾部清除按钮是否启用。
void setClearButtonEnabled(bool enabled): 尾部清除按钮是否启用。
int clearButtonSize() const: 清除按钮尺寸，默认为 24 个逻辑像素。
void setClearButtonSize(int size): 清除按钮尺寸，默认为 24 个逻辑像素。
QPoint clearButtonOffset() const: 清除按钮应用的像素偏移。
void setClearButtonOffset(const QPoint& offset): 清除按钮应用的像素偏移。
int focusedBorderWidth() const: 聚焦时底部边框宽度。
void setFocusedBorderWidth(int width): 聚焦时底部边框宽度。
int unfocusedBorderWidth() const: 未聚焦时底部边框宽度。
void setUnfocusedBorderWidth(int width): 未聚焦时底部边框宽度。
bool isFrameVisible() const: LineEdit 是否绘制输入框外框和焦点下划线。
void setFrameVisible(bool visible): LineEdit 是否绘制输入框外框和焦点下划线。
QString trailingText() const
void setTrailingText(const QString& text): 显示纯文字尾缀，不改变可编辑值，并替换已承载的控件内容。
QWidget* trailingWidget() const
WidgetOwnership trailingWidgetOwnership() const
bool setTrailingWidget(QWidget* widget, WidgetOwnership ownership): 按显式所有权承载一个尾部控件；拒绝宿主自身及祖先控件。
QWidget* takeTrailingWidget(): 脱离并将自定义尾部控件交回调用方。
void releaseTrailingWidget(): 按记录的所有权策略释放自定义尾部内容。
QString clearButtonAccessibleName() const
void setClearButtonAccessibleName(const QString& name)
Qt::FocusPolicy clearButtonFocusPolicy() const
void setClearButtonFocusPolicy(Qt::FocusPolicy policy)

信号

void contentMarginsChanged(): 内容边距；水平值已包含 Qt 内部文字留白，零值不会重复增加原生边距。
void fontRoleChanged(): 文本绘制使用的 Fluent 排版角色。
void clearButtonEnabledChanged(): 尾部清除按钮是否启用。
void clearButtonSizeChanged(): 清除按钮尺寸，默认为 24 个逻辑像素。
void clearButtonOffsetChanged(): 清除按钮应用的像素偏移。
void focusedBorderWidthChanged(): 聚焦时底部边框宽度。
void unfocusedBorderWidthChanged(): 未聚焦时底部边框宽度。
void frameVisibleChanged(): LineEdit 是否绘制输入框外框和焦点下划线。
void trailingTextChanged()
void trailingWidgetChanged()
void trailingWidgetOwnershipChanged()
void clearButtonAccessibleNameChanged()
void clearButtonFocusPolicyChanged()

继承自 fluent::FluentElement

方法

static void setTheme(Theme theme): 更新全局主题，并通知所有活跃的 FluentElement 实例。
static void setThemeDeferred(Theme theme): 以可见元素优先的批次调度主题刷新，避免阻塞当前交互。
static Theme currentTheme(): 返回当前生效的全局主题。
static bool themeUsesDarkAppearance(Theme theme): 返回指定主题是否使用暗色底的 chrome 与材质 token。
static void refreshTheme(): 在设计 token 变化后重新广播当前主题以触发重绘。
static int themeGeneration(): 每次主题变化自增的单调计数器，用于过期判断。
Theme effectiveTheme() const: 解析此元素实际使用的主题，会优先读取 QWidget 父链上的局部主题覆盖。
bool effectiveThemeUsesDarkAppearance() const: 返回此元素的实际主题是否使用暗色底 chrome。
bool setThemeOverrides(const QJsonObject& overrides): 供组件侧访问的设计 token 接口。
QJsonObject themeOverrides() const: 返回当前元素的覆盖配置。
void clearThemeOverrides(): 恢复全部 token 跟随全局主题。
Colors themeColors() const
const Colors& themeColorsRef() const: 对当前色板的零拷贝访问（用于绘制热路径）。
FontStyle themeFont(Typography::FontRole role = Typography::FontRole::Body) const
Radius themeRadius() const
Spacing themeSpacing() const
Animation themeAnimation() const
Material::AcrylicToken themeAcrylic() const: 材质、阴影和自适应布局 token。
Material::MicaToken themeMica() const
Material::SmokeToken themeSmoke() const
Elevation::ShadowParams themeShadow(Elevation::Level level) const
int themeBreakpoint(Breakpoints::Breakpoint breakpoint = Breakpoints::Breakpoint::Medium) const
QColor themeBackdrop(bool active) const: 给定激活状态下的窗口 chrome 背景色。
virtual void onThemeUpdated(): 全局主题变化后调用。

枚举

enum Theme: 解析设计 token 时使用的全局视觉主题。
Light = 0
Dark = 1
HighContrast = 2

类型与别名

struct Colors: 返回给组件使用的设计 token 快照。
struct FontStyle
struct Radius
struct Spacing
struct Animation

继承自 fluent::QMLPlus

方法

AnchorLayout::Anchors* anchors(): 返回 QWidget 宿主的可变锚点配置。
void setState(const QString& name): 应用具名 state；名称为空时恢复默认状态。
QString state() const
void addState(const QMLState& state): 注册或替换一个具名 state 定义。
void evaluateStates(): 重新计算条件；按注册顺序选择首个成立的条件。
QMLPlusRuntime* runtime(): 返回按需创建、由宿主持有的状态观察对象。
void setAnchors(const AnchorLayout::Anchors& anchors): 替换宿主的全部锚点，并使父布局失效。
void resetAnchors(): 清除宿主全部锚点，并使父布局失效。
void bind(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction dir = PropertyBinder::OneWay): 将 source 属性绑定到 QWidget 宿主上的 target 属性。
BindingHandle bindManaged(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction direction = PropertyBinder::OneWay, BindingOptions options = {}): 在当前 QWidget 宿主上安装可管理的直接绑定。
BindingHandle bindComputed(const char* targetProp, const QVector<BindingDependency>& dependencies, std::function<QVariant()> evaluate, BindingOptions options = {}): 在当前 QWidget 宿主上安装使用显式依赖的 C++ 表达式绑定。
void addTransition(const StateTransition& transition): 按优先顺序注册状态过渡。
void setBehavior(const char* propertyName, const PropertyAnimation& animation): 设置宿主受管理属性写入时使用的默认动画。
void clearBehavior(const char* propertyName): 移除后续受管理写入使用的默认动画。
bool writeProperty(const char* propertyName, const QVariant& value): 通过 Behavior 写入宿主属性，且不移除该属性的绑定。

Qt 基类完整成员：QLineEdit