# EasyTab

**Repository Path**: kingstk/webtab

## Basic Information

- **Project Name**: EasyTab
- **Description**: 一个安全极简版的 EasyTab 新标签页插件，无冗余、无请求、纯净轻量，替换浏览器默认标签页。使用 React + Vite + TypeScript 构建，遵循最新的 Edge 扩展 V3 规范。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-01-18
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: chrome-plugins

**Tags**: None

## README

# EasyTab 新标签页扩展

一个安全极简版的 EasyTab 新标签页插件，无冗余、无请求、纯净轻量，替换浏览器默认标签页。使用 React + Vite + TypeScript 构建，遵循最新的 Edge 扩展 V3 规范。

## 🚀 功能特性

- **React + Vite + TypeScript** - 现代前端开发技术栈
- **Edge 扩展 V3** - 遵循最新的 Edge 扩展规范
- **新标签页替换** - 自定义新标签页，美观简洁的设计
- **快速链接** - 可自定义的快捷链接网格，支持文件夹分类
- **搜索栏** - 内置搜索功能，支持多种搜索引擎
- **键盘快捷键** - 快速访问扩展功能
- **主题支持** - 浅色、深色和自动主题切换
- **安全存储** - 类型安全的存储解决方案，支持本地存储和 Chrome 存储
- **热重载** - Vite 热重载，开发效率高
- **响应式设计** - 适配各种屏幕尺寸

## 📁 项目结构

```
├── public/                 # 静态资源
│   ├── icons/             # 扩展图标
│   │   ├── icon16.svg
│   │   ├── icon32.svg
│   │   ├── icon48.svg
│   │   └── icon128.svg
│   └── vite.svg
├── src/
│   ├── background/        # 后台服务工作线程
│   │   ├── background.ts
│   │   └── hot-reload.ts
│   ├── components/         # React 组件
│   │   ├── QuickLinks/     # 快速链接相关组件
│   │   └── SearchBar/      # 搜索栏组件
│   ├── content-scripts/   # 内容脚本
│   │   └── content-script.ts
│   ├── hooks/              # 自定义 React Hooks
│   ├── types/              # TypeScript 类型定义
│   ├── utils/              # 工具函数
│   │   └── storage.ts      # 类型安全的存储封装
│   ├── App.module.scss     # 主样式
│   ├── App.tsx             # 主 React 组件 (新标签页)
│   ├── main.tsx            # 应用入口
├── manifest.json           # 扩展清单 (V3)
├── vite.config.ts          # Vite 配置
├── tsconfig.json           # TypeScript 配置
└── package.json            # 依赖管理
```

## 🛠️ 安装

1. 克隆或下载此仓库
2. 安装依赖：
   ```bash
   npm install
   ```

## 🔧 开发

### 启动开发服务器

```bash
npm run dev
```

这将启动带有热重载功能的 Vite 开发服务器。

### 在 Edge 中加载扩展

1. 打开 Microsoft Edge
2. 前往 `edge://extensions/`
3. 在左下角启用"开发者模式"
4. 点击"加载解包扩展"并选择项目目录
5. 扩展现在应该已加载并激活

### 测试新标签页替换

1. 在 Edge 中打开一个新标签页
2. 你应该看到自定义的新标签页，而不是默认的 Edge 新标签页

### 测试键盘快捷键

- `Ctrl+Shift+T` - 切换扩展功能

### 测试内容脚本

1. 导航到任何网页
2. 打开开发者工具 (F12)
3. 转到控制台选项卡
4. 你应该看到"Content script loaded successfully!"

## 🏗️ 生产构建

```bash
npm run build
```

这将创建一个 `dist` 目录，其中包含生产就绪的扩展文件。

## 📤 发布到 Edge 插件商店

### 步骤 1: 打包扩展

1. 运行 `npm run build` 创建生产构建
2. 构建文件将位于 `dist` 目录中
3. 创建 `dist` 目录内容的 ZIP 文件（不要包含目录本身）

### 步骤 2: 准备商店资产

你需要：
- 一个 128x128px 的商店图标（PNG 格式）
- 一个小促销 tile（440x280px）
- 一个大促销 tile（920x680px）
- 扩展的详细描述
- 显示扩展运行的截图

### 步骤 3: 上传到 Edge 插件商店

1. 前往 [Microsoft Edge 插件开发者仪表板](https://partner.microsoft.com/zh-cn/dashboard/microsoftedge/overview)
2. 使用你的 Microsoft 账户登录
3. 点击"提交新扩展"
4. 按照屏幕上的说明：
   - 上传你的 ZIP 文件
   - 提供扩展详情、截图和促销图片
   - 设置价格（免费或付费）
   - 选择分发区域
   - 审核并提交

### 步骤 4: 等待审核

你的扩展将经过审核过程，通常需要 1-5 个工作日。

## ⚠️ 常见问题与解决方案

### 1. Manifest V3 问题

**问题**：V3 不支持后台页面，只支持服务工作线程。

**解决方案**：在清单中使用 `service_worker` 而不是 `page`：
```json
"background": {
  "service_worker": "src/background/background.ts"
}
```

### 2. Vite 构建路径问题

**问题**：构建后扩展文件无法找到其依赖项。

**解决方案**：在 `vite.config.ts` 中设置 `base: './'` 使用相对路径：
```typescript
export default defineConfig({
  base: './',
  // ...
})
```

### 3. Chrome API 的 TypeScript 错误

**问题**：TypeScript 不识别 chrome.* API。

**解决方案**：安装 `@types/chrome` 并确保它在你的 `devDependencies` 中：
```bash
npm install @types/chrome -D
```

### 4. 热重载不工作

**问题**：更改不会自动显示在扩展中。

**解决方案**：
- 确保你正确使用 `@crxjs/vite-plugin`
- 检查你的清单路径是否与实际文件结构匹配
- 尝试在 `edge://extensions/` 中重新加载扩展

### 5. 键盘快捷键冲突

**问题**：扩展快捷键与 Edge 或其他扩展冲突。

**解决方案**：
- 选择不太常见的快捷键组合
- 允许用户在 `edge://extensions/shortcuts` 中自定义快捷键

### 6. 内容脚本加载问题

**问题**：内容脚本未注入到页面中。

**解决方案**：
- 检查清单中的 `matches` 模式
- 确保内容脚本文件存在于指定路径
- 验证清单中的权限是否正确

### 7. 存储数据不持久

**问题**：存储在 `chrome.storage` 中的数据不持久。

**解决方案**：
- 使用 `chrome.storage.local` 存储持久数据
- 如果你不需要跨设备同步，避免使用 `chrome.storage.sync`
- 确保你的存储操作被包装在 try-catch 块中

## 📚 API 参考

### 存储工具

```typescript
import { Storage } from './utils/storage';

// 设置数据
await Storage.set({ settings: { background: 'linear-gradient(...)' } });

// 获取数据
const { settings, gridItems } = await Storage.get(['settings', 'gridItems']);

// 获取所有数据
const allData = await Storage.getAll();

// 获取网格项目
const items = await Storage.getGridItems();

// 设置网格项目
await Storage.setGridItems([{ id: '1', title: 'Google', url: 'https://www.google.com' }]);

// 获取文件夹
const folders = await Storage.getFolders();

// 设置文件夹
await Storage.setFolders([{ id: '1', title: 'Work', items: [] }]);

// 获取设置
const appSettings = await Storage.getSettings();

// 设置设置
await Storage.setSettings({ background: 'linear-gradient(...)' });

// 监听变更
const unsubscribe = Storage.onChanged((changes) => {
  if (changes.theme) {
    console.log('主题已更改:', changes.theme.newValue);
  }
});
```

### 后台服务工作线程

```typescript
// 监听安装
chrome.runtime.onInstalled.addListener(() => {
  // 初始化存储
});

// 监听消息
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 处理消息
});

// 监听命令
chrome.commands.onCommand.addListener((command) => {
  // 处理键盘命令
});
```

### 内容脚本

```typescript
// 修改网页
function modifyPage() {
  // DOM 操作
}

// 向后台发送消息
chrome.runtime.sendMessage({
  type: 'MESSAGE_TYPE',
  data: { /* ... */ }
});
```

## 🎨 自定义

### 主题颜色

修改 `App.module.scss` 中的渐变颜色：

```scss
.app-container {
  background: linear-gradient(to bottom right, #f97316, #ef4444, #e11d48);
  // 可以修改为你喜欢的渐变
}
```

### 快捷键

在 `manifest.json` 中编辑键盘快捷键：

```json
"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+T",
      "mac": "MacCtrl+Shift+T"
    },
    "description": "Toggle extension feature"
  }
}
```

### 快速链接

快速链接可以通过扩展界面直接添加和管理，也可以通过存储 API 进行操作：

```typescript
// 添加快速链接
const currentItems = await Storage.getGridItems();
const newItem = { id: Date.now().toString(), title: 'GitHub', url: 'https://github.com' };
await Storage.setGridItems([...currentItems, newItem]);
```

## 📄 许可证

MIT 许可证 - 请随意将此项目用于个人或商业用途。

## 🤝 贡献

欢迎贡献、提交问题和功能请求！

## 📞 支持

如需支持或有问题，请在仓库中打开一个 issue。

---

使用 React + Vite + TypeScript 为 Microsoft Edge 构建，❤️