T
ToyCode v2.0.5 教程 (2-28章)
官网首页
ToyCode 2.0.5 官方使用教程

ToyCode 2.0.5 接口全景手册与详尽教程 (第 2 至 28 章)

本页面包含第 2 章至第 28 章的完整详细描述、所有底层原理解释、属性对照表以及完整 C++17 代码。已按要求移除第 1 章，直接从快速上手开始。

2. 快速上手

2.1 第一个布局界面

在 ToyCode 中，构建漂亮的现代化界面非常直观。通过 VStack 容器、圆角、阴影以及事件绑定，您可以轻松创建一个带有响应交互的登录或欢迎卡片。以下是完整代码： 

#include <ToyCode.h>
using namespace toy;
int main()
{
    App a("欢迎使用 ToyCode");
    a.Background(Colors.FromRGB(235, 244, 255));
    auto page = a.AddVStack()
        .Size(760, 430)
        .Align(Align.Center)
        .Padding(42)
        .Spacing(22)
        .Background(Colors.White)
        .CornerRadius(28)
        .Shadow(Colors.FromRGBA(60, 90, 130, 55))
        .ShadowOffset(0, 12)
        .ShadowBlur(24);
    auto title = page.UI.AddLabel("Hello ToyCode")
        .Height(70)
        .FontSize(44)
        .TextColor(Colors.Blue);
    title.Bold = true;
    auto result = page.UI.AddLabel("等待点击")
        .Height(58)
        .FontSize(25)
        .TextColor(Colors.Slate);
    auto button = page.UI.AddButton("开始")
        .Size(220, 62)
        .FontSize(25)
        .TextColor(Colors.White)
        .Background(Colors.Blue)
        .CornerRadius(16);
    button.Click([=](auto e){
        result.Text("按钮已点击");
    });
    return a.Run();
}

在这段代码中，VStack 自动管理了子元素垂直方向的流式排列。您不需要计算每个 Label 和 Button 的绝对像素坐标，框架会根据 Spacing 和 Padding 自动完成排版。

2.2 从对象加点号开始

ToyCode 的核心设计理念之一就是“所见即所得的点号调用”。通过在对象后输入点号，您可以直接访问其 UI 控件工厂、图形工厂或音频接口。

功能类别 语法特征 代码示例
UI 控件添加 box.UI.AddXXX page.UI.AddButton("确定")
基础图形添加 box.Shape.AddXXX page.Shape.AddCircle(80)
内容/媒体对象 box.AddXXX page.AddImage("logo.png")
全局音频 app.AddSound / AddMusic a.AddSound("click.wav")

3. Getter Setter 与链式配置

3.1 同名读取与写入

ToyCode 采用了优雅的同名函数设计：当传递参数时即为 Setter（写入属性），不传参数时即为 Getter（读取属性）。这种设计极大地减少了记忆负担。 

label.Text("你好");          // Setter
label.FontSize(32);          // Setter
label.TextColor(Colors.Blue);  // Setter

std::string text = label.Text();   // Getter
float size = label.FontSize();     // Getter
Color color = label.TextColor();   // Getter

3.2 链式配置

大多数修改属性的函数都会返回当前对象的引用（通过 CRTP 技术实现），因此您可以将多行配置合并为一条流畅的链式调用语句： 

auto label = page.UI.AddLabel("用户信息")
    .Size(320, 64)
    .FontSize(30)
    .TextColor(Colors.Navy)
    .Background(Colors.FromRGB(232, 242, 255))
    .Padding(18)
    .CornerRadius(12);

4. 对象树和自动内存管理

ToyCode 建立在严格的树状对象层级之上。App 作为根对象拥有整个生命周期管理权，每个容器都持有并管理其子对象。当父容器被销毁时，其内部包含的所有子控件、事件监听器以及底层渲染缓存都会被自动释放，彻底杜绝了内存泄漏的隐患。 

auto panel = a.AddVStack();
auto button = panel.UI.AddButton("保存");
auto icon = button.AddImage("save.png");
// 当 panel 被释放时，button 和 icon 会被自动级联释放。
panel.Dispose();

5. 坐标尺寸颜色与调试文本

ToyCode 提供了丰富且强类型的值对象（如 Vec2、Size2D、Color 等），每个对象都内置了 ToString() 方法，方便在调试时直接输出状态。

数据类型包含字段调试输出示例
Vec2X, YVec2{X=100, Y=200}
Size2DWidth, HeightSize2D{Width=1920, Height=1080}
ColorR, G, B, AColor{R=33, G=150, B=243, A=255}

6. 容器和布局

除了基础的 VStack 和 HStack 外，ToyCode 还支持功能强大的 Grid 网格布局，允许您通过行列字符串（如 "240,*,*"）灵活划分界面区域。 

auto grid = a.AddGrid().Size(1000, 560).Align(Align.Center);
grid.Columns = "240,*,*";
grid.Rows = "80,*,100";

7. 外观效果

ToyCode 内置了现代 UI 渲染管线，支持圆角（CornerRadius）、多层次阴影（Shadow）、发光特效（Glow）以及毛玻璃背景模糊（BackdropBlur）。 

auto card = a.AddVStack()
    .Size(620, 360)
    .Background(Colors.FromRGBA(255, 255, 255, 220))
    .CornerRadius(28)
    .Shadow(Colors.FromRGBA(30, 60, 90, 60))
    .ShadowOffset(0, 14)
    .ShadowBlur(28);

8. 事件系统

事件系统全面拥抱 C++ 现代 Lambda 表达式。通过 [=] 捕获轻量句柄，您可以极其轻松地编写点击、悬停、拖拽等交互逻辑。 

button.Click([=](auto e){
    result.Text("保存成功");
});

9. 常用文本与输入控件

提供 Label、RichText 和带占位符的 TextBox。TextBox 支持内容变更监听（Change 事件），非常适合实现实时搜索或表单联动。 

auto name = page.UI.AddTextBox("请输入名字").Size(420, 58);
name.Change([=](auto e){ preview.Text("你好，" + name.Text()); });

10. 选择与数值控件

包含 CheckBox、ToggleSwitch、RadioButton、Slider、NumberBox 与 ProgressBar，满足各类参数调节需求。 

auto slider = page.UI.AddSlider().Width(420);
slider.Min = 0.0F; slider.Max = 100.0F; slider.Value = 35.0F;

11. 复合 UI 控件

提供 TabView、Expander、SplitView、TreeView 及 Menu / ContextMenu，轻松构建多标签页或带右键菜单的复杂桌面应用。 

auto tabs = page.UI.AddTabView().Size(900, 520);
auto general = tabs.AddTab("常规");

12. 图片 SVG 与自定义字体

原生支持 JPG、PNG、SVG 矢量图加载以及自定义 TTF 字体注册，确保跨平台文字与图标渲染清晰锐利。 

auto image = page.AddImage("photo.jpg").Fit(ImageFit.Cover);
a.Font.Regular("MyFont.ttf");

13. 资源和 ZIP 包

支持将所有资源打包进 ZIP 文件（如 assets.zip），程序启动时通过 AddZip 挂载，方便资源的加密与发布。 

App a("资源示例");
a.Assets.AddZip("assets.zip");

14. 音乐与音效

提供轻量级音效（Sound）与背景音乐（Music）接口，支持音量调节与循环播放。 

auto click = a.AddSound("click.wav");
click.Volume(0.8F);
button.Click([=](auto e){ click.Play(); });

15. 键盘定时器与逐帧更新

通过 Update 回调与 DeltaTime 实现平滑的逐帧位移和键盘状态轮询，非常适合制作 2D 动作小游戏。 

player.Update([=](auto e){
    Vec2 p = player.Position();
    float speed = 420.0F * e.DeltaTime;
    if (a.Keyboard.Down(Keys.Left)) p.X -= speed;
    player.Position(p);
});

16. View 与屏幕适配

支持多视图切换（AddView）及虚拟分辨率等比缩放（ScreenFit.Fit），确保游戏和应用在不同显示器上完美呈现。 

auto home = a.AddView();
a.VirtualSize = Size2D{1920, 1080};
a.ScreenMode = ScreenFit.Fit;

17. 动作系统

内置丰富的补间动画动作（Sequence、RotateTo、MoveTo、FadeTo），几行代码即可实现复杂的视觉演出。 

hero.Do(Sequence(
    RotateTo(360, 0.6F),
    MoveTo({1200, 540}, 1.0F)
));

18. Sprite 序列帧动画

支持精灵表单（Sprite Sheet）切割与多状态动画循环播放，轻松实现角色走动、攻击等帧动画。 

auto knight = a.AddSprite("knight.png", 128, 128);
knight.AddAnimation("idle", 0, 4, 8, true);
knight.Play("idle");

19. 粒子系统

内置高性能 2D 粒子发射器，支持调节发射速率、粒子寿命与颜色渐变，用于实现爆炸、魔法、下雪等特效。 

auto particles = a.AddParticles().Position(960, 540);
particles.Rate = 180.0F; particles.Play();

20. 碰撞检测

提供矩形与圆形包围盒碰撞检测，并支持 Collision.Enter 事件监听，方便实现得分、扣血等游戏逻辑。 

player.Collider(true).CollisionSize(70, 90);
player.Collision.Enter([=](auto e){ status.Text("发生碰撞"); });

21. TileMap 地图与寻路

支持网格瓦片地图加载与内置 A* 寻路算法，适合开发 RPG、战棋或塔防类游戏。 

auto map = a.AddTileMap("tiles.png", 32, 32);
map.Resize(60, 34);
auto path = map.FindPath({2, 3}, {40, 20});

22. Surface 动态画布

允许直接在离屏画布上进行点、线、矩形及自定义像素绘制，适合实现画板或自定义图形渲染。 

auto surface = a.AddSurface(640, 360);
surface.Clear(Colors.Black);
surface.DrawLine({20, 20}, {620, 340}, Colors.Cyan);
surface.Present();

23. Lottie 矢量动画

原生支持 JSON 格式的 Lottie 矢量动画播放，为 UI 交互提供绚丽的加载和成功动画效果。 

auto animation = page.AddLottie("success.json").Size(320, 320);
animation.Loop = true; animation.Play();

24. 基础 3D 世界

提供轻量级 3D 视口与基础网格（如 Cube）渲染能力，满足基础 3D 教学与轻度展示需求。 

auto world = a.AddWorld3D(1280, 720);
auto cube = world.AddCube();
cube.Color(Colors.Orange);

25. XML 布局

支持通过原始 XML 字符串直接解析和构建界面树，实现 UI 结构与 C++ 业务逻辑的解耦。 

auto ui = a.AddLayout(R"(<VStack Width="760" Padding="30">
    <Label Name="title" Text="用户登录" FontSize="36" />
</VStack>)");

26. 调试与性能

提供实时帧率（FPS）、渲染统计与窗口标题实时显示，方便开发者定位性能瓶颈。 

a.Debug.ShowStats(true);
a.Debug.ShowInTitle(true);

27. 完整 UI 样例

展示如何综合运用 Grid、Label、TextBox 和 Button 构建一个完整的用户资料编辑面板。 

#include <ToyCode.h>
using namespace toy;
int main(){
    App a("用户资料");
    a.Background(Colors.FromRGB(235, 244, 252));
    auto card = a.AddGrid().Size(980, 640).Align(Align.Center);
    return a.Run();
}

28. 完整游戏骨架 (星星收集)

综合运用 Sprite 动画、键盘控制与碰撞检测，搭建一个完整的“星星收集”2D 小游戏骨架。 

#include <ToyCode.h>
using namespace toy;
int main(){
    App a("星星收集");
    a.Background(Colors.FromRGB(18, 32, 58));
    auto player = a.AddSprite("hero.png", 64, 64);
    player.Play("idle");
    return a.Run();
}
← 返回官网首页 ToyCode v2.0.5 Documentation (Chapters 2-28 Complete Edition)