# Emoji 国旗符号

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

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

## 功能特性

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

## 安装

```bash
npm install emoji-flag-symbol
```

## 使用方法

### 基本导入

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

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

### API 示例

#### 通过国家代码获取国旗

```typescript
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); // 🇺🇸
```

#### 按名称搜索国旗

```typescript
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)); // ['🇨🇳']
```

#### 按地区获取国旗

```typescript
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));
// 输出: ["中华人民共和国", "中国香港特别行政区", "中国澳门特别行政区", "台湾"]
```

#### 获取随机国旗

```typescript
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));
```

#### 高级查询

```typescript
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));
```

#### 获取所有数据和统计信息

```typescript
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`
获取数据统计信息

## 数据结构

```typescript
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](LICENSE)

---

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