Column

Column 是一种将其子项沿单个列定位的类型。它是不使用锚点的情况下垂直定位一系列项目的便捷方式。

add : Transition

bottomPadding : real

leftPadding : real

move : Transition

padding : real

populate : Transition

rightPadding : real

spacing : real

topPadding : real

Rectangle（矩形）：用于创建矩形区域，可以设置其颜色、边框等属性。

属性：

基础属性

id：这是一个字符串类型的属性，用于在 QML 中唯一标识该矩形。

objectName：同样是字符串类型，主要用于在 C++ 代码里查找这个矩形。

位置与大小属性

x、y：均为实数类型，分别代表矩形左上角的水平和垂直坐标。

width、height：也是实数类型，分别表示矩形的宽度和高度。

implicitWidth、implicitHeight：这两个是只读的实数属性，代表矩形的默认宽度和高度。

visible：布尔类型，用于控制矩形是否可见，默认值为 true。

opacity：实数类型，取值范围是 0.0（完全透明）到 1.0（完全不透明），用于设置矩形的不透明度。

clip：布尔类型，若设为 true，超出矩形边界的内容将被裁剪掉，默认是 false。

z：整数类型，用于确定矩形在 Z 轴方向上的堆叠顺序，数值大的会显示在上面。

外观属性

color：颜色类型，用于设置矩形的填充颜色，默认是 transparent（透明）。

border.color：颜色类型，用于设置矩形边框的颜色。

border.width：实数类型，用于设置矩形边框的宽度，默认是 0。

radius：实数类型，用于设置矩形的圆角半径，默认是 0。

gradient：Gradient 类型，用于为矩形设置渐变效果，设置了渐变后，color 属性会被忽略。

smooth：布尔类型，若设为 true，会对矩形边缘进行抗锯齿处理，默认是 false。

antialiasing：布尔类型，用于控制是否开启抗锯齿，默认是 false。

交互属性

enabled：布尔类型，若设为 false，矩形将无法响应用户交互，默认是 true。

hoverEnabled：布尔类型，若设为 true，矩形可以检测鼠标悬停状态。

focus：布尔类型，若设为 true，矩形能够获得键盘焦点。

focusPolicy：FocusPolicy 枚举类型，用于控制矩形获取焦点的方式。

状态与动画属性

states：状态列表，用于定义矩形的不同状态。

transitions：过渡效果列表，用于定义状态切换时的动画效果。

scale：实数类型，用于设置矩形的缩放比例，默认是 1.0。

rotation：实数类型，用于设置矩形的旋转角度，单位是度，默认是 0。

transformOrigin：TransformOrigin 枚举类型，用于设置变换的原点位置。

子元素与布局属性

children：子元素列表，包含了矩形内的所有子项。

data：数据列表，用于添加不能作为视觉子项的内容。

anchors：锚点系统，用于将矩形相对于其他元素进行定位。

Layout.alignment：布局对齐方式，用于在布局中设置矩形的对齐方式。

事件处理属性

onClicked：点击事件处理函数。

onDoubleClicked：双击事件处理函数。

onPressed：按下事件处理函数。

onReleased：释放事件处理函数。

onHoveredChanged：鼠标悬停状态改变事件处理函数。

onActiveFocusChanged：焦点状态改变事件处理函数。

高级属性

layer：ItemLayer 类型，用于设置矩形的高级视觉效果，像阴影、模糊等。

opacityMask：Brush 类型，用于设置基于遮罩的透明度效果。

renderType：RenderType 枚举类型，用于控制矩形的渲染方式。

renderTarget：RenderTarget 枚举类型，用于指定矩形的渲染目标。

Text（文本）：用于显示文本内容，可以设置字体、颜色、大小等属性。

Image（图像）：用于显示图像，可以设置其来源、宽度、高度等属性。

图像源与加载属性

source：字符串类型，用于指定图像的源文件路径，可以是本地文件路径、网络 URL 或者资源路径（如 qrc:/image.png）。

sourceSize：size 类型，可设置图像的原始大小，若未设置，则使用图像的实际大小。

fillMode：Image.FillMode 枚举类型，用于控制图像的填充方式，其值有：

Image.Stretch：直接拉伸图像，可能会导致图像变形。

Image.PreserveAspectFit：保持图像的宽高比进行缩放，使图像完全适应容器，但可能会在容器内留下空白。

Image.PreserveAspectCrop：保持图像的宽高比进行缩放，使图像填满容器，超出容器的部分会被裁剪掉。

Image.Tile：横向和纵向重复平铺图像。

Image.TileVertically：仅纵向重复平铺图像。

Image.TileHorizontally：仅横向重复平铺图像。

smooth：布尔类型，若设为 true，会对图像进行平滑处理，提升缩放后的图像质量，默认值是 false。

cache：布尔类型，若设为 true，图像会被缓存起来，以便后续重用，默认值是 true。

mirror：布尔类型，若设为 true，图像会水平翻转，默认值是 false。

asynchronous：布尔类型，若设为 true，图像会异步加载，避免阻塞 UI 线程，默认值是 false。

status：Image.Status 枚举类型，用于表示图像的加载状态，其值有：

Image.Null：初始状态。

Image.Ready：图像已成功加载。

Image.Loading：图像正在加载中。

Image.Error：图像加载过程中出现错误。

progress：实数类型，用于表示图像加载的进度，范围是 0.0（未开始加载）到 1.0（加载完成）。

errorString：字符串类型，当图像加载出错时，该属性会包含错误信息。

位置与大小属性

x、y：实数类型，分别表示图像左上角的水平和垂直坐标。

width、height：实数类型，分别表示图像的显示宽度和高度。若未设置这两个属性，图像会以原始大小显示；若只设置了其中一个属性，另一个属性会按原始宽高比自动计算；若两个属性都设置了，图像会根据 fillMode 进行缩放。

implicitWidth、implicitHeight：只读的实数属性，分别表示图像的原始宽度和高度。

visible：布尔类型，用于控制图像是否可见，默认值是 true。

opacity：实数类型，取值范围是 0.0（完全透明）到 1.0（完全不透明），用于设置图像的不透明度。

clip：布尔类型，若设为 true，超出图像边界的内容将被裁剪掉，默认值是 false。

z：整数类型，用于确定图像在 Z 轴方向上的堆叠顺序，数值大的会显示在上面。

交互属性

enabled：布尔类型，若设为 false，图像将无法响应用户交互，默认值是 true。

hoverEnabled：布尔类型，若设为 true，图像可以检测鼠标悬停状态。

focus：布尔类型，若设为 true，图像能够获得键盘焦点。

focusPolicy：FocusPolicy 枚举类型，用于控制图像获取焦点的方式。

状态与动画属性

states：状态列表，用于定义图像的不同状态。

transitions：过渡效果列表，用于定义状态切换时的动画效果。

scale：实数类型，用于设置图像的缩放比例，默认值是 1.0。

rotation：实数类型，用于设置图像的旋转角度，单位是度，默认值是 0。

transformOrigin：TransformOrigin 枚举类型，用于设置变换的原点位置。

子元素与布局属性

children：子元素列表，包含了图像内的所有子项。

data：数据列表，用于添加不能作为视觉子项的内容。

anchors：锚点系统，用于将图像相对于其他元素进行定位。

Layout.alignment：布局对齐方式，用于在布局中设置图像的对齐方式。

事件处理属性

onClicked：点击事件处理函数。

onDoubleClicked：双击事件处理函数。

onPressed：按下事件处理函数。

onReleased：释放事件处理函数。

onHoveredChanged：鼠标悬停状态改变事件处理函数。

onActiveFocusChanged：焦点状态改变事件处理函数。

onStatusChanged：图像加载状态改变事件处理函数。

高级属性

layer：ItemLayer 类型，用于设置图像的高级视觉效果，像阴影、模糊等。

opacityMask：Brush 类型，用于设置基于遮罩的透明度效果。

renderType：RenderType 枚举类型，用于控制图像的渲染方式。

renderTarget：RenderTarget 枚举类型，用于指定图像的渲染目标。

MouseArea 是用于处理鼠标事件的交互元素

基础属性

id

字符串类型，唯一标识组件。

objectName

字符串类型，用于 C++ 查找对象。

位置与大小属性

x、y

实数类型，鼠标区域的左上角坐标（相对于父元素）。

width、height

实数类型，鼠标区域的宽高。若未设置，则默认为父元素的大小。

anchors

锚点系统，用于定位和调整大小（如 anchors.fill: parent）。

交互属性

enabled

布尔类型，是否启用鼠标事件处理，默认 true。

visible

布尔类型，是否可见（仅影响子元素，自身不可见），默认 false。

hoverEnabled

布尔类型，是否跟踪鼠标悬停状态，默认 false。

pressAndHoldThreshold

实数类型，长按识别的时间阈值（毫秒），默认 800。

drag

Drag 对象，配置拖放行为（如 drag.target、drag.axis）。

acceptedButtons

位掩码类型，接受的鼠标按钮（如 Qt.LeftButton | Qt.RightButton）。

ignoreEvents

布尔类型，是否忽略鼠标事件（但仍响应悬停），默认 false。

状态属性

pressed

布尔类型，鼠标按钮是否被按下。

containsMouse

布尔类型，鼠标是否在区域内（需 hoverEnabled: true）。

hovered

布尔类型，鼠标是否悬停在区域上（需 hoverEnabled: true）。

underMouse

布尔类型，鼠标是否直接在区域上（忽略子元素）。

mouseX、mouseY

实数类型，鼠标在区域内的坐标（仅在按下或悬停时有效）。

mouse.button

Qt.MouseButton 枚举类型，当前按下的鼠标按钮。

wheelDelta

整数类型，鼠标滚轮滚动的增量值。

信号与事件处理

onPressed

信号处理函数，鼠标按下时触发。

onReleased

信号处理函数，鼠标释放时触发。

onClicked

信号处理函数，点击（按下并释放）时触发。

onDoubleClicked

信号处理函数，双击时触发。

onPositionChanged

信号处理函数，鼠标位置变化时触发。

onEntered

信号处理函数，鼠标进入区域时触发（需 hoverEnabled: true）。

onExited

信号处理函数，鼠标离开区域时触发（需 hoverEnabled: true）。

onWheel

信号处理函数，鼠标滚轮滚动时触发。

onPressAndHold

信号处理函数，长按（按住超过阈值）时触发。

拖放属性

drag.target

Item 类型，拖放操作的目标元素。

drag.axis

Drag.Axis 枚举类型，允许的拖动方向：

Drag.XAndYAxis（默认）：自由拖动。

Drag.XAxis：仅水平拖动。

Drag.YAxis：仅垂直拖动。

drag.minimumX、drag.minimumY

实数类型，拖动的最小坐标限制。

drag.maximumX、drag.maximumY

实数类型，拖动的最大坐标限制。

drag.snapX、drag.snapY

布尔类型，是否吸附到网格。

drag.snapDistance

实数类型，吸附距离阈值。

drag.active

布尔类型，拖放操作是否正在进行中。

高级属性

cursorShape

Qt.CursorShape 枚举类型，鼠标悬停时的光标形状（如 Qt.PointingHandCursor）。

parent

Item 类型，父元素。

z

整数类型，Z 轴堆叠顺序。

acceptedModifiers

位掩码类型，接受的键盘修饰键（如 Qt.ControlModifier）。

children

Item 列表，子元素（通常为空，因 MouseArea 不可见）。

Button（按钮）：用于创建按钮，可以设置按钮的文本、样式、点击事件等属性。

id

字符串类型，唯一标识组件。

objectName

字符串类型，用于 C++ 查找对象。

外观属性

background

Item 类型，按钮的背景元素（可自定义）。

contentItem

Item 类型，按钮的内容元素（如文本或图标）。

width、height

实数类型，按钮的宽高。

implicitWidth、implicitHeight

只读实数，默认宽高。

enabled

布尔类型，是否启用交互（禁用时变灰），默认true。

visible

布尔类型，是否可见，默认true。

opacity

实数类型，透明度（0.0~1.0）。

z

整数类型，Z 轴堆叠顺序。

文本与图标属性

text

字符串类型，按钮显示的文本。

font

Font 类型，文本字体（如font.pixelSize、font.family）。

textColor

颜色类型，文本颜色。

icon.source

字符串类型，图标源路径（图像文件或资源路径）。

icon.width、icon.height

实数类型，图标宽高。

icon.mirror

布尔类型，图标是否水平镜像。

状态属性

pressed

布尔类型，按钮是否被按下。

hovered

布尔类型，鼠标是否悬停（需hoverEnabled: true）。

checked

布尔类型，按钮是否处于选中状态（用于 toggle 按钮）。

checkable

布尔类型，按钮是否可切换状态，默认false。

flat

布尔类型，是否为扁平化样式（无边框），默认false。

交互属性

onClicked

信号处理函数，点击时触发。

onPressed

信号处理函数，按下时触发。

onReleased

信号处理函数，释放时触发。

onToggled

信号处理函数，状态切换时触发（仅checkable为true时有效）。

repeat

布尔类型，长按是否重复触发点击事件，默认false。

keyNavigationEnabled

布尔类型，是否支持键盘导航（如 Tab 键），默认true。

布局属性

anchors

锚点系统，用于定位。

Layout.fillWidth、Layout.fillHeight

布尔类型，是否填充布局空间。

Layout.preferredWidth、Layout.preferredHeight

实数类型，布局中的首选宽高。

Layout.minimumWidth、Layout.minimumHeight

实数类型，布局中的最小宽高。

Layout.maximumWidth、Layout.maximumHeight

实数类型，布局中的最大宽高。

高级属性

state

字符串类型，自定义状态名称（需配合states属性使用）。

states

State 列表，定义按钮的不同状态。

transitions

Transition 列表，定义状态切换的动画效果。

focus

布尔类型，是否获取焦点。

clip

布尔类型，是否裁剪超出边界的内容。

平台风格属性

style

Style 类型，自定义按钮样式（覆盖默认风格）。

styleData

只读对象，包含按钮的风格数据（如styleData.pressed）。

TextInput（文本输入框）：用于接收用户输入的文本，可以设置其提示文字、样式等属性。

对象文本内容属性

text

字符串类型，输入框中的文本内容。

placeholderText

字符串类型，当输入框为空时显示的占位文本。

echoMode

TextInput.EchoMode 枚举类型，控制文本显示方式：

TextInput.Normal（默认）：正常显示。

TextInput.Password：用密码掩码显示。

TextInput.NoEcho：不显示任何内容。

TextInput.PasswordEchoOnEdit：编辑时显示，之后转为密码掩码。

inputMethodHints

位掩码类型，设置输入法提示（如 Qt.ImhDigitsOnly 仅允许数字）。

外观属性

background

Item 类型，输入框的背景元素（可自定义）。

contentItem

Item 类型，文本内容的显示元素。

width、height

实数类型，输入框的宽高。

implicitWidth、implicitHeight

只读实数，默认宽高。

visible

布尔类型，是否可见，默认 true。

opacity

实数类型，透明度（0.0~1.0）。

z

整数类型，Z 轴堆叠顺序。

文本样式属性

font

Font 类型，文本字体（如 font.pixelSize、font.family）。

color

颜色类型，文本颜色。

selectionColor

颜色类型，选中文本的前景色。

selectedTextColor

颜色类型，选中文本的背景色。

placeholderTextColor

颜色类型，占位文本的颜色。

光标属性

cursorVisible

布尔类型，光标是否可见，默认 true。

cursorPosition

整数类型，光标的位置索引。

selectionStart

整数类型，选中文本的起始位置。

selectionLength

整数类型，选中文本的长度。

cursorRectangle

只读 rect 类型，光标所在的矩形区域。

cursorWidth

实数类型，光标的宽度，默认 1px。

输入控制属性

enabled

布尔类型，是否启用输入，默认 true。

readOnly

布尔类型，是否为只读模式，默认 false。

maximumLength

整数类型，允许输入的最大字符数（0 表示无限制）。

validator

Validator 类型，输入验证器（如 IntValidator、RegExpValidator）。

inputMask

字符串类型，输入掩码（如电话号码格式 999-9999）。

交互属性

focus

布尔类型，是否获取焦点。

editable

布尔类型，是否可编辑，默认 true。

selectByMouse

布尔类型，是否允许鼠标选择文本，默认 true。

mouseSelectionMode

TextInput.SelectionMode 枚举类型，鼠标选择模式：

TextInput.SelectCharacters（默认）：逐个字符选择。

TextInput.SelectWords：按单词选择。

TextInput.SelectLines：按行选择。

wrapMode

TextInput.WrapMode 枚举类型，文本换行模式（单行输入框通常不生效）。

信号与事件

onTextChanged

信号处理函数，文本内容变化时触发。

onEditingFinished

信号处理函数，编辑完成时触发（如按下 Enter 或失去焦点）。

onCursorPositionChanged

信号处理函数，光标位置变化时触发。

onSelectionChanged

信号处理函数，选中文本变化时触发。

布局属性

anchors

锚点系统，用于定位。

Layout.fillWidth、Layout.fillHeight

布尔类型，是否填充布局空间。

Layout.preferredWidth、Layout.preferredHeight

实数类型，布局中的首选宽高。

Layout.minimumWidth、Layout.minimumHeight

实数类型，布局中的最小宽高。

高级属性

state

字符串类型，自定义状态名称（需配合 states 属性使用）。

states

State 列表，定义输入框的不同状态。

transitions

Transition 列表，定义状态切换的动画效果。

clip

布尔类型，是否裁剪超出边界的内容。

style

Style 类型，自定义输入框样式（覆盖默认风格）。

styleData

只读对象，包含输入框的风格数据（如 styleData.pressed）。

CheckBox（复选框）：用于提供多选的选项，可以设置其文本、选中状态等属性。

对象状态属性

checked

布尔类型，复选框是否被选中，默认 false。

tristate

布尔类型，是否支持三态（选中、未选中、不确定），默认 false。

state

字符串类型，当前状态（如 "checked", "unchecked", "indeterminate"）。

indeterminate

布尔类型，是否处于不确定状态（仅当 tristate: true 时有效）。

外观属性

background

Item 类型，复选框的背景元素（可自定义）。

indicator

Item 类型，复选框的指示器（勾选标记部分）。

contentItem

Item 类型，复选框的内容（通常是文本标签）。

width、height

实数类型，复选框的宽高。

implicitWidth、implicitHeight

只读实数，默认宽高。

visible

布尔类型，是否可见，默认 true。

opacity

实数类型，透明度（0.0~1.0）。

z

整数类型，Z 轴堆叠顺序。

文本属性

text

字符串类型，复选框旁边的文本标签。

font

Font 类型，文本字体（如 font.pixelSize、font.family）。

color

颜色类型，文本颜色。

交互属性

enabled

布尔类型，是否启用交互，默认 true。

hovered

布尔类型，鼠标是否悬停，默认 false。

pressed

布尔类型，复选框是否被按下，默认 false。

focus

布尔类型，是否获取焦点，默认 false。

checkable

布尔类型，是否可切换状态，默认 true。

信号与事件

onCheckedChanged

信号处理函数，选中状态变化时触发。

onToggled

信号处理函数，状态切换时触发（等同于 onCheckedChanged）。

onPressed

信号处理函数，按下时触发。

onReleased

信号处理函数，释放时触发。

onClicked

信号处理函数，点击时触发。

布局属性

anchors

锚点系统，用于定位。

Layout.fillWidth、Layout.fillHeight

布尔类型，是否填充布局空间。

Layout.preferredWidth、Layout.preferredHeight

实数类型，布局中的首选宽高。

Layout.minimumWidth、Layout.minimumHeight

实数类型，布局中的最小宽高。

高级属性

states

State 列表，定义复选框的不同状态（如自定义样式）。

transitions

Transition 列表，定义状态切换的动画效果。

clip

布尔类型，是否裁剪超出边界的内容。

style

Style 类型，自定义复选框样式（覆盖默认风格）。

styleData

只读对象，包含复选框的风格数据（如 styleData.checked）。

GridView 是一种用于展示二维网格布局数据的控件，通常来自 QtQuick.Controls 或 QtQuick 模块。以下是 GridView 的所有属性分类整理

基础属性

id

字符串类型，唯一标识组件。

objectName

字符串类型，用于 C++ 查找对象。

数据与模型属性

model

模型类型，网格视图的数据模型（如 ListModel、数组或 JavaScript 对象）。

delegate

Item 类型，每个网格项的视觉代理（定义外观和交互）。

highlight

Item 类型，当前选中项的高亮指示器。

currentIndex

整数类型，当前选中项的索引。

currentItem

Item 类型，当前选中的项。

布局属性

cellWidth、cellHeight

实数类型，网格单元格的宽高（默认为 undefined，由代理决定）。

flow

GridView.Flow 枚举类型，流动方向：

GridView.LeftToRight（默认）：从左到右排列。

GridView.TopToBottom：从上到下排列。

orientation

GridView.Orientation 枚举类型，滚动方向：

GridView.Horizontal：水平滚动。

GridView.Vertical（默认）：垂直滚动。

layoutDirection

Qt.LayoutDirection 枚举类型，布局方向：

Qt.LeftToRight（默认）：从左到右。

Qt.RightToLeft：从右到左。

spacing

实数类型，单元格之间的间距（默认 0）。

visibleItemCount

整数类型，可视区域内的最大项数（性能优化）。

cacheBuffer

实数类型，可视区域外预渲染的缓冲区大小（提高滚动流畅度）。

滚动与定位属性

contentWidth、contentHeight

只读实数类型，内容的总宽度和高度。

contentX、contentY

实数类型，内容的滚动偏移量。

flickDeceleration

实数类型，轻扫后的减速速率（默认 2000）。

boundsBehavior

Flickable.BoundsBehavior 枚举类型，边界行为：

Flickable.StopAtBounds（默认）：停在边界。

Flickable.DragOverBounds：可拖动超过边界。

Flickable.ElasticBounds：弹性边界（拖动后回弹）。

scrollBarPolicy

Qt.ScrollBarPolicy 枚举类型，滚动条策略：

Qt.ScrollBarAsNeeded（默认）：按需显示。

Qt.ScrollBarAlwaysOff：始终隐藏。

Qt.ScrollBarAlwaysOn：始终显示。

scrollBarStyle

Style 类型，自定义滚动条样式。

外观属性

width、height

实数类型，网格视图的宽高。

clip

布尔类型，是否裁剪超出边界的内容（默认 true）。

background

Item 类型，背景元素（如 Rectangle）。

highlightRangeMode

GridView.HighlightRangeMode 枚举类型，高亮范围模式：

GridView.NoHighlightRange（默认）：无高亮范围。

GridView.StrictlyEnforceRange：严格限制高亮范围。

GridView.ApproximateHighlightRange：近似高亮范围。

highlightMoveDuration

整数类型，高亮指示器移动的动画时长（毫秒）。

交互属性

focus

布尔类型，是否获取焦点（默认 false）。

enabled

布尔类型，是否启用交互（默认 true）。

pressDelay

整数类型，长按识别的延迟时间（毫秒，默认 500）。

interactive

布尔类型，是否可交互（如滚动、选择，默认 true）。

moveDistance

实数类型，触发移动的最小距离（默认 5）。

信号与事件

onPositionChanged

信号处理函数，内容位置变化时触发。

onContentXChanged、onContentYChanged

信号处理函数，水平 / 垂直滚动位置变化时触发。

onCurrentIndexChanged

信号处理函数，当前选中项索引变化时触发。

onAdd

信号处理函数，添加项时触发。

onRemove

信号处理函数，移除项时触发。

onMove

信号处理函数，移动项时触发。

onClicked

信号处理函数，点击项时触发。

onDoubleClicked

信号处理函数，双击项时触发。

onPressed

信号处理函数，按下项时触发。

onReleased

信号处理函数，释放项时触发。

高级属性

keyNavigationWraps

布尔类型，键盘导航是否循环（默认 false）。

visibleArea

Flickable.VisibleArea 对象，可视区域的信息（如 visibleArea.progress）。

repeater

Repeater 类型，内部使用的重复器（只读）。

states

State 列表，定义不同状态（如选中、禁用）。

transitions

Transition 列表，定义状态切换的动画效果。

RadioButton（单选按钮）：用于提供单选的选项，可以设置其文本、选中状态等属性。

对象

ProgressBar（进度条）：用于显示任务的进度，可以设置其进度值、样式等属性。

对象

Slider（滑动条）：用于提供可调节的数值范围，可以设置最小值、最大值、当前值等属性。

对象

List View（列表视图）：用于显示一个可滚动的列表，可以设置其数据模型、样式等属性。

属性 类型 描述

model var 数据源（如 ListModel、数组、JavaScript 对象）。

delegate Component 每个列表项的视觉呈现组件。

orientation enumeration 列表方向：ListView.Horizontal 或 ListView.Vertical（默认）。

spacing real 列表项之间的间距（像素）。

highlight Item 当前高亮项的视觉指示器（如选中项背景）。

highlightFollowsCurrentItem bool 高亮是否跟随当前项（默认 true）。

currentIndex int 当前选中项的索引（-1 表示无选中项）。

currentItem Item 当前选中项的实例。

二、滚动与定位

属性 类型 描述

contentHeight real（只读） 内容总高度（所有项和间距的总和）。

contentWidth real（只读） 内容总宽度。

contentX real 水平滚动位置（左边缘偏移量）。

contentY real 垂直滚动位置（上边缘偏移量）。

flickDeceleration real 滚动减速速率（像素 / 秒 ²），影响惯性滚动的停止速度。

boundsBehavior enumeration 边界行为：

- ListView.StopAtBounds

- ListView.OverShootBounds

- ListView.FollowBounds

scrollBarPolicy enumeration 滚动条策略：

- Qt.ScrollBarAsNeeded

- Qt.ScrollBarAlwaysOff

- Qt.ScrollBarAlwaysOn

scrollMode enumeration 滚动模式：

- ListView.ScrollFree

- ListView.SnapToItem

- ListView.SnapOneItem

visibleArea VisibleArea 可视区域信息（包含 progress、heightRatio 等属性）。

三、性能优化

属性 类型 描述

cacheBuffer real 缓存区大小（像素），控制可视区域外预渲染的项目数量。

clip bool 是否裁剪不可见区域（默认 false，设为 true 可提高性能）。

graphicsEffect GraphicsEffect 应用于整个列表的图形效果（如模糊、阴影）。

implicitHeight real 隐式高度（由内容决定）。

implicitWidth real 隐式宽度。

invertViewport bool 是否反转视图方向（用于特殊布局需求）。

isHighlighting bool（只读） 是否正在高亮（用于动画控制）。

四、交互与事件

属性 类型 描述

add signal 当模型添加项时触发。

move signal 当模型移动项时触发。

remove signal 当模型移除项时触发。

update signal 当模型更新项时触发。

contentItem Item（只读） 内容项（包含所有列表项的容器）。

flickBegin signal 开始快速滚动时触发。

flickEnd signal 快速滚动结束时触发。

pressed signal 列表项被按下时触发。

released signal 列表项被释放时触发。

clicked signal 列表项被点击时触发。

doubleClicked signal 列表项被双击时触发。

contentXChanged signal 水平滚动位置变化时触发。

contentYChanged signal 垂直滚动位置变化时触发。

五、高级布局与代理

属性 类型 描述

header Item 列表头部（固定在顶部）。

footer Item 列表尾部（固定在底部）。

section Section 分组信息（用于分组列表）。

layoutDirection enumeration 布局方向：Qt.LeftToRight 或 Qt.RightToLeft。

requiredProperty string 代理中必须存在的属性（用于性能优化）。

visibleItemCount int 可视区域内的最大项数（用于性能预估）。

六、方法

方法 描述

positionViewAtBeginning() 滚动到列表开始位置。

positionViewAtEnd() 滚动到列表结束位置。

positionViewAtIndex(index, policy) 将指定索引项滚动到可视区域，policy 控制对齐方式（如 ListView.AlignCenter）。

positionViewAtItem(item, policy) 将指定项滚动到可视区域。

forceLayout() 强制重新布局（用于动态内容变化后）。

itemAt(x, y) 返回指定坐标处的列表项。