sensitive-data-display/README.md

A Vue 3 component for displaying sensitive data with masking and toggle functionality

# Sensitive Data Display

一个用于脱敏展示敏感数据的Vue 3组件，支持多种脱敏模式和缓存策略。

> 📚 **完整文档**: [查看详细文档](./docs/README.md)

## 特性

- 🚀 **Vue 3 Composition API** - 完全支持Vue 3
- 🔒 **多种脱敏模式** - 服务端、客户端、自定义模式
- 📱 **内置脱敏规则** - 手机号、身份证、银行卡、邮箱等
- 💾 **灵活的缓存策略** - 内存、会话存储、本地存储
- 🎨 **可自定义样式** - 支持自定义脱敏字符和显示规则
- ⚡ **TypeScript支持** - 完整的类型定义

## 安装

```bash
npm install sensitive-data-display
```

## 使用方法

### 基础用法

```vue
<template>
  <SensitiveDataDisplay
    :value="phoneNumber"
    type="phone"
    mode="client"
  />
</template>

<script setup>
import { SensitiveDataDisplay } from 'sensitive-data-display';
import { ref } from 'vue';

const phoneNumber = ref('13812345678');
</script>
```

### 使用Hooks

```vue
<template>
  <SensitiveDataDisplayComponent
    :value="idCard"
    type="idCard"
    mode="server"
    :fetchFullData="fetchIdCardData"
    :dataId="userId"
  />
</template>

<script setup>
import { useSensitiveDataDisplay } from 'sensitive-data-display';
import { ref } from 'vue';

const { SensitiveDataDisplayComponent } = useSensitiveDataDisplay();
const idCard = ref('123456********1234');
const userId = ref(123);

const fetchIdCardData = async () => {
  // 模拟API调用
  return new Promise(resolve => {
    setTimeout(() => resolve('123456789012345678'), 1000);
  });
};
</script>
```

### 自定义脱敏规则

```vue
<template>
  <SensitiveDataDisplay
    :value="customData"
    type="custom"
    :showStart="2"
    :showEnd="3"
    maskChar="#"
  />
</template>

<script setup>
import { SensitiveDataDisplay } from 'sensitive-data-display';
import { ref } from 'vue';

const customData = ref('ABCDEFGHIJKLMN');
</script>
```

## API

### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `value` | `string` | - | 原始敏感数据或已脱敏数据（必填） |
| `mode` | `'server' \| 'client' \| 'custom'` | `'server'` | 脱敏模式 |
| `type` | `'phone' \| 'idCard' \| 'bankCard' \| 'email' \| 'custom'` | `'custom'` | 脱敏类型 |
| `showStart` | `number` | `3` | 自定义脱敏规则 - 显示前几位 |
| `showEnd` | `number` | `4` | 自定义脱敏规则 - 显示后几位 |
| `maskChar` | `string` | `'*'` | 自定义脱敏字符 |
| `defaultVisible` | `boolean` | `false` | 是否默认显示完整内容 |
| `fetchFullData` | `() => Promise<string>` | - | 获取完整数据的API函数（服务端模式必填） |
| `dataId` | `string \| number` | - | 数据唯一标识（用于API请求参数） |
| `cacheExpiry` | `number` | `10` | 缓存时效（分钟） |
| `cacheStorage` | `'memory' \| 'session' \| 'local'` | `'memory'` | 缓存存储方式 |

### Events

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `toggleRequest` | `(currentVisible: boolean, dataId?: string \| number)` | 自定义模式下，用户点击切换按钮时触发 |

### Methods

| 方法名 | 参数 | 说明 |
|--------|------|------|
| `setFullDataAndShow` | `(data: string)` | 设置完整数据并显示 |
| `hideData` | - | 隐藏数据 |
| `toggle` | - | 切换显示状态 |
| `getVisibleState` | - | 获取当前显示状态 |
| `clearCache` | - | 清除缓存 |

## 脱敏模式说明

### 服务端模式 (`mode="server"`)
- 数据在服务端加密，前端只显示脱敏数据
- 需要提供 `fetchFullData` 函数来获取完整数据
- 支持缓存机制，避免重复请求

### 客户端模式 (`mode="client"`)
- 数据在前端脱敏，原始数据存储在 `value` 中
- 点击按钮直接切换显示状态
- 适用于数据已经在客户端的场景

### 自定义模式 (`mode="custom"`)
- 完全自定义脱敏逻辑
- 点击按钮触发 `toggleRequest` 事件
- 由父组件处理数据获取和显示逻辑

## 缓存策略

### 内存缓存 (`cacheStorage="memory"`)
- 数据存储在组件状态中
- 页面刷新后失效
- 适用于临时数据

### 会话存储 (`cacheStorage="session"`)
- 数据存储在 `sessionStorage` 中
- 浏览器标签页关闭后失效
- 适用于会话期间的数据

### 本地存储 (`cacheStorage="local"`)
- 数据存储在 `localStorage` 中
- 浏览器关闭后仍然保留
- 适用于长期缓存的数据

## 全局缓存清理

```javascript
import { clearAllSensitiveCache } from 'sensitive-data-display';

// 清理所有敏感数据缓存
clearAllSensitiveCache();
```

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build
```

## 许可证

MIT