npm package: @shifone/jsc-util
Description: 一个基于 Vue 3 + TypeScript 的组件库，提供 jsc 常用的 Vue 组件和实用的数据资源。
Author: Shifone
Latest version: 0.0.9

# @shifone/jsc-util

一个基于 Vue 3 + TypeScript 的组件库，提供常用的 Vue 组件和实用的数据资源。

## 特性

- 🚀 基于 Vue 3 Composition API
- 💪 使用 TypeScript 开发，提供完整的类型定义
- 📦 支持 ES Module 和 CommonJS
- 🎨 现代化的组件设计
- 🗂️ 实用的JSON数据资源
- 📱 支持按需引入

## 安装

```bash
npm install @shifone/jsc-util
# 或
yarn add @shifone/jsc-util
# 或
pnpm add @shifone/jsc-util
```

## 快速开始

### 完整引入

```typescript
import { createApp } from 'vue'
import JscUtil from '@shifone/jsc-util'
import '@shifone/jsc-util/dist/jsc-util.css' // 导入样式文件（必需）
import App from './App.vue'

const app = createApp(App)
app.use(JscUtil)
app.mount('#app')
```

### 按需引入

```typescript
import { AutoScrollTable, DevTools, BasicCard, mapStyle, suzhouDistrict } from '@shifone/jsc-util'
import '@shifone/jsc-util/dist/jsc-util.css' // 导入样式文件（使用组件时必需）

// 在组件中使用
export default {
  components: {
    AutoScrollTable,
    DevTools,
    BasicCard
  },
  setup() {
    // 使用JSON数据
    console.log(mapStyle) // 百度地图样式配置
    console.log(suzhouDistrict) // 苏州区域边界数据
    return {}
  }
}
```

## 组件

### AutoScrollTable

自动滚动表格组件，支持数据自动滚动显示。

```vue
<template>
  <AutoScrollTable 
    :columns="columns"
    :data="tableData"
    :scroll-speed="2000"
  />
</template>

<script setup>
import { AutoScrollTable } from '@shifone/jsc-util'
import type { AutoScrollTableColumn } from '@shifone/jsc-util'

const columns: AutoScrollTableColumn[] = [
  { key: 'name', title: '姓名' },
  { key: 'age', title: '年龄' }
]

const tableData = [
  { name: '张三', age: 25 },
  { name: '李四', age: 30 }
]
</script>
```

### DevTools

开发辅助工具组件，提供调试和开发时的实用功能。

```vue
<template>
  <DevTools v-if="isDev" />
</template>

<script setup>
import { DevTools } from '@shifone/jsc-util'

const isDev = process.env.NODE_ENV === 'development'
</script>
```

### BasicCard

基础卡片容器组件，提供统一的卡片样式和加载、空状态处理。

```vue
 <template>
   <BasicCard 
     title="数据统计" 
     :showHeader="true"
     :loading="loading" 
     :empty="data.length === 0"
     :bodyStyle="{ minHeight: '200px' }"
   >
     <template #title>
       <span>📊 数据统计</span>
     </template>
     
     <template #operate>
       <button @click="refresh">刷新</button>
     </template>
     
     <template #empty>
       <div>暂无统计数据</div>
     </template>
     
     <!-- 卡片内容 -->
     <div v-for="item in data" :key="item.id">
       {{ item.name }}: {{ item.value }}
     </div>
   </BasicCard>
 </template>
 
 <script setup>
 import { BasicCard } from '@shifone/jsc-util'
 import { ref } from 'vue'
 
 const loading = ref(false)
 const data = ref([])
 
 const refresh = () => {
   loading.value = true
   // 模拟数据加载
   setTimeout(() => {
     data.value = [{ id: 1, name: '用户数', value: 1000 }]
     loading.value = false
   }, 1000)
 }
 </script>
 ```

## 数据资源

### JSON 数据

提供实用的 JSON 数据资源，可直接在项目中使用。

```typescript
import { mapStyle, suzhouDistrict } from '@shifone/jsc-util'

// 百度地图样式配置
console.log(mapStyle)
// 包含地图样式的完整配置对象

// 苏州区域边界数据
console.log(suzhouDistrict)
// 包含苏州各区域边界坐标的数据对象
```

#### 可用数据

| 数据名称 | 说明 | 类型 | 用途 |
|----------|------|------|------|
| mapStyle | 百度地图样式配置 | object | 地图样式定制 |
| suzhouDistrict | 苏州区域边界数据 | object | 地理信息展示 |

## 百度地图工具库

提供完整的百度地图集成解决方案，包括地图初始化、区域绘制、坐标转换等功能。

### 基础用法

```typescript
import {
  loadBaiduMapScript,
  initBaiduMap,
  drawDistrictBoundary,
  translatePoint
} from '@shifone/jsc-util'

// 加载百度地图API
const BMap = await loadBaiduMapScript('your-api-key')

// 初始化地图
const map = await initBaiduMap('map-container', {
  center: new BMap.Point(120.62477, 31.308559),
  zoom: 14,
  enableScrollWheelZoom: true
})

// 绘制苏州行政区划边界
const overlays = drawDistrictBoundary(map, {
  districts: ['姑苏区', '虎丘区', '吴中区'],
  colors: ['#AD4646', '#4679AD', '#46AD79']
})

// 坐标转换
const baiduPoint = translatePoint({
  longitude: '120.123456',
  latitude: '31.123456'
})
console.log(baiduPoint) // { lng: 120.xxx, lat: 31.xxx }

// 创建圆形标记
const circleMarker = createCircleMarker(
  map,
  { lng: 120.62477, lat: 31.308559 },
  50, // 半径
  ['#FF6B6B', '#FFE66D'], // 边框和填充颜色
  {
    enableAnimation: true,
    animationDuration: 2
  }
)
map.addOverlay(circleMarker)

// 创建标记（使用图片URL）
const marker1 = createMarker(
  { lng: 120.585294, lat: 31.299758 },
  {
    icon: 'https://example.com/marker-icon.png', // 直接使用图片URL
    title: '苏州市',
    draggable: true,
    enableAnimation: true, // 启用动画
    label: {
      content: '这里是苏州',
      offset: { x: 20, y: -10 }, // 使用 {x, y} 结构
      style: {
        color: '#333',
        fontSize: '12px',
        backgroundColor: '#fff',
        border: '1px solid #ccc',
        padding: '2px 4px',
        borderRadius: '3px'
      }
    },
    onClick: (event) => {
      console.log('标记被点击', event)
    }
  }
)
map.addOverlay(marker1)

// 创建标记（使用图标配置对象和偏移量）
const marker2 = createMarker(
  { lng: 120.595294, lat: 31.309758 },
  {
    icon: {
      url: 'https://example.com/custom-icon.png',
      size: { width: 40, height: 40 },
      anchor: { x: 20, y: 40 },
      imageOffset: { x: 0, y: 0 }
    },
    offset: { x: 5, y: -10 }, // 使用 {x, y} 格式的偏移量
    enableAnimation: true,
    animation: window.BMAP_ANIMATION_DROP, // 自定义动画类型
    title: '自定义图标标记'
  }
)
map.addOverlay(marker2)
```

### API 参考

#### loadBaiduMapScript(ak?: string)

加载百度地图API脚本。

**参数：**
- `ak` (可选): 百度地图应用密钥，默认使用内置密钥

**返回：** `Promise<BMap>`

#### initBaiduMap(containerId?: string, options?: MapInitOptions)

初始化百度地图实例。

**参数：**
- `containerId` (可选): 地图容器ID，默认 'map-container'
- `options` (可选): 地图配置选项

**MapInitOptions 接口：**
```typescript
interface MapInitOptions {
  center?: any;                // 地图中心点
  zoom?: number;              // 缩放级别
  enableMapClick?: boolean;   // 是否启用地图点击
  enableScrollWheelZoom?: boolean; // 是否启用滚轮缩放
  mapStyle?: any;            // 地图样式
}
```

**返回：** `Promise<BMap.Map>`

#### drawDistrictBoundary(map: BMap.Map, options?: DistrictDrawOptions)

绘制行政区划边界。

**参数：**
- `map`: 百度地图实例
- `options` (可选): 绘制配置选项

**DistrictDrawOptions 接口：**
```typescript
interface DistrictDrawOptions {
  areaDistrict?: Record<string, any>; // 区域数据
  districts?: string[];               // 要绘制的区域名称
  colors?: string[];                  // 区域颜色
}
```

**返回：** `MapOverlays`

#### translatePoint(point: InputPoint)

将WGS84坐标转换为百度坐标系。

**参数：**
- `point`: 输入坐标点

**InputPoint 接口：**
```typescript
interface InputPoint {
  longitude: string | number; // 经度
  latitude: string | number;  // 纬度
}
```

**返回：** `CoordinatePoint`

```typescript
interface CoordinatePoint {
  lng: number; // 转换后的经度
  lat: number; // 转换后的纬度
}
```

#### createCircleMarker(map: any, point: CoordinatePoint, radius: number, colors?: string[] | CircleMarkerColors, options?: CircleMarkerOptions)

在地图上创建带有渐变效果和脉动动画的圆形标记。

**参数：**
- `map`: 百度地图实例
- `point`: 圆形标记的中心坐标
- `radius`: 圆形半径（像素）
- `colors` (可选): 颜色配置，可以是颜色数组或颜色对象
- `options` (可选): 圆形标记配置选项

**CircleMarkerColors 接口：**
```typescript
interface CircleMarkerColors {
  stroke: string;  // 边框颜色
  fill: string;    // 填充颜色
}
```

**CircleMarkerOptions 接口：**
```typescript
interface CircleMarkerOptions {
  strokeColor?: string;     // 边框颜色
  strokeWeight?: number;    // 边框宽度
  strokeOpacity?: number;   // 边框透明度
  strokeStyle?: 'solid' | 'dashed' | 'dotted'; // 边框样式
  fillColor?: string;       // 填充颜色
  fillOpacity?: number;     // 填充透明度
  enableMassClear?: boolean; // 是否允许批量清除
  enableAnimation?: boolean; // 是否启用脉动动画
  animationDuration?: number; // 动画持续时间(秒)
}
```

**返回：** 百度地图覆盖物实例

#### createMarker(point: CoordinatePoint | any, options?: MarkerOptions)

创建百度地图标记点。

**参数：**
- `point`: 标记位置坐标点
- `options` (可选): 标记配置选项

**MarkerOptions 接口：**
```typescript
interface MarkerOptions {
  icon?: any | string | MarkerIconOptions; // 标记图标：BMap.Icon对象、图片URL或图标配置
  offset?: any | { x: number; y: number }; // 偏移量：BMap.Size对象或{x, y}结构
  draggable?: boolean;           // 是否可拖拽
  title?: string;                // 标记标题
  label?: MarkerLabelOptions;    // 标签配置
  enableAnimation?: boolean;     // 是否启用动画
  animation?: any;               // 动画效果类型
  onClick?: (event: any) => void; // 点击事件回调
}
```

**MarkerIconOptions 接口：**
```typescript
interface MarkerIconOptions {
  url: string;                   // 图标图片URL
  size?: { width: number; height: number }; // 图标尺寸
  anchor?: { x: number; y: number }; // 图标锚点
  imageOffset?: { x: number; y: number }; // 图片偏移量
}
```

**MarkerLabelOptions 接口：**
```typescript
interface MarkerLabelOptions {
  content: string;               // 标签内容
  offset?: any | { x: number; y: number }; // 标签偏移量：BMap.Size对象或{x, y}结构
  style?: Record<string, any>;   // 标签样式
}
```

**返回：** 百度地图标记实例

### 完整示例

```vue
<template>
  <div id="map-container" style="width: 100%; height: 400px;"></div>
</template>

<script setup lang="ts">
import { onMounted } from 'vue'
import { initBaiduMap, drawDistrictBoundary, createCircleMarker, createMarker } from '@shifone/jsc-util'

onMounted(async () => {
  try {
    // 初始化地图
    const map = await initBaiduMap('map-container', {
      zoom: 10,
      enableScrollWheelZoom: true
    })
    
    // 绘制苏州区域边界
    const overlays = drawDistrictBoundary(map)
    
    // 添加圆形标记
    const circleMarker = createCircleMarker(
      map,
      { lng: 120.62477, lat: 31.308559 },
      60,
      ['#FF6B6B', '#FFE66D'],
      {
        enableAnimation: true,
        animationDuration: 3,
        strokeWeight: 3
      }
    )
    map.addOverlay(circleMarker)
    
    // 添加普通标记（使用图标配置）
    const marker = createMarker(
      { lng: 120.58477, lat: 31.28559 },
      {
        icon: {
          url: 'https://api.map.baidu.com/images/marker_red.png',
          size: { width: 32, height: 32 },
          anchor: { x: 16, y: 32 }
        },
        title: '重要地点',
        draggable: true,
        enableAnimation: true, // 启用动画
        label: {
          content: '可拖拽标记',
          style: {
            color: '#fff',
            backgroundColor: '#007bff',
            padding: '4px 8px',
            borderRadius: '4px'
          }
        },
        onClick: () => alert('标记被点击!')
      }
    )
    map.addOverlay(marker)
    
    console.log('地图初始化成功', { map, overlays, circleMarker, marker })
  } catch (error) {
    console.error('地图初始化失败:', error)
  }
})
</script>
```

## 开发

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

### 构建库

```bash
npm run build
```

### 预览构建结果

```bash
npm run preview
```

## 项目结构

```
jsc-util/
├── src/
│   ├── components/          # Vue 组件
│   │   ├── AutoScrollTable/ # 自动滚动表格组件
│   │   └── DevTools/        # 开发工具组件
│   ├── utils/              # 数据资源
│   │   └── baidu/          # 百度相关数据
│   │       ├── map-style.json      # 地图样式配置
│   │       └── suzhou-district.json # 苏州区域数据
│   ├── index.ts            # 主入口文件
│   ├── demo.ts             # 演示入口
│   └── DemoApp.vue         # 演示应用
├── dist/                   # 构建输出目录
├── vite.config.ts          # Vite 配置
├── tsconfig.json           # TypeScript 配置
├── package.json
└── README.md
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 发布到 NPM

### 快速发布

1. 登录 NPM：
   ```bash
   npm login
   ```

2. 更新包信息（首次发布）：
   - 修改 `package.json` 中的 `name` 字段为你的包名
   - 更新 `author`、`repository` 等信息

3. 发布：
   ```bash
   # 发布正式版本
   npm run publish:npm
   
   # 发布测试版本
   npm run publish:beta
   ```

详细发布指南请参考 [PUBLISH.md](./PUBLISH.md)

## 更新日志

### v1.0.0

- 🎉 初始版本发布
- ✨ 添加 AutoScrollTable 自动滚动表格组件
- ✨ 添加 DevTools 开发辅助工具组件
- 🗂️ 提供百度地图样式和苏州区域边界 JSON 数据
- 📦 支持 ES Module 和 CommonJS
- 💪 完整的 TypeScript 支持
- 🚀 添加 NPM 发布配置