Java Swing自定义复选框CusCheckBox组件(附源码)

一、背景

用过Swing的朋友都知道，原生的JCheckBox复选框图标是跟着系统走的。Windows、macOS、Linux，每个平台画出来的样子都不一样。这要是想做个界面风格统一的桌面应用，可就头疼了——圆角、颜色、鼠标悬停效果，这些统统没法自定义。

所以，想要一个完全听你指挥的复选框，就得自己动手画。今天要聊的这个CusCheckBox组件，就是通过实现Icon接口，把绘制逻辑完全掌握在自己手里，圆角、颜色、悬停、禁用状态，想怎么调就怎么调。

二、核心设计

整个CusCheckBox的实现非常清晰，主要由两个类构成：

• CheckBoxIcon：这是核心的“画家”。它实现了Icon接口，专门负责绘制复选框的图标部分，包括背景、边框、对勾（或叉号）。
• CusCheckBox：这是对标准JCheckBox的“包装”。它继承自JCheckBox，但把默认图标换成了我们自己的CheckBoxIcon，并对外提供了一整套设置样式的方法。

这种分工很明确：一个管画，一个管用。

三、CheckBoxIcon 源码

import lombok.Setter;

import ja vax.swing.*;
import ja va.awt.*;

/**
 * 自定义 JCheckBox 图标类
 * 实现 Icon 接口，负责绘制复选框的图标部分
 *
 * 使用示例：
 * CheckBoxIcon icon = new CheckBoxIcon(20, Color.decode("#409EFF"), Color.WHITE);
 */
@Setter
public class CheckBoxIcon implements Icon {
    /** 复选框大小 */
    private int size;
    /** 圆角 */
    private boolean rounded = true;
    /** 圆角半径 */
    private int borderRadius = 8;
    /** 边框宽度 */
    private int borderThickness = 1;
    /** 边框颜色 */
    private Color borderColor = Color.GRAY;
    /** 选中背景颜色 */
    private Color selectedBg;
    /** 对勾颜色 */
    private Color checkColor;
    /** 悬停颜色 */
    private Color hoverColor;
    /** 禁用颜色 */
    private Color disabledColor = Color.decode("#E4E7ED");
    /** 对勾宽度 */
    private float checkThickness = 2.0f;
    /** 是否使用对勾（true=对勾，false=叉号） */
    private boolean useCheckMark = true;
    /** 是否启用 */
    private boolean enabled = true;

    /**
     * 构造函数
     * @param size 图标尺寸
     * @param selectedBg 选中时的背景色
     * @param checkColor 对勾颜色
     */
    public CheckBoxIcon(int size, Color selectedBg, Color checkColor) {
        this.size = Math.max(16, size);
        this.selectedBg = selectedBg;
        this.checkColor = checkColor;
    }

    @Override
    public void paintIcon(Component c, Graphics g, int x, int y) {
        AbstractButton button = (AbstractButton) c;
        ButtonModel model = button.getModel();
        Graphics2D g2 = (Graphics2D) g;
        // 启用抗锯齿
        g2.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
        // 获取状态
        boolean isSelected = model.isSelected();
        boolean isPressed = model.isPressed();
        boolean isRollover = model.isRollover();
        // 计算实际绘制区域
        int drawWidth = size - 1;
        int drawHeight = size - 1;
        // 根据状态选择颜色
        Color currentBorder = enabled ? borderColor : disabledColor;
        Color currentBg = Color.WHITE;
        if (isSelected) {
            currentBg = enabled ? selectedBg : disabledColor.brighter();
        }
        if (isRollover && !isPressed && enabled && null != hoverColor) {
            currentBg = hoverColor;
        }
        if (isPressed && enabled) {
            currentBg = selectedBg.darker();
        }
        if (!enabled) {
            currentBg = disabledColor;
        }
        // 绘制背景
        g2.setColor(currentBg);
        if (rounded) {
            g2.fillRoundRect(x, y, drawWidth, drawHeight, borderRadius, borderRadius);
        } else {
            g2.fillRect(x, y, drawWidth, drawHeight);
        }
        // 绘制边框
        g2.setColor(currentBorder);
        g2.setStroke(new BasicStroke(borderThickness));
        if (rounded) {
            g2.drawRoundRect(x, y, drawWidth, drawHeight, borderRadius, borderRadius);
        } else {
            g2.drawRect(x, y, drawWidth, drawHeight);
        }
        // 绘制选中标记
        if (isSelected) {
            drawCheckMark(g2, x, y, drawWidth, drawHeight);
        }
    }

    /**
     * 绘制选中标记（对勾或叉号）
     * @param g2 Graphics2D 对象
     * @param x 起始 X 坐标
     * @param y 起始 Y 坐标
     * @param width 绘制宽度
     * @param height 绘制高度
     */
    private void drawCheckMark(Graphics2D g2, int x, int y, int width, int height) {
        Color currentCheckColor = enabled ? checkColor : Color.DARK_GRAY;
        g2.setColor(currentCheckColor);
        g2.setStroke(new BasicStroke(checkThickness, BasicStroke.CAP_ROUND, BasicStroke.JOIN_ROUND));
        // 20% 内边距
        float padding = width * 0.2f;
        int startX = (int) (x + padding);
        int startY = y + height / 2;
        int midX = x + width / 2;
        int midY = (int) (y + height - padding);
        int endX = (int) (x + width - padding);
        int endY = (int) (y + padding);
        if (useCheckMark) {
            // 对勾
            g2.drawLine(startX, startY, midX, midY);
            g2.drawLine(midX, midY, endX, endY);
        } else {
            // 叉号
            g2.drawLine(startX, startY, endX, endY);
            g2.drawLine(startX, endY, endX, startY);
        }
    }

    @Override
    public int getIconWidth() {
        return size;
    }

    @Override
    public int getIconHeight() {
        return size;
    }

    /**
     * 设置图标尺寸
     * @param size 尺寸
     */
    public void setSize(int size) {
        this.size = Math.max(16, size);
    }
}

四、CusCheckBox 源码

import ja vax.swing.*;
import ja va.awt.*;

/**
 * 自定义复选框
 * 通过自定义 Icon 实现统一的复选框样式
 *
 * 使用示例：
 * CusCheckBox checkBox = new CusCheckBox("同意协议");
 * checkBox.setSelected(true);
 * checkBox.setHoverColor(Color.LIGHT_GRAY);
 */
public class CusCheckBox extends JCheckBox {
    /** 默认尺寸 */
    private static final int DEFAULT_SIZE = 20;
    /** 默认选中背景颜色 */
    private static final Color DEFAULT_BG = Color.decode("#409EFF");
    /** 默认选中对勾颜色 */
    private static final Color DEFAULT_CHECK = Color.WHITE;
    /** 内部图标实例 */
    private final CheckBoxIcon icon;

    /**
     * 默认构造函数
     * @param text 复选框文本
     */
    public CusCheckBox(String text) {
        this(text, DEFAULT_SIZE, DEFAULT_BG, DEFAULT_CHECK, false);
    }

    /**
     * 指定选中状态
     * @param text 复选框文本
     * @param selected 是否选中
     */
    public CusCheckBox(String text, boolean selected) {
        this(text, DEFAULT_SIZE, DEFAULT_BG, DEFAULT_CHECK, selected);
    }

    /**
     * 指定尺寸
     * @param text 复选框文本
     * @param size 图标尺寸
     */
    public CusCheckBox(String text, int size) {
        this(text, size, DEFAULT_BG, DEFAULT_CHECK, false);
    }

    /**
     * 指定尺寸和选中状态
     * @param text 复选框文本
     * @param size 图标尺寸
     * @param selected 是否选中
     */
    public CusCheckBox(String text, int size, boolean selected) {
        this(text, size, DEFAULT_BG, DEFAULT_CHECK, selected);
    }

    /**
     * 指定颜色
     * @param text 复选框文本
     * @param bg 选中时背景色
     * @param check 对勾颜色
     */
    public CusCheckBox(String text, Color bg, Color check) {
        this(text, DEFAULT_SIZE, bg, check, false);
    }

    /**
     * 指定颜色和选中状态
     * @param text 复选框文本
     * @param bg 选中时背景色
     * @param check 对勾颜色
     * @param selected 是否选中
     */
    public CusCheckBox(String text, Color bg, Color check, boolean selected) {
        this(text, DEFAULT_SIZE, bg, check, selected);
    }

    /**
     * 指定尺寸和颜色
     * @param text 复选框文本
     * @param size 图标尺寸
     * @param bg 选中时背景色
     * @param check 对勾颜色
     */
    public CusCheckBox(String text, int size, Color bg, Color check) {
        this(text, size, bg, check, false);
    }

    /**
     * 完整构造函数
     * @param text 复选框文本
     * @param size 图标尺寸
     * @param bg 选中时背景色
     * @param check 对勾颜色
     * @param selected 是否选中
     */
    public CusCheckBox(String text, int size, Color bg, Color check, boolean selected) {
        super(text);
        // 创建自定义图标
        this.icon = new CheckBoxIcon(size, bg, check);
        // 设置图标（选中和未选中共用同一个图标实例，通过状态区分绘制）
        this.setIcon(icon);
        this.setSelectedIcon(icon);
        // 设置选中状态
        this.setSelected(selected);
        // 设置文本颜色和字体
        this.setForeground(Color.BLACK);
        this.setFont(new Font("Microsoft YaHei", Font.PLAIN, 16));
        // 设置透明背景，让父容器背景显示
        this.setOpaque(false);
        // 禁用默认内容区域填充
        this.setContentAreaFilled(false);
        // 禁用边框绘制
        this.setBorderPainted(false);
        // 图标与文字间距
        this.setIconTextGap(10);
    }

    /**
     * 获取自定义图标
     * @return 图标对象
     */
    @Override
    public CheckBoxIcon getIcon() {
        return icon;
    }

    /**
     * 设置图标尺寸
     * @param size 尺寸
     */
    public void setIconSize(int size) {
        icon.setSize(size);
        revalidate();
        repaint();
    }

    /**
     * 设置选中时的背景色
     * @param color 颜色
     */
    public void setSelectedBackground(Color color) {
        icon.setSelectedBg(color);
        repaint();
    }

    /**
     * 设置对勾颜色
     * @param color 颜色
     */
    public void setCheckColor(Color color) {
        icon.setCheckColor(color);
        repaint();
    }

    /**
     * 设置边框颜色
     * @param color 颜色
     */
    public void setBorderColor(Color color) {
        icon.setBorderColor(color);
        repaint();
    }

    /**
     * 设置是否圆角
     * @param rounded 是否圆角
     */
    public void setRounded(boolean rounded) {
        icon.setRounded(rounded);
        repaint();
    }

    /**
     * 设置圆角半径
     * @param radius 半径
     */
    public void setBorderRadius(int radius) {
        icon.setRounded(true);
        icon.setBorderRadius(radius);
        repaint();
    }

    /**
     * 设置边框粗细
     * @param thickness 粗细
     */
    public void setBorderThickness(int thickness) {
        icon.setBorderThickness(thickness);
        repaint();
    }

    /**
     * 设置对勾线条粗细
     * @param thickness 粗细
     */
    public void setCheckThickness(float thickness) {
        icon.setCheckThickness(thickness);
        repaint();
    }

    /**
     * 设置使用对勾还是叉号
     * @param useCheckMark true=对勾，false=叉号
     */
    public void setUseCheckMark(boolean useCheckMark) {
        icon.setUseCheckMark(useCheckMark);
        repaint();
    }

    /**
     * 设置悬停时的背景色
     * @param color 颜色
     */
    public void setHoverColor(Color color) {
        icon.setHoverColor(color);
        repaint();
    }

    /**
     * 重写 setEnabled 以同步图标状态
     * @param enabled 是否启用
     */
    @Override
    public void setEnabled(boolean enabled) {
        super.setEnabled(enabled);
        if (icon != null) {
            icon.setEnabled(enabled);
            repaint();
        }
    }
}

五、核心功能说明

看完代码，我们来梳理一下这两个类的核心职责。

图标绘制（CheckBoxIcon）：

• paintIcon：这是灵魂所在。它根据按钮的实时状态（选中、悬停、按下、禁用）来决定绘制什么颜色和样式，实现了状态驱动的动态外观。
• drawCheckMark：负责绘制选中标记，支持对勾和叉号两种样式，线条粗细和颜色都可以定制。
• 配置丰富：圆角还是直角？边框什么颜色多粗？背景、悬停、禁用状态的颜色是什么？这些都可以通过属性灵活设置。

复选框封装（CusCheckBox）：

• 核心操作就是用我们自定义的CheckBoxIcon替换掉原生的图标。
• 提供了多个构造函数，让你可以按需组合尺寸、颜色和初始选中状态，用起来很方便。
• 对外暴露了一整套样式设置方法，从圆角、颜色到悬停效果、对勾样式，应有尽有。
• 通过设置透明背景，可以完美融入任何父容器，不会产生突兀的色块。

六、使用示例

理论说再多，不如看几个实际的例子来得直观。

6.1 基本用法

CusCheckBox checkBox = new CusCheckBox("同意用户协议");
panel.add(checkBox);

6.2 指定选中状态

CusCheckBox checkBox = new CusCheckBox("记住密码", true);
panel.add(checkBox);

6.3 自定义颜色和尺寸

CusCheckBox checkBox = new CusCheckBox("自定义样式", 24, Color.decode("#67C23A"), Color.WHITE);
checkBox.setHoverColor(Color.decode("#E6F7E6"));
panel.add(checkBox);

6.4 圆角半径调整

CusCheckBox checkBox = new CusCheckBox("圆角复选框");
checkBox.setBorderRadius(12);
panel.add(checkBox);

6.5 使用叉号代替对勾

CusCheckBox checkBox = new CusCheckBox("拒绝");
checkBox.setUseCheckMark(false);
checkBox.setSelectedBackground(Color.decode("#F56C6C"));
panel.add(checkBox);

6.6 禁用状态

CusCheckBox checkBox = new CusCheckBox("不可选");
checkBox.setEnabled(false);
panel.add(checkBox);

6.7 监听选中事件

CusCheckBox checkBox = new CusCheckBox("接收通知");
checkBox.addItemListener(e -> {
    boolean selected = e.getStateChange() == ItemEvent.SELECTED;
    System.out.println("选中状态：" + selected);
});

七、注意事项

在实际使用中，有几个细节需要留意：

• 图标共用：选中和未选中的状态，用的是同一个CheckBoxIcon实例。它内部通过ButtonModel.isSelected()来判断当前该画什么，这是一种高效的设计。
• 透明背景：代码中通过setOpaque(false)和setContentAreaFilled(false)确保了组件背景透明，这样它就能自然地“贴”在父容器上，不会遮挡背景。
• 字体兼容性：示例中字体设置为“Microsoft YaHei”，这在Windows上没问题。如果你的应用要跨平台，记得替换成更通用的字体，比如“DejaVu Sans”。
• 默认主题：默认的主题色#409EFF是参考了Element UI的风格，你可以根据自己项目的设计规范进行调整。
• 尺寸下限：图标尺寸被限制为最小16px，这是为了保证良好的可交互性，避免用户点不到。

八、小结

总的来说，CusCheckBox通过自定义Icon接口，成功绕开了Swing原生样式的限制，实现了高度可控的复选框组件。它的核心思路非常清晰：

• 实现Icon接口，在paintIcon方法里自己画。
• 根据按钮的各种状态（选中、悬停、禁用、按下）来动态改变绘制内容。
• 通过丰富的构造函数和setter方法，把配置的灵活性的交给使用者。

这种“自绘图标”的思路其实是一种通用解法，完全可以举一反三，应用到其他需要自定义样式的Swing组件上，比如单选框（RadioButton）、开关（ToggleButton）等等。掌握了它，就等于掌握了Swing界面定制化的一把钥匙。