# naive-web

**Repository Path**: lslands/naive-web

## Basic Information

- **Project Name**: naive-web
- **Description**: 当前版本为demo版本，有待完善
- **Primary Language**: HTML/CSS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-04
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flyover 项目说明

一套基于 Vue 3 + TypeScript + Vite 的基础工程，内置路由、状态管理、Axios 封装、国际化、UnoCSS 与 Sass，支持开发/生产环境与代理配置。

## 技术栈
- **Vue 3** + **TypeScript** + **Vite**
- **Vue Router 4**：路由与路由守卫
- **Pinia** + `pinia-plugin-persistedstate`：全局状态与持久化
- **Axios**：HTTP 客户端，统一拦截器与 `baseURL`
- **vue-i18n 9**：国际化与运行时切换
- **UnoCSS**：原子化样式，支持 Attributify、Icons、safelist、transformers
- **Sass**：全局变量自动注入（`$brand` 等）

## 目录结构与作用
```
./
├─ .env.development            # 开发环境变量（含代理目标）
├─ .env.production             # 生产环境变量
├─ package.json                # 脚本与依赖
├─ tsconfig*.json              # TS 配置与路径别名
├─ vite.config.ts              # Vite 插件、别名、CSS 预处理、代理
├─ uno.config.ts               # UnoCSS 预设、safelist、transformers
└─ src/
   ├─ main.ts                  # 应用入口：注册 Pinia、i18n、Router，注入样式
   ├─ App.vue                  # 根组件
   ├─ style.css                # 模板默认样式（可逐步迁移到 Uno/SCSS）
   ├─ styles/
   │  └─ variables.scss        # 全局 SCSS 变量（已全局注入）
   ├─ assets/                  # 静态资源
   ├─ components/
   │  └─ HelloWorld.vue        # 示例组件
   ├─ router/
   │  └─ index.ts              # 路由表、`beforeEach` 设置页面标题
   ├─ services/
   │  └─ http.ts               # Axios 实例与拦截器（从 Pinia 读取 token）
   ├─ stores/
   │  ├─ index.ts              # 创建 Pinia，注册持久化插件
   │  └─ auth.ts               # 认证 Store（token，持久化）
   ├─ i18n/
   │  └─ index.ts              # i18n 实例与 `setLocale()` 切换
   ├─ locales/
   │  ├─ en.json               # 英文文案
   │  └─ zh-CN.json            # 中文文案
   └─ views/
      ├─ About.vue             # 关于页
      └─ Dashboard/
         ├─ Layout.vue         # 仪表盘布局（路由嵌套）
         ├─ Overview.vue       # 示例页：使用 UnoCSS 与 i18n
         ├─ Settings.vue       # 设置页
         └─ Sidebar.vue        # 侧栏视图（命名视图）
```

## 关键文件说明
- **`src/main.ts`**：
  - 引入 `./style.css`、`uno.css` 全局样式；
  - 注册 `pinia`、`i18n`、`router`；
  - `createApp(App).use(pinia).use(i18n).use(router).mount('#app')`。

- **`src/router/index.ts`**：
  - 基于 `createWebHistory(import.meta.env.BASE_URL)` 创建路由；
  - 使用命名视图（`default`/`sidebar`）；
  - `beforeEach` 中根据 `meta.title` 设置 `document.title`。

- **`src/stores/index.ts`**：
  - `createPinia()` 并 `pinia.use(piniaPluginPersistedstate)` 开启持久化能力。

- **`src/stores/auth.ts`**：
  - `token` 的存取动作，`persist: true` 默认持久化到 `localStorage`。

- **`src/services/http.ts`**：
  - `axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, ... })`
  - 请求拦截器：从 `useAuthStore(pinia)` 读取 `token`，注入 `Authorization` 头；
  - 响应拦截器：统一返回 `response.data`。

- **`src/i18n/index.ts`**：
  - 自动检测语言（`localStorage` 优先，其次浏览器首选）；
  - `setLocale('en' | 'zh-CN')` 运行时切换并持久化；
  - 示例在 `views/Dashboard/Overview.vue` 中演示 `t()` 与语言切换按钮。

- **`uno.config.ts`**：
  - 预设：`presetUno()`、`presetAttributify()`、`presetIcons()`；
  - `safelist`：保留常用显示/文本/图标类；
  - `transformerVariantGroup()`：支持 `hover:(bg-blue-500 text-white)` 等写法。

- **`vite.config.ts`**：
  - 插件：`@vitejs/plugin-vue`、`unocss/vite`；
  - 别名：`@ -> ./src`；
  - 全局 SCSS 注入：`@use "@/styles/variables.scss" as *;`；
  - 按环境读取 `.env.*`，在开发环境根据 `VITE_PROXY_TARGET` 配置 `server.proxy`。

## 环境与代理
- **开发环境**（`.env.development`）
  - `VITE_API_BASE_URL=/api`
  - `VITE_PROXY_TARGET=https://dev-api.example.com`
  - 本地请求 `http.get('/api/xxx')` 将被 Vite 代理到 `https://dev-api.example.com/api/xxx`。
- **生产环境**（`.env.production`）
  - `VITE_API_BASE_URL=https://api.example.com`
  - 不启用本地代理，构建后会直连生产 API。
- 如果后端不需要 `/api` 前缀，可在 `vite.config.ts` 的 `rewrite` 注释处开启去前缀逻辑。

## 关键功能用法
- **Axios（`src/services/http.ts`）**：
```ts
import { http } from '@/api/http'

const list = await http.get('/api/users')
const res = await http.post('/api/login', payload)
```
- **Pinia（`src/stores/auth.ts`）**：
```ts
import { useAuthStore } from '@/stores/auth'
const auth = useAuthStore()
auth.setToken('your_token')
```
- **i18n（`src/i18n/index.ts`）**：
```ts
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
// 模板：{{ t('nav.dashboard') }}
```
切换语言：
```ts
import { setLocale } from '@/i18n'
setLocale('zh-CN') // 或 'en'
```
- **UnoCSS**：
  - 直接在模板使用原子类：`class="p-4 text-center text-2xl text-blue-600"`
  - Attributify：`<div p-4 text="center 2xl blue-600" />`
  - 图标：`<i class="i-ep:home-filled text-2xl" />`
- **Sass**：
  - 组件中直接使用全局变量：
```vue
<style lang="scss" scoped>
.button { background: $brand; border-radius: $radius; }
</style>
```

## 启动与构建
- **开发**：`yarn dev`
- **构建**：`yarn build`
- **本地预览**：`yarn preview`

## 常见个性化配置
- 修改品牌色/圆角：`src/styles/variables.scss`
- 扩展 UnoCSS：`uno.config.ts` 的 `theme`、`shortcuts`、`rules`、`safelist`
- 新增语言：在 `src/locales/` 添加对应 JSON，并在 `i18n/index.ts` 注册
- 路由标题国际化：`meta.title` 存放 i18n key，并在 `beforeEach` 使用 `t()` 设置 `document.title`

## 约定
- 业务请求尽量通过 `src/services/` 下模块封装，避免在组件内分散写 `axios`
- 全局状态放入 Pinia，对需要持久化的 store 使用 `persist`
- 复杂样式/组件可结合 UnoCSS 与 SCSS，常用风格沉淀到 `shortcuts`