gpui-focus-handle
提供 GPUI 应用中键盘导航与焦点控制的核心能力,支持元素聚焦状态跟踪、Tab 键顺序切换、焦点获取与失去事件响应,以及模态框内焦点约束等交互模式,确保界面符合无障碍访问标准。
软件开发
| name | gpui-focus-handle |
| description | Focus management and keyboard navigation in GPUI. Use when handling focus, focus handles, or keyboard navigation. Enables keyboard-driven interfaces with proper focus tracking and navigation between focusable elements. |
Overview
GPUI's focus system enables keyboard navigation and focus management.
Key Concepts:
- FocusHandle: Reference to focusable element
- Focus tracking: Current focused element
- Keyboard navigation: Tab/Shift-Tab between elements
- Focus events: on_focus, on_blur
Quick Start
Creating Focus Handles
▼rust复制代码struct FocusableComponent { focus_handle: FocusHandle, } impl FocusableComponent { fn new(cx: &mut Context<Self>) -> Self { Self { focus_handle: cx.focus_handle(), } } }
Making Elements Focusable
▼rust复制代码impl Render for FocusableComponent { fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement { div() .track_focus(&self.focus_handle) .on_action(cx.listener(Self::on_enter)) .child("Focusable content") } fn on_enter(&mut self, _: &Enter, cx: &mut Context<Self>) { // Handle Enter key when focused cx.notify(); } }
Focus Management
▼rust复制代码impl MyComponent { fn focus(&mut self, cx: &mut Context<Self>) { self.focus_handle.focus(cx); } fn is_focused(&self, cx: &App) -> bool { self.focus_handle.is_focused(cx) } fn blur(&mut self, cx: &mut Context<Self>) { cx.blur(); } }
Focus Events
Handling Focus Changes
▼rust复制代码impl Render for MyInput { fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement { let is_focused = self.focus_handle.is_focused(cx); div() .track_focus(&self.focus_handle) .on_focus(cx.listener(|this, _event, cx| { this.on_focus(cx); })) .on_blur(cx.listener(|this, _event, cx| { this.on_blur(cx); })) .when(is_focused, |el| { el.bg(cx.theme().focused_background) }) .child(self.render_content()) } } impl MyInput { fn on_focus(&mut self, cx: &mut Context<Self>) { // Handle focus gained cx.notify(); } fn on_blur(&mut self, cx: &mut Context<Self>) { // Handle focus lost cx.notify(); } }
Keyboard Navigation
Tab Order
Elements with track_focus() automatically participate in Tab navigation.
▼rust复制代码div() .child( input1.track_focus(&focus1) // Tab order: 1 ) .child( input2.track_focus(&focus2) // Tab order: 2 ) .child( input3.track_focus(&focus3) // Tab order: 3 )
Focus Within Containers
▼rust复制代码impl Container { fn focus_first(&mut self, cx: &mut Context<Self>) { if let Some(first) = self.children.first() { first.update(cx, |child, cx| { child.focus_handle.focus(cx); }); } } fn focus_next(&mut self, cx: &mut Context<Self>) { // Custom focus navigation logic } }
Common Patterns
1. Auto-focus on Mount
▼rust复制代码impl MyDialog { fn new(cx: &mut Context<Self>) -> Self { let focus_handle = cx.focus_handle(); // Focus when created focus_handle.focus(cx); Self { focus_handle } } }
2. Focus Trap (Modal)
▼rust复制代码impl Modal { fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement { div() .track_focus(&self.focus_handle) .on_key_down(cx.listener(|this, event: &KeyDownEvent, cx| { if event.key == Key::Tab { // Keep focus within modal this.focus_next_in_modal(cx); cx.stop_propagation(); } })) .child(self.render_content()) } }
3. Conditional Focus
▼rust复制代码impl Searchable { fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement { div() .track_focus(&self.focus_handle) .when(self.search_active, |el| { el.on_mount(cx.listener(|this, _, cx| { this.focus_handle.focus(cx); })) }) .child(self.search_input()) } }
Best Practices
✅ Track Focus on Interactive Elements
▼rust复制代码// ✅ Good: Track focus for keyboard interaction input() .track_focus(&self.focus_handle) .on_action(cx.listener(Self::on_enter))
✅ Provide Visual Focus Indicators
▼rust复制代码let is_focused = self.focus_handle.is_focused(cx); div() .when(is_focused, |el| { el.border_color(cx.theme().focused_border) })
❌ Don't: Forget to Track Focus
▼rust复制代码// ❌ Bad: No track_focus, keyboard navigation won't work div() .on_action(cx.listener(Self::on_enter))
Reference Documentation
- API Reference: See api-reference.md
- FocusHandle API, focus management
- Events, keyboard navigation
- Best practices
软件开发









