游戏开发

Cocos2d-x ScrollView偏移计算详解与滚动定位实现

, , ,

引言

ScrollView 是游戏开发中常用的 UI 组件，用于展示超出屏幕范围的内容。在实际开发中，经常需要计算 ScrollView 的滚动范围，并实现精确的定位滚动。本文将详细解析 Cocos2d-x 中 ScrollView 的 maxContainerOffset 和 minContainerOffset 方法，并提供实用的滚动定位实现方案。

ScrollView 基础

核心概念

1
2
3
4
5
6
7
8
9
10
11
12
13
14
┌─────────────────────────────────────┐
│        ScrollView (视口)            │
│    ┌─────────────────────────┐      │
│    │                         │      │
│    │     Container (内容)    │      │
│    │    ┌───────────────┐    │      │
│    │    │   Content     │    │      │
│    │    │   (实际内容)   │    │      │
│    │    │               │    │      │
│    │    └───────────────┘    │      │
│    │                         │      │
│    └─────────────────────────┘      │
│                                     │
└─────────────────────────────────────┘
  • ScrollView：可视区域（View），决定能看到的范围
  • Container：内容容器，包含所有子元素
  • ContentOffset：容器相对于视口的偏移量

创建 ScrollView

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// 创建 ScrollView
ScrollView* scrollView = ScrollView::create();
scrollView->setDirection(ScrollView::Direction::VERTICAL);
scrollView->setContentSize(Size(400, 600));
scrollView->setPosition(Vec2(100, 100));

// 创建内容容器
Layer* container = Layer::create();
container->setContentSize(Size(400, 1200));
scrollView->setContainer(container);

// 添加子元素
for (int i = 0; i < 20; i++) {
    auto item = createListItem(i);
    item->setPosition(Vec2(200, 1150 - i * 80));
    container->addChild(item);
}

this->addChild(scrollView);

偏移计算方法

maxContainerOffset - 最大偏移位置

1
2
Vec2 maxOffset = scrollView->maxContainerOffset();
// 结果：始终返回 Vec2(0, 0)

含义解释：

maxContainerOffset 返回容器可以移动的最大偏移坐标。在标准 Cocos2d-x 坐标系中（原点在左下角）：

  • 当 Container 的左下角与 ScrollView 的左下角对齐时，偏移量为 (0, 0)
  • 这是内容的”顶部”位置（对于垂直滚动）
  • 内容不能再向上滚动（否则会出现空白）
1
2
3
4
5
6
7
8
9
┌──────────────────┐
│                  │
│   maxOffset      │  ← 内容顶部对齐
│   = (0, 0)       │
│                  │
│   ┌──────────┐   │
│   │ Content  │   │
│   └──────────┘   │
└──────────────────┘

minContainerOffset - 最小偏移位置

1
Vec2 minOffset = scrollView->minContainerOffset();

含义解释：

minContainerOffset 返回容器可以移动的最小偏移坐标。这是内容的”底部”位置：

  • 计算公式：Vec2(viewSize.width - containerSize.width, viewSize.height - containerSize.height)
  • 当 Container 的右下角/顶部与 ScrollView 对齐时
  • 内容不能再向下滚动（否则会出现空白）
1
2
3
4
5
6
7
8
9
┌──────────────────┐
│   ┌──────────┐   │
│   │ Content  │   │
│   └──────────┘   │
│                  │
│   minOffset      │  ← 内容底部对齐
│   = (0, -600)    │
│                  │
└──────────────────┘

偏移计算图解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Y 轴正方向 ↑
           │
           │    maxOffset (0, 0)
           │    ┌────────────────────────┐
           │    │  Container             │
           │    │  ┌────┐ ┌────┐ ┌────┐  │
           │    │  │ 0  │ │ 1  │ │ 2  │  │  ← 可见区域
           │    │  └────┘ └────┘ └────┘  │
           │    │  ┌────┐ ┌────┐ ┌────┐  │
           │    │  │ 3  │ │ 4  │ │ 5  │  │  ← 可见区域
    ┌──────┼────┼──┴────┴─┴────┴─┴────┴──┼──┐
    │      │    │                        │  │
    │ View │    │  ┌────┐ ┌────┐ ┌────┐  │  │  ← 隐藏区域
    │ Port │    │  │ 6  │ │ 7  │ │ 8  │  │  │
    │      │    │  └────┘ └────┘ └────┘  │  │
    │      │    │  ┌────┐ ┌────┐ ┌────┐  │  │  ← 隐藏区域
    │      │    │  │ 9  │ │ 10 │ │ 11 │  │  │
    │      │    │  └────┘ └────┘ └────┘  │  │
    └──────┼────┼────────────────────────┼──┘
           │    minOffset (0, -containerHeight + viewHeight)
           │
           └──────────────────────────────────→ X 轴正方向

实际应用：滚动到指定 Cell

需求分析

在游戏中常见的需求：

  • 点击某个按钮，自动滚动到对应的关卡
  • 选中某个道具，滚动到列表中的该道具位置
  • 恢复到上次查看的位置

实现代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// 滚动到指定索引的 Cell
void scrollToCell(ScrollView* scrollView, int cellIndex, int cellHeight) {
    // 获取偏移范围
    Vec2 minOffset = scrollView->minContainerOffset();
    Vec2 maxOffset = scrollView->maxContainerOffset();

    // 计算目标位置的 Y 坐标
    // cellIndex * cellHeight：该 Cell 顶部的偏移量
    float targetY = minOffset.y + cellIndex * cellHeight;

    // 边界检查：不能小于 minOffset.y
    if (targetY < minOffset.y) {
        targetY = minOffset.y;
    }

    // 边界检查：不能大于 maxOffset.y（通常是 0）
    if (targetY > maxOffset.y) {
        targetY = maxOffset.y;
    }

    // 设置偏移
    scrollView->setContentOffset(Vec2(0, targetY), true);  // true 表示动画
}

优化版本：居中对齐

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 滚动到指定 Cell 并使其居中
void scrollToCellCenter(ScrollView* scrollView, int cellIndex,
                        int cellHeight, int viewHeight) {
    Vec2 minOffset = scrollView->minContainerOffset();
    Vec2 maxOffset = scrollView->maxContainerOffset();

    // 计算 Cell 的中心位置
    float cellCenterY = cellIndex * cellHeight + cellHeight / 2;

    // 计算视口中心对应的内容偏移
    float targetY = minOffset.y + cellCenterY - viewHeight / 2;

    // 边界检查
    targetY = clampf(targetY, minOffset.y, maxOffset.y);

    scrollView->setContentOffset(Vec2(0, targetY), true);
}

// 辅助函数：限制值在范围内
float clampf(float value, float min, float max) {
    if (value < min) return min;
    if (value > max) return max;
    return value;
}

完整示例：关卡选择界面

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// LevelSelectScene.h
#ifndef __LEVEL_SELECT_SCENE_H__
#define __LEVEL_SELECT_SCENE_H__

#include "cocos2d.h"
#include "ui/CocosGUI.h"

USING_NS_CC;
using namespace ui;

class LevelSelectScene : public Layer {
public:
    static Scene* createScene();
    virtual bool init();
    CREATE_FUNC(LevelSelectScene);

private:
    ScrollView* _scrollView;
    const int CELL_HEIGHT = 80;
    const int VISIBLE_CELLS = 7;

    void setupScrollView();
    void createLevelCells(int totalLevels);
    void scrollToLevel(int levelIndex);
    void onLevelClicked(Ref* sender, int levelIndex);
};

#endif
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
// LevelSelectScene.cpp
#include "LevelSelectScene.h"

Scene* LevelSelectScene::createScene() {
    auto scene = Scene::create();
    auto layer = LevelSelectScene::create();
    scene->addChild(layer);
    return scene;
}

bool LevelSelectScene::init() {
    if (!Layer::init()) {
        return false;
    }

    Size visibleSize = Director::getInstance()->getVisibleSize();
    Vec2 origin = Director::getInstance()->getVisibleOrigin();

    // 背景
    auto background = LayerColor::create(Color4B(50, 50, 50, 255));
    this->addChild(background);

    // 标题
    auto title = Label::createWithSystemFont("选择关卡", "Arial", 36);
    title->setPosition(Vec2(visibleSize.width / 2,
                            visibleSize.height - 50));
    this->addChild(title);

    // 设置 ScrollView
    setupScrollView();

    // 创建关卡按钮
    createLevelCells(50);

    // 测试：滚动到第 20 关
    auto testButton = Button::create();
    testButton->setTitleText("跳转到第20关");
    testButton->setTitleFontSize(24);
    testButton->setPosition(Vec2(visibleSize.width / 2, 80));
    testButton->addClickEventListener([this](Ref* sender) {
        this->scrollToLevel(19);  // 索引从 0 开始
    });
    this->addChild(testButton);

    return true;
}

void LevelSelectScene::setupScrollView() {
    Size visibleSize = Director::getInstance()->getVisibleSize();

    // 创建 ScrollView
    _scrollView = ScrollView::create();
    _scrollView->setDirection(ScrollView::Direction::VERTICAL);
    _scrollView->setContentSize(Size(400, CELL_HEIGHT * VISIBLE_CELLS));
    _scrollView->setPosition(Vec2(
        (visibleSize.width - 400) / 2,
        120
    ));

    // 设置弹性效果
    _scrollView->setBounceable(true);

    // 添加背景（仅用于显示边界）
    auto scrollBg = LayerColor::create(Color4B(30, 30, 30, 255));
    scrollBg->setContentSize(_scrollView->getContentSize());
    _scrollView->addChild(scrollBg, -1);

    this->addChild(_scrollView);
}

void LevelSelectScene::createLevelCells(int totalLevels) {
    // 创建容器
    auto container = Layer::create();
    container->setContentSize(Size(400, totalLevels * CELL_HEIGHT));
    _scrollView->setContainer(container);

    // 创建每个关卡按钮
    for (int i = 0; i < totalLevels; i++) {
        // 背景
        auto cellBg = LayerColor::create(
            i % 2 == 0 ? Color4B(60, 60, 60, 255)
                       : Color4B(70, 70, 70, 255)
        );
        cellBg->setContentSize(Size(400, CELL_HEIGHT));
        cellBg->setPosition(Vec2(0, (totalLevels - 1 - i) * CELL_HEIGHT));
        container->addChild(cellBg);

        // 关卡标签
        auto levelLabel = Label::createWithSystemFont(
            StringUtils::format("关卡 %d", i + 1),
            "Arial", 28
        );
        levelLabel->setPosition(Vec2(100, CELL_HEIGHT / 2));
        levelLabel->setAnchorPoint(Vec2(0, 0.5));
        cellBg->addChild(levelLabel);

        // 星级显示（模拟）
        for (int star = 0; star < 3; star++) {
            auto starSprite = Sprite::create("star.png");
            if (starSprite) {
                starSprite->setPosition(Vec2(250 + star * 40, CELL_HEIGHT / 2));
                starSprite->setScale(0.5);
                cellBg->addChild(starSprite);
            }
        }

        // 点击事件
        auto listener = EventListenerTouchOneByOne::create();
        listener->setSwallowTouches(true);
        listener->onTouchBegan = [this, i](Touch* touch, Event* event) {
            auto target = event->getCurrentTarget();
            Vec2 location = target->convertToNodeSpace(touch->getLocation());
            Rect rect = Rect(0, 0, target->getContentSize().width,
                           target->getContentSize().height);

            if (rect.containsPoint(location)) {
                this->onLevelClicked(target, i);
                return true;
            }
            return false;
        };

        Director::getInstance()->getEventDispatcher()
            ->addEventListenerWithSceneGraphPriority(listener, cellBg);
    }

    // 设置初始偏移（显示最上面的内容）
    _scrollView->setContentOffset(Vec2(0, 0));
}

void LevelSelectScene::scrollToLevel(int levelIndex) {
    // 获取偏移范围
    Vec2 minOffset = _scrollView->minContainerOffset();
    Vec2 maxOffset = _scrollView->maxContainerOffset();

    // 计算目标 Y 坐标
    // 注意：Cocos2d-x 坐标系 Y 轴向上为正
    float targetY = minOffset.y + levelIndex * CELL_HEIGHT;

    // 边界检查
    if (targetY < minOffset.y) {
        targetY = minOffset.y;
    }
    if (targetY > maxOffset.y) {
        targetY = maxOffset.y;
    }

    // 动画滚动到目标位置
    _scrollView->setContentOffset(Vec2(0, targetY), true);

    CCLOG("滚动到关卡 %d, targetY: %f, minOffset: %f, maxOffset: %f",
          levelIndex + 1, targetY, minOffset.y, maxOffset.y);
}

void LevelSelectScene::onLevelClicked(Ref* sender, int levelIndex) {
    CCLOG("选择了关卡 %d", levelIndex + 1);

    // 可以在这里添加选中效果
    auto cell = dynamic_cast<LayerColor*>(sender);
    if (cell) {
        cell->setColor(Color3B(100, 100, 150));

        // 延迟恢复颜色
        auto delay = DelayTime::create(0.2);
        auto resetColor = CallFunc::create([cell, levelIndex]() {
            cell->setColor(levelIndex % 2 == 0
                ? Color3B(60, 60, 60)
                : Color3B(70, 70, 70));
        });
        cell->runAction(Sequence::create(delay, resetColor, nullptr));
    }
}

常见问题

1. 滚动范围计算错误

1
2
3
4
5
6
7
8
// ❌ 错误：没有考虑边界
float targetY = index * cellHeight;

// ✅ 正确：使用 minContainerOffset 限制
Vec2 minOffset = scrollView->minContainerOffset();
float targetY = minOffset.y + index * cellHeight;
if (targetY < minOffset.y) targetY = minOffset.y;
if (targetY > 0) targetY = 0;

2. 动画不流畅

1
2
3
4
5
6
7
8
9
10
11
12
13
// 确保在主线程更新
void update(float dt) {
    // ScrollView 的动画在 update 中处理
}

// 或者在动作回调中更新
scrollView->runAction(Sequence::create(
    DelayTime::create(0.1),
    CallFunc::create([scrollView]() {
        scrollView->setContentOffset(...);
    }),
    nullptr
));

3. 触摸事件冲突

1
2
3
4
5
// ScrollView 和 Button 的触摸冲突解决
scrollView->setSwallowTouches(false);  // 不吞噬触摸

// 或者使用 EventListener 的优先级
listener->setSwallowTouches(true);

总结

方法 返回值 含义
maxContainerOffset() Vec2(0, 0) 内容顶部对齐位置
minContainerOffset() Vec2(x, y) 内容底部对齐位置

关键公式：

1
2
3
4
// 滚动到指定 Cell
float targetY = minOffset.y + cellIndex * cellHeight;
targetY = clampf(targetY, minOffset.y, maxOffset.y);
scrollView->setContentOffset(Vec2(0, targetY), true);

掌握这些知识，可以实现各种复杂的滚动定位需求，如聊天消息定位、商品列表跳转等。