focalload/README.md

A smart web resource loading library based on user behavior prediction

# FocalLoad

[![npm version](https://img.shields.io/npm/v/focalload.svg)](https://www.npmjs.com/package/focalload)
[![License](https://img.shields.io/npm/l/focalload.svg)](https://github.com/your-username/focalload/blob/main/LICENSE)
![npm bundle size](https://img.shields.io/bundlephobia/min/focalload)

一个基于用户行为预测的智能网页资源加载库，通过分析用户交互行为来预测视觉焦点区域，从而优先加载最可能被访问的内容，显著提升页面性能和用户体验。

## 🌟 特性

- **智能预测**：利用滚动速度、方向、鼠标移动等用户行为信号预测视觉焦点区域
- **动态优先级计算**：实时更新资源加载顺序，适应用户行为变化
- **性能优化**：显著改善LCP（最大内容绘制）和INP（输入延迟）等核心Web Vitals指标
- **轻量集成**：非侵入式设计，提供简洁API，易于接入现有项目
- **自适应模式**：根据用户行为自动切换保守模式（快速滚动）和激进模式（慢速浏览）
- **区域权重**：自动分析页面结构并为不同区域分配权重

## 🚀 快速开始

### 安装

```bash
# 使用 npm
npm install focalload

# 使用 yarn
yarn add focalload

# 使用 pnpm
pnpm add focalload
```

### 基本使用

1. 在HTML中使用`data-src`属性标识需要懒加载的资源：

```html
<!-- 使用 data-section 标识页面区域 -->
<section data-section="hero">
  <!-- 使用 data-src 标识需要懒加载的资源 -->
  <img data-src="path/to/hero-image.jpg" alt="首页大图">
</section>

<section data-section="gallery">
  <div class="gallery">
    <img data-src="path/to/image1.jpg" alt="图片1">
    <img data-src="path/to/image2.jpg" alt="图片2">
    <img data-src="path/to/image3.jpg" alt="图片3">
  </div>
</section>

<!-- iframe 也支持懒加载 -->
<iframe data-src="path/to/content.html"></iframe>
```

2. 在JavaScript中引入并初始化：

```html
<!-- 引入 FocalLoad -->
<script src="node_modules/focalload/dist/focalload.umd.js"></script>
<script>
  // 初始化 FocalLoad
  FocalLoad.init();
</script>
```

或者在模块化环境中使用：

```javascript
import FocalLoad from 'focalload';

// 使用默认配置初始化
FocalLoad.init();

// 或者使用自定义配置
FocalLoad.init({
  updateInterval: 150  // 优先级更新间隔（毫秒）
});
```

## 📖 详细使用指南

### HTML标记规范

FocalLoad通过特定的HTML属性来识别页面结构和资源：

#### 页面区域标识
```html
<!-- 语义化标签自动识别 -->
<main data-role="main">...</main>
<section data-section="content">...</section>
<aside data-section="sidebar">...</aside>
<header>...</header>
<footer>...</footer>

<!-- 或者使用 data-zone 属性 -->
<div data-zone="hero">...</div>
<div data-zone="features">...</div>
```

#### 资源懒加载标识
```html
<!-- 图片懒加载 -->
<img data-src="path/to/image.jpg" alt="描述文字">

<!-- iframe懒加载 -->
<iframe data-src="path/to/content.html"></iframe>

<!-- 其他元素懒加载 -->
<div data-src="path/to/content.css"></div>
```

### JavaScript API

#### FocalLoad.init(options)

初始化FocalLoad实例。

**参数：**
- `options` (Object): 配置选项
  - `updateInterval` (Number): 优先级更新间隔（毫秒），默认为100

```javascript
FocalLoad.init({
  updateInterval: 150
});
```

#### FocalLoad.destroy()

销毁FocalLoad实例，清理事件监听器。

```javascript
FocalLoad.destroy();
```

#### FocalLoad.getStatus()

获取当前系统状态信息。

```javascript
const status = FocalLoad.getStatus();
console.log(status);
// {
//   isInitialized: true,
//   pageAnalyzer: { zonesCount: 5, resourcesCount: 12 },
//   behaviorTracker: { isTracking: true, scrollSpeed: 0.5, scrollDirection: 1 },
//   priorityScheduler: { isInitialized: true, loadingMode: 'aggressive', networkStatus: {...} }
// }
```

## 🧠 工作原理

FocalLoad采用模块化架构，包含以下核心组件：

### 1. 页面结构分析器 (PageStructureAnalyzer)
- 自动识别页面逻辑区域（section, article, main, aside等）
- 根据位置、语义标签和内容密度计算区域初始权重
- 识别带有data-src属性的可加载资源

### 2. 用户行为追踪器 (UserBehaviorTracker)
- 实时追踪滚动速度、方向和加速度
- 监控鼠标移动轨迹和悬停时间
- 基于物理学运动学原理预测用户滚动目标位置

### 3. 优先级调度器 (PriorityScheduler)
- 结合区域权重和用户行为预测计算资源加载优先级
- 根据网络状态和用户行为模式动态切换加载策略
- 实时调度资源加载顺序

## 📊 性能优势

通过智能预测算法，FocalLoad相比传统懒加载方案具有显著优势：

1. **更快的感知加载速度**：预加载用户可能关注的内容，减少等待时间
2. **更智能的资源管理**：避免加载用户不感兴趣的内容，节省带宽
3. **更好的用户体验**：根据用户行为动态调整加载策略
4. **改善核心Web Vitals**：显著提升LCP和INP指标

## 📄 许可证

[MIT](./LICENSE)