React-Fluent

基于 React 18 + TypeScript + Vite 实现的 Fluent Design 组件库，让你能在 Web 端（React 技术栈）使用与原生桌面端一致的 Fluent 控件。

---

✨ 特性

• 🎨 设计还原：配色、圆角、阴影、动效与原生 Fluent 控件高度一致。
• 🌗 明暗双主题：内置 light / dark 两套主题，一键切换。
• 🎯 主题色派生：给定任意主题色，自动按 HSV 算法派生出 light1~3 / dark1~3 衍生色（算法对齐 qfluentwidgets 的 ThemeColor.color()）。
• 🧩 组件齐全：按钮、输入、选择、导航、信息展示、弹窗等覆盖桌面端的常见控件。
• ⚡ 开箱即用：import 主入口即自动加载 Fluent 设计变量与组件样式，无需额外配置。
• 📦 纯组件库：仓库自带一个 Gallery 演示页（src/pages），既可预览也可作为用法参考。

---

📦 组件清单

分类	组件
按钮	PushButton、PrimaryPushButton、ToolButton、PrimaryToolButton、Transparent*、HyperlinkButton、ToggleButton、Pill*、DropDown*、SplitButton
输入	LineEdit、CheckBox、RadioButton、SwitchButton、Slider、ComboBox
选择 / 导航	Nav、Pivot、Menu、Flyout
信息展示	Card、Label、InfoBar、Progress、CollectionView、ScrollBar
弹窗 / 窗口	Dialog、Window（FluentWindow 外壳，含标题栏 + 导航 + 内容区）
主题 / 图标	theme（主题色工具）、icons（SVG 图标）、fluentIcons

---

🚀 快速开始

作为组件库使用（import 即用）

本仓库已做库化改造，别人克隆/安装后可直接 import 即用：

• 统一入口 src/fluent/index.ts 在顶部 import './fluent.css'，因此导入组件即自动带上样式，无需、也不应再单独 import 'react-fluent/style.css'。
• package.json 的 name 已改为 react-fluent，并移除了 private；exports / main / module / types 全部指向 src/fluent/index.ts，react / react-dom 设为 peerDependencies（由消费方自备）。

// 一行导入全部需要的组件与主题工具，样式已随入口自动加载
import {
  FluentWindow, PrimaryPushButton, LineEdit,
  applyThemeColor, setThemeMode,
} from 'react-fluent'

function App() {
  // 设置主题色（默认 Fluent 青色 #009faa）
  applyThemeColor('#009faa')
  // 切换明暗主题：'light' | 'dark'
  setThemeMode('dark')

  return (
    <FluentWindow title="My App" items={[{ key: 'home', text: 'Home' }]} currentKey="home">
      <PrimaryPushButton>点我</PrimaryPushButton>
    </FluentWindow>
  )
}

仓库主入口 src/fluent/index.ts 已通过 package.json 的 exports 字段暴露为包名 react-fluent，可直接被外部项目引用，无需关心内部路径。

本地预览 Gallery 演示页

# 安装依赖
npm install

# 启动开发服务器（默认 http://localhost:5173）
npm run dev

# 类型检查 + 生产构建，产物输出到 dist/
npm run build

# 本地预览构建产物
npm run preview

💡 构建时 vite.config.ts 将 base 设为相对路径 ./，因此构建后直接双击 dist/index.html（file://）也能正常运行，方便离线分发。

---

🎨 主题定制

主题工具位于 src/fluent/theme.ts：

import { applyThemeColor, setThemeMode } from 'react-fluent'

// 1. 任意十六进制颜色，自动派生衍生色并写入 :root CSS 变量
applyThemeColor('#009faa')

// 2. 明暗模式切换（写入 <html data-theme="...">）
setThemeMode('dark')

支持的工具函数：

• deriveThemeColors(hex)：返回 { primary, light1, light2, light3, dark1, dark2, dark3 } 派生色板。
• applyThemeColor(hex)：写入 --theme-primary / --theme-light-* / --theme-dark-* 等 CSS 变量，组件样式全部引用这些变量，改一处即可全局生效。
• setThemeMode('light' | 'dark')：切换明暗主题。

---

📁 目录结构

fluent-web/
├── index.html              # Vite 入口
├── vite.config.ts          # Vite 配置（base:'./' 便于离线打开）
├── package.json            # 组件库元信息与脚本
├── public/                 # 静态资源（350+ SVG 图标）
└── src/
    ├── main.tsx            # 演示应用入口
    ├── App.tsx             # FluentWindow 外壳 + 导航 + 页面路由
    ├── fluent/             # 组件库源码
    │   ├── index.ts        # 统一导出入口（自动加载样式）
    │   ├── fluent.css      # Fluent 设计变量与组件样式
    │   ├── theme.ts        # 主题色派生与明暗切换
    │   ├── icons.tsx       # 通用 SVG 图标
    │   ├── fluentIcons.ts  # Fluent 图标集
    │   └── *.tsx           # 各组件实现（Button/Card/Dialog/...）
    └── pages/              # Gallery 演示页面
        ├── BasicInputPage.tsx
        ├── TextPage.tsx
        ├── StatusPage.tsx
        ├── NavigationPage.tsx
        ├── ViewPage.tsx
        ├── DialogPage.tsx
        ├── IconPage.tsx
        └── SettingsPage.tsx

---

🚀 部署到 GitHub Pages

本仓库已配置 GitHub Actions（.github/workflows/deploy.yml），把 Gallery 演示页自动构建并发布到 GitHub Pages。

工作原理

• 监听 main 分支的 push（也支持在 Actions 页面手动 Run workflow）。
• 在 ubuntu-latest 上 npm ci 安装依赖 → npm run build 生成 dist/。
• 通过官方 upload-pages-artifact / deploy-pages 将 dist/ 发布到 Pages。
• vite.config.ts 已设 base: './'（相对路径），因此产物在 https://<user>.github.io/<repo>/ 子路径下也能正确加载。

你需要做的

1. 把代码推送到 main 分支：git push origin main。
2. 进入仓库 Settings → Pages → Build and deployment → Source，选择 GitHub Actions。
3. 等待一次 Actions 跑完，站点地址即为：https://zhouchentao666.github.io/react-fluent/

如需自定义站点路径，可把 vite.config.ts 的 base 改为 '/react-fluent/'；当前 ./ 相对写法已能兼容。

---

🔧 技术栈

• React 18 + TypeScript 5（peerDependencies，需宿主项目提供）
• Vite 5 构建与开发服务器
• 纯 CSS 变量驱动主题，无第三方 UI 依赖