Fluent-Qt

集合视图

FileListView 文件列表

显示文件列表、传输进度和处理状态。

示例

文件列表的真实 Gallery 示例

用法

文件与进度

通过模型角色提供每个文件的说明、状态和进度;用 retryRequested 和 removeRequested 响应重试与移除。

#include <FluentQt/Collections.h>
using namespace fluent::collections;

auto* panel = new QWidget(this);
panel->setMaximumWidth(720);
auto* layout = new QVBoxLayout(panel);
layout->setContentsMargins(0, 0, 0, 0);
layout->setSpacing(16);
auto* model = new QStandardItemModel(panel);
auto addFile = [model](const QString& name, const QString& detail,
                       FileListView::Status state, qreal progress) {
    auto* item = new QStandardItem(name);
    item->setData(detail, FileListView::MetadataRole);
    item->setData(state, FileListView::StatusRole);
    item->setData(progress, FileListView::ProgressRole);
    item->setData(state == FileListView::Rejected, FileListView::RetryableRole);
    model->appendRow(item);
};
addFile("brand-guidelines.pdf", "2.4 MB · Ready to use", FileListView::Ready, 1.0);
addFile("product-shot.png", "3.6 / 5.8 MB · Uploading", FileListView::Uploading, 0.62);
addFile("research-notes-for-the-autumn-product-release-and-accessibility-review.pdf",
        "Connection lost · Retry when you are ready", FileListView::Rejected, 0.0);
auto* files = new FileListView(panel);
files->setObjectName("fileList");
files->setAccessibleName("Transfer examples");
files->setMinimumHeight(240);
files->setBackgroundVisible(false);
files->setBorderVisible(false);
files->setProperty("fluentPreserveParentSurface", true);
files->viewport()->setProperty("fluentPreserveParentSurface", true);
files->setModel(model);
layout->addWidget(files);
QObject::connect(files, &FileListView::removeRequested, panel,
                 [model](const QModelIndex& index) { model->removeRow(index.row()); });
QObject::connect(files, &FileListView::retryRequested, panel,
                 [model](const QModelIndex& index) {
    model->setData(index, FileListView::Uploading, FileListView::StatusRole);
    model->setData(index, false, FileListView::RetryableRole);
    model->setData(index, "Reconnected · Uploading", FileListView::MetadataRole);
    model->setData(index, 0.0, FileListView::ProgressRole);
});
auto* advance = new Button("Advance example transfers", panel);
advance->setObjectName("advanceTransfer");
advance->setFluentStyle(Button::Subtle);
QObject::connect(advance, &Button::clicked, panel, [model]() {
    for (int row = 0; row < model->rowCount(); ++row) {
        const QModelIndex index = model->index(row, 0);
        if (index.data(FileListView::StatusRole).toInt() != FileListView::Uploading)
            continue;
        const qreal progress = qMin(1.0, index.data(FileListView::ProgressRole).toReal() + 0.19);
        model->setData(index, progress, FileListView::ProgressRole);
        model->setData(index, progress >= 1.0 ? "Ready to use" : "Uploading",
                       FileListView::MetadataRole);
        if (progress >= 1.0)
            model->setData(index, FileListView::Ready, FileListView::StatusRole);
    }
});
layout->addWidget(advance, 0, Qt::AlignLeft);

fluent::collections::FileListView

继承自 ListView

从调用方持有的模型展示文件名、传输状态和操作。

构造函数

属性

bool animationEnabled
读取 isAnimationEnabled()设置 setAnimationEnabled()通知 animationEnabledChanged()

方法

void setModel(QAbstractItemModel* model) override

借用模型,不改变其父对象或修改其内容。

void setAnimationEnabled(bool enabled)

在 MotionPolicy 允许时启用短暂的悬停和进度过渡。

信号

void removeRequested(const QModelIndex& index)

请求移除;由应用决定是否修改模型。

void retryRequested(const QModelIndex& index)

请求重试,不启动传输或更改文件状态。

枚举

enum Status

文件展示状态;实际传输由应用负责。

  • Ready = 0
  • Uploading = 1
  • Rejected = 2
enum DataRole

文件 delegate 在 Qt::DisplayRole 之外使用的模型角色。

  • MetadataRole = Qt::UserRole + 1
  • StatusRole
  • ProgressRole
  • RemovableRole
  • RetryableRole

析构函数

子类扩展接口

方法

继承自 fluent::collections::ListView

属性

SelectionMode selectionMode

集合视图使用的选择模式。

读取 selectionMode()设置 setSelectionMode()通知 selectionModeChanged()
Typography::FontRole fontRole

文本绘制使用的 Fluent 排版角色。

读取 fontRole()设置 setFontRole()通知 fontRoleChanged()
int trailingTextRole

可选的行尾辅助文字角色;-1 表示不显示。

读取 trailingTextRole()设置 setTrailingTextRole()通知 trailingTextRoleChanged()
bool viewportHovered

item-view viewport 当前是否处于悬停状态。

读取 viewportHovered()通知 viewportHoveredChanged()
Flow flow

底层 item view 使用的列表流向。

读取 flow()设置 setFlow()通知 flowChanged()
qreal selectedIndicatorProgress

选中项指示器的动画进度。

读取 selectedIndicatorProgress()通知 selectedIndicatorProgressChanged()
IndicatorMotionDirection selectedIndicatorMotionDirection

选中指示器动效使用的方向。

读取 selectedIndicatorMotionDirection()通知 selectedIndicatorMotionDirectionChanged()
bool selectedIndicatorAnimationEnabled

是否启用选中指示器动画。

读取 selectedIndicatorAnimationEnabled()设置 setSelectedIndicatorAnimationEnabled()通知 selectedIndicatorAnimationEnabledChanged()
bool selectionIndicatorVisible

是否绘制选中项指示器。

读取 selectionIndicatorVisible()设置 setSelectionIndicatorVisible()通知 selectionIndicatorVisibleChanged()
bool borderVisible

是否绘制控件外框边线。

读取 borderVisible()设置 setBorderVisible()通知 borderVisibleChanged()
bool backgroundVisible

是否绘制控件背景。

读取 backgroundVisible()设置 setBackgroundVisible()通知 backgroundVisibleChanged()
QWidget* header

承载在 ListView 头部区域的自定义控件。

读取 header()设置 setHeader()通知 headerChanged()
QString headerText

显示在头部区域的便捷标题文本。

读取 headerText()设置 setHeaderText()通知 headerTextChanged()
QString placeholderText

model 没有可展示行时显示的占位文本。

读取 placeholderText()设置 setPlaceholderText()通知 placeholderTextChanged()
bool canReorderItems

是否启用拖拽重排。

读取 canReorderItems()设置 setCanReorderItems()通知 canReorderItemsChanged()
bool scrollChainingEnabled

边界滚轮输入是否允许继续传递给外层滚动容器。

读取 isScrollChainingEnabled()设置 setScrollChainingEnabled()通知 scrollChainingEnabledChanged()
bool sectionEnabled

是否为分组行启用 section header。

读取 sectionEnabled()设置 setSectionEnabled()通知 sectionEnabledChanged()

方法

Flow flow() const

底层 item view 使用的列表流向。

void setFlow(Flow flow)

底层 item view 使用的列表流向。

void setSelectionMode(SelectionMode mode)

集合视图使用的选择模式。

void setFontRole(Typography::FontRole role)

文本绘制使用的 Fluent 排版角色。

int trailingTextRole() const

可选的行尾辅助文字角色;-1 表示不显示。

void setTrailingTextRole(int role)

设置默认 delegate 使用的角色,自定义 delegate 仍由调用方负责。

bool borderVisible() const

是否绘制控件外框边线。

void setBorderVisible(bool visible)

是否绘制控件外框边线。

bool backgroundVisible() const

是否绘制控件背景。

void setBackgroundVisible(bool visible)

是否绘制控件背景。

QWidget* header() const

--- Header / Footer (custom widget API) ---

void setHeader(QWidget* widget)

承载在 ListView 头部区域的自定义控件。

QString headerText() const

--- Header / Footer (convenience text API) ---

void setHeaderText(const QString& text)

显示在头部区域的便捷标题文本。

QString placeholderText() const

model 没有可展示行时显示的占位文本。

void setPlaceholderText(const QString& text)

model 没有可展示行时显示的占位文本。

bool viewportHovered() const

item-view viewport 当前是否处于悬停状态。

bool canReorderItems() const

--- Drag reorder ---

void setCanReorderItems(bool enabled)

是否启用拖拽重排。

bool isScrollChainingEnabled() const

边界滚轮输入是否允许继续传递给外层滚动容器。

void setScrollChainingEnabled(bool enabled)

边界滚轮输入是否允许继续传递给外层滚动容器。

bool sectionEnabled() const

是否为分组行启用 section header。

void setSectionEnabled(bool enabled)

是否为分组行启用 section header。

void setSectionKeyFunction(SectionKeyFunc func)

设置分组 key 回调。相邻行返回相同 key 的归为一组,key 作为 section header 绘制。

int selectedIndex() const

--- Selection API ---

qreal selectedIndicatorProgress() const

--- Selected indicator motion API ---

bool selectedIndicatorAnimationEnabled() const

控制 selected indicator 过渡动画;关闭后选择变更直接落到目标几何,便于确定性测试。

bool selectionIndicatorVisible() const

返回是否绘制选中项指示器。

void setSelectionIndicatorVisible(bool visible)

显示或隐藏指示器,但不改变选择语义。

QRectF selectedIndicatorRect() const

返回当前绘制用的 selected indicator viewport 几何;无可见选中项时为空。

QRectF selectedIndicatorRect(qreal progress) const

返回指定归一化进度下的 selected indicator viewport 几何,供自动化测试验证过渡轨迹。

QRectF selectedIndicatorRectForRow(int row) const

返回指定行的 selected indicator viewport 几何;多选模式用于验证每个选中项自己的 reveal 指示器。

void refreshFluentScrollChrome()

隐藏内置滚动条并刷新 Fluent 滚动条。

信号

void selectionModeChanged()

集合视图使用的选择模式。

void fontRoleChanged()

文本绘制使用的 Fluent 排版角色。

void trailingTextRoleChanged()

可选的行尾辅助文字角色;-1 表示不显示。

void viewportHoveredChanged()

item-view viewport 当前是否处于悬停状态。

void flowChanged()

底层 item view 使用的列表流向。

void borderVisibleChanged()

是否绘制控件外框边线。

void backgroundVisibleChanged()

是否绘制控件背景。

void headerChanged()

承载在 ListView 头部区域的自定义控件。

void headerTextChanged()

显示在头部区域的便捷标题文本。

void placeholderTextChanged()

model 没有可展示行时显示的占位文本。

void canReorderItemsChanged()

是否启用拖拽重排。

void scrollChainingEnabledChanged()

边界滚轮输入是否允许继续传递给外层滚动容器。

void sectionEnabledChanged()

是否为分组行启用 section header。

void selectedIndicatorProgressChanged()

选中项指示器的动画进度。

void selectedIndicatorMotionDirectionChanged()

选中指示器动效使用的方向。

void selectedIndicatorAnimationEnabledChanged()

是否启用选中指示器动画。

void selectionIndicatorVisibleChanged()

是否绘制选中项指示器。

void itemClicked(int index)

与继承的 clicked() 对应,在同一次指针点击中发送一次行号。

枚举

类型与别名

using Flow = QListView::Flow

TopToBottom or LeftToRight

继承自 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 跟随全局主题。

const Colors& themeColorsRef() const

对当前色板的零拷贝访问(用于绘制热路径)。

Material::AcrylicToken themeAcrylic() const

材质、阴影和自适应布局 token。

QColor themeBackdrop(bool active) const

给定激活状态下的窗口 chrome 背景色。

virtual void onThemeUpdated()

全局主题变化后调用。

枚举

enum Theme

解析设计 token 时使用的全局视觉主题。

  • Light = 0
  • Dark = 1
  • HighContrast = 2

类型与别名

struct Colors

返回给组件使用的设计 token 快照。

继承自 fluent::QMLPlus

方法

AnchorLayout::Anchors* anchors()

返回 QWidget 宿主的可变锚点配置。

void setState(const QString& name)

应用具名 state;名称为空时恢复默认状态。

void addState(const QMLState& state)

注册或替换一个具名 state 定义。

void evaluateStates()

重新计算条件;按注册顺序选择首个成立的条件。

QMLPlusRuntime* runtime()

返回按需创建、由宿主持有的状态观察对象。

void setAnchors(const AnchorLayout::Anchors& anchors)

替换宿主的全部锚点,并使父布局失效。

void resetAnchors()

清除宿主全部锚点,并使父布局失效。

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 基类完整成员:QListView