getfocusables参数具体指什么，如何使用？

getFocusables 是 Java Swing 中 javax.swing.Container 类的一个方法，它的主要作用是获取一个容器内所有可以被键盘焦点（keyboard focus）选中的组件。

方法签名

我们来看一下它的完整方法签名：

public java.util.List<Component> getFocusables(Container container)

这个方法有两个重载版本：

getFocusables(Container container)

这是最常用的版本,它只需要一个参数。

• 参数:

  
  （图片来源网络，侵删）
  • Container container: 一个 java.awt.Container 对象（JPanel, JFrame, JDialog, JScrollPane 等），你想要在这个容器内查找可聚焦的组件。

• 返回值:

  • java.util.List<Component>: 一个包含 Component 对象的列表，列表中的每一个组件都是可以在该容器内接收键盘焦点的。

getFocusables(Container container, boolean orderTraversal)

这个版本多了一个布尔参数,用于控制组件在列表中的顺序。

• 参数:
  • Container container: 同上，要搜索的容器。
  • boolean orderTraversal: 一个布尔值，它决定了返回的组件列表的顺序。
    • 如果为 true: 组件将按照它们的“焦点遍历顺序”（focus traversal order）排列，这个顺序通常由组件的添加顺序、setFocusCycleRoot 方法和 setFocusTraversalPolicy 方法共同决定，这通常是最符合用户直觉的“Tab键顺序”。
    • 如果为 false: 组件将按照它们在容器中的“绘制顺序”（painting order），也就是从上到下、从左到右的顺序排列，这个顺序可能与 Tab 键的跳转顺序不一致。

核心概念：什么是“可聚焦的组件”？

一个组件是否“可聚焦”是由以下几个因素决定的，它们之间是“与”的关系，即必须全部满足：

1. 组件必须是可显示的:

   • 组件本身必须是可见的（component.isVisible() 返回 true）。
   • 组件的所有父容器也必须是可见的,如果一个组件在某个不可见的 JPanel 内部，那么它也是不可聚焦的。

2. 组件必须是可聚焦的:

   • 组件本身必须支持聚焦（component.isFocusable() 返回 true）。
   • 对于 Swing 组件，大部分交互式组件（如 JButton, JTextField, JCheckBox, JComboBox 等）默认是可聚焦的。
   • 而非交互式组件（如 JLabel, JPanel）默认是不可聚焦的，你可以通过调用 component.setFocusable(true) 来手动启用它们的聚焦能力。

3. 组件不能被禁止:

   • 组件不能处于禁用状态（component.isEnabled() 返回 true），一个禁用的 JButton 是无法接收焦点的。

4. 组件必须位于焦点遍历循环内:

   • 这是最关键但也最容易被忽略的一点,即使一个组件是可见、可聚焦且启用的，它也可能被排除在焦点遍历循环之外。
   • JComponent 的 setFocusable(boolean): 当你将一个组件设置为 false 时，它不仅会失去焦点能力，还会被永久性地从焦点遍历循环中移除。
   • FocusTraversalPolicy 的 accept(Component): 每个容器都有一个焦点遍历策略（FocusTraversalPolicy），在策略决定一个组件是否应该被包含在遍历路径中时，会调用该策略的 accept() 方法。accept() 返回 false，那么该组件就不会被包含。
   • Container 的 setFocusCycleRoot(boolean): 一个容器可以被设置为焦点循环的根，这意味着焦点可以在该容器及其子组件之间循环，而不会“溢出”到其他容器，这会影响哪些组件被认为是“可聚焦的”以及它们的遍历顺序。

代码示例

下面是一个简单的示例,演示如何使用 getFocusables。

import javax.swing.*;
import java.awt.*;
import java.util.List;
public class GetFocusablesExample {
    public static void main(String[] args) {
        SwingUtilities.invokeLater(() -> {
            // 1. 创建主窗口
            JFrame frame = new JFrame("getFocusables 示例");
            frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            frame.setSize(400, 300);
            frame.setLayout(new FlowLayout());
            // 2. 创建一个面板作为容器
            JPanel panel = new JPanel();
            panel.setBorder(BorderFactory.createTitledBorder("我的面板"));
            panel.setLayout(new GridLayout(3, 2, 5, 5));
            // 3. 向面板中添加各种组件
            JButton button1 = new JButton("按钮 1");
            JTextField textField1 = new JTextField("文本框 1");
            JLabel label1 = new JLabel("标签 1 (默认不可聚焦)");
            JCheckBox checkBox1 = new JCheckBox("复选框 1");
            // 创建一个默认不可聚焦的标签，但手动让它可聚焦
            JLabel label2 = new JLabel("标签 2 (手动可聚焦)");
            label2.setFocusable(true);
            label2.setBorder(BorderFactory.createLineBorder(Color.GRAY));
            // 创建一个禁用的按钮
            JButton disabledButton = new JButton("禁用的按钮");
            disabledButton.setEnabled(false);
            panel.add(button1);
            panel.add(textField1);
            panel.add(label1);
            panel.add(label2);
            panel.add(checkBox1);
            panel.add(disabledButton);
            frame.add(panel);
            // 4. 获取可聚焦组件列表 (使用默认的 orderTraversal=true)
            List<Component> focusableComponents = panel.getFocusables(panel);
            // 5. 打印结果
            System.out.println("--- 使用 orderTraversal=true (Tab顺序) ---");
            System.out.println("找到 " + focusableComponents.size() + " 个可聚焦组件:");
            for (Component c : focusableComponents) {
                System.out.println("- " + c.getClass().getSimpleName() + " (" + c.getName() + "): " + c);
            }
            // 6. 获取按绘制顺序排列的可聚焦组件列表
            List<Component> paintOrderComponents = panel.getFocusables(panel, false);
            System.out.println("\n--- 使用 orderTraversal=false (绘制顺序) ---");
            System.out.println("找到 " + paintOrderComponents.size() + " 个可聚焦组件:");
            for (Component c : paintOrderComponents) {
                System.out.println("- " + c.getClass().getSimpleName() + " (" + c.getName() + "): " + c);
            }
            frame.setVisible(true);
        });
    }
}

预期输出分析:

在上述代码的输出中,你会发现：

• label1 (默认不可聚焦的标签) 不会出现在列表中。
• disabledButton (禁用的按钮) 不会出现在列表中。
• label2 (手动设置为可聚焦的标签) 会出现在列表中。
• 使用 orderTraversal=true 和 false 得到的列表中，组件的顺序可能会不同，具体取决于布局管理器，对于 GridLayout，顺序可能看起来一样，但对于更复杂的布局（如 BorderLayout 或自定义布局），差异会非常明显。

主要用途

getFocusables 方法在以下场景中非常有用：

1. 调试和验证: 当你自定义 FocusTraversalPolicy 或处理复杂的焦点逻辑时，可以使用此方法来检查容器内实际有哪些组件参与了焦点循环，帮助验证你的逻辑是否正确。

2. 动态修改焦点顺序: 如果你需要根据某些运行时条件动态地改变 Tab 键的跳转顺序，你可以获取 getFocusables 返回的列表，然后修改这个列表（通过自定义的 FocusTraversalPolicy），或者基于这个列表来手动调用 requestFocus()。

3. 无障碍访问: 在实现无障碍功能时，了解哪些组件可以被用户通过键盘操作是非常重要的。

4. 单元测试: 编写测试用例来验证特定 UI 容器的焦点行为是否符合预期。