@gm-mobile/swiper 1.1.12 → 1.1.13

package/README.md

@@ -0,0 +1,121 @@
+# @gm-mobile/swiper
+
+## 简介
+
+@gm-mobile/swiper 是基于 Swiper 库封装的轮播组件包，提供了多个轮播场景的解决方案，包括图片轮播、分类导航和图片预览等功能。
+
+## 安装
+
+```bash
+npm install @gm-mobile/swiper
+# 或
+yarn add @gm-mobile/swiper
+```
+
+## 包含的组件
+
+### 1. SwiperImg
+图片轮播组件，支持自动播放、循环滚动、图片懒加载等功能。
+
+- **适用场景**：商品展示、广告轮播、Banner 轮播
+- **主要功能**：
+  - 自动播放和循环模式
+  - 图片懒加载
+  - 分页器指示
+  - 点击事件回调
+- **详细文档**：[SwiperImg README](src/swiper_img/README.md)
+
+### 2. SwiperCategory
+分类轮播组件，用于展示分类导航的轮播容器。
+
+- **适用场景**：分类菜单、导航选项、标签页
+- **主要功能**：
+  - 自定义轮播内容
+  - 支持多个分类页
+  - 滑动交互
+  - Swiper 配置定制
+- **详细文档**：[SwiperCategory README](src/swiper_category/README.md)
+
+### 3. PreviewImage
+图片预览组件，支持单张和多张图片的全屏预览。
+
+- **适用场景**：商品详情、相册查看、图片浏览
+- **主要功能**：
+  - 全屏图片预览
+  - 多图滑动切换
+  - 页码显示
+  - 静态方法调用
+- **详细文档**：[PreviewImage README](src/preview_image/README.md)
+
+## 使用示例
+
+### 引入样式
+
+在使用组件前，需要先引入 Swiper 的样式文件：
+
+```jsx
+import 'swiper/css/swiper.css'
+```
+
+### 基础用法
+
+```jsx
+import { SwiperImg, SwiperCategory, PreviewImage } from '@gm-mobile/swiper'
+import 'swiper/css/swiper.css'
+
+// 图片轮播
+const imageData = [
+  { img: 'https://example.com/image1.jpg' },
+  { img: 'https://example.com/image2.jpg' },
+]
+
+<SwiperImg data={imageData} />
+
+// 分类轮播
+<SwiperCategory>
+  <div>
+    <div>分类1</div>
+    <div>分类2</div>
+  </div>
+  <div>
+    <div>分类3</div>
+    <div>分类4</div>
+  </div>
+</SwiperCategory>
+
+// 图片预览
+PreviewImage.render({
+  images: [
+    { img: 'https://example.com/image1.jpg' },
+    { img: 'https://example.com/image2.jpg' },
+  ],
+  defaultIndex: 0,
+})
+```
+
+## 开发依赖
+
+- **React**: ^16.13.1
+- **Swiper**: ^5.3.8
+- **@gm-mobile/react**: ^1.1.11
+
+## 相关包
+
+- [@gm-mobile/react](../react/README.md) - 基础组件库
+- [@gm-mobile/business](../business/README.md) - 业务组件库
+- [@gm-mobile/service_time](../service_time/README.md) - 服务时间组件库
+
+## 快速链接
+
+- [SwiperImg 组件文档](src/swiper_img/README.md)
+- [SwiperCategory 组件文档](src/swiper_category/README.md)
+- [PreviewImage 组件文档](src/preview_image/README.md)
+
+## 许可证
+
+ISC
+
+---
+
+**版本**: v1.1.12
+**最后更新**: 2026-03-27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gm-mobile/swiper",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "> TODO: description",
   "author": "liyatang <liyatang@qq.com>",
   "homepage": "https://github.com/gmfe/gm-mobile#readme",
@@ -21,12 +21,12 @@
     "url": "https://github.com/gmfe/gm-mobile/issues"
   },
   "dependencies": {
-    "@gm-mobile/react": "^1.1.11",
+    "@gm-mobile/react": "^1.1.13",
     "swiper": "^5.3.8"
   },
   "peerDependencies": {
     "react": "^16.13.1",
     "react-dom": "^16.13.1"
   },
-  "gitHead": "6be0c5a0fc3a049330b084dfa5e945784e29c4b2"
+  "gitHead": "99f7babda660876d45627b0f0c9378ce655de360"
 }

package/src/preview_image/README.md

@@ -0,0 +1,161 @@
+# PreviewImage
+
+## 简介
+图片预览组件 - 全屏图片预览组件，支持单张和多张图片的滑动浏览，适用于商品详情、相册查看等场景
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| images | 图片数组，每个元素包含 img（图片URL）和 onClick（点击回调）属性 | array | - | 是 |
+| onHide | 关闭预览的回调函数 | function | _.noop | 否 |
+| defaultIndex | 多张图片预览时，默认显示的图片索引 | number | 0 | 否 |
+| className | 自定义类名 | string | - | 否 |
+| style | 自定义样式 | object | - | 否 |
+
+### 方法
+
+| 方法名 | 说明 | 参数 | 返回值 |
+|--------|------|------|--------|
+| PreviewImage.render | 静态方法，全屏渲染图片预览组件 | options (object) - 包含 images、defaultIndex、onHide 等属性 | void |
+| PreviewImage.hide | 静态方法，隐藏当前显示的图片预览 | 无 | void |
+
+## 示例
+
+### 基础用法
+
+```jsx
+import { PreviewImage } from '@gm-mobile/swiper'
+
+// 单张图片预览
+PreviewImage.render({
+  images: [
+    {
+      img: 'https://example.com/image1.jpg'
+    }
+  ]
+})
+
+// 多张图片预览
+PreviewImage.render({
+  images: [
+    {
+      img: 'https://example.com/image1.jpg'
+    },
+    {
+      img: 'https://example.com/image2.jpg'
+    },
+    {
+      img: 'https://example.com/image3.jpg'
+    }
+  ],
+  defaultIndex: 1
+})
+```
+
+### 常见用法
+
+```jsx
+import { PreviewImage } from '@gm-mobile/swiper'
+
+// 带关闭回调的预览
+PreviewImage.render({
+  images: [
+    {
+      img: 'https://example.com/image1.jpg',
+      onClick: () => {
+        console.log('图片被点击')
+      }
+    }
+  ],
+  onHide: () => {
+    console.log('预览已关闭')
+  }
+})
+
+// 点击图片缩略图触发预览
+const handleImageClick = (imageList, currentIndex) => {
+  PreviewImage.render({
+    images: imageList,
+    defaultIndex: currentIndex
+  })
+}
+
+// 在组件中使用
+<div>
+  {images.map((image, index) => (
+    <img
+      key={index}
+      src={image.img}
+      onClick={() => handleImageClick(images, index)}
+    />
+  ))}
+</div>
+```
+
+### 高级用法
+
+```jsx
+import { PreviewImage } from '@gm-mobile/swiper'
+
+// 手动控制预览的显示和隐藏
+const showPreview = () => {
+  PreviewImage.render({
+    images: imageList,
+    defaultIndex: 0,
+    onHide: () => {
+      console.log('用户关闭了预览')
+    }
+  })
+}
+
+const hidePreview = () => {
+  PreviewImage.hide()
+}
+
+// 结合业务场景
+const ProductImageGallery = ({ images }) => {
+  return (
+    <div>
+      {images.map((image, index) => (
+        <div
+          key={index}
+          className="thumbnail"
+          onClick={() => {
+            PreviewImage.render({
+              images: images.map(img => ({
+                img: img.url,
+                onClick: () => {
+                  // 图片点击事件
+                  console.log('点击了图片:', img.url)
+                }
+              })),
+              defaultIndex: index
+            })
+          }}
+        >
+          <img src={image.thumbnail} alt={`商品图片 ${index + 1}`} />
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## 注意事项
+
+- 组件使用 `LayoutRoot.renderWith()` 渲染到 POPUP 层，确保在应用中已正确配置 LayoutRoot
+- `images` 数组中的每个元素必须包含 `img` 属性（图片 URL）
+- `onClick` 是可选的，用于在预览时点击图片的回调处理
+- 多张图片预览时，支持滑动切换和当前页码显示（格式：当前页/总页数）
+- 点击预览区域背景会自动关闭预览（触发 `onHide` 回调）
+- 单张图片预览时不显示页码计数器
+- `PreviewImage.render()` 是静态方法，不需要实例化组件即可使用
+- 确保 images 数组不为空，否则会导致组件异常
+
+## 相关组件
+
+- [SwiperImg](../swiper_img/) - 图片轮播组件
+- [SwiperCategory](../swiper_category/) - 分类轮播组件

package/src/swiper_category/README.md

@@ -0,0 +1,88 @@
+# SwiperCategory
+
+## 简介
+分类轮播组件 - 用于展示分类导航的轮播容器，支持自定义内容和滑动交互，适用于分类菜单、导航选项等场景。
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| options | Swiper 配置对象，用于自定义轮播行为（如 autoplay、speed 等） | object | - | 否 |
+| className | 自定义类名，用于添加额外的样式类 | string | - | 否 |
+| style | 自定义内联样式 | object | - | 否 |
+| children | 轮播内容，每个直接子元素会成为一个滑动页面 | node | - | 是 |
+
+## 示例
+
+### 基础用法
+```jsx
+import { SwiperCategory } from '@gm-mobile/react'
+
+<SwiperCategory>
+  <div>
+    <div onClick={() => console.log('点击收藏')}>我的收藏</div>
+    <div onClick={() => console.log('点击蔬菜')}>蔬菜</div>
+    <div onClick={() => console.log('点击肉类')}>肉类</div>
+  </div>
+  <div>
+    <div onClick={() => console.log('点击冻品')}>冻品</div>
+    <div onClick={() => console.log('点击水果')}>水果</div>
+  </div>
+</SwiperCategory>
+```
+
+### 自定义轮播配置
+```jsx
+import { SwiperCategory } from '@gm-mobile/react'
+
+<SwiperCategory
+  options={{
+    autoplay: {
+      delay: 3000,
+      disableOnInteraction: false,
+    },
+    speed: 500,
+  }}
+>
+  <div>
+    <div>分类1</div>
+    <div>分类2</div>
+  </div>
+  <div>
+    <div>分类3</div>
+    <div>分类4</div>
+  </div>
+</SwiperCategory>
+```
+
+### 自定义样式
+```jsx
+import { SwiperCategory } from '@gm-mobile/react'
+
+<SwiperCategory
+  className="custom-category"
+  style={{ height: '200px' }}
+>
+  <div style={{ background: '#f5f5f5' }}>
+    <div>首页</div>
+    <div>分类</div>
+    <div>购物车</div>
+  </div>
+  <div style={{ background: '#e8e8e8' }}>
+    <div>我的</div>
+    <div>设置</div>
+  </div>
+</SwiperCategory>
+```
+
+## 注意事项
+- 组件基于 Swiper 库实现，options 支持所有 Swiper 的配置选项
+- 当只有一个子元素时，不会显示分页器
+- 每个 slide 内可以包含多个交互元素，支持点击等事件
+- 默认开启循环模式（loop: true）
+- 确保已正确引入 Swiper 的样式文件
+
+## 相关组件
+- [SwiperImg](../swiper_img/README.md) - 图片轮播组件
+- [PreviewImage](../preview_image/README.md) - 图片预览组件

package/src/swiper_img/README.md

@@ -0,0 +1,113 @@
+# SwiperImg
+
+## 简介
+图片轮播组件 - 基于 Swiper 库实现，支持自动播放、循环滚动、图片懒加载等功能，适用于商品展示、广告轮播等场景。
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 轮播图片数据数组，每个元素包含 img（图片地址，必填）和 onClick（点击回调，可选） | array | - | 是 |
+| options | Swiper 配置项，用于覆盖默认配置（默认已配置 loop、autoplay、lazy、pagination） | object | - | 否 |
+| className | 自定义类名 | string | - | 否 |
+| style | 自定义样式 | object | - | 否 |
+
+**data 数据结构：**
+```typescript
+{
+  img: string  // 图片地址，必填
+  onClick?: (item: any) => void  // 点击回调函数，可选
+  [key: string]: any  // 其他自定义字段
+}
+```
+
+**默认配置：**
+组件已默认配置以下 Swiper 选项，可通过 options 覆盖：
+- `loop: true` - 循环播放
+- `autoplay: true` - 自动播放
+- `disableOnInteraction: false` - 用户操作后继续自动播放
+- `lazy.loadPrevNext: true` - 懒加载前后图片
+- `pagination.el: '.swiper-pagination'` - 显示分页器
+
+## 示例
+
+### 基础用法
+```jsx
+import { SwiperImg } from '@gm-mobile/react'
+
+const imageData = [
+  {
+    onClick: (item) => {
+      console.log('点击了第1张图片', item)
+    },
+    img: 'https://img.guanmai.cn/station_pic/sha1_eb0e548b7a574fcb3069a91a1dd816a1d8dddef8.jpg',
+  },
+  {
+    img: 'https://img.guanmai.cn/station_pic/sha1_6f6bd1497f8e5c1db37593110af99437589a570f.jpg',
+  },
+  {
+    img: 'https://img.guanmai.cn/station_pic/sha1_d9600fa7ed07af43313992501128e7cbd13f6b58.jpg',
+  },
+]
+
+<SwiperImg data={imageData} />
+```
+
+### 自定义配置
+```jsx
+import { SwiperImg } from '@gm-mobile/react'
+
+const imageData = [
+  {
+    onClick: () => console.log('点击图片'),
+    img: 'https://img.guanmai.cn/station_pic/xxx.jpg',
+  },
+]
+
+// 自定义 Swiper 配置
+const swiperOptions = {
+  autoplay: {
+    delay: 3000, // 自动播放间隔 3 秒
+  },
+  loop: false, // 关闭循环播放
+  pagination: {
+    clickable: true, // 分页器可点击
+  },
+}
+
+<SwiperImg data={imageData} options={swiperOptions} />
+```
+
+### 自定义样式
+```jsx
+import { SwiperImg } from '@gm-mobile/react'
+
+const imageData = [
+  {
+    img: 'https://img.guanmai.cn/station_pic/xxx.jpg',
+  },
+]
+
+const customStyle = {
+  height: '200px',
+  borderRadius: '8px',
+}
+
+<SwiperImg
+  data={imageData}
+  className="my-custom-swiper"
+  style={customStyle}
+/>
+```
+
+## 注意事项
+- 必须确保已引入 Swiper 的样式文件：`import 'swiper/css/swiper.css'`
+- data 数组中每个对象必须包含 `img` 字段（图片地址）
+- 在 loop 模式下（默认开启），点击事件已做特殊处理，可正常触发 onClick 回调
+- 图片懒加载功能默认开启，有利于提升性能
+- 如需关闭自动播放或修改播放间隔，请通过 options 配置 `autoplay` 属性
+
+## 相关组件
+- [PreviewImage](../preview_image/README.md) - 图片预览组件
+- [SwiperCategory](../swiper_category/README.md) - 分类轮播组件