# playwrightUtils

**Repository Path**: wuqianrui/playwright-utils

## Basic Information

- **Project Name**: playwrightUtils
- **Description**: 创建 playwright 的工具仓库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-24
- **Last Updated**: 2025-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Playwright 网页抓取工具

基于 Playwright 构建的灵活网页抓取工具包。本工具包提供了一个可重用的网页抓取解决方案，支持自定义提取规则。

## 功能特点

- 支持自定义网页元素选择器（CSS 和 XPath）
- 灵活的模板变量系统，支持动态参数注入
- 自动获取和保存网页元数据
- 内置丰富的抓取任务操作：
  - 等待元素/超时控制
  - 页面截图和元素截图
  - 点击和表单操作
  - 资源下载和本地化
  - 页面滚动和动态加载
  - 完整动作结果保存
- 元素移除和隐藏功能
- 媒体资源自动下载和本地化
- 灵活的配置系统
- Markdown 格式转换
- 可视化配置生成器
  - 直观的网站规则配置界面
  - 实时配置预览
  - 内置配置示例参考
  - 一键复制配置

## 环境要求

- Node.js >= 16.0.0
- pnpm >= 8.x

## 安装步骤

1. 将 `playwrightUtils` 文件夹复制到你的项目中
2. 安装依赖：
```bash
pnpm install
```
3. 安装 Playwright 浏览器：
```bash
pnpm prepare
```

## 快速开始

### 配置生成器

1. 打开 `config/config-generator.html` 在浏览器中
2. 输入网站匹配规则和内容选择器
3. 添加所需的抓取动作（等待、点击、选择器等）
4. 实时预览生成的配置
5. 复制配置并添加到 `sites.json`

### 基本使用

```javascript
const WebScraper = require('./lib/WebScraper');

// 创建实例
const scraper = new WebScraper({
    templateVars: {
        productno: '12345'
    }
});

// 抓取内容
const result = await scraper.scrape('https://example.com/product');
```

### 配置文件示例 (sites.json)

```json
{
    "example.com/product": {
        "content": ".product-content",
        "extendData": {
            "productId": "${productno}",
            "source": "example.com"
        },
        "actions": [
            {
                "type": "wait",
                "selector": ".product-details",
                "waitTime": 2000
            },
            {
                "type": "remove",
                "selectors": [".ads", ".related-products"]
            },
            {
                "type": "selectors",
                "rules": {
                    "title": {
                        "selector": "h1.product-title",
                        "attr": "text"
                    },
                    "price": {
                        "selector": ".price",
                        "attr": "text"
                    },
                    "images": {
                        "selector": ".product-images img",
                        "attr": "src",
                        "multi": true
                    }
                }
            }
        ]
    }
}
```

## Action 系统

### 当前支持的 Actions

1. **wait**: 等待元素或时间
   ```javascript
   {
       "type": "wait",
       "selector": ".element",  // 可选，如果不提供则纯等待时间
       "waitTime": 2000        // 等待时间（毫秒）
   }
   ```

2. **scroll**: 页面滚动
   ```javascript
   {
       "type": "scroll",
       "selector": "window",   // 可选，默认为 window
       "distance": 500        // 可选，滚动距离（像素）
   }
   ```

3. **click**: 点击元素
   ```javascript
   {
       "type": "click",
       "selector": ".button",
       "waitAfter": 1000     // 可选，点击后等待时间（毫秒）
   }
   ```

4. **remove**: 移除元素
   ```javascript
   {
       "type": "remove",
       "selectors": [".ad", ".popup"]  // 要移除的元素选择器数组
   }
   ```

5. **selectors**: 内容提取
   ```javascript
   {
       "type": "selectors",
       "rules": {
           "title": { 
               "selector": "h1.title", 
               "attr": "text"     // text, html, 或其他属性名
           },
           "images": { 
               "selector": ".gallery img", 
               "attr": "src",
               "multi": true      // true 返回数组，false 返回单个值
           }
       }
   }
   ```

6. **screenshot**: 页面截图
   ```javascript
   {
       "type": "screenshot",
       "selector": ".content",    // 可选，指定元素截图
       "filename": "product",     // 可选，自定义文件名
       "fullPage": false         // 可选，是否截取完整页面
   }
   ```

7. **clickByText**: 通过文本内容查找并点击元素
   ```javascript
   {
       "type": "clickByText",
       "selector": "点击这里"  // 要点击的文本内容
   }
   ```

### 未来规划的 Actions

1. **交互增强**
   ```javascript
   // 鼠标悬停
   {
       "type": "hover",
       "selector": ".menu-item",
       "waitTime": 1000
   }

   // 文本输入
   {
       "type": "input",
       "selector": "#search",
       "value": "搜索关键词",
       "pressEnter": true
   }

   // 键盘操作
   {
       "type": "keyboard",
       "sequence": ["Tab", "Enter"],
       "delay": 100
   }

   // 自定义 JS 执行
   {
       "type": "evaluate",
       "script": "window.scrollTo(0, document.body.scrollHeight)",
       "args": []
   }
   ```

2. **流程控制**
   ```javascript
   // 条件判断
   {
       "type": "if",
       "condition": {
           "selector": ".error-message",
           "exists": true
       },
       "then": [/* actions */],
       "else": [/* actions */]
   }

   // 循环操作
   {
       "type": "loop",
       "while": {
           "selector": ".next-page",
           "exists": true
       },
       "actions": [/* actions */],
       "maxIterations": 10
   }
   ```

## 配置系统

### 基础配置

```javascript
{
    "content": ".main-content",     // 主内容选择器
    "urlNormalization": {           // URL 标准化规则
        "ignoreParams": ["utm_source", "utm_medium"]
    },
    "extendData": {                // 扩展数据
        "source": "数据来源",
        "category": "${category}",  // 使用模板变量
        "timestamp": "${now}"      // 内置变量
    }
}
```

### 模板变量

```javascript
// 初始化时传入变量
const scraper = new WebScraper({
    templateVars: {
        category: "electronics",
        productId: "12345"
    }
});

// 配置中使用变量
{
    "extendData": {
        "category": "${category}",
        "id": "${productId}"
    }
}
```

### 输出示例

```javascript
{
    "url": "https://example.com/product/12345",
    "title": "产品标题",
    "price": "$99.99",
    "images": [
        "/assets/image1.jpg",
        "/assets/image2.jpg"
    ],
    "category": "electronics",
    "id": "12345",
    "timestamp": "2024-01-20T08:00:00Z"
}
```

## 注意事项

1. 选择器优先使用 CSS 选择器，必要时才使用 XPath
2. 模板变量使用 `${variableName}` 语法
3. 资源文件会自动下载到本地
4. 时间戳自动添加到元数据中
5. URL 会自动进行标准化处理

## 开源协议

MIT