@sankyu/vue-circle-flags

[!NOTE] 🚧 Beta 版本

此包目前处于 Beta 阶段。API 可能会在未来版本中发生变化。如遇任何问题，请及时反馈！

📖 概述

本库为 Vue 3 提供 400+ 个圆形 SVG 国旗组件，具备 完整的 TypeScript 支持 以及 Tree-shaking 优化。

专为需要快速、清晰显示国旗且无需外部图片请求的应用而设计。

:world_map: 在线演示

✨ 核心特性

[!TIP] 欲了解更多信息，请参阅 文档。

• 🎯 支持 Tree-shaking 优化 - 仅打包您使用的国旗
• 📦 TypeScript - 包含完整的类型定义
• ⚡ 零依赖 - 仅需 Vue 3 作为对等依赖
• 🎨 内联 SVG - 无需外部请求，支持离线使用
• 🔧 完全可定制 - 支持所有标准 SVG 属性
• 📱 SSR 兼容 - 适用于 Nuxt.js、Quasar 等框架
• 🪶 轻量级 - 每个国旗约 1KB

📦 安装

npm install @sankyu/vue-circle-flags
# 或
pnpm add @sankyu/vue-circle-flags
# 或
yarn add @sankyu/vue-circle-flags
# 或
bun add @sankyu/vue-circle-flags

[!TIP] 欲了解更多信息，请参阅 安装指南。

🤖 正在 Vibe Coding?

你是一位资深 Web 开发专家。请参考文档：https://react-circle-flags.js.org/llms.txt

1. **项目审计**：检查我项目中的国旗图标使用情况，找出：
   - 指向 `HatScripts/circle-flags` 的原始 `<img>` 标签。
   - 旧版 `react-circle-flags` 第三方库的使用。
2. **迁移建议**：根据我当前的框架（React/Vue/Solid），提供向 `@sankyu/{framework}-circle-flags` 家族库迁移的方案。
3. **极致优化**：根据文档规范，将通用的 `CircleFlag` 组件或原始 `<img>` 标签替换为**具名导入**（例如 `import { FlagUs, FlagDe } from '...'`），以确保 Tree-shaking 达到最小 Bundle 体积。

🚀 使用

导入单个国旗（推荐）

<script setup lang="ts">
import { FlagUs, FlagCn, FlagGb } from '@sankyu/vue-circle-flags'
</script>

<template>
  <div>
    <FlagUs :width="48" :height="48" />
    <FlagCn :width="48" :height="48" />
    <FlagGb :width="48" :height="48" />
  </div>
</template>

使用 FlagSizes 预设

<script setup lang="ts">
import { FlagJp, FlagDe, FlagFr, FlagSizes } from '@sankyu/vue-circle-flags'
</script>

<template>
  <div>
    <FlagJp :width="FlagSizes.sm" :height="FlagSizes.sm" />
    <!-- 24px -->
    <FlagDe :width="FlagSizes.md" :height="FlagSizes.md" />
    <!-- 32px -->
    <FlagFr :width="FlagSizes.lg" :height="FlagSizes.lg" />
    <!-- 48px -->
  </div>
</template>

动态选择国旗

<script setup lang="ts">
import { ref } from 'vue'
import { DynamicFlag } from '@sankyu/vue-circle-flags'

const countryCode = ref('us')
</script>

<template>
  <DynamicFlag :code="countryCode" :width="48" :height="48" />
</template>

[!CAUTION] DynamicFlag 适合离线优先且需要同步渲染运行时代码的场景，但会打包全部 400+ 国旗 （约 ~600 KB，无法 tree-shaking）。若代码集合有限，优先使用具名导入或“具名导入 + map”。

其他使用示例

[!TIP] 欲了解更多信息，请参阅 使用指南。

📚 API

属性

尺寸预设

构建元信息

您可以通过 buildMeta 导出项访问库的构建元信息：

<script setup lang="ts">
import { buildMeta } from '@sankyu/vue-circle-flags'

console.log(buildMeta.version) // 例如："0.0.1"
console.log(buildMeta.builtTimestamp) // 例如：1760000000000
console.log(buildMeta.commitHash) // 例如：<示例-sha256-哈希值>
console.log(buildMeta.circleFlagsCommitHash) // 例如：<示例-sha256-哈希值>
</script>

可用的国旗

每个国旗均按 Flag{帕斯卡命名法 ISO_CODE} 模式导出（例如 FlagUs、FlagCn）。为常见的双字母代码提供了便捷别名：FlagUs、FlagCn、FlagGb、FlagJp。

• FlagUs - 美国
• FlagCn - 中国
• FlagGb - 英国
• FlagJp - 日本
• ... 以及更多

请在图库中查看 国旗完整列表。

🎨 样式

国旗组件接受所有标准 SVG 属性，可使用 Vue 的 class 和 style 绑定轻松设置样式。

[!TIP] 欲了解更多信息，请参阅 样式指南。

<script setup lang="ts">
import { FlagUs } from '@sankyu/vue-circle-flags'
</script>

<template>
  <!-- 使用 class -->
  <FlagUs class="rounded-full shadow-lg hover:scale-110 transition-transform" />

  <!-- 使用内联样式 -->
  <FlagUs :style="{ filter: 'grayscale(100%)' }" />

  <!-- 自定义属性 -->
  <FlagUs aria-label="美国国旗" role="img" />
</template>

🔧 TypeScript

所有国旗组件均使用 TypeScript 完全类型化，开箱即用提供自动完成和类型安全。

[!TIP] 欲了解更多信息，请参阅 TypeScript 指南。

import type { FlagComponentProps, FlagCode } from '@sankyu/vue-circle-flags'

// FlagCode 是所有有效国旗代码的联合类型
const code: FlagCode = 'us' // ✓ 有效
const invalid: FlagCode = 'xyz' // ✗ 类型错误

📦 打包大小与 Tree-shaking 优化

@sankyu/vue-circle-flags 专为 Tree-shaking 优化而设计。

导入单个国旗可确保只有使用到的国旗被包含在您的打包文件中。

[!TIP] 欲了解更多信息，请参阅 打包大小与 Tree-shaking 优化指南。

<script setup lang="ts">
// ✓ 推荐 - 仅打包 FlagUs 和 FlagCn
import { FlagUs, FlagCn } from '@sankyu/vue-circle-flags'
</script>

🤝 贡献

请参阅 CONTRIBUTING.md 了解贡献指南。

📄 许可证

@sankyu/vue-circle-flags 基于 MIT 许可证授权，© Sankyu Lab

🙏 致谢

• 国旗设计源自 HatScripts/circle-flags
• 使用 tsup 构建