Focus System
AIUI pages not only have hosting semantics, but also participate in a focus model tied to interactive activation. Understanding focus helps you design keyboard navigation, card activation, element selection, and page-level event handling correctly.
Two Layers Of Focus
In AIUI, it is useful to distinguish between two layers of focus:
- Host Focus: Whether the current page instance is in the host's active interactive state
- Element Focus: Which specific node in the page tree is currently selected or receiving focus semantics
These two concepts are related, but they are not the same:
- Host focus determines whether the page can take over directional keys, confirm keys, and other interactions, and whether it is in an actively navigable state
- Element focus determines which node inside the page shows focus styles, receives
focus/blurevents, or becomes the currently activatable object
You can think of it this way: host focus answers "can this page interact right now," while element focus answers "where is the interaction currently inside the page."
Styling Focus States With CSS
At the CSS level, the currently supported focus-related pseudo-class is :host-focus, which is used to express whether the page is currently in host focus.
.agent-shell {
opacity: 0.72;
transform: scale(0.98);
transition: opacity 0.2s, transform 0.2s;
}
.agent-shell:host-focus {
opacity: 1;
transform: scale(1);
}
It is recommended to use this state to express whether the page has returned to the active foreground interaction context.
Listening To Focus Events In App And Page
If you need to react to host focus changes in the logic layer, you can listen to these callbacks on App or Page:
onHostFocus(): Triggered when the page regains host focusonHostBlur(): Triggered when the page loses host focus
App is suitable for global state coordination, such as pausing global shortcuts, restoring sound effects, or rebuilding global interaction state:
export default {
onHostFocus() {
console.log('app host focus restored');
},
onHostBlur() {
console.log('app host blurred');
}
}
Page is suitable for page-specific styling, text, and interaction feedback:
export default {
data: {
hostFocused: false
},
onHostFocus() {
this.setData({ hostFocused: true });
},
onHostBlur() {
this.setData({ hostFocused: false });
}
}
Element-Level Focus
Beyond host focus, the runtime also maintains element-level focus inside the page. You can use element events and state to implement UI feedback for the currently selected item.
<view
class="action-item {{focused ? 'action-item--focused' : ''}}"
bindfocus="onItemFocus"
bindblur="onItemBlur"
>
Open details
</view>
export default {
data: {
focused: false
},
onItemFocus() {
this.setData({ focused: true });
},
onItemBlur() {
this.setData({ focused: false });
}
}
This kind of element-level focus is commonly used for:
- Highlighting list items
- Switching inside button groups
- Focusing form inputs
- Indicating the current navigation position
Navigation Interaction Mode
On hosts that support directional keys or device buttons, pages usually participate in a focus-driven Navigation interaction mode. Its purpose is to let users move, choose, and activate content without relying on touch.
You can understand this mode in the following way:
Enter: Enter navigation mode, or activate the current targetArrowUp/ArrowDown: Move within the current navigation path, or scroll the root view when the page does not take overBackspace: Exit the current level, go back to the previous level, or request the page to close
If the page needs to take over these behaviors, call event.preventDefault() in the corresponding event callback, and then manage focus movement, scrolling, and activation on your own. For the built-in key behaviors, continue reading Events.
What Is Limited When The Page Is Not Focused
When a page is not in host focus, the first thing that is usually affected is interaction takeover rather than rendering:
- Directional navigation and confirm-key activation that depend on the current active page are usually limited
- The page's ability to take over default key behavior is usually limited
- Focus movement, selection, and confirm flows that depend on the page being the active interactive context are usually limited
Pure presentation capabilities are usually unaffected, for example:
- The page can keep rendering existing content
- Asynchronous data updates and
setData - Normal styling and state changes that do not depend on active focus
The exact boundary still depends on the host implementation, so it is best to treat "is the page in host focus" as an explicit state in your interaction design.
Recommended Reading
- Page Overview
- Events
- Target