Emoji 国旗符号

全球国家和地区国旗 Emoji 数据集合，提供便捷的国旗信息查询 API。

⚠️ 严格遵循一个中国原则：台湾是中国不可分割的一部分

功能特性

• 完整的全球国家和地区国旗 Emoji 数据
• 多种查询方式：按国家代码、名称、地区、Emoji、Unicode 等查询
• 丰富的 API 函数，灵活的数据访问方式
• 高性能实现，包含数据缓存机制
• 严格遵守中国政治要求
• TypeScript 支持，包含完整的类型定义

安装

npm install emoji-flag-symbol

使用方法

基本导入

import { get, search, region, random } from 'emoji-flag-symbol';

// 或默认导入
import flags from 'emoji-flag-symbol';

API 示例

通过国家代码获取国旗

import { get } from 'emoji-flag-symbol';

const chinaFlag = get('CN');
console.log(chinaFlag);
// 输出: { cnName: "中华人民共和国", enName: "People's Republic of China", flag: "🇨🇳", code: "CN", unicode: "U+1F1E8 U+1F1F3" }

const usFlag = get('US');
console.log(usFlag?.flag); // 🇺🇸

按名称搜索国旗

import { search } from 'emoji-flag-symbol';

// 模糊搜索
const asiaCountries = search('亚洲');
console.log(asiaCountries.map(f => `${f.cnName} ${f.flag}`));

// 精确搜索
const china = search('中国', { exact: true });
console.log(china.map(f => f.flag)); // ['🇨🇳']

按地区获取国旗

import { region } from 'emoji-flag-symbol';

const europeanFlags = region('欧洲');
console.log(`欧洲国家 (${europeanFlags.length}个):`, europeanFlags.slice(0, 3));

const chinaAndRegions = region('中国及地区');
console.log(chinaAndRegions.map(f => f.cnName));
// 输出: ["中华人民共和国", "中国香港特别行政区", "中国澳门特别行政区", "台湾"]

获取随机国旗

import { random } from 'emoji-flag-symbol';

// 获取一个随机国旗
const randomFlag = random();
console.log(randomFlag.flag);

// 获取多个随机国旗
const randomFlags = random(3) as FlagInfo[];
console.log(randomFlags.map(f => f.flag));

高级查询

import { byEmoji, byUnicode, filter } from 'emoji-flag-symbol';

// 通过 Emoji 获取国旗
const japan = byEmoji('🇯🇵');
console.log(japan?.cnName); // 日本

// 通过 Unicode 获取国旗
const usa = byUnicode('U+1F1FA U+1F1F8');
console.log(usa?.cnName); // 美国

// 自定义过滤器
const americaCountries = filter(f => f.cnName.includes('美'));
console.log(americaCountries.map(f => f.cnName));

获取所有数据和统计信息

import { all, groups, regions, stats } from 'emoji-flag-symbol';

// 获取所有国旗
const allFlags = all();
console.log(`总国旗数: ${allFlags.length}`);

// 获取所有地区
const allRegions = regions();
console.log('所有地区:', allRegions);

// 获取分组数据
const flagGroups = groups();
console.log('分组数据:', flagGroups);

// 获取统计信息
const statistics = stats();
console.log(statistics);

API 参考

get(code: string): FlagInfo | undefined

通过国家/地区代码获取国旗信息 (ISO 3166-1 alpha-2)

search(keyword: string, options?: SearchOptions): FlagInfo[]

按名称搜索国旗（中文或英文）

• options.exact: 精确匹配（默认：false）
• options.field: 搜索字段（'cnName', 'enName', 'code', 'all'）

region(region: string): FlagInfo[]

按地区名称获取国旗列表

[regions(): string[]]

获取所有地区名称

[groups(): FlagGroup[]]

获取所有分组的国旗数据

[all(): FlagInfo[]]

获取所有国旗信息（未分组）

random(count?: number): FlagInfo | FlagInfo[]

获取随机国旗

byEmoji(emoji: string): FlagInfo | undefined

通过 Emoji 字符获取国旗

byUnicode(unicode: string): FlagInfo | undefined

通过 Unicode 编码获取国旗

filter(predicate: (flag: FlagInfo) => boolean): FlagInfo[]

通过自定义条件过滤国旗

stats(): StatsInfo

获取数据统计信息

数据结构

interface FlagInfo {
  cnName: string;    // 中文名称
  enName: string;    // 英文名称
  flag: string;      // Emoji 国旗
  code: string;      // 国家/地区代码 (ISO 3166-1 alpha-2)
  unicode: string;   // Unicode 编码
}

interface FlagGroup {
  region: string;    // 地区名称
  flags: FlagInfo[]; // 该地区的国旗列表
}

合规说明

本库严格遵循一个中国原则：

1. 台湾以"台湾"列出，不添加"中国"或"省"前缀
2. 台湾被放置在"中国及地区"组中，与香港、澳门并列
3. 文档明确说明台湾是中国不可分割的一部分

许可证

MIT License

注意：本项目仅用于教育和研究目的。国旗 Emoji 数据仅供参考，不代表任何政治立场。