OpenATC Components V3

一套基于 Vue 3、Element Plus、TypeScript 的专业交通信号控制组件库。

📖 文档导航

• 🚀 快速开始 - 5分钟快速上手指南（推荐从这里开始）
• 📚 完整使用指南 - 详细的使用说明、多 UI 框架共存方案和完整示例
• 🔧 API 参考 - 完整的 API 文档和组件列表
• 🗺️ 文档索引 - 文档导航和学习路径

✨ 特性

• 🎯 专为交通信号控制系统设计
• 🎨 支持深色/浅色主题切换
• 🌍 内置中英文国际化
• 🔐 完善的权限管理体系
• 📦 30+ 开箱即用的业务组件
• 💪 TypeScript 类型支持
• 🔌 可与其他 UI 框架共存（Naive UI、Ant Design Vue 等）

📦 安装

npm install openatc-components-v3
# 或
yarn add openatc-components-v3
# 或
pnpm add openatc-components-v3

🔧 依赖要求

# 必需依赖
npm install vue@^3.5.0 element-plus@^2.9.0 @element-plus/icons-vue pinia@^2.3.0 vue-i18n@^11.0.0

⚠️ 重要：即使你的项目使用 Naive UI、Ant Design Vue 等其他 UI 框架，也需要安装 Element Plus，因为本组件库基于 Element Plus 构建。详见 多 UI 框架共存方案。

🚀 快速开始

1. 基础配置

``typescript // main.ts import { createApp } from 'vue' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' import * as ElementPlusIconsVue from '@element-plus/icons-vue' import { createPinia } from 'pinia' import { createI18n } from 'vue-i18n' import App from './App.vue'

// 引入组件库 import OpenATCComponents from 'openatc-components-v3' import 'openatc-components-v3/dist/index.css'

const app = createApp(App)

// 注册插件 app.use(ElementPlus) for (const [key, component] of Object.entries(ElementPlusIconsVue)) { app.component(key, component) } app.use(createPinia())

// 配置国际化 const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh: OpenATCComponents.language.zh, en: OpenATCComponents.language.en } }) app.use(i18n)

// 注册组件库 app.use(OpenATCComponents)

// 基础配置（只需这两行） OpenATCComponents.func.setHost('http://your-api-server.com') OpenATCComponents.func.setToken('your-token')

app.mount('#app')

### 2. 使用组件

``vue
<template>
  <div>
    <!-- 直接使用全局注册的组件 -->
    <KanBan title="设备状态" :data="stats" />
    <IntersectionWithInterface @change="handleChange" />
    
    <!-- 主题切换 -->
    <el-button @click="toggleTheme">切换主题</el-button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import OpenATCComponents from 'openatc-components-v3'

const stats = ref({ total: 100, online: 95 })

const toggleTheme = () => {
  const theme = OpenATCComponents.func.getTheme() === 'dark' ? 'light' : 'dark'
  OpenATCComponents.func.switchTheme(theme)
}

const handleChange = (data) => {
  console.log('数据变化:', data)
}
</script>

🎯 核心功能

🔐 Token 认证

``typescript OpenATCComponents.func.setToken('your-token') // 设置 OpenATCComponents.func.getToken() // 获取 OpenATCComponents.func.removeToken() // 清除

### 🎨 主题切换

``typescript
OpenATCComponents.func.switchTheme('dark')         // 深色主题
OpenATCComponents.func.switchTheme('light')        // 浅色主题
OpenATCComponents.func.getTheme()                  // 获取当前主题

🌍 国际化

``typescript OpenATCComponents.func.setLanguage('zh') // 中文 OpenATCComponents.func.setLanguage('en') // 英文 OpenATCComponents.func.getLanguage() // 获取当前语言

### 🔒 权限管理

``typescript
OpenATCComponents.func.setIsCheckPermission(true)  // 启用权限检查
OpenATCComponents.func.setUserRoles(['admin'])     // 设置角色
OpenATCComponents.func.setPermissions(['*'])       // 设置权限
OpenATCComponents.func.hasPermission('device:read')// 检查权限

🎨 多 UI 框架共存

本组件库可以与 Naive UI、Ant Design Vue 等其他 UI 框架共存：

``vue

<!-- OpenATC 组件（基于 Element Plus） -->
<KanBan title="看板" :data="data" />

> 📖 详细的共存方案见：[多 UI 框架共存方案](./USAGE_GUIDE.md#多-ui-框架共存方案)

## 📚 组件分类

### 🚦 路口管理
- `IntersectionWithInterface` - 路口接口配置
- `IntersectionMap` - 路口地图展示
- `IntersectionDirectionSelection` - 路口方向选择
- `SelectCrossPhase` - 选择路口相位

### 🔄 相位与方案
- `PhaseDirectionSelect` - 相位方向选择
- `PhaseLegend` - 相位图例
- `patternList` - 方案列表
- `PatternOptimize` - 方案优化
- `Stages` - 阶段配置

### 📊 监控看板
- `KanBan` - 看板
- `XiaoKanBan` - 小看板
- `CommonKanban` - 通用看板
- `OverviewComponent` - 总览组件

### ⚠️ 故障管理
- `FaultDetailModal` - 故障详情弹窗
- `MessageBox` - 消息框

> 🔧 查看所有组件和详细 API：[API 参考文档](./API_REFERENCE.md#组件列表)

## 🛠️ 技术栈

- **Vue**: ^3.5.0
- **Element Plus**: >=2.9.0
- **TypeScript**: >=4.9.0
- **Pinia**: ^2.3.0
- **Vue I18n**: ^11.0.0

## 📝 开发指南

### 学习路径

1. **新手** → [快速开始](./QUICK_START.md)（5分钟上手）
2. **进阶** → [完整使用指南](./USAGE_GUIDE.md)（详细配置和示例）
3. **查阅** → [API 参考](./API_REFERENCE.md)（API 文档）
4. **导航** → [文档索引](./DOCUMENTATION_INDEX.md)（快速定位）

### 完整示例

查看 [完整项目示例](./USAGE_GUIDE.md#完整项目示例)，包含：
- package.json
- vite.config.ts
- main.ts
- App.vue
- Dashboard.vue（含 KanBan 完整示例）
- Intersection.vue（含路口配置示例）

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

本项目遵循 Mulan PSL v2 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 🔗 相关链接

- [GitHub Repository](https://github.com/open-atc/open-atc-admin-ui-v3)
- [CHANGELOG](./CHANGELOG.md)
- [Issues](https://github.com/open-atc/open-atc-admin-ui-v3/issues)