Thư viện emoji-java là một giải pháp mã nguồn mở giúp xử lý biểu tượng cảm xúc (emoji) trong ứng dụng Java một cách hiệu quả và chuẩn hóa. Dưới đây là hướng dẫn chi tiết để tích hợp và sử dụng thư viện này.

Cấu trúc dự án chính

Khi tải về hoặc clone kho lưu trữ gốc (vdurmont/emoji-java), bạn sẽ thấy tổ chức thư mục như sau:

.
├── .travis.yml
├── CHANGELOG.md
├── DEPLOY.md
├── EMOJIS.md
├── LICENSE
├── README.md
├── emoji-table-generator/
│   └── src/main/resources/emojis/i18n.json
└── pom.xml

• i18n.json: Tệp dữ liệu trung tâm chứa danh sách đầy đủ các emoji, bao gồm mã Unicode, tên chuẩn, biệt danh đa ngôn ngữ và các thuộc tính khác.
• emoji-table-generator: Dự án con dùng để tự động thu thập, chuẩn hóa và xuất dữ liệu emoji từ các nguồn chính thức (Unicode Consortium, GitHub Emoji API…).
• pom.xml ở gốc: Định nghĩa các phụ thuộc, plugin và cấu hình build cho toàn bộ thư viện.

Cách thêm thư viện vào dự án

Vì emoji-java là một thư viện (không phải ứng dụng độc lập), nên không có file "chạy" riêng. Thay vào đó, bạn khai báo nó như một dependency trong hệ thống quản lý gói của dự án.

Trong Gradle (build.gradle):

dependencies {
    implementation 'com.vdurmont:emoji-java:5.1.1'
}

Trong Maven (pom.xml):

<dependency>
  <groupId>com.vdurmont</groupId>
  <artifactId>emoji-java</artifactId>
  <version>5.1.1</version>
</dependency>

Một số ví dụ sử dụng cơ bản

Sau khi thêm dependency, bạn có thể bắt đầu tương tác với emoji thông qua lớp EmojiManager:

import com.vdurmont.emoji.Emoji;
import com.vdurmont.emoji.EmojiManager;

public class EmojiDemo {
    public static void main(String[] args) {
        // Tìm emoji theo alias tiếng Anh
        Emoji happyFace = EmojiManager.getByAlias("grinning_face_with_smiling_eyes");
        System.out.println(happyFace.getUnicode()); // → "😀"

        // Kiểm tra chuỗi có chứa emoji hay không
        boolean containsEmoji = EmojiManager.isEmoji("Hello 🌍!");
        System.out.println(containsEmoji); // → true

        // Chuyển đổi emoji sang dạng HTML entity (dành cho hiển thị web)
        String htmlSafe = EmojiManager.toHtml("Java ❤️ Emoji");
        System.out.println(htmlSafe); // → "Java ❤️ Emoji"
    }
}

Tùy chỉnh dữ liệu emoji

Thư viện đọc dữ liệu từ tệp i18n.json trong classpath. Nếu cần hỗ trợ emoji tùy chỉnh hoặc cập nhật phiên bản mới sớm hơn bản phát hành chính thức, bạn có thể:

• Tạo bản sao i18n.json trong src/main/resources/emojis/ của dự án hiện tại để ghi đè phiên bản mặc định.
• Sử dụng EmojiManager.setEmojiList(...) để cung cấp danh sách emoji đã được parse thủ công.
• Fork repository và chạy lại emoji-table-generator để sinh lại dữ liệu từ nguồn mới nhất.

Lưu ý: Định dạng JSON phải tuân thủ cấu trúc gốc — mỗi phần tử là một đối tượng có các trường name, unicode, aliases, tags, và category.