npm package: @nianzai_why/gitee-file-show-frontend
Description: 基于 Vue 3 实现的 Gitee 文件展示/浏览组件（前端部分），样式和图标已内置，开箱即用
Author: Nianzai518
Latest version: 1.0.0

# @nianzai_why/gitee-file-show-frontend

基于 Vue 3 实现的 Gitee 文件展示/浏览组件（前端部分）

> **✨ 开箱即用**：样式和图标已内置，无需额外配置！

## 安装

### 从 Gitee 仓库安装（推荐）

```bash
npm install git+https://gitee.com/Nianzai518/frontend.git
```

或者使用 yarn / pnpm：

```bash
yarn add git+https://gitee.com/Nianzai518/frontend.git
# 或
pnpm add git+https://gitee.com/Nianzai518/frontend.git
```

### 从 npm 安装（如果已发布）

```bash
npm i @nianzai_why/gitee-file-show-frontend
```

### 安装依赖

> **注意**：只需要安装 Vue 3（如果项目中没有）

```bash
# Vue 3（如果项目中没有）
npm install vue@^3.0.0
```

> **提示**：`@iconify/vue` 已作为依赖自动安装，图标已内置，无需额外配置！

## 快速开始

### 1. 安装包和依赖

```bash
npm install @nianzai_why/gitee-file-show-frontend
npm install vue@^3.0.0  # 如果项目中没有 Vue 3
```

> **提示**：样式和图标已内置，无需额外配置！

### 2. 在项目中使用

**方式一：插件方式（推荐）**

```ts
// main.js 或 main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { GiteeFileShowFrontend } from '@nianzai_why/gitee-file-show-frontend'

const app = createApp(App)
app.use(GiteeFileShowFrontend, { 
  apiBaseUrl: 'http://localhost:3000/files' // 可选，不传默认 /files
})
app.mount('#app')
```

```vue
<!-- 在组件中使用 -->
<template>
  <GiteeFileBrowser />
</template>
```

**方式二：按需导入**

```vue
<template>
  <FileBrowser />
</template>

<script setup>
import { FileBrowser, setApiBaseUrl } from '@nianzai_why/gitee-file-show-frontend'

// 配置 API 地址（如果需要）
setApiBaseUrl('http://localhost:3000/files')
</script>
```

### 3. 配置 API 地址（可选）

如果前后端分离，需要配置 API 地址：

```ts
import { setApiBaseUrl } from '@nianzai_why/gitee-file-show-frontend'

// 方式一：使用函数
setApiBaseUrl('http://localhost:3000/files')

// 方式二：使用 API 对象
import { fileSystemApi } from '@nianzai_why/gitee-file-show-frontend'
fileSystemApi.setApiBaseUrl('http://localhost:3000/files')
```

**或者使用代理**（Vite 示例）：

```js
// vite.config.js
export default {
  server: {
    proxy: {
      '/files': {
        target: 'http://localhost:3000',
        changeOrigin: true
      }
    }
  }
}
```

## 项目配置

### Vite 项目（推荐）

**无需额外配置**，Vite 会自动处理 `.vue` 文件和 CSS 导入。

### Vue CLI / Webpack 项目

确保项目已配置 `vue-loader` 来处理 `.vue` 文件。如果使用 Vue CLI 创建的项目，通常已经配置好了。

如果遇到问题，检查 `vue.config.js` 或 `webpack.config.js` 中是否包含：

```js
// vue.config.js (Vue CLI)
module.exports = {
  // 通常无需额外配置
}

// 或 webpack.config.js
module: {
  rules: [
    {
      test: /\.vue$/,
      loader: 'vue-loader'
    },
    {
      test: /\.css$/,
      use: ['style-loader', 'css-loader']
    }
  ]
}
```

## 样式说明

组件样式已内置并**自动导入**，**无需手动导入样式文件**。样式使用 `.gitee-file-browser` 作为命名空间，不会与项目中的其他样式冲突。

### 如果样式不生效

如果发现组件没有样式（极少见的情况），可以手动导入：

```ts
// main.js 或 main.ts
import '@nianzai_why/gitee-file-show-frontend/FileBrowser.css'
```

### 样式隔离说明

- 组件样式使用 `.gitee-file-browser` 命名空间，不会影响其他页面
- 其他页面使用 `<style scoped>` 不会受到影响
- 样式已提取到独立的 CSS 文件中，通过组件自动导入
- 样式在组件加载时自动导入，无需任何配置

## API 说明

### fileSystemApi 方法

- `getAllowedDirs()`: 获取允许访问的目录列表
- `getFolderContent(path)`: 获取文件夹内容
- `getServerFile(path)`: 获取服务器文件内容
- `setApiBaseUrl(baseUrl)`: 设置 API 基础地址

## 完整示例

```vue
<template>
  <div class="app-container">
    <h1>文件浏览器</h1>
    <FileBrowser />
  </div>
</template>

<script setup>
import { FileBrowser, setApiBaseUrl } from '@nianzai_why/gitee-file-show-frontend'

// 配置 API 地址（如果需要）
setApiBaseUrl('http://localhost:3000/files')
</script>

<style>
.app-container {
  width: 100%;
  height: 100vh;
}
</style>
```

## 依赖

- `vue`: ^3.0.0 (peer dependency，必须安装)
- `@iconify/vue`: ^4.0.0 (dependencies，自动安装)

## 注意事项

1. **构建工具要求**：
   - Vite 项目：无需配置，开箱即用
   - Vue CLI / Webpack：确保已配置 `vue-loader`
   - 其他构建工具：需要支持 `.vue` 文件和 CSS 导入

2. **依赖要求**：
   - Vue 3.x（必须，peer dependency）
   - @iconify/vue >= 4.0.0（自动安装，无需手动安装）

3. **后端 API**：
   - 组件需要后端 API 支持，确保后端服务正常运行
   - 如果使用代理，确保代理配置正确

4. **图标和样式**：
   - 所有图标已内置在包中，无需额外安装图标集包
   - 样式已自动导入，无需手动导入
   - 图标和样式在组件加载时自动注册，开箱即用
   - 无需配置，无需担心 CDN 访问问题

5. **样式问题排查**：
   - 确保组件正确导入
   - 检查 Vue 版本（需要 Vue 3.x）
   - 检查浏览器控制台是否有错误
   - 检查构建工具是否能正确处理 CSS 导入
   - 如果样式不生效，参考上面的"如果样式不生效"部分