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): 初始版本
development
Run local code quality checks covering a subset of OpenHarmony gate CI (copyright, CodeArts C/C++) plus additional local checks (pylint/flake8, shellcheck/bashate, gn format). Use before committing to reduce gate failures. Triggers on: /oh-precommit-codecheck, "门禁检查", "门禁预检", "检查代码", "run codecheck", "check code quality", "lint my code", "代码检查", or after completing code implementation. WHEN to use: before git commit, before creating PR, after modifying C/C++/Python/Shell/GN files, when gate CI fails with codecheck defects, or when you want to preview what gate will flag.
development
OpenHarmony PR full lifecycle workflow. Five modes: - Commit: standardized commit with DCO sign-off and Issue linking - Create PR: commit + push to fork + create Issue + create PR on upstream - Fix Codecheck: fetch gate CI codecheck defects from a PR and auto-fix them - Review PR: fetch a PR's changes to local for code review - Fix Review: fetch unresolved review comments from a PR and auto-fix them Triggers on: /oh-pr-workflow, "提交代码", "创建PR", "提个PR", "commit", "修复告警", "修复门禁", "修复codecheck", "fix codecheck", "review pr", "review这个pr", "看下这个pr", "检视pr", "修复review", "修复检视意见", "fix review", or a GitCode PR URL with fix/review intent.
testing
分析 HM Desktop PRD 文档,提取需求信息、验证完整性、检查章节顺序(需求来源→需求背景→需求价值分析→竞品分析→需求描述)、检查 KEP 定义、检测需求冲突并生成结构化分析报告。适用于用户请求:(1) 分析或审查 PRD 文档, (2) 从需求中提取 KEP 列表, (3) 检查 PRD 完整性或一致性, (4) 将需求映射到模块架构, (5) 验证 PRD 格式合规性, (6) 验证竞品分析章节完整性。关键词:PRD分析, requirement extraction, KEP验证, completeness check, chapter order validation, 竞品分析检查, analyze PRD, 需求提取, 完整性检查, 章节顺序验证
development
基于 PRD 文档自动生成鸿蒙系统设计文档,包括架构设计文档和功能设计文档。生成前会分析 OpenHarmony 存量代码结构,确保与现有架构兼容。架构设计文档第2章必须为竞品方案分析,位于需求背景之后。适用于用户请求:(1) 生成架构设计文档, (2) 生成功能设计文档, (3) 从 PRD 生成设计文档, (4) 创建系统架构设计, (5) 编写功能规格说明, (6) 分析 OH 代码结构。关键词:architecture design, functional design, design doc, 竞品方案分析, OpenHarmony code analysis, 架构设计, 功能设计, 设计文档生成, OH代码分析, analyze codebase, competitor analysis