Class CaptchaFontUtil

java.lang.Object
cloud.opencode.base.captcha.support.CaptchaFontUtil
public final class CaptchaFontUtil extends Object
Captcha Font Utility - Font handling utilities 验证码字体工具 - 字体处理工具

This class provides font-related utilities for CAPTCHA rendering.

此类提供验证码渲染的字体相关工具。

Features | 主要功能:

  • Font style variation - 字体样式变化
  • Configurable font size - 可配置字体大小

Usage Examples | 使用示例:

Font font = CaptchaFontUtil.getFont(config);
Font[] fonts = CaptchaFontUtil.getFonts(config, 4);

Security | 安全性:

  • Thread-safe: Yes (ConcurrentHashMap + volatile caching) - 线程安全: 是（ConcurrentHashMap + volatile 缓存）
  • Null-safe: No (config must not be null) - 空值安全: 否（配置不能为null）

Performance | 性能特性:

  • Time complexity: O(1) - bounded by small constant font/color lists - 时间复杂度: O(1)，由常量字体/颜色列表限制
  • Space complexity: O(1) - stateless utility - 空间复杂度: O(1) 无状态工具类
Since:
JDK 25, opencode-base-captcha V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • getFont

      public static Font getFont(CaptchaConfig config)
      Gets a font based on configuration. 根据配置获取字体。
      Parameters:
      config - the configuration | 配置
      Returns:
      the font | 字体

    • getFont

      public static Font getFont(String fontName, float fontSize)
      Gets a font with specified name and size. 获取指定名称和大小的字体。
      Parameters:
      fontName - the font name | 字体名称
      fontSize - the font size | 字体大小
      Returns:
      the font | 字体

    • getRandomStyleFont

      public static Font getRandomStyleFont(Font font)
      Gets a random font style. 获取随机字体样式。
      Parameters:
      font - the base font | 基础字体
      Returns:
      the styled font | 样式化字体

    • getRotatedFont

      public static Font getRotatedFont(Font font, double angle)
      Gets a rotated font. 获取旋转字体。
      Parameters:
      font - the base font | 基础字体
      angle - the rotation angle in radians | 旋转角度（弧度）
      Returns:
      the rotated font | 旋转后的字体

    • getChineseFont

      public static Font getChineseFont(float fontSize)
      Gets a font suitable for Chinese characters. 获取适合中文字符的字体。
      Parameters:
      fontSize - the font size | 字体大小
      Returns:
      the font | 字体

    • getRandomColor

      public static Color getRandomColor(CaptchaConfig config)
      Gets a random color from the config colors. 从配置颜色中获取随机颜色。
      Parameters:
      config - the configuration | 配置
      Returns:
      the random color | 随机颜色

    • randomColor

      public static Color randomColor()
      Generates a random color. 生成随机颜色。
      Returns:
      the random color | 随机颜色

    • randomLightColor

      public static Color randomLightColor()
      Generates a light random color. 生成浅随机颜色。
      Returns:
      the light color | 浅颜色

    • randomDarkColor

      public static Color randomDarkColor()
      Generates a dark random color. 生成深随机颜色。
      Returns:
      the dark color | 深颜色

    • loadCustomFont

      public static Font loadCustomFont(String path, float fontSize)
      Loads a custom font from a file path (TTF or OTF). 从文件路径加载自定义字体（TTF 或 OTF）。

      The loaded font is registered with the local GraphicsEnvironment and cached for subsequent calls with the same path and size.

      加载的字体会注册到本地 GraphicsEnvironment 并缓存，以供后续相同路径和大小的调用使用。

      Security note: This method only validates the file extension (.ttf/.otf) and canonical path. The caller is responsible for ensuring the path is safe and not controlled by untrusted input (e.g., user-supplied paths could lead to arbitrary file reads).

      安全说明: 本方法仅验证文件扩展名(.ttf/.otf)和规范路径。 调用者负责确保路径安全，不受不可信输入控制（例如，用户提供的路径可能导致任意文件读取）。

      Parameters:
      path - the font file path | 字体文件路径
      fontSize - the desired font size | 期望字体大小
      Returns:
      the loaded font | 加载的字体
      Throws:
      CaptchaException - if the font file cannot be loaded | 如果字体文件无法加载
      Since:
      JDK 25, opencode-base-captcha V1.0.3

    • getRandomFontsPerChar

      public static Font[] getRandomFontsPerChar(String baseFontName, List<String> customPaths, float fontSize, int charCount)
      Generates an array of random fonts, one per character, for anti-OCR. 为每个字符生成一个随机字体数组，用于抗 OCR。

      Builds a candidate font pool from the base font, fallback fonts, and any valid custom font paths. Each character gets a randomly selected font with a randomly applied style (PLAIN/BOLD/ITALIC/BOLD+ITALIC).

      从基础字体、备用字体和有效的自定义字体路径构建候选字体池。每个字符随机选择 一个字体并随机应用样式（普通/粗体/斜体/粗斜体）。

      Parameters:
      baseFontName - the base font name | 基础字体名称
      customPaths - the custom font paths (may be empty) | 自定义字体路径（可为空）
      fontSize - the font size | 字体大小
      charCount - the number of characters | 字符数
      Returns:
      array of fonts, one per character | 字体数组，每字符一个
      Since:
      JDK 25, opencode-base-captcha V1.0.3