@lishangpei/nav-sidebar/README.md

企业级站点导航组件 - 基于 Web Components，真正的跨框架复用

# @lishangpei/nav-sidebar

企业级站点导航组件 - 基于 Web Components，真正的跨框架复用

[![npm version](https://img.shields.io/npm/v/@lishangpei/nav-sidebar.svg)](https://www.npmjs.com/package/@lishangpei/nav-sidebar)
[![license](https://img.shields.io/npm/l/@lishangpei/nav-sidebar.svg)](https://github.com/your-company/nav-sidebar/blob/main/LICENSE)

## ✨ 特性

- 🧩 **Web Components** - 基于标准 Web Components API，真正的跨框架
- 🔒 **完全封装** - Shadow DOM 样式隔离，不会污染全局样式
- 🎯 **零依赖** - 不依赖任何框架，可在任何项目中使用
- 🔄 **环境切换** - 支持ST/UAT/PRD等多环境快速切换
- 📦 **不占空间** - 浮动图标设计,不影响原有页面布局
- ⚡ **即点即现** - 点击图标同时展开搜索栏和站点列表
- 🎨 **精美UI** - 现代化渐变设计,流畅动画效果
- 🔌 **框架集成** - 提供React和Vue专用组件,开箱即用
- 📱 **响应式** - 完美适配PC和移动端
- 🔍 **实时搜索** - 按站点名称或URL搜索过滤
- ⌨️ **快捷键** - Ctrl/Cmd+K聚焦搜索,ESC关闭
- 📝 **TypeScript** - 完整的类型定义

## 📦 安装

```bash
npm install @lishangpei/nav-sidebar
```

## 🚀 快速开始

### 🧩 Web Component (推荐)

**适用于任何框架或原生 HTML！**

```html
<!-- 1. 引入 Web Component -->
<script src="node_modules/@lishangpei/nav-sidebar/dist/nav-sidebar-wc.js"></script>

<!-- 2. 使用组件 -->
<nav-sidebar api-url="https://api.company.com/sites?env={env}"></nav-sidebar>
```

### ⚛️ React 中使用

```jsx
import NavSidebar from '@lishangpei/nav-sidebar/react-wc';

function App() {
  return (
    <div>
      <NavSidebar apiUrl="https://api.company.com/sites?env={env}" />

      {/* 你的应用内容 */}
      <h1>欢迎使用</h1>
    </div>
  );
}
```

### 🟢 Vue 中使用

```vue
<template>
  <div>
    <NavSidebar api-url="https://api.company.com/sites?env={env}" />

    <!-- 你的应用内容 -->
    <h1>欢迎使用</h1>
  </div>
</template>

<script setup>
import NavSidebar from '@lishangpei/nav-sidebar/vue-wc';
</script>
```

### 📦 旧版 API (仍支持)

如果你使用的是旧版本，仍然可以使用原来的 API：

```javascript
import NavSidebar from '@lishangpei/nav-sidebar';

new NavSidebar({
  apiUrl: 'https://api.company.com/sites?env={env}'
});
```

## ⚙️ 配置选项

### 🧩 Web Component 属性

```html
<nav-sidebar
  api-url="https://api.company.com/sites?env={env}"
  title="站点导航"
  environments="ST,UAT,PRD"
  default-env="PRD"
  float-icon="🧭"
  enable-frequent-visits="true"
  frequent-visits-limit="5"
></nav-sidebar>
```

### 📡 监听事件

```javascript
const navSidebar = document.querySelector('nav-sidebar');

// 监听站点点击事件
navSidebar.addEventListener('site-click', (e) => {
  console.log('点击站点:', e.detail.site);
  // 阻止默认跳转: e.preventDefault();
});

// 监听环境切换事件
navSidebar.addEventListener('env-change', (e) => {
  console.log(`环境切换: ${e.detail.oldEnv} → ${e.detail.newEnv}`);
});

// 其他事件
navSidebar.addEventListener('ready', () => console.log('组件已就绪'));
navSidebar.addEventListener('show', () => console.log('显示'));
navSidebar.addEventListener('hide', () => console.log('隐藏'));
```

### 🔧 JavaScript API

```javascript
const nav = document.querySelector('nav-sidebar');

nav.show();                    // 显示侧边栏
nav.hide();                    // 隐藏侧边栏
nav.toggle();                  // 切换显示状态
nav.refresh();                 // 刷新站点数据
nav.switchEnvironment('ST');   // 切换环境
nav.getCurrentEnvironment();   // 获取当前环境
nav.setSites([...]);          // 设置站点数据
nav.getSites();               // 获取站点数据
nav.clearVisitStats();        // 清除访问统计
```

### ⚛️ React Props

```jsx
<NavSidebar
  apiUrl="https://api.company.com/sites?env={env}"
  title="站点导航"
  environments={['ST', 'UAT', 'PRD']}
  defaultEnv="PRD"
  floatIcon="🧭"
  onEnvChange={(newEnv, oldEnv) => {
    console.log(`环境切换: ${oldEnv} → ${newEnv}`);
  }}
  onSiteClick={(site, event) => {
    console.log('点击站点:', site.name);
  }}
/>
```

### 🟢 Vue Props

```vue
<NavSidebar
  api-url="https://api.company.com/sites?env={env}"
  title="站点导航"
  :environments="['ST', 'UAT', 'PRD']"
  default-env="PRD"
  float-icon="🧭"
  :on-env-change="handleEnvChange"
  :on-site-click="handleSiteClick"
/>
```

## 📡 API响应格式

你的API应该返回以下格式的JSON:

```json
{
  "success": true,
  "environment": "PRD",
  "sites": [
    {
      "id": 1,
      "name": "用户管理系统",
      "url": "https://user.example.com",
      "description": "可选的描述"
    }
  ]
}
```

或者简化版(直接返回数组):

```json
[
  {
    "id": 1,
    "name": "用户管理系统",
    "url": "https://user.example.com"
  }
]
```

## 📖 完整示例

### React完整示例

```jsx
import React from 'react';
import NavSidebar from '@lishangpei/nav-sidebar/react';
import '@lishangpei/nav-sidebar/dist/nav-sidebar.css';

function App() {
  const handleEnvChange = (newEnv, oldEnv) => {
    console.log(`环境从 ${oldEnv} 切换到 ${newEnv}`);
    // 可以在这里触发其他操作
  };

  const handleSiteClick = (site, event) => {
    console.log('用户点击了:', site.name);
    // 可以添加埋点统计等
    // 返回 false 可以阻止默认跳转
  };

  return (
    <div className="app">
      <NavSidebar
        apiUrl="https://api.company.com/sites?env={env}"
        title="公司站点导航"
        environments={['ST', 'UAT', 'PRD']}
        defaultEnv="PRD"
        onEnvChange={handleEnvChange}
        onSiteClick={handleSiteClick}
      />

      <main>
        <h1>我的应用</h1>
        <p>导航组件已自动加载</p>
      </main>
    </div>
  );
}

export default App;
```

### Vue完整示例

```vue
<template>
  <div class="app">
    <NavSidebar
      api-url="https://api.company.com/sites?env={env}"
      title="公司站点导航"
      :environments="['ST', 'UAT', 'PRD']"
      default-env="PRD"
      :on-env-change="handleEnvChange"
      :on-site-click="handleSiteClick"
    />

    <main>
      <h1>我的应用</h1>
      <p>导航组件已自动加载</p>
    </main>
  </div>
</template>

<script setup>
import NavSidebar from '@lishangpei/nav-sidebar/vue';
import '@lishangpei/nav-sidebar/dist/nav-sidebar.css';

const handleEnvChange = (newEnv, oldEnv) => {
  console.log(`环境从 ${oldEnv} 切换到 ${newEnv}`);
};

const handleSiteClick = (site, event) => {
  console.log('用户点击了:', site.name);
};
</script>
```

## 🎯 TypeScript支持

```typescript
import NavSidebar from '@lishangpei/nav-sidebar/react';
import type { NavSidebarProps, Site } from '@lishangpei/nav-sidebar/react';

const props: NavSidebarProps = {
  apiUrl: 'https://api.company.com/sites?env={env}',
  onSiteClick: (site: Site) => {
    console.log(site.name);
  }
};
```

## 🎯 使用场景

- 🏢 **企业内部系统** - 统一多个管理后台的入口
- 🔄 **多环境切换** - 开发、测试、生产环境快速切换
- 📊 **数据分析平台** - 集成多个数据工具
- 🛠️ **DevOps工具集** - CI/CD、监控等工具快速访问

## 📖 完整文档

- [使用指南](https://github.com/your-company/nav-sidebar/blob/main/USAGE.md)
- [发布指南](https://github.com/your-company/nav-sidebar/blob/main/PUBLISH_GUIDE.md)
- [API文档](https://github.com/your-company/nav-sidebar/blob/main/api-server/README.md)

## 🤝 贡献

欢迎提交Issue和Pull Request!

## 📄 许可证

[MIT](LICENSE)

## 🔗 相关链接

- [GitHub](https://github.com/your-company/nav-sidebar)
- [npm](https://www.npmjs.com/package/@lishangpei/nav-sidebar)
- [更新日志](https://github.com/your-company/nav-sidebar/blob/main/CHANGELOG.md)