@sankyu/react-circle-flags

简体中文 | English Version

:star: 在 GitHub 上 Star 我们 | :bug: 在此 提交问题

:rocket: 探索 演示图库 | :book: 阅读文档

📖 概述

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

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

:world_map: 在线演示

✨ 核心特性

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

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

📦 安装

npm install @sankyu/react-circle-flags
# 或
pnpm add @sankyu/react-circle-flags
# 或
yarn add @sankyu/react-circle-flags
# 或
bun add @sankyu/react-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 体积。

🚀 使用

导入单个国旗（推荐）

import { FlagUs, FlagCn, FlagGb } from '@sankyu/react-circle-flags'

export default function App() {
  return (
    <div>
      <FlagUs width={48} height={48} />
      <FlagCn width={48} height={48} />
      <FlagGb width={48} height={48} />
    </div>
  )
}

其他使用示例

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

⚠️ 弃用警告：<CircleFlag />

<CircleFlag /> 已弃用，不推荐在新代码中使用。

• 它会在运行时拉取 SVG（非离线优先）。
• 加载后渲染的是 wrapper 并注入 SVG HTML，许多仅 SVG 生效的 props 无法按预期工作。

详见：https://react-circle-flags.js.org/docs/deprecated/circleflag/

📚 API

构建元信息

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

import { buildMeta } from '@sankyu/react-circle-flags'

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

其他属性

...欲了解更多信息，请参阅 API 参考。

可用的国旗

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

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

请在 react-circle-flags 图库中查看 国旗完整列表。

🎨 样式

国旗组件接受所有标准 SVG 属性，因此可使用任何 CSS 方法轻松设置样式。

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

🔧 TypeScript

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

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

📖 示例

[!TIP] 欲了解更多信息，请参阅 指南 - 基础用法。

📦 打包大小与 Tree-shaking 优化

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

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

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

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

🤝 贡献

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

📄 许可证

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

官网 基于 GPL-3.0 许可证授权，© Sankyu Lab

🙏 致谢

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