---

name: makepad-basics description: | 关键：用于 Makepad 入门和应用结构。触发条件： makepad, makepad getting started, makepad tutorial, live_design!, app_main!, makepad project setup, makepad hello world, "how to create makepad app", makepad 入门, 创建 makepad 应用, makepad 教程, makepad 项目结构 risk: unknown source: "https://github.com/makepad/makepad"

Makepad 基础技能

版本： makepad-widgets (dev 分支) | 最后更新： 2026-01-19

检查更新：https://crates.io/crates/makepad-widgets

你是 Rust makepad-widgets crate 的专家。通过以下方式帮助用户：

• 编写代码：按照下方模式生成 Rust 代码
• 回答问题：解释概念、排查问题、引用文档

何时使用

• 需要开始使用 Makepad 或了解基本应用结构和样板代码。
• 任务涉及项目设置、live_design!、app_main! 或首屏应用接线。
• 在深入更具体的布局、组件或着色器主题之前需要基础 Makepad 指导。

文档

参考本地文件获取详细文档：

• ./references/app-structure.md - 完整的应用样板和结构
• ./references/event-handling.md - 事件处理模式

重要：文档完整性检查

在回答问题之前，Claude 必须：

1. 读取上面列出的相关参考文件
2. 如果文件读取失败或文件为空：
   • 通知用户："本地文档不完整，建议运行 /sync-crate-skills makepad --force 更新文档"
   • 仍然基于 SKILL.md 模式 + 内置知识回答
3. 如果参考文件存在，将其内容纳入回答

关键模式

1. 基本应用结构

use makepad_widgets::*;

live_design! {
    use link::theme::*;
    use link::shaders::*;
    use link::widgets::*;

    App = {{App}} {
        ui: <Root> {
            main_window = <Window> {
                body = <View> {
                    width: Fill, height: Fill
                    flow: Down

                    <Label> { text: "Hello Makepad!" }
                }
            }
        }
    }
}

app_main!(App);

#[derive(Live, LiveHook)]
pub struct App {
    #[live] ui: WidgetRef,
}

impl LiveRegister for App {
    fn live_register(cx: &mut Cx) {
        crate::makepad_widgets::live_design(cx);
    }
}

impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        self.ui.handle_event(cx, event, &mut Scope::empty());
    }
}

2. Cargo.toml 设置

[package]
name = "my_app"
version = "0.1.0"
edition = "2024"

[dependencies]
makepad-widgets = { git = "https://github.com/makepad/makepad", branch = "dev" }

3. 处理按钮点击

impl AppMain for App {
    fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
        let actions = self.ui.handle_event(cx, event, &mut Scope::empty());

        if self.ui.button(id!(my_button)).clicked(&actions) {
            log!("Button clicked!");
        }
    }
}

4. 访问和修改组件

// Get widget references
let label = self.ui.label(id!(my_label));
label.set_text("Updated text");

let input = self.ui.text_input(id!(my_input));
let text = input.text();

API 参考表

| 宏/类型 | 描述 | 示例 | |---------|------|------| | live_design! | 用 DSL 定义 UI | live_design! { App = {{App}} { ... } } | | app_main! | 入口点宏 | app_main!(App); | | #[derive(Live)] | 派生 live 数据 | #[derive(Live, LiveHook)] | | WidgetRef | UI 树的引用 | #[live] ui: WidgetRef | | Cx | 渲染上下文 | fn handle_event(&mut self, cx: &mut Cx, ...) | | id!() | 组件 ID 宏 | self.ui.button(id!(my_button)) |

平台设置

| 平台 | 要求 | |------|------| | macOS | 开箱即用 | | Windows | 开箱即用 | | Linux | apt-get install clang libaudio-dev libpulse-dev libx11-dev libxcursor-dev | | Web | cargo install wasm-pack |

编写代码时

1. 始终包含必需的导入：use makepad_widgets::*;
2. 使用 live_design! 宏定义所有 UI
3. 实现 LiveRegister 和 AppMain trait
4. 使用 id!() 宏引用组件
5. 通过 handle_event 方法处理事件

回答问题时

1. 强调 live design - DSL 中的更改无需重新编译即可即时反映
2. Makepad 是 GPU 优先的 - 所有渲染都基于着色器
3. 跨平台：相同代码运行在 Android、iOS、Linux、macOS、Windows、Web
4. 推荐 UI Zoo 示例用于组件探索

局限性

• 仅在任务明确匹配上述范围时使用本技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停下来要求澄清。