feat: v-lazy

Author: 李磊

apps/docs/.vitepress/config/zh.ts

@@ -47,7 +47,10 @@ export const zh = defineConfig({
         },
         {
           text: '指令（@ssuperlilei/directives）',
-          items: [{ text: 'vFocus 聚焦', link: '/guide/directives/vFocus' }],
+          items: [
+            { text: 'vFocus 聚焦', link: '/guide/directives/vFocus' },
+            { text: 'vLazy 懒加载', link: '/guide/directives/vLazy' },
+          ],
         },
         {
           text: '工具函数（@ssuperlilei/utils）',

apps/docs/examples/directives/vLazy/basic.vue

@@ -0,0 +1,150 @@
+<template>
+  <div class="v-lazy-demo">
+    <h1>v-lazy 图片懒加载指令演示</h1>
+
+    <div class="description">
+      <p>v-lazy 指令用于图片的懒加载，只有当图片进入视口或即将进入视口时才会加载图片。</p>
+      <p>滚动页面查看效果，图片将在进入视口时才开始加载。</p>
+    </div>
+
+    <div v-for="(image, index) in images" :key="index" class="image-container">
+      <div class="image-card">
+        <div class="image-wrapper">
+          <img
+            v-lazy="image.url"
+            :alt="'示例图片 ' + (index + 1)"
+            class="lazy-image"
+            data-loaded="false"
+            @load="onImageLoad"
+          />
+          <div class="loading-placeholder">加载中...</div>
+        </div>
+        <div class="image-info">
+          <h3>图片 {{ index + 1 }}</h3>
+          <p>{{ image.description }}</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { vLazy } from '@ssuperlilei/directives';
+
+// 图片数组，包含真实的图片URL
+const images = ref([
+  {
+    url: 'https://picsum.photos/id/1/800/400',
+    description: '这是一张使用 v-lazy 指令懒加载的图片。它只会在滚动到视图中时才会加载。',
+  },
+  {
+    url: 'https://picsum.photos/id/10/800/400',
+    description: '懒加载可以减少初始页面加载时间，提高用户体验。',
+  },
+  {
+    url: 'https://picsum.photos/id/100/800/400',
+    description: 'v-lazy 指令使用 IntersectionObserver API 来检测元素可见性。',
+  },
+  {
+    url: 'https://picsum.photos/id/1000/800/400',
+    description: '当图片元素至少有 10% 可见或在视口 100px 范围内时，图片将开始加载。',
+  },
+  {
+    url: 'https://picsum.photos/id/1001/800/400',
+    description: '图片加载后，IntersectionObserver 将停止对该元素的观察。',
+  },
+  {
+    url: 'https://picsum.photos/id/1002/800/400',
+    description: '这个指令非常适合长页面和图片密集型应用程序。',
+  },
+  {
+    url: 'https://picsum.photos/id/1003/800/400',
+    description: '通过减少不必要的图片加载，可以节省带宽并提高页面性能。',
+  },
+  {
+    url: 'https://picsum.photos/id/1004/800/400',
+    description: '如果你已经滚动到了这里，前面的所有图片已经被懒加载了。',
+  },
+]);
+
+// 图片加载完成时的处理函数
+const onImageLoad = (event: Event) => {
+  const img = event.target as HTMLImageElement;
+  img.dataset.loaded = 'true';
+};
+</script>
+
+<style scoped>
+.v-lazy-demo {
+  max-width: 800px;
+  padding: 20px;
+  margin: 0 auto;
+}
+
+h1 {
+  margin-bottom: 30px;
+  text-align: center;
+}
+
+.description {
+  padding: 15px;
+  margin-bottom: 30px;
+  background-color: #f5f5f5;
+  border-radius: 8px;
+}
+
+.image-container {
+  margin-bottom: 50px;
+}
+
+.image-card {
+  overflow: hidden;
+  border-radius: 8px;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 10%);
+}
+
+.image-wrapper {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  aspect-ratio: 2/1;
+  overflow: hidden;
+  background-color: #f0f0f0;
+}
+
+.lazy-image {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.lazy-image[data-loaded='true'] {
+  opacity: 1;
+}
+
+.loading-placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  font-size: 18px;
+  color: #666;
+}
+
+.image-info {
+  padding: 15px;
+}
+
+h3 {
+  margin-top: 0;
+  margin-bottom: 10px;
+}
+</style>

apps/docs/zh/guide/directives/vLazy.md

@@ -0,0 +1,96 @@
+# v-lazy 懒加载指令
+
+## 介绍
+
+`v-lazy` 指令用于实现图片的懒加载功能，只有当图片进入视口或即将进入视口时才会加载图片。这种延迟加载图片的方式可以显著提高页面性能，减少不必要的网络请求，尤其适合图片密集型应用。
+
+## 特性
+
+- 基于 IntersectionObserver API，性能高效
+- 只有当图片至少 10% 可见或在视口 100px 范围内时，才会加载图片
+- 自动停止对已加载图片的观察
+- 简单易用，只需添加一个指令
+
+## 安装
+
+```bash
+# npm
+npm install @ssuperlilei/directives
+
+# yarn
+yarn add @ssuperlilei/directives
+
+# pnpm
+pnpm add @ssuperlilei/directives
+```
+
+## 注册
+
+### 全局注册
+
+```typescript
+import { createApp } from 'vue';
+import { vLazy } from '@ssuperlilei/directives';
+import App from './App.vue';
+
+const app = createApp(App);
+app.directive('lazy', vLazy);
+app.mount('#app');
+```
+
+### 局部注册
+
+```vue
+<script setup>
+import { vLazy } from '@ssuperlilei/directives';
+</script>
+
+<template>
+  <img v-lazy="imageUrl" alt="Lazy loaded image" />
+</template>
+```
+
+## 基本用法
+
+只需将 `v-lazy` 指令添加到 `<img>` 标签上，并传入图片 URL 即可：
+
+```vue
+<img v-lazy="'https://example.com/image.jpg'" alt="懒加载图片" />
+```
+
+当图片进入视口或接近视口时，指令会自动设置 `src` 属性，加载图片。
+
+## 示例
+
+以下是一个使用 `v-lazy` 指令实现图片懒加载的示例：
+
+::: raw
+<demo class="vp-raw" vue="directives/vLazy/basic.vue" />
+:::
+
+## API 参考
+
+### 指令参数
+
+`v-lazy` 指令接受一个字符串参数，表示图片的 URL：
+
+```vue
+<img v-lazy="imageUrl" />
+```
+
+### 配置选项
+
+目前 `v-lazy` 指令使用以下固定配置：
+
+- `rootMargin`: 100px - 图片距离视口 100px 内时开始加载
+- `threshold`: 0.1 - 图片 10% 可见时开始加载
+
+## 注意事项
+
+- `v-lazy` 指令只能用于 `<img>` 元素，用于其他元素会在控制台发出警告
+- 该指令使用 IntersectionObserver API，在不支持该 API 的旧浏览器上需要提供 polyfill
+- 为了更好的用户体验，建议为懒加载的图片提供加载状态的视觉反馈
+
+## 浏览器兼容性
+
+`v-lazy` 指令依赖于 IntersectionObserver API，该 API 在现代浏览器中得到广泛支持。如需在旧浏览器中使用，请考虑添加相应的 polyfill。

packages/directives/src/index.ts

@@ -1,8 +1,10 @@
-import type { App, Directive } from 'vue';
+import type { App } from 'vue';
 import vFocus from './v-focus';
+import vLazy from './v-lazy';
 
 const directives = {
   vFocus,
+  vLazy,
 };
 export { version } from './version';
 
@@ -25,6 +27,6 @@ const globalRegister = (app: App, directiveKeys?: DirectiveKeys[]): void => {
     });
   }
 };
-export { vFocus, globalRegister };
+export { vFocus, vLazy, globalRegister };
 
 export default directives;

packages/directives/src/v-lazy/index.ts

@@ -0,0 +1,29 @@
+import type { DirectiveBinding } from 'vue';
+
+const lazy = {
+  mounted(el: HTMLImageElement, binding: DirectiveBinding<string>) {
+    // 确保 el 是 <img> 标签
+    if (el.tagName !== 'IMG') {
+      console.warn('v-lazy 只能用于 <img> 元素');
+      return;
+    }
+
+    const loadImage = (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          el.src = binding.value; // 设置真实图片地址
+          observer.unobserve(el); // 加载后停止观察
+        }
+      });
+    };
+
+    const observer = new IntersectionObserver(loadImage, {
+      rootMargin: '100px', // 提前 100px 触发加载
+      threshold: 0.1, // 当图片 10% 可见时加载
+    });
+
+    observer.observe(el);
+  },
+};
+
+export default lazy;

playground/src/main.ts

@@ -8,7 +8,7 @@ import 'ant-design-vue/dist/reset.css';
 // 引入@ssuperlilei/ui
 import ll_libUI from '~@ssuperlilei/ui';
 import '@ssuperlilei/ui/style.css';
-// import { globalRegister } from '@ssuperlilei/directives';
+// import { globalRegister } from '~@ssuperlilei/directives';
 
 const app = createApp(App);
 app.use(Antd); // 全局引入antdv组件