状态栏NSMenu中带自定义视图的NSMenuItem VoiceOver无法正常工作

这个问题我之前也踩过坑——自定义NSMenuItem的view后，VoiceOver会因为无法识别自定义视图的无障碍属性，导致菜单导航卡住。本质是默认NSMenuItem自带完整的无障碍支持，但替换成自定义视图后，系统不知道该怎么把这个视图当成菜单项来处理，所以需要手动给自定义视图补上无障碍协议的实现。

下面是具体的解决步骤，亲测有效：

1. 让自定义视图适配无障碍协议 #

创建你的自定义视图类时，除了继承NSView，需要手动实现NSAccessibility相关的核心属性（Swift中可以直接重写对应方法，无需显式声明协议）。这个类要同时承载进度条和处理无障碍识别逻辑。

2. 实现关键无障碍属性 #

需要重写几个核心属性，让VoiceOver把这个视图识别成标准菜单项：

• accessibilityRole：返回.menuItem，明确告诉系统这是一个菜单项
• accessibilityLabel：设置菜单项的可读标题，最好直接关联对应的NSMenuItem的title，保持内容一致性
• accessibilityValue：如果进度条是确定状态，返回当前进度的百分比，让VoiceOver能播报进度详情
• accessibilityParent：关联到对应的NSMenuItem，确保无障碍元素的层级结构正确

3. 子元素的无障碍处理（可选） #

如果自定义视图里包含NSProgressIndicator，你可以选择让VoiceOver单独识别它，或者把进度信息合并到菜单项的播报内容里。如果要单独识别，重写accessibilityChildren()返回包含进度条的数组即可。

代码示例（Swift） #

class ProgressMenuItemView: NSView {
    // 关联对应的菜单项，方便同步标题等信息
    weak var menuItem: NSMenuItem?
    
    // 进度条控件
    private let progressIndicator: NSProgressIndicator = {
        let indicator = NSProgressIndicator()
        indicator.style = .bar
        indicator.isIndeterminate = false
        indicator.controlSize = .small
        indicator.sizeToFit()
        return indicator
    }()
    
    override init(frame frameRect: NSRect) {
        super.init(frame: frameRect)
        setupLayout()
    }
    
    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
    
    private func setupLayout() {
        addSubview(progressIndicator)
        // 用AutoLayout布局进度条，适配菜单项尺寸
        progressIndicator.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            progressIndicator.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 8),
            progressIndicator.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8),
            progressIndicator.centerYAnchor.constraint(equalTo: centerYAnchor),
            progressIndicator.heightAnchor.constraint(equalToConstant: 12)
        ])
    }
    
    // MARK: - 无障碍相关实现
    override var accessibilityRole: NSAccessibilityRole? {
        return .menuItem
    }
    
    override var accessibilityLabel: String? {
        // 直接复用菜单项的标题，保持内容统一
        return menuItem?.title ?? "正在处理"
    }
    
    override var accessibilityValue: String? {
        // 播报进度百分比，不确定状态下返回nil
        guard !progressIndicator.isIndeterminate else { return nil }
        return String(format: "%.0f%%", progressIndicator.doubleValue * 100)
    }
    
    override var accessibilityParent: Any? {
        // 关联到对应的菜单项，确保无障碍层级正确
        return menuItem
    }
    
    override func accessibilityChildren() -> [Any]? {
        // 让VoiceOver单独识别进度条（不需要的话可以返回nil）
        return [progressIndicator]
    }
}

4. 关联自定义视图与NSMenuItem #

在创建菜单项并设置视图时，记得把菜单项关联到自定义视图：

// 创建菜单项
let progressMenuItem = NSMenuItem(title: "正在同步数据", action: nil, keyEquivalent: "")
progressMenuItem.isEnabled = true // 确保VoiceOver能识别到可交互元素

// 创建自定义视图并关联
let customView = ProgressMenuItemView(frame: NSRect(x: 0, y: 0, width: 220, height: 22))
customView.menuItem = progressMenuItem
progressMenuItem.view = customView

// 添加到状态栏菜单
statusMenu.addItem(progressMenuItem)

额外注意事项 #

• 确保NSMenuItem的isEnabled属性设置正确，VoiceOver不会导航到禁用的元素
• 测试时用VoiceOver专用导航键（Ctrl+Option+方向键）验证，而不是普通菜单上下键，因为VoiceOver的导航基于无障碍元素树
• 如果自定义视图需要响应点击，还要重写accessibilityPerformAction(_:)方法，把点击事件转发给菜单项的action

这样处理后，VoiceOver就能正确识别你的自定义菜单项，并且可以正常在菜单中导航了。

内容的提问来源于stack exchange，提问作者Durgaprasad