skills/arkui-menu-debug/SKILL.md
This skill should be used when user asks to "Menu宽度为0", "Menu宽度问题", "Menu显示异常", "Menu子窗口问题", "Menu layout异常", "recreate subwindow", "快速打开Menu问题", "Menu闪退", "Menu位置错误", "子窗口recreate", "Menu崩溃", "Menu打印recreate", "点击无响应", "点击菜单关闭", "菜单位置左上角", "菜单方向不对", "菜单避让坑", "宽度高度为0", or mentions any Menu component issues like Menu width being 0, Menu display problems, Menu subwindow issues, Menu layout exceptions, positioning errors, crashes, click response issues, menu closing immediately, incorrect positioning, direction issues, safe area issues, or zero width/height problems. Provides systematic debugging guidance for Menu component issues including width problems, subwindow recreation, layout exceptions, positioning errors, crash analysis, click issues, menu positioning, and dimension problems with automatic log enhancement patch generation.
npx skillsauth add openharmonyinsight/openharmony-skills menu-debugInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Systematic debugging and problem diagnosis for Menu component issues in OpenHarmony ACE Engine. This skill provides structured troubleshooting guidance for Menu-related problems with automatic log enhancement patch generation.
Menu component debugging requires analyzing multiple layers:
Critical Requirements:
Symptoms:
Common Causes:
displayWindowRectInfo.Width() returns 0 (async initialization not complete)Symptoms:
Common Causes:
Symptoms:
Common Causes:
Symptoms:
Common Causes:
Symptoms:
Common Causes:
Symptoms:
Common Causes:
Symptoms:
Common Causes:
Symptoms:
Common Causes:
Symptoms:
Common Causes:
Based on symptoms, identify which problem category:
Width/Dimension Issues → Look for:
Menu width is 0
menuMaxWidth = 0
displayWindowRectInfo.Width() = 0
Subwindow Issues → Look for:
recreate subwindow
DETACHING state
MenuWindowRect
Layout Issues → Look for:
MenuOffset incorrect
position calculation error
menuWindowRect
Crash Issues → Look for:
Segmentation fault
Null pointer
CHECK_NULL_*
Click/Auto-Close Issues → Look for:
HideMenu called
state transition
gesture event not received
Positioning Issues → Look for:
anchorPoint calculation
MenuWindowRect values
offset errors
For Width/Dimension Issues:
menu_layout_algorithm.cpp:941 - UpdateChildConstraintByDevicemenu_layout_algorithm.cpp:3618 - GetMenuWindowRectInfomenu_layout_algorithm.cpp:931 - Pipeline context sourcemenu_pattern.cpp - Menu wrapper initializationFor Subwindow Issues:
subwindow_manager.cpp:1954 - GetOrCreateMenuSubWindowsubwindow_manager.cpp:1965 - Recreate logmenu_wrapper_pattern.cpp - Menu wrapper lifecycleFor Layout Issues:
menu_layout_algorithm.cpp:3611-3659 - GetMenuWindowRectInfomenu_pattern.cpp - Menu positioningmulti_menu_layout_algorithm.cpp - Multi-menu layoutFor Click/Auto-Close Issues:
menu_wrapper_pattern.cpp - OnDetach/OnAttachmenu_pattern.cpp - Menu state managementmenu_view.cpp - Event handlingFor Positioning Issues:
menu_layout_algorithm.cpp - GetMenuWindowRectInfomenu_pattern.cpp - Offset calculationsubwindow_manager.cpp - Window rect calculationKey log tags to filter:
# Menu-related logs
cat xxx.log | grep "ACE_MENU"
cat xxx.log | grep "ACE_SUB_WINDOW"
cat xxx.log | grep "ACE_OVERLAY"
# Specific issues
cat xxx.log | grep "recreate subwindow"
cat xxx.log | grep "DisplayWindowRectInfo"
cat xxx.log | grep "MenuWindowRect"
cat xxx.log | grep "HideMenu"
cat xxx.log | grep "OnClick"
Critical log patterns:
recreate subwindow → Subwindow recreation occurredDisplayWindowRectInfo width is 0 → Width initialization problemDETACHING → Window state transitionMenuWindowRect → Window rect calculationHideMenu → Menu hide operationSymptoms:
Possible Causes:
事件中心未正确初始化
菜单状态不正确
点击区域被遮挡
事件被消费
Debug Steps:
检查事件注册
# 查找菜单事件相关日志
cat xxx.log | grep "OnClick"
cat xxx.log | grep "GestureEventHub"
检查菜单状态
# 查找菜单状态
cat xxx.log | grep "MenuWrapper"
cat xxx.log | grep "MenuState"
检查 window 状态
# 查找子窗口状态
cat xxx.log | grep "ACE_SUB_WINDOW"
cat xxx.log | grep "MenuWindowRect"
Code Locations:
menu_wrapper_pattern.cpp:OnDetach() - 状态转换menu_pattern.cpp:OnClick - 点击处理menu_view.cpp:Create() - 菜单创建流程Solutions:
确保事件正确注册
检查菜单状态机
验证点击区域
添加调试日志
// 在点击处理中添加日志
TAG_LOGI(AceLogTag::ACE_MENU, "OnClick called: menuId=%{public}d", menuId);
Symptoms:
Possible Causes:
状态机错误
触摸事件冲突
Window 焦点问题
超时配置错误
Debug Steps:
检查状态转换日志
# 查找快速的状态变化
cat xxx.log | grep -E "ATTACHING|DETACHING" | head -20
检查 HideMenu 调用
# 查找谁调用了 HideMenu
cat xxx.log | grep "HideMenu" | grep -B 5 "ShowMenu"
检查触摸事件
# 查找触摸事件
cat xxx.log | grep "Touch"
cat xxx.log | grep "Click"
检查窗口生命周期
# 查找子窗口创建和销毁
cat xxx.log | grep "GetOrCreateMenuSubWindow"
cat xxx.log | grep "RemoveMenuSubWindow"
Code Locations:
menu_wrapper_pattern.cpp:OnDetach() - 状态管理menu_wrapper_pattern.cpp:HideMenu() - 隐藏逻辑menu_pattern.cpp - 状态机实现Solutions:
修复状态转换逻辑
优化事件处理
检查焦点管理
增加状态保护
// 添加状态检查
if (menuWrapperPattern->GetState() != MenuWrapperState::DETACHING) {
TAG_LOGW(AceLogTag::ACE_MENU,
"Invalid HideMenu call, current state=%{public}d",
static_cast<int>(state));
return;
}
Symptoms:
Possible Causes:
Offset 计算错误
锚点配置错误
MenuWindowRect 计算错误
Placement 配置未生效
Debug Steps:
检查位置相关日志
# 查找菜单位置计算
cat xxx.log | grep "MenuOffset"
cat xxx.log | grep "MenuPosition"
cat xxx.log | grep "targetOffset"
检查窗口 Rect 信息
# 查找窗口矩形
cat xxx.log | grep "MenuWindowRect"
cat xxx.log | grep "DisplayWindowRectInfo"
检查 placement 配置
# 查找 placement 配置
cat xxx.log | grep "placement"
cat xxx.log | grep "anchor"
Code Locations:
menu_layout_algorithm.cpp:3611-3659 - GetMenuWindowRectInfomenu_layout_algorithm.cpp - Offset 计算menu_pattern.cpp - PositionOffset 更新menu_view.cpp:1627 - UpdateMenuPlacementSolutions:
验证 Offset 计算
检查锚点配置
验证 Placement
添加位置调试日志
// 添加位置日志
TAG_LOGI(AceLogTag::ACE_MENU,
"Menu position: offset=(%{public}f,%{public}f), target=(%{public}f,%{public}f)",
offsetX, offsetY, targetOffsetX, targetOffsetY);
Symptoms:
Possible Causes:
Direction 参数错误
Placement 计算错误
Target 位置计算错误
布局算法方向错误
Debug Steps:
检查方向相关配置
# 查找方向配置
cat xxx.log | grep -E "direction|font|arrow"
检查 placement 配置
cat xxx.log | grep "placement"
cat xxx.log | grep "AlignDirection"
检查布局方向
cat xxx.log | grep "mainAxisSize"
cat xxx.log | grep "crossAxis"
Code Locations:
menu_pattern.cpp - Direction 配置menu_layout_algorithm.cpp - Placement 计算menu_item/ - 菜单项布局Solutions:
验证 Direction 参数
修正 Placement 计算
检查目标位置
添加方向调试日志
TAG_LOGI(AceLogTag::ACE_MENU,
"Menu direction: placement=%{public}d, direction=%{public}d",
placement, direction);
Symptoms:
Possible Causes:
SafeArea 未应用
Window Rect 计算错误
Z-Order 问题
Maximize 设置错误
Debug Steps:
检查 SafeArea 相关日志
cat xxx.log | grep -i "safe|safeArea"
检查 Window Mode
cat xxx.log | grep "LayoutFullScreen"
cat xxx.log | grep "WindowMode"
检查 Window Rect
cat xxx.log | grep "DisplayWindowRectInfo"
Code Locations:
subwindow_manager.cpp - Window 创建menu_layout_algorithm.cpp - SafeArea 应用Solutions:
应用 SafeArea 约束
调整 Window Mode
修正 Window Rect 计算
验证 Z-Order
Symptoms:
Possible Causes:
异步初始化未完成
Pipeline Context 来源错误
MenuParam 配置错误
计算公式错误
Debug Steps:
检查 displayWidth 相关日志
# 查找宽度计算
cat xxx.log | grep "displayWidth"
cat xxx.log | grep "displayWindowRect.Width"
cat xxx.log | grep "menuMaxWidthRatio"
检查 MenuParam
cat xxx.log | grep "MenuParam"
cat xxx.log | grep "fontSize"
检查 Pipeline Context
cat xxx.log | grep "PipelineContext"
cat xxx.log | grep "GetMainPipelineContext"
Code Locations:
menu_layout_algorithm.cpp:920-966 - UpdateChildConstraintByDevicemenu_layout_algorithm.cpp:3618 - GetMenuWindowRectInfomenu_pattern.cpp - MenuParam 处理Solutions:
添加初始化检查
// 在 GetMenuWindowRectInfo 中添加检查
auto displayWidth = displayWindowRectInfo.Width();
if (displayWidth <= 0.0f) {
TAG_LOGE(AceLogTag::ACE_MENU,
"Invalid displayWidth=%{public}f, waiting for async init",
displayWidth);
return menuWindowRect;
}
验证 Context 来源
延迟宽度计算
添加异步初始化日志
TAG_LOGI(AceLogTag::ACE_MENU,
"Async display init: displayWidth=%{public}f, ready=%{public}d",
displayWidth, IsDisplayReady());
1. State Transition Logging
TAG_LOGI(AceLogTag::ACE_SUB_WINDOW,
"Subwindow state transition: %{public}d -> %{public}d",
static_cast<int>(oldState), static_cast<int>(newState));
2. Value Context Logging
TAG_LOGI(AceLogTag::ACE_MENU,
"Calculation: displayWidth=%{public}f, menuMaxWidthRatio=%{public}f, result=%{public}f",
displayWidth, menuMaxWidthRatio, menuMaxWidth);
3. Code Path Logging
TAG_LOGI(AceLogTag::ACE_MENU,
"GetMenuWindowRectInfo: host=%{public}p, menuId=%{public}d, targetTag=%{public}d, targetNodeId=%{public}d",
host.Get(), menuPattern->GetMenuId(), targetTag_, targetNodeId_);
4. Error Context Logging
if (displayWidth <= 0.0f) {
TAG_LOGE(AceLogTag::ACE_MENU,
"Invalid displayWidth=%{public}f, expected>%{public}f",
displayWidth, expectedWidth);
return;
}
For Width/Height Issues:
displayWindowRectInfo.Width() / Height()menuMaxWidth / menuMaxHeightmenuMaxWidthRatio / menuMaxHeightRatiotheme->GetMenuMaxWidthRatio()pipeline->GetDisplayWindowRectInfo()For Subwindow Issues:
subwindow->GetDetachState()subwindow->GetShown()subwindow->GetRect().GetSize()instanceId / searchKey.ToString()For Layout Issues:
menuWindowRect (all fields)targetOffset_ / targetSize_GetMenuWindowRectInfo() return valueplacement / anchorPosition| Problem Type | File | Line(s) | Function | Key Variables |
|-------------|------|----------|----------|---------------|
| Click issues | menu_wrapper_pattern.cpp | - | OnDetach / OnAttach | state_ |
| Auto-close | menu_pattern.cpp | - | State machine | isShowing_ |
| Position (top-left) | menu_layout_algorithm.cpp | 3611-3659 | GetMenuWindowRectInfo | menuWindowRect |
| Direction | menu_pattern.cpp | - | direction_ / placement | - |
| Safe area | subwindow_manager.cpp | - | Window creation params | - |
| Width=0/Height=0 | menu_layout_algorithm.cpp | 920-966 | UpdateChildConstraintByDevice | displayWidth |
Extract all Menu-related logs:
# Comprehensive Menu logs
grep -E "ACE_MENU|ACE_SUB_WINDOW|ACE_OVERLAY" xxx.log > menu_debug.log
# Width-specific logs
grep -E "DisplayWindowRectInfo|menuMaxWidth|displayWidth" xxx.log
# Subwindow recreation logs
grep -E "recreate subwindow|DETACHING|MenuWindowState" xxx.log
# Positioning logs
grep -E "MenuOffset|MenuPosition|targetOffset|placement" xxx.log
# Click/Event logs
grep -E "OnClick|TouchEvent|GestureEvent" xxx.log
Filter by specific instance:
# For specific container ID
grep "instanceId: 123" xxx.log
# For specific menu node
grep "menuId: 456" xxx.log
DO:
DON'T:
This skill complements:
0.2.0 (2026-02-12): 新增6个常见问题分析
0.1.0 (2026-02-12): 初始版本
testing
--- name: ohos-req-value-decision description: Use after review meeting to record decision and route to next step. Triggers: 评审决策纪要, 评审结论回流, value decision, 评审接纳, 评审不接纳, 评审退回, 下次重新上会. Do NOT use for feature baseline (ohos-req-feature-baseline), review gate checks (ohos-req-review-gate), or IR generation (ohos-req-feature-to-ir). metadata: author: openharmony scope: common stage: requirements capability: value-decision version: 0.3.0 status: draft tags: - sdd - requirements
development
Use when converting an OpenHarmony requirement document, spec, or design proposal into an OpenHarmony review slide deck (需求评审 / 需求变更评审 / 设计评审 PPTX) — produces the fixed OpenHarmony-branded review-deck structure (OH logo on every page) with architecture/flow diagrams and field tables. Triggers on "需求评审PPT", "需求变更评审", "把需求文档转成评审PPT", "spec转评审PPT", "requirement/spec to review deck". NOT for arbitrary or generic slide decks unrelated to OpenHarmony requirement/design review.
testing
Use when performing the Phase 0 Step 0.5 Review Ready Gate on a 04-feature.md, especially when the user says "evaluate gate", "review readiness", "feature ready?", "should we generate IR", or when the ohos-req-intake-orchestration main session needs a structured Ready / Conditional Ready / Not Ready judgment instead of doing the check inline. Reads 01-04, runs seven fixed checks plus a conditional-items check, and returns a machine-readable JSON summary plus a human-readable table that the main session can route on. Do NOT use for feature baseline generation (ohos-req-feature-baseline), value decision recording (ohos-req-value-decision), or IR generation (ohos-req-feature-to-ir).
testing
--- name: ohos-req-requirement-intake description: Use when importing an OHOS requirement into Phase 0.1, especially for 01-requirement.md, requirement intake, background, user value, scenarios, scope, FR/NFR, affected modules, or priority. Triggers: 需求导入, 01-requirement, 需求基线, RR单号. Do NOT use for feasibility analysis (ohos-req-feasibility-analysis), architecture decision (ohos-req-arch-decision), or feature baseline (ohos-req-feature-baseline). metadata: author: openharmony scope: common