robius-widget-patterns
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRobius Widget Patterns Skill
Robius Widget 模式 Skill
Best practices for designing reusable Makepad widgets based on Robrix and Moly codebase patterns.
Source codebases:
- Robrix: Matrix chat client - Avatar, RoomsList, RoomScreen widgets
- Moly: AI chat application - Slot, ChatLine, PromptInput, AdaptiveView widgets
基于Robrix和Moly代码库模式,设计可复用Makepad组件的最佳实践。
源代码库:
- Robrix:Matrix聊天客户端 - Avatar、RoomsList、RoomScreen组件
- Moly:AI聊天应用 - Slot、ChatLine、PromptInput、AdaptiveView组件
Triggers
触发场景
Use this skill when:
- Creating reusable Makepad widgets
- Designing widget component APIs
- Implementing text/image toggle patterns
- Dynamic styling in Makepad
- Keywords: robrix widget, makepad component, reusable widget, widget design pattern
在以下场景使用本Skill:
- 创建可复用Makepad组件
- 设计组件API
- 实现文本/图片切换模式
- Makepad中的动态样式
- 关键词:robrix widget、makepad component、reusable widget、widget design pattern
Production Patterns
生产级模式
For production-ready widget patterns, see the directory:
_base/| Pattern | Description |
|---|---|
| 01-widget-extension | Add helper methods to widget references |
| 02-modal-overlay | Popups, dialogs using DrawList2d overlay |
| 03-collapsible | Expandable/collapsible sections |
| 04-list-template | Dynamic lists with LivePtr templates |
| 05-lru-view-cache | Memory-efficient view caching |
| 14-callout-tooltip | Tooltips with arrow positioning |
| 20-redraw-optimization | Efficient redraw patterns |
| 15-dock-studio-layout | IDE-style resizable panels |
| 16-hover-effect | Hover effects with instance variables |
| 17-row-based-grid-layout | Dynamic grid layouts |
| 18-drag-drop-reorder | Drag-and-drop widget reordering |
| 19-pageflip-optimization | PageFlip 切换优化,即刻销毁/缓存模式 |
| 21-collapsible-row-portal-list | Auto-grouping consecutive items in portal lists with FoldHeader |
| 22-dropdown-overlay | Dropdown popups using DrawList2d overlay (no layout push) |
如需生产就绪的组件模式,请查看目录:
_base/| 模式 | 描述 |
|---|---|
| 01-widget-extension | 为组件引用添加辅助方法 |
| 02-modal-overlay | 使用DrawList2d叠加层实现弹窗、对话框 |
| 03-collapsible | 可展开/折叠的区域 |
| 04-list-template | 基于LivePtr模板的动态列表 |
| 05-lru-view-cache | 内存高效的视图缓存 |
| 14-callout-tooltip | 带箭头定位的提示框 |
| 20-redraw-optimization | 高效重绘模式 |
| 15-dock-studio-layout | IDE风格的可调整大小面板 |
| 16-hover-effect | 带实例变量的悬停效果 |
| 17-row-based-grid-layout | 动态网格布局 |
| 18-drag-drop-reorder | 拖拽重排组件 |
| 19-pageflip-optimization | PageFlip切换优化,即刻销毁/缓存模式 |
| 21-collapsible-row-portal-list | 使用FoldHeader在门户列表中自动分组连续项 |
| 22-dropdown-overlay | 使用DrawList2d叠加层实现下拉弹窗(无需布局推送) |
Standard Widget Structure
标准组件结构
rust
use makepad_widgets::*;
live_design! {
use link::theme::*;
use link::widgets::*;
pub MyWidget = {{MyWidget}} {
width: Fill, height: Fit,
flow: Down,
// Child widgets defined in DSL
inner_view = <View> {
// ...
}
}
}
#[derive(Live, LiveHook, Widget)]
pub struct MyWidget {
#[deref] view: View, // Delegate to inner View
#[live] some_property: f64, // DSL-configurable property
#[live(100.0)] default_val: f64, // With default value
#[rust] internal_state: State, // Rust-only state (not in DSL)
#[animator] animator: Animator, // For animations
}
impl Widget for MyWidget {
fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
self.view.handle_event(cx, event, scope);
// Custom event handling...
}
fn draw_walk(&mut self, cx: &mut Cx2d, scope: &mut Scope, walk: Walk) -> DrawStep {
self.view.draw_walk(cx, scope, walk)
}
}rust
use makepad_widgets::*;
live_design! {
use link::theme::*;
use link::widgets::*;
pub MyWidget = {{MyWidget}} {
width: Fill, height: Fit,
flow: Down,
// Child widgets defined in DSL
inner_view = <View> {
// ...
}
}
}
#[derive(Live, LiveHook, Widget)]
pub struct MyWidget {
#[deref] view: View, // Delegate to inner View
#[live] some_property: f64, // DSL-configurable property
#[live(100.0)] default_val: f64, // With default value
#[rust] internal_state: State, // Rust-only state (not in DSL)
#[animator] animator: Animator, // For animations
}
impl Widget for MyWidget {
fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
self.view.handle_event(cx, event, scope);
// Custom event handling...
}
fn draw_walk(&mut self, cx: &mut Cx2d, scope: &mut Scope, walk: Walk) -> DrawStep {
self.view.draw_walk(cx, scope, walk)
}
}Text/Image Toggle Pattern
文本/图片切换模式
A common pattern for widgets that show either text or an image (like avatars):
rust
live_design! {
pub Avatar = {{Avatar}} {
width: 36.0, height: 36.0,
align: { x: 0.5, y: 0.5 }
flow: Overlay, // Stack views on top of each other
text_view = <View> {
visible: true, // Default visible
show_bg: true,
draw_bg: {
uniform background_color: #888888
fn pixel(self) -> vec4 {
let sdf = Sdf2d::viewport(self.pos * self.rect_size);
let c = self.rect_size * 0.5;
sdf.circle(c.x, c.x, c.x)
sdf.fill_keep(self.background_color);
return sdf.result
}
}
text = <Label> {
text: "?"
}
}
img_view = <View> {
visible: false, // Hidden by default
img = <Image> {
fit: Stretch,
width: Fill, height: Fill,
}
}
}
}
#[derive(LiveHook, Live, Widget)]
pub struct Avatar {
#[deref] view: View,
#[rust] info: Option<UserInfo>,
}
impl Avatar {
/// Show text content, hiding the image
pub fn show_text<T: AsRef<str>>(
&mut self,
cx: &mut Cx,
bg_color: Option<Vec4>,
info: Option<AvatarTextInfo>,
username: T,
) {
self.info = info.map(|i| i.into());
// Get first character
let first_char = utils::first_letter(username.as_ref())
.unwrap_or("?").to_uppercase();
self.label(ids!(text_view.text)).set_text(cx, &first_char);
// Toggle visibility
self.view(ids!(text_view)).set_visible(cx, true);
self.view(ids!(img_view)).set_visible(cx, false);
// Apply optional background color
if let Some(color) = bg_color {
self.view(ids!(text_view)).apply_over(cx, live! {
draw_bg: { background_color: (color) }
});
}
}
/// Show image content, hiding the text
pub fn show_image<F, E>(
&mut self,
cx: &mut Cx,
info: Option<AvatarImageInfo>,
image_set_fn: F,
) -> Result<(), E>
where
F: FnOnce(&mut Cx, ImageRef) -> Result<(), E>
{
let img_ref = self.image(ids!(img_view.img));
let res = image_set_fn(cx, img_ref);
if res.is_ok() {
self.view(ids!(img_view)).set_visible(cx, true);
self.view(ids!(text_view)).set_visible(cx, false);
self.info = info.map(|i| i.into());
}
res
}
/// Check current display status
pub fn status(&mut self) -> DisplayStatus {
if self.view(ids!(img_view)).visible() {
DisplayStatus::Image
} else {
DisplayStatus::Text
}
}
}适用于显示文本或图片的组件(如头像)的常见模式:
rust
live_design! {
pub Avatar = {{Avatar}} {
width: 36.0, height: 36.0,
align: { x: 0.5, y: 0.5 }
flow: Overlay, // Stack views on top of each other
text_view = <View> {
visible: true, // Default visible
show_bg: true,
draw_bg: {
uniform background_color: #888888
fn pixel(self) -> vec4 {
let sdf = Sdf2d::viewport(self.pos * self.rect_size);
let c = self.rect_size * 0.5;
sdf.circle(c.x, c.x, c.x)
sdf.fill_keep(self.background_color);
return sdf.result
}
}
text = <Label> {
text: "?"
}
}
img_view = <View> {
visible: false, // Hidden by default
img = <Image> {
fit: Stretch,
width: Fill, height: Fill,
}
}
}
}
#[derive(LiveHook, Live, Widget)]
pub struct Avatar {
#[deref] view: View,
#[rust] info: Option<UserInfo>,
}
impl Avatar {
/// Show text content, hiding the image
pub fn show_text<T: AsRef<str>>(
&mut self,
cx: &mut Cx,
bg_color: Option<Vec4>,
info: Option<AvatarTextInfo>,
username: T,
) {
self.info = info.map(|i| i.into());
// Get first character
let first_char = utils::first_letter(username.as_ref())
.unwrap_or("?").to_uppercase();
self.label(ids!(text_view.text)).set_text(cx, &first_char);
// Toggle visibility
self.view(ids!(text_view)).set_visible(cx, true);
self.view(ids!(img_view)).set_visible(cx, false);
// Apply optional background color
if let Some(color) = bg_color {
self.view(ids!(text_view)).apply_over(cx, live! {
draw_bg: { background_color: (color) }
});
}
}
/// Show image content, hiding the text
pub fn show_image<F, E>(
&mut self,
cx: &mut Cx,
info: Option<AvatarImageInfo>,
image_set_fn: F,
) -> Result<(), E>
where
F: FnOnce(&mut Cx, ImageRef) -> Result<(), E>
{
let img_ref = self.image(ids!(img_view.img));
let res = image_set_fn(cx, img_ref);
if res.is_ok() {
self.view(ids!(img_view)).set_visible(cx, true);
self.view(ids!(text_view)).set_visible(cx, false);
self.info = info.map(|i| i.into());
}
res
}
/// Check current display status
pub fn status(&mut self) -> DisplayStatus {
if self.view(ids!(img_view)).visible() {
DisplayStatus::Image
} else {
DisplayStatus::Text
}
}
}Dynamic Styling with apply_over
使用apply_over实现动态样式
Apply dynamic styles at runtime:
rust
// Apply single property
self.view(ids!(content)).apply_over(cx, live! {
draw_bg: { color: #ff0000 }
});
// Apply multiple properties
self.view(ids!(message)).apply_over(cx, live! {
padding: { left: 20, right: 20 }
margin: { top: 10 }
});
// Apply with variables
let highlight_color = if is_selected { vec4(1.0, 0.0, 0.0, 1.0) } else { vec4(0.5, 0.5, 0.5, 1.0) };
self.view(ids!(item)).apply_over(cx, live! {
draw_bg: { color: (highlight_color) }
});在运行时应用动态样式:
rust
// Apply single property
self.view(ids!(content)).apply_over(cx, live! {
draw_bg: { color: #ff0000 }
});
// Apply multiple properties
self.view(ids!(message)).apply_over(cx, live! {
padding: { left: 20, right: 20 }
margin: { top: 10 }
});
// Apply with variables
let highlight_color = if is_selected { vec4(1.0, 0.0, 0.0, 1.0) } else { vec4(0.5, 0.5, 0.5, 1.0) };
self.view(ids!(item)).apply_over(cx, live! {
draw_bg: { color: (highlight_color) }
});Widget Reference Pattern
组件引用模式
Implement methods for external API:
*Refrust
impl AvatarRef {
/// See [`Avatar::show_text()`].
pub fn show_text<T: AsRef<str>>(
&self,
cx: &mut Cx,
bg_color: Option<Vec4>,
info: Option<AvatarTextInfo>,
username: T,
) {
if let Some(mut inner) = self.borrow_mut() {
inner.show_text(cx, bg_color, info, username);
}
}
/// See [`Avatar::show_image()`].
pub fn show_image<F, E>(
&self,
cx: &mut Cx,
info: Option<AvatarImageInfo>,
image_set_fn: F,
) -> Result<(), E>
where
F: FnOnce(&mut Cx, ImageRef) -> Result<(), E>
{
if let Some(mut inner) = self.borrow_mut() {
inner.show_image(cx, info, image_set_fn)
} else {
Ok(())
}
}
}为外部API实现方法:
*Refrust
impl AvatarRef {
/// See [`Avatar::show_text()`].
pub fn show_text<T: AsRef<str>>(
&self,
cx: &mut Cx,
bg_color: Option<Vec4>,
info: Option<AvatarTextInfo>,
username: T,
) {
if let Some(mut inner) = self.borrow_mut() {
inner.show_text(cx, bg_color, info, username);
}
}
/// See [`Avatar::show_image()`].
pub fn show_image<F, E>(
&self,
cx: &mut Cx,
info: Option<AvatarImageInfo>,
image_set_fn: F,
) -> Result<(), E>
where
F: FnOnce(&mut Cx, ImageRef) -> Result<(), E>
{
if let Some(mut inner) = self.borrow_mut() {
inner.show_image(cx, info, image_set_fn)
} else {
Ok(())
}
}
}Collapsible/Expandable Pattern
可折叠/展开模式
rust
live_design! {
pub CollapsibleSection = {{CollapsibleSection}} {
flow: Down,
header = <View> {
cursor: Hand,
icon = <Icon> { }
title = <Label> { text: "Section" }
}
content = <View> {
visible: false,
// Expandable content here
}
}
}
#[derive(Live, LiveHook, Widget)]
pub struct CollapsibleSection {
#[deref] view: View,
#[rust] is_expanded: bool,
}
impl CollapsibleSection {
pub fn toggle(&mut self, cx: &mut Cx) {
self.is_expanded = !self.is_expanded;
self.view(ids!(content)).set_visible(cx, self.is_expanded);
// Rotate icon
let rotation = if self.is_expanded { 90.0 } else { 0.0 };
self.view(ids!(header.icon)).apply_over(cx, live! {
draw_icon: { rotation: (rotation) }
});
self.redraw(cx);
}
}rust
live_design! {
pub CollapsibleSection = {{CollapsibleSection}} {
flow: Down,
header = <View> {
cursor: Hand,
icon = <Icon> { }
title = <Label> { text: "Section" }
}
content = <View> {
visible: false,
// Expandable content here
}
}
}
#[derive(Live, LiveHook, Widget)]
pub struct CollapsibleSection {
#[deref] view: View,
#[rust] is_expanded: bool,
}
impl CollapsibleSection {
pub fn toggle(&mut self, cx: &mut Cx) {
self.is_expanded = !self.is_expanded;
self.view(ids!(content)).set_visible(cx, self.is_expanded);
// Rotate icon
let rotation = if self.is_expanded { 90.0 } else { 0.0 };
self.view(ids!(header.icon)).apply_over(cx, live! {
draw_icon: { rotation: (rotation) }
});
self.redraw(cx);
}
}Loading State Pattern
加载状态模式
rust
live_design! {
pub LoadableContent = {{LoadableContent}} {
flow: Overlay,
content = <View> {
visible: true,
// Main content
}
loading_overlay = <View> {
visible: false,
show_bg: true,
draw_bg: { color: #00000088 }
align: { x: 0.5, y: 0.5 }
<BouncingDots> { }
}
error_view = <View> {
visible: false,
error_label = <Label> { }
}
}
}
#[derive(Live, LiveHook, Widget)]
pub struct LoadableContent {
#[deref] view: View,
#[rust] state: LoadingState,
}
pub enum LoadingState {
Idle,
Loading,
Loaded,
Error(String),
}
impl LoadableContent {
pub fn set_state(&mut self, cx: &mut Cx, state: LoadingState) {
self.state = state;
match &self.state {
LoadingState::Idle | LoadingState::Loaded => {
self.view(ids!(content)).set_visible(cx, true);
self.view(ids!(loading_overlay)).set_visible(cx, false);
self.view(ids!(error_view)).set_visible(cx, false);
}
LoadingState::Loading => {
self.view(ids!(content)).set_visible(cx, true);
self.view(ids!(loading_overlay)).set_visible(cx, true);
self.view(ids!(error_view)).set_visible(cx, false);
}
LoadingState::Error(msg) => {
self.view(ids!(content)).set_visible(cx, false);
self.view(ids!(loading_overlay)).set_visible(cx, false);
self.view(ids!(error_view)).set_visible(cx, true);
self.label(ids!(error_view.error_label)).set_text(cx, msg);
}
}
self.redraw(cx);
}
}rust
live_design! {
pub LoadableContent = {{LoadableContent}} {
flow: Overlay,
content = <View> {
visible: true,
// Main content
}
loading_overlay = <View> {
visible: false,
show_bg: true,
draw_bg: { color: #00000088 }
align: { x: 0.5, y: 0.5 }
<BouncingDots> { }
}
error_view = <View> {
visible: false,
error_label = <Label> { }
}
}
}
#[derive(Live, LiveHook, Widget)]
pub struct LoadableContent {
#[deref] view: View,
#[rust] state: LoadingState,
}
pub enum LoadingState {
Idle,
Loading,
Loaded,
Error(String),
}
impl LoadableContent {
pub fn set_state(&mut self, cx: &mut Cx, state: LoadingState) {
self.state = state;
match &self.state {
LoadingState::Idle | LoadingState::Loaded => {
self.view(ids!(content)).set_visible(cx, true);
self.view(ids!(loading_overlay)).set_visible(cx, false);
self.view(ids!(error_view)).set_visible(cx, false);
}
LoadingState::Loading => {
self.view(ids!(content)).set_visible(cx, true);
self.view(ids!(loading_overlay)).set_visible(cx, true);
self.view(ids!(error_view)).set_visible(cx, false);
}
LoadingState::Error(msg) => {
self.view(ids!(content)).set_visible(cx, false);
self.view(ids!(loading_overlay)).set_visible(cx, false);
self.view(ids!(error_view)).set_visible(cx, true);
self.label(ids!(error_view.error_label)).set_text(cx, msg);
}
}
self.redraw(cx);
}
}PortalList Item Pattern
PortalList 项模式
For virtual list items:
rust
live_design! {
pub ItemsList = {{ItemsList}} {
list = <PortalList> {
keep_invisible: false,
auto_tail: false,
width: Fill, height: Fill,
flow: Down,
// Item templates
item_entry = <ItemEntry> {}
header = <SectionHeader> {}
empty = <View> {}
}
}
}
impl Widget for ItemsList {
fn draw_walk(&mut self, cx: &mut Cx2d, scope: &mut Scope, walk: Walk) -> DrawStep {
while let Some(item) = self.view.draw_walk(cx, scope, walk).step() {
if let Some(mut list) = item.as_portal_list().borrow_mut() {
list.set_item_range(cx, 0, self.items.len());
while let Some(item_id) = list.next_visible_item(cx) {
let item = list.item(cx, item_id, live_id!(item_entry));
// Populate item with data
self.populate_item(cx, item, &self.items[item_id]);
item.draw_all(cx, scope);
}
}
}
DrawStep::done()
}
}适用于虚拟列表项:
rust
live_design! {
pub ItemsList = {{ItemsList}} {
list = <PortalList> {
keep_invisible: false,
auto_tail: false,
width: Fill, height: Fill,
flow: Down,
// Item templates
item_entry = <ItemEntry> {}
header = <SectionHeader> {}
empty = <View> {}
}
}
}
impl Widget for ItemsList {
fn draw_walk(&mut self, cx: &mut Cx2d, scope: &mut Scope, walk: Walk) -> DrawStep {
while let Some(item) = self.view.draw_walk(cx, scope, walk).step() {
if let Some(mut list) = item.as_portal_list().borrow_mut() {
list.set_item_range(cx, 0, self.items.len());
while let Some(item_id) = list.next_visible_item(cx) {
let item = list.item(cx, item_id, live_id!(item_entry));
// Populate item with data
self.populate_item(cx, item, &self.items[item_id]);
item.draw_all(cx, scope);
}
}
}
DrawStep::done()
}
}Best Practices
最佳实践
- Use for delegation: Delegate to inner View for standard behavior
#[deref] - Separate DSL properties () from Rust state (
#[live])#[rust] - Implement both inner methods and wrappers
*Ref - Use for dynamic runtime styling
apply_over - Use for toggle/swap patterns
flow: Overlay - Use to toggle between alternative views
set_visible() - Always call after state changes
redraw(cx)
- 使用进行委托:将标准行为委托给内部View
#[deref] - 分离DSL属性()与Rust状态(
#[live])#[rust] - 同时实现内部方法和包装器
*Ref - 使用实现运行时动态样式
apply_over - 使用实现切换/替换模式
flow: Overlay - 使用在备选视图间切换
set_visible() - 状态变更后务必调用
redraw(cx)
Reference Files
参考文件
- - Additional widget patterns (Robrix)
references/widget-patterns.md - - Dynamic styling patterns (Robrix)
references/styling-patterns.md - - Moly-specific patterns
references/moly-widget-patterns.md- widget for runtime content replacement
Slot - conditional rendering wrapper
MolyRoot - for responsive Mobile/Desktop layouts
AdaptiveView - Chat line variants (UserLine, BotLine, ErrorLine, etc.)
- with action buttons
CommandTextInput - Sidebar navigation with radio buttons
- - 更多组件模式(Robrix)
references/widget-patterns.md - - 动态样式模式(Robrix)
references/styling-patterns.md - - Moly专属模式
references/moly-widget-patterns.md- 组件:用于运行时内容替换
Slot - 条件渲染包装器
MolyRoot - :响应式移动端/桌面端布局
AdaptiveView - 聊天行变体(UserLine、BotLine、ErrorLine等)
- :带操作按钮的文本输入框
CommandTextInput - 带单选按钮的侧边栏导航