Hutool
  • 指南
  • 核心(hutool-core)
  • 编码解码(codec)
Hutool
2026-01-03
目录

Hex工具类-HexUtil

# 📚 介绍

HexUtil 是 Hutool 核心模块中的十六进制工具类，它继承自 Hex 类，提供了丰富的十六进制编码解码功能，以及与十六进制相关的转换和识别工具。十六进制（简写为hex或下标16）是一种逢16进1的进位制，一般用数字0到9和字母A到F表示（其中:A~F即10~15）。

# 设计理念

  • 功能全面：涵盖了几乎所有十六进制相关的操作
  • 简单易用：提供简洁的API，一行代码即可完成复杂的十六进制操作
  • 高性能：底层实现经过优化，性能优异
  • 可扩展性强：基于接口设计，便于扩展新的功能
  • 线程安全：所有工具类都是线程安全的，可以在多线程环境下安全使用

# 🔧 核心方法详解

# 1. 颜色编解码

# encodeColor(Color color)

功能：将 Color 对象编码为 Hex 形式

参数：

  • color：要编码的 Color 对象

返回值：Hex 颜色字符串，格式为 #RRGGBB

示例：

// 创建颜色对象
Color red = Color.RED;

// 编码为Hex颜色字符串
String hexColor = HexUtil.encodeColor(red);
Console.log(hexColor); // #ff0000

# encodeColor(Color color, String prefix)

功能：将 Color 对象编码为 Hex 形式，支持自定义前缀

参数：

  • color：要编码的 Color 对象
  • prefix：前缀字符串，可以是 #、0x 等

返回值：带前缀的 Hex 颜色字符串

示例：

// 创建颜色对象
Color blue = Color.BLUE;

// 使用0x前缀编码
String hexColor = HexUtil.encodeColor(blue, "0x");
Console.log(hexColor); // 0x0000ff

# decodeColor(String hexColor)

功能：将 Hex 颜色值转换为 Color 对象

参数：

  • hexColor：16进制颜色值，可以以 # 开头，也可以用 0x 开头

返回值：解码后的 Color 对象

示例：

// 解码#开头的颜色
Color red = HexUtil.decodeColor("#ff0000");

// 解码0x开头的颜色
Color blue = HexUtil.decodeColor("0x0000ff");

# 2. 十六进制识别

# isHexNumber(String value)

功能：判断给定字符串是否为16进制数

参数：

  • value：要检查的值

返回值：是否为16进制数

示例：

// 检查有效的十六进制数
boolean isHex1 = HexUtil.isHexNumber("0x123");
Console.log(isHex1); // true

boolean isHex2 = HexUtil.isHexNumber("#123abc");
Console.log(isHex2); // true

// 检查无效的十六进制数
boolean isHex3 = HexUtil.isHexNumber("123g");
Console.log(isHex3); // false

# 3. Unicode转换

# toUnicodeHex(int value)

功能：将指定int值转换为Unicode字符串形式

参数：

  • value：int值，也可以是char

返回值：Unicode表现形式

示例：

// 转换字符为Unicode
String unicode1 = HexUtil.toUnicodeHex('你');
Console.log(unicode1); // \u4f60

// 转换整数为Unicode
String unicode2 = HexUtil.toUnicodeHex(0x4f60);
Console.log(unicode2); // \u4f60

# toUnicodeHex(char ch)

功能：将指定char值转换为Unicode字符串形式

参数：

  • ch：char值

返回值：Unicode表现形式

示例：

// 转换字符为Unicode
String unicode = HexUtil.toUnicodeHex('中');
Console.log(unicode); // \u4e2d

# 4. 数值转换

# toHex(int value)

功能：将int值转换为16进制字符串

参数：

  • value：int值

返回值：16进制字符串

示例：

// 转换int为十六进制
String hex = HexUtil.toHex(255);
Console.log(hex); // ff

# hexToInt(String value)

功能：16进制字符串转为int

参数：

  • value：16进制字符串

返回值：int值

示例：

// 转换十六进制为int
int value = HexUtil.hexToInt("ff");
Console.log(value); // 255

# toHex(long value)

功能：将long值转换为16进制字符串

参数：

  • value：long值

返回值：16进制字符串

示例：

// 转换long为十六进制
String hex = HexUtil.toHex(123456789L);
Console.log(hex); // 75bcd15

# hexToLong(String value)

功能：16进制字符串转为long

参数：

  • value：16进制字符串

返回值：long值

示例：

// 转换十六进制为long
long value = HexUtil.hexToLong("75bcd15");
Console.log(value); // 123456789

# toHex(float value)

功能：将float值转换为16进制字符串

参数：

  • value：float值

返回值：16进制字符串

示例：

// 转换float为十六进制
String hex = HexUtil.toHex(123.45f);
Console.log(hex); // 42f6e666

# hexToFloat(String value)

功能：16进制字符串转为float

参数：

  • value：16进制字符串

返回值：float值

示例：

// 转换十六进制为float
float value = HexUtil.hexToFloat("42f6e666");
Console.log(value); // 123.45

# toHex(double value)

功能：将double值转换为16进制字符串

参数：

  • value：double值

返回值：16进制字符串

示例：

// 转换double为十六进制
String hex = HexUtil.toHex(123.45);
Console.log(hex); // 405edccccccccccd

# hexToDouble(String value)

功能：16进制字符串转为double

参数：

  • value：16进制字符串

返回值：double值

示例：

// 转换十六进制为double
double value = HexUtil.hexToDouble("405edccccccccccd");
Console.log(value); // 123.45

# 5. 十六进制格式化

# format(String hexStr)

功能：格式化Hex字符串，每2位加一个空格

参数：

  • hexStr：Hex字符串

返回值：格式化后的字符串

示例：

// 格式化十六进制字符串
String formatted = HexUtil.format("e88c670380cb220095268f");
Console.log(formatted); // e8 8c 67 03 80 cb 22 00 95 26 8f

# format(String hexStr, String prefix)

功能：格式化Hex字符串，每2位加一个空格，并添加前缀

参数：

  • hexStr：Hex字符串
  • prefix：自定义前缀，如0x

返回值：带前缀的格式化字符串

示例：

// 格式化并添加前缀
String formatted = HexUtil.format("e88c670380cb220095268f", "0x");
Console.log(formatted); // 0xe8 0x8c 0x67 0x03 0x80 0xcb 0x22 0x00 0x95 0x26 0x8f

# format(String hexStr, String prefix, String separator)

功能：格式化Hex字符串，每2位加一个自定义分隔符，并添加前缀

参数：

  • hexStr：Hex字符串
  • prefix：自定义前缀，如0x
  • separator：自定义分隔符，如逗号

返回值：带前缀和自定义分隔符的格式化字符串

示例：

// 格式化并使用自定义分隔符
String formatted = HexUtil.format("e88c670380cb220095268f", "0x", ", ");
Console.log(formatted); // 0xe8, 0x8c, 0x67, 0x03, 0x80, 0xcb, 0x22, 0x00, 0x95, 0x26, 0x8f

# 🚀 综合示例

# 示例1：Hex编码解码

public void hexEncodeDecodeTest() {
    // 字符串编码为十六进制
    String str = "Hello Hutool";
    String hex = HexUtil.encodeHexStr(str);
    Console.log("编码结果：" + hex); // 48656c6c6f204875746f6f6c

    // 十六进制解码为字符串
    String decodedStr = HexUtil.decodeHexStr(hex);
    Console.log("解码结果：" + decodedStr); // Hello Hutool
}

# 示例2：颜色编解码

public void colorEncodeDecodeTest() {
    // 创建颜色对象
    Color red = new Color(255, 0, 0);
    Color green = new Color(0, 255, 0);
    Color blue = new Color(0, 0, 255);

    // 编码颜色
    String redHex = HexUtil.encodeColor(red);
    String greenHex = HexUtil.encodeColor(green);
    String blueHex = HexUtil.encodeColor(blue);

    Console.log("红色Hex：" + redHex); // #ff0000
    Console.log("绿色Hex：" + greenHex); // #00ff00
    Console.log("蓝色Hex：" + blueHex); // #0000ff

    // 解码颜色
    Color decodedRed = HexUtil.decodeColor(redHex);
    Color decodedGreen = HexUtil.decodeColor(greenHex);
    Color decodedBlue = HexUtil.decodeColor(blueHex);

    Console.log("解码红色：" + decodedRed); // java.awt.Color[r=255,g=0,b=0]
    Console.log("解码绿色：" + decodedGreen); // java.awt.Color[r=0,g=255,b=0]
    Console.log("解码蓝色：" + decodedBlue); // java.awt.Color[r=0,g=0,b=255]
}

# 示例3：数值与十六进制转换

public void numberHexConvertTest() {
    // 各种数值类型转换为十六进制
    String intHex = HexUtil.toHex(255);
    String longHex = HexUtil.toHex(123456789L);
    String floatHex = HexUtil.toHex(123.45f);
    String doubleHex = HexUtil.toHex(123.45);

    Console.log("int转十六进制：" + intHex); // ff
    Console.log("long转十六进制：" + longHex); // 75bcd15
    Console.log("float转十六进制：" + floatHex); // 42f6e666
    Console.log("double转十六进制：" + doubleHex); // 405edccccccccccd

    // 十六进制转换回数值类型
    int intValue = HexUtil.hexToInt("ff");
    long longValue = HexUtil.hexToLong("75bcd15");
    float floatValue = HexUtil.hexToFloat("42f6e666");
    double doubleValue = HexUtil.hexToDouble("405edccccccccccd");

    Console.log("十六进制转int：" + intValue); // 255
    Console.log("十六进制转long：" + longValue); // 123456789
    Console.log("十六进制转float：" + floatValue); // 123.45
    Console.log("十六进制转double：" + doubleValue); // 123.45
}

# 示例4：十六进制字符串操作

public void hexStringOperationTest() {
    // 判断是否为十六进制数
    boolean isHex1 = HexUtil.isHexNumber("0x123");
    boolean isHex2 = HexUtil.isHexNumber("#123abc");
    boolean isHex3 = HexUtil.isHexNumber("123g");

    Console.log("0x123是否为十六进制：" + isHex1); // true
    Console.log("#123abc是否为十六进制：" + isHex2); // true
    Console.log("123g是否为十六进制：" + isHex3); // false

    // 格式化十六进制字符串
    String hexStr = "e88c670380cb220095268f";
    String formatted1 = HexUtil.format(hexStr);
    String formatted2 = HexUtil.format(hexStr, "0x");
    String formatted3 = HexUtil.format(hexStr, "0x", ", ");

    Console.log("默认格式化：" + formatted1); // e8 8c 67 03 80 cb 22 00 95 26 8f
    Console.log("带0x前缀格式化：" + formatted2); // 0xe8 0x8c 0x67 0x03 0x80 0xcb 0x22 0x00 0x95 0x26 0x8f
    Console.log("带0x前缀和逗号分隔格式化：" + formatted3); // 0xe8, 0x8c, 0x67, 0x03, 0x80, 0xcb, 0x22, 0x00, 0x95, 0x26, 0x8f
}

# 🎯 设计优势

  1. 功能全面：涵盖了几乎所有与十六进制相关的操作，包括编码解码、转换、识别和格式化
  2. 简单易用：提供简洁的API，一行代码即可完成复杂的十六进制操作
  3. 继承扩展：继承自Hex类，扩展了更多实用功能
  4. 高性能：底层实现经过优化，性能优异
  5. 线程安全：所有方法都是线程安全的，可以在多线程环境下安全使用
  6. 灵活扩展：支持自定义前缀、分隔符等，满足不同场景需求

# 📌 注意事项

  1. 字符编码：在进行字符串与十六进制转换时，注意指定正确的字符编码，避免乱码
  2. 数值范围：在进行数值类型转换时，注意数值范围，避免溢出
  3. 前缀处理：HexUtil会自动处理常见的十六进制前缀（0x、#），但在自定义场景下需要注意
  4. 大小写敏感：十六进制字符串默认是大小写不敏感的，但在某些场景下可能需要注意大小写
  5. 空值处理：输入参数为null时会抛出NullPointerException，需要注意处理

# 🚀 总结

HexUtil 是一个功能强大、使用便捷的十六进制工具类，为 Java 开发者提供了丰富的十六进制操作解决方案。它继承自 Hex 类，扩展了更多实用功能，包括颜色编解码、数值转换、十六进制识别和格式化等。

无论是简单的十六进制编码解码，还是复杂的颜色转换和数值转换，HexUtil 都能轻松应对。通过合理使用 HexUtil，可以简化十六进制相关的开发工作，提高开发效率，同时保证转换的准确性和性能。

HexUtil 是 Hutool 编码解码模块中的重要组成部分，与其他编码工具类一起，构成了完整的编码解码解决方案，为 Java 开发者提供了丰富的编码解码工具。

进制转换工具类-RadixUtil
哈希工具类-HashUtil

← 哈希工具类-HashUtil→

Theme by Vdoing | Copyright © 2025-2026 Hutool | Apache-2.0