docs(API_Tutorial): 移除链式调用示例并更新UI文档

更新UI系统文档,移除了所有链式调用方法的示例,统一使用标准设置方法
修改最佳实践部分,移除关于链式调用的推荐
This commit is contained in:
ChestnutYueyue 2026-02-13 16:58:40 +08:00
parent 866fd4b1ff
commit 65825946be
1 changed files with 25 additions and 63 deletions

View File

@ -33,22 +33,21 @@ enum class CoordinateSpace {
// 屏幕空间UI 常用) // 屏幕空间UI 常用)
button->setCoordinateSpace(CoordinateSpace::Screen); button->setCoordinateSpace(CoordinateSpace::Screen);
button->setScreenPosition(100.0f, 50.0f); button->setScreenPosition(100.0f, 50.0f);
// 或使用链式调用
button->withCoordinateSpace(CoordinateSpace::Screen)
->withScreenPosition(100.0f, 50.0f);
``` ```
## 通用链式调用方法 ## 通用设置方法
所有 UI 组件都支持以下链式调用方法 所有 UI 组件都支持以下设置方法(来自基类 Node 和 Widget
```cpp ```cpp
widget->withPosition(x, y) // 设置位置 // 来自 Node 基类
->withAnchor(x, y) // 设置锚点 (0-1) widget->setPosition(x, y); // 设置位置
->withCoordinateSpace(space) // 设置坐标空间 widget->setAnchor(x, y); // 设置锚点 (0-1)
->withScreenPosition(x, y) // 设置屏幕位置
->withCameraOffset(x, y); // 设置相机偏移 // 来自 Widget 基类
widget->setCoordinateSpace(space); // 设置坐标空间
widget->setScreenPosition(x, y); // 设置屏幕位置
widget->setCameraOffset(x, y); // 设置相机偏移
``` ```
## 按钮Button ## 按钮Button
@ -59,21 +58,15 @@ widget->withPosition(x, y) // 设置位置
auto& resources = Application::instance().resources(); auto& resources = Application::instance().resources();
auto font = resources.loadFont("assets/font.ttf", 24); auto font = resources.loadFont("assets/font.ttf", 24);
// 方式1简单创建 // 创建按钮
auto button = Button::create(); auto button = Button::create();
button->setText("点击我"); button->setText("点击我");
button->setFont(font); button->setFont(font);
button->setPosition(Vec2(400, 300)); button->setPosition(Vec2(400, 300));
button->setSize(200, 60);
// 方式2链式调用创建 button->setTextColor(Colors::White);
auto button = Button::create() button->setBackgroundColor(Colors::Blue, Colors::Green, Colors::Red);
->withText("点击我") button->setBorder(Colors::White, 2.0f);
->withFont(font)
->withPosition(400, 300)
->withSize(200, 60)
->withTextColor(Colors::White)
->withBackgroundColor(Colors::Blue, Colors::Green, Colors::Red)
->withBorder(Colors::White, 2.0f);
// 设置点击回调 // 设置点击回调
button->setOnClick([]() { button->setOnClick([]() {
@ -297,17 +290,12 @@ void GameOverLayer::onUpdate(float dt) {
### 创建文本 ### 创建文本
```cpp ```cpp
// 方式1简单创建 // 创建文本
auto text = Text::create("Hello World", font); auto text = Text::create("Hello World", font);
text->setPosition(Vec2(100, 50)); text->setPosition(Vec2(100, 50));
text->setTextColor(Colors::White);
// 方式2链式调用 text->setFontSize(24);
auto text = Text::create("Hello World") text->setAlignment(Alignment::Center);
->withFont(font)
->withPosition(100, 50)
->withTextColor(Colors::White)
->withFontSize(24)
->withAlignment(Alignment::Center);
addChild(text); addChild(text);
``` ```
@ -352,13 +340,6 @@ auto label = Label::create("玩家名称", font);
label->setPosition(Vec2(100, 50)); label->setPosition(Vec2(100, 50));
label->setTextColor(Colors::White); label->setTextColor(Colors::White);
// 链式调用
auto label = Label::create("玩家名称")
->withFont(font)
->withPosition(100, 50)
->withTextColor(Colors::White)
->withFontSize(24);
addChild(label); addChild(label);
``` ```
@ -398,12 +379,8 @@ checkBox->setChecked(true);
// 方式2带标签 // 方式2带标签
checkBox = CheckBox::create("启用音效"); checkBox = CheckBox::create("启用音效");
checkBox->setPosition(Vec2(100, 200)); checkBox->setPosition(Vec2(100, 200));
checkBox->setFont(font);
// 方式3链式调用 checkBox->setTextColor(Colors::White);
checkBox = CheckBox::create("启用音效")
->withPosition(100, 200)
->withFont(font)
->withTextColor(Colors::White);
// 状态改变回调 // 状态改变回调
checkBox->setOnStateChange([](bool checked) { checkBox->setOnStateChange([](bool checked) {
@ -510,14 +487,6 @@ slider->setValue(50.0f);
// 方式2带初始值创建 // 方式2带初始值创建
auto slider = Slider::create(0.0f, 100.0f, 50.0f); auto slider = Slider::create(0.0f, 100.0f, 50.0f);
// 方式3链式调用
auto slider = Slider::create()
->withPosition(200, 400)
->withSize(200, 20)
->withMinValue(0.0f)
->withMaxValue(100.0f)
->withValue(50.0f);
// 值改变回调 // 值改变回调
slider->setOnValueChange([](float value) { slider->setOnValueChange([](float value) {
E2D_LOG_INFO("滑块值: {}", value); E2D_LOG_INFO("滑块值: {}", value);
@ -582,12 +551,6 @@ progressBar->setValue(75.0f); // 75%
// 方式2带范围创建 // 方式2带范围创建
auto progressBar = ProgressBar::create(0.0f, 100.0f, 75.0f); auto progressBar = ProgressBar::create(0.0f, 100.0f, 75.0f);
// 方式3链式调用
auto progressBar = ProgressBar::create()
->withPosition(200, 500)
->withSize(300, 30)
->withProgress(0.75f); // 0-1 的进度值
addChild(progressBar); addChild(progressBar);
``` ```
@ -745,11 +708,10 @@ private:
## 最佳实践 ## 最佳实践
1. **使用屏幕空间** - UI 控件通常使用 `CoordinateSpace::Screen` 固定在屏幕上 1. **使用屏幕空间** - UI 控件通常使用 `CoordinateSpace::Screen` 固定在屏幕上
2. **使用链式调用** - 创建控件时优先使用链式调用,代码更简洁 2. **设置合适的锚点** - 使用锚点0.5, 0.5)让控件中心对齐,方便布局
3. **设置合适的锚点** - 使用锚点0.5, 0.5)让控件中心对齐,方便布局 3. **复用字体资源** - 避免重复加载相同字体
4. **复用字体资源** - 避免重复加载相同字体 4. **使用回调函数** - 使用 `setOnClick`、`setOnValueChange` 等回调响应用户操作
5. **使用回调函数** - 使用 `setOnClick`、`setOnValueChange` 等回调响应用户操作 5. **使用切换按钮** - 对于需要显示两种状态的按钮(如开关),使用 `setToggleMode(true)`
6. **使用切换按钮** - 对于需要显示两种状态的按钮(如开关),使用 `setToggleMode(true)`
## 下一步 ## 下一步