# lazy-gate

**Repository Path**: library-components/lazy-gate

## Basic Information

- **Project Name**: lazy-gate
- **Description**: vue懒加载指令
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lazy Gate (Open Source)

[![CI](https://img.shields.io/badge/CI-GitHub_Actions-181717?logo=github)](#发布与持续集成)
[![pnpm](https://img.shields.io/badge/pnpm-9+-F69220?logo=pnpm&logoColor=white)](#开发方式)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Vue 2](https://img.shields.io/badge/Vue-2.x-42b883?logo=vue.js)](#安装矩阵)
[![Vue 3](https://img.shields.io/badge/Vue-3.x-42b883?logo=vue.js)](#安装矩阵)

Lazy Gate 是一个面向 **Vue2 / Vue3** 的懒加载与统一释放协议类库。它关注的不只是“进入视口再加载”，而是把 **企业级图片加载体验（blur-up / skeleton / color / fade）、重块挂载、副作用回收、路由切换释放、强制降级策略** 放进同一套运行时模型中。

## 安装矩阵

| 场景 | 推荐安装包 | 说明 |
| --- | --- | --- |
| Vue3 业务项目 | `@lazy-gate/vue3` | 对外公开入口，推荐直接安装 |
| Vue2 业务项目 | `@lazy-gate/vue2` | 对外公开入口，推荐直接安装 |
| 需要直接消费共享类型与底层运行时 | `@lazy-gate/core` | 适合框架封装层或高级接入场景 |
| 需要强释放规则解析能力 | `@lazy-gate/selector` | 单独消费 selector / threshold 能力 |
| 需要远程配置或上报桥接 | `@lazy-gate/adapters` | 可选适配层 |

### Vue3

```bash
pnpm add @lazy-gate/vue3
```

```ts
import { createApp } from "vue";
import App from "./App.vue";
import { createLazyGate } from "@lazy-gate/vue3";

createApp(App)
  .use(createLazyGate({
    policy: {
      enabled: true,
      levelOrder: ["P0", "P1", "P2"],
      forceSelector: "<=P0"
    }
  }))
  .mount("#app");
```

### Vue2

```bash
pnpm add @lazy-gate/vue2
```

```js
import Vue from "vue";
import App from "./App.vue";
import LazyGate from "@lazy-gate/vue2";

Vue.use(LazyGate);
new Vue({ render: (h) => h(App) }).$mount("#app");
```

## 仓库定位

本仓库采用 **pnpm monorepo** 组织，默认中文文档，英文文档作为补充。当前主要包含：

- `@lazy-gate/core`：核心运行时与共享实现
- `@lazy-gate/vue3`：Vue3 独立发布入口，推荐业务直接安装
- `@lazy-gate/vue2`：Vue2 独立发布入口，推荐业务直接安装
- `@lazy-gate/adapters`：可选适配器，例如远程配置与上报桥接
- `@lazy-gate/selector`：强释放规则选择器与阈值编译能力
- `examples/*`：Vue2 / Vue3 最小示例工程
- `docs/*`：VitePress 文档站点

## 架构设计思路

### 1. 分层原则

仓库按“**核心能力 / 可选适配 / 示例工程 / 文档站点**”拆分，避免把演示代码、业务接入代码、运行时基础设施混在一起：

```text
packages/
  core/        # 核心运行时与指令
  vue2/        # Vue2 对外发布入口
  vue3/        # Vue3 对外发布入口
  selector/    # 强释放规则解析与计算
  adapters/    # 可选远程配置、上报桥接
examples/
  vue2-vite/   # Vue2 示例
  vue3-vite/   # Vue3 示例
  shared/      # 示例共享配置，避免重复代码
scripts/
  workspace-utils.ts  # monorepo alias / fs.allow 共享工具
```

### 2. 单文件单逻辑

当前工程遵循以下约束：

- `scripts/workspace-utils.ts` 只处理 workspace alias 与 `server.fs.allow`
- `examples/shared/demo-config.ts` 只处理示例公共常量与构造函数
- 示例 `App.vue` 只负责页面编排，不再堆积所有配置与演示逻辑
- 示例中的图片区域、重块区域拆分为独立组件，便于替换与扩展
- `@` 统一指向各示例工程的 `src`，缩短导入路径并提升 IDE 提示质量

### 3. 运行时模型

Lazy Gate 的核心不是单一指令，而是一套可组合的释放模型：

1. **进入视口**：加载图片或挂载重块
2. **离开视口**：按策略执行 `keep / hide / remove / unload-src / remove-dom`
3. **路由变化**：通过 RouteHub / DisposeHub 统一回收副作用
4. **策略升级**：通过 selector 与 level 概念控制更激进的释放策略

这套模型对以下场景更有价值：

- 长列表图片流
- 报表页 / 低代码设计器画布
- 富交互重块（图表、SSE、监听器、定时器）
- iOS / WebView 等内存敏感环境

## core 内部进一步分层

```text
packages/core/src
  shared/
    runtime/
      dom.ts                # DOM 释放 / 清空 / 隐藏
      lazyImgRuntime.ts     # v-lazy-img 统一状态机
      lazyPageRuntime.ts    # v-lazy-page 动态扫描状态机
      lazyMountRuntime.ts   # v-lazy-mount 共享状态机入口
      lazyBoundaryRuntime.ts# LazyBoundary 共享控制器
      gateFactory.ts        # createLazyGate 公共初始化工厂
  vue2/
    lazyGate.ts             # Vue2 指令注册与桥接
  vue3/
    lazyGate.ts             # Vue3 指令注册与桥接
```

## 文档入口

- 中文首页：`docs/index.md`
- 中文指南：`docs/guide/introduction.md`
- 英文指南：`docs/en/guide/introduction.md`
- 示例说明：`examples/README.md`

## 开发方式

```bash
pnpm i
pnpm typecheck
pnpm build
pnpm docs:api
pnpm docs:build
```

常用命令：

```bash
pnpm dev:example:vue3
pnpm dev:example:vue2
pnpm build:packages
pnpm build:examples
pnpm test
```


## 发版前终检脚本

除常规 `pnpm typecheck / pnpm test / pnpm build` 外，当前仓库还提供两组发布面终检脚本：

```bash
pnpm audit:release
pnpm audit:consumer
pnpm audit:all
```

用途分别是：

- `audit:release`：校验公开发布包的 `package.json`、`exports`、`files`、`README`、`LICENSE` 等元数据
- `audit:consumer`：校验示例工程与中文文档是否统一使用 `@lazy-gate/vue2` / `@lazy-gate/vue3` 公开入口
- `audit:all`：串联执行以上两类终检

发版完成后，建议继续按 `docs/guide/post-release-verification.md` 执行一轮外部消费验证。

## 发布与持续集成

仓库使用 Changesets 与 GitHub Actions：

- 创建变更：`pnpm changeset`
- 版本推进：`pnpm version-packages`
- 发布：`pnpm release`
- CI：`.github/workflows/ci.yml`
- Release：`.github/workflows/release.yml`

## IDE 常见问题

如果业务工程已经升级到公开安装入口，推荐优先使用 `@lazy-gate/vue3` / `@lazy-gate/vue2`。

如果源码联调阶段 IDE 仍提示 `Cannot find module @lazy-gate/vue3` 或旧路径 `@lazy-gate/core/vue3`：

- 先确认在仓库根目录执行 `pnpm i`
- 再重启 TypeScript Server / 重新加载 IDE
- 示例工程已通过 workspace alias 直接指向源码，不依赖先产出 dist 才能开发


> Demo note: appearance-related image examples use remote network images for real fetch behaviour; placeholders and error fallback remain local so network failure is distinguishable.