QML ListView文字超出圆角矩形边界的解决方案（禁用Qt5Compat特效）

问题场景 #

使用QML开发的ListView中，自定义委托包含Text组件，滚动ListView时，部分字母（如'H'）会超出带圆角的父Rectangle边界，显示在圆角边缘上。要求不依赖Qt5Compat.GraphicalEffects和OpacityMask解决该问题。

核心代码示例：

Rectangle{
    anchors.fill: parent
    color: "#141414"

    // 容纳ListView的容器
    Rectangle {
        id: rectList
        anchors.centerIn: parent
        width: 200
        height: 400
        radius: 10
           
        ListModel{
            id: bla
            ListElement{name: "A"}
            // 其余字母元素省略
        }

        Component{
            id: delegateComponent
            Rectangle{
                id: rectListView
                width: rectList.width
                height: 30
                color: "transparent"
                z: -1
                readonly property ListView __lv: ListView.view
                Text {
                    id: txt
                    anchors.fill: rectListView
                    anchors.left: rectListView.left
                    anchors.bottomMargin: 5
                    width: rectListView.width
                    height: rectListView.height
                    text: model.name
                   }
               }
        }

        ListView{
            id: lv
            model: bla
            delegate: delegateComponent
            anchors.fill: parent
            focus: true
            clip: true
            cacheBuffer: 5000
            spacing: 15
        }
    }
}

可行解决方案 #

方案1：给圆角容器开启裁剪 #

带圆角的rectList未开启裁剪是问题核心，只需添加clip: true即可让超出圆角的内容被自动截断：

Rectangle {
    id: rectList
    anchors.centerIn: parent
    width: 200
    height: 400
    radius: 10
    clip: true // 启用原生裁剪
    // ... 其余代码不变
}

这是QML原生的裁剪机制，无需额外依赖，能直接处理超出容器圆角边界的所有内容。

方案2：给Text组件添加内边距 #

通过设置Text的左右内边距，让文字远离容器圆角区域，从根源避免文字触及边界：

Text {
    id: txt
    // ... 其余属性不变
    leftPadding: 8
    rightPadding: 8
    // 也可通过anchors margin控制：
    // anchors.leftMargin: 8
    // anchors.rightMargin: 8
}

可根据圆角半径调整内边距大小，确保文字不会出现在圆角覆盖的区域内。

方案3：缩小ListView的显示范围 #

让ListView的宽度小于圆角容器的宽度，主动避开圆角区域，同时同步调整委托宽度：

ListView{
    id: lv
    model: bla
    delegate: delegateComponent
    width: rectList.width - 20 // 左右各预留10px避开圆角
    height: rectList.height
    anchors.centerIn: parent
    focus: true
    clip: true
    cacheBuffer: 5000
    spacing: 15
}

// 委托中同步调整宽度
Component{
    id: delegateComponent
    Rectangle{
        id: rectListView
        width: lv.width // 跟随ListView宽度
        height: 30
        color: "transparent"
        z: -1
        readonly property ListView __lv: ListView.view
        Text {
            id: txt
            anchors.fill: rectListView
            anchors.left: rectListView.left
            anchors.bottomMargin: 5
            text: model.name
           }
       }
}

这种方式让内容区域本身就不覆盖圆角部分，自然不会出现文字超出的情况。

内容的提问来源于stack exchange，提问作者siamak mirifar