zz-shopify-components 0.3.1-beta.9 → 0.4.0

package/blocks/zz-icon.liquid

@@ -1,4 +1,3 @@
-
 {% schema %}
 {
   "name": "Icon",

package/blocks/zz-normal-swiper.liquid

@@ -0,0 +1,364 @@
+{% assign block_size = block.blocks.size %}
+
+<style>
+  #shopify-block-{{block.id}} {
+    background: {{ block.settings.bg_color }};
+    width: 100%;
+    box-sizing: border-box;
+    overflow: hidden;
+    position: relative;
+  }
+  #shopify-block-{{block.id}} .zz-normal-swiper {
+    width: 100%;
+    box-sizing: border-box;
+    overflow: hidden;
+    position: relative;
+    letter-spacing: 0;
+  }
+
+  #shopify-block-{{block.id}} .swiper-button-next:after,
+  #shopify-block-{{block.id}} .swiper-button-prev:after {
+    display: none;
+  }
+
+  #shopify-block-{{block.id}} .zz-normal-swiper .swiper-pagination-bullets {
+    bottom: 16px;
+  }
+  #shopify-block-{{block.id}} .zz-normal-swiper .swiper-pagination-bullet {
+    margin: 0 4px;
+    width: 6px;
+    height: 6px;
+    border-radius: 6px;
+    background: {{ block.settings.mb_pagination_color | color_modify: 'alpha', 0.3 }};
+    opacity: 1;
+    transition: 0.3s;
+  }
+  #shopify-block-{{block.id}} .zz-normal-swiper .swiper-pagination-bullet-active {
+    background: {{ block.settings.mb_pagination_color }};
+  }
+
+  @media screen and (min-width: 1024px) {
+    #shopify-block-{{block.id}} .zz-normal-swiper .swiper-pagination-bullets {
+      bottom: 24px;
+    }
+    #shopify-block-{{block.id}} .zz-normal-swiper .swiper-pagination-bullet {
+      margin: 0 6px;
+      width: 10px;
+      height: 10px;
+      border-radius: 10px;
+      background: {{ block.settings.pagination_color | color_modify: 'alpha', 0.3 }};
+    }
+    #shopify-block-{{block.id}} .zz-normal-swiper .swiper-pagination-bullet-active {
+      background: {{ block.settings.pagination_color }};
+    }
+    #shopify-block-{{block.id}} .swiper-button-next,
+    #shopify-block-{{block.id}} .swiper-button-prev {
+      width: 48px;
+      height: 48px;
+      top: 50%;
+      transform: translateY(-50%);
+    }
+    #shopify-block-{{block.id}} .swiper-button-prev { left: 16px; }
+    #shopify-block-{{block.id}} .swiper-button-next { right: 16px; }
+  }
+
+  @media screen and (max-width: 1023px) {
+    {% if block.settings.show_navigation_mobile == false %}
+    #shopify-block-{{block.id}} .swiper-button-next,
+    #shopify-block-{{block.id}} .swiper-button-prev { display: none; }
+    {% endif %}
+  }
+</style>
+
+<div
+  class='zz-normal-swiper swiper zz-normal-swiper-{{ block.id }}'
+>
+  <div class='zz-swiper-wrapper swiper-wrapper'>
+    {% for block in block.blocks %}
+      <div class='swiper-slide'>
+        {% render block %}
+      </div>
+    {% endfor %}
+  </div>
+
+  {% if block.settings.show_navigation %}
+    <div class='swiper-button-prev {% if block_size <= 1 %} tw-hidden {% endif %}'>
+      {% render 'zz-prev-next-btn',
+        type: 'prev',
+        color_type: block.settings.prev_next_type
+      %}
+    </div>
+    <div class='swiper-button-next {% if block_size <= 1 %} tw-hidden {% endif %}'>
+      {% render 'zz-prev-next-btn',
+        type: 'next',
+        color_type: block.settings.prev_next_type
+      %}
+    </div>
+  {% endif %}
+
+  {% if block.settings.pagination_type != 'none' %}
+    <div class='swiper-pagination'></div>
+  {% endif %}
+</div>
+
+<script>
+  document.addEventListener('DOMContentLoaded', function () {
+    const block = document.getElementById('shopify-block-{{block.id}}');
+    const swiperWrapper = block.querySelector('.zz-swiper-wrapper');
+    {% comment %} const slides = swiperWrapper ? swiperWrapper.querySelectorAll(':scope > div') : [];
+    slides.forEach((slide) => slide.classList.add('swiper-slide'));
+    swiperWrapper.classList.add('swiper-wrapper'); {% endcomment %}
+
+    const swiperSelector = '.zz-normal-swiper-{{ block.id }}';
+    let instance = null;
+    let initialized = false;
+
+    const options = {
+      loop: {{ block.settings.loop | json }},
+      speed: {{ block.settings.speed | default: 500 }},
+      autoHeight: {{ block.settings.auto_height | json }},
+      centeredSlides: {{ block.settings.centered_slides | json }},
+      watchOverflow: true,
+      spaceBetween: {{ block.settings.space_between | default: 8 }},
+      {% if block.settings.pagination_type != 'none' %}
+      pagination: {
+        el: '#shopify-block-{{block.id}} .swiper-pagination',
+        clickable: true,
+        type: '{{ block.settings.pagination_type }}',
+      },
+      {% endif %}
+      {% if block.settings.show_navigation %}
+      navigation: {
+        nextEl: '#shopify-block-{{block.id}} .swiper-button-next',
+        prevEl: '#shopify-block-{{block.id}} .swiper-button-prev',
+      },
+      {% endif %}
+      {% if block.settings.autoplay %}
+      autoplay: {
+        delay: {{ block.settings.autoplay_delay | default: 4000 }},
+        disableOnInteraction: false,
+        pauseOnMouseEnter: true,
+      },
+      {% endif %}
+      breakpoints: {
+        0: {
+          slidesPerView: {{ block.settings.slides_per_view_mb | default: 1 }},
+          slidesPerGroup: {{ block.settings.slides_per_group_mb | default: 1 }},
+        },
+        1024: {
+          slidesPerView: {{ block.settings.slides_per_view_pc | default: 3 }},
+          slidesPerGroup: {{ block.settings.slides_per_group_pc | default: 1 }},
+        }
+      }
+    };
+
+    function initSwiper() {
+      if (initialized) return;
+      initialized = true;
+      instance = new Swiper(swiperSelector, options);
+    }
+
+    const root = block.querySelector(swiperSelector);
+    const io = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          if (!initialized) initSwiper();
+          {% if block.settings.autoplay %}
+          if (instance && instance.autoplay) instance.autoplay.start();
+          {% endif %}
+        } else {
+          {% if block.settings.autoplay %}
+          if (instance && instance.autoplay) instance.autoplay.stop();
+          {% endif %}
+        }
+      });
+    }, { threshold: 0.2 });
+
+    if (root) io.observe(root);
+  });
+</script>
+
+{% schema %}
+{
+  "name": "ZZ Normal Swiper",
+  "class": "zz-normal-swiper-block",
+  "settings": [
+    {
+      "type": "color",
+      "id": "bg_color",
+      "default": "#ffffff",
+      "label": "背景色"
+    },
+    { "type": "checkbox", "id": "loop", "label": "循环播放", "default": true },
+    {
+      "type": "range",
+      "id": "speed",
+      "label": "切换速度(ms)",
+      "default": 500,
+      "min": 100,
+      "max": 5000,
+      "step": 50
+    },
+    {
+      "type": "range",
+      "id": "space_between",
+      "label": "卡片间距(px)",
+      "default": 8,
+      "min": 0,
+      "max": 80,
+      "step": 2
+    },
+    {
+      "type": "checkbox",
+      "id": "centered_slides",
+      "label": "居中显示",
+      "default": false
+    },
+    {
+      "type": "checkbox",
+      "id": "auto_height",
+      "label": "自适应高度",
+      "default": false
+    },
+
+    {
+      "type": "checkbox",
+      "id": "autoplay",
+      "label": "自动播放",
+      "default": false
+    },
+    {
+      "type": "range",
+      "id": "autoplay_delay",
+      "label": "自动播放间隔(ms)",
+      "default": 4000,
+      "min": 1000,
+      "max": 9500,
+      "step": 500,
+      "visible_if": "{{ block.settings.autoplay == true }}"
+    },
+
+    {
+      "type": "select",
+      "id": "pagination_type",
+      "label": "分页器",
+      "options": [
+        { "value": "none", "label": "隐藏" },
+        { "value": "bullets", "label": "圆点" },
+        { "value": "fraction", "label": "分式" },
+        { "value": "progressbar", "label": "进度条" }
+      ],
+      "default": "bullets"
+    },
+    {
+      "type": "color",
+      "id": "pagination_color",
+      "default": "#000000",
+      "label": "分页器颜色(PC)"
+    },
+    {
+      "type": "color",
+      "id": "mb_pagination_color",
+      "default": "#000000",
+      "label": "分页器颜色(Mobile)"
+    },
+
+    {
+      "type": "checkbox",
+      "id": "show_navigation",
+      "label": "显示左右导航",
+      "default": true
+    },
+    {
+      "type": "checkbox",
+      "id": "show_navigation_mobile",
+      "label": "移动端显示导航",
+      "default": false,
+      "visible_if": "{{ block.settings.show_navigation == true }}"
+    },
+    {
+      "type": "select",
+      "id": "prev_next_type",
+      "label": "导航颜色主题",
+      "options": [
+        { "value": "dark", "label": "黑色" },
+        { "value": "light", "label": "白色" }
+      ],
+      "default": "dark"
+    },
+
+    {
+      "type": "range",
+      "id": "slides_per_view_mb",
+      "label": "可见数(Mobile)",
+      "default": 1,
+      "min": 1,
+      "max": 3,
+      "step": 0.1
+    },
+    {
+      "type": "range",
+      "id": "slides_per_group_mb",
+      "label": "每次滑动(Mobile)",
+      "default": 1,
+      "min": 1,
+      "max": 3,
+      "step": 1
+    },
+    {
+      "type": "range",
+      "id": "slides_per_view_pc",
+      "label": "可见数(PC)",
+      "default": 3,
+      "min": 1,
+      "max": 6,
+      "step": 0.1
+    },
+    {
+      "type": "range",
+      "id": "slides_per_group_pc",
+      "label": "每次滑动(PC)",
+      "default": 1,
+      "min": 1,
+      "max": 6,
+      "step": 1
+    }
+  ],
+  "blocks": [
+    {
+      "type": "@theme"
+    }
+  ],
+  "presets": [
+    {
+      "name": "ZZ Normal Swiper",
+      "category": "ZZ Components",
+      "settings": {
+        "bg_color": "#ffffff",
+        "loop": true,
+        "speed": 500,
+        "space_between": 8,
+        "centered_slides": false,
+        "auto_height": false,
+        "autoplay": false,
+        "autoplay_delay": 4000,
+        "pagination_type": "bullets",
+        "pagination_color": "#000000",
+        "mb_pagination_color": "#000000",
+        "show_navigation": true,
+        "show_navigation_mobile": false,
+        "prev_next_type": "dark",
+        "slides_per_view_mb": 1,
+        "slides_per_group_mb": 1,
+        "slides_per_view_pc": 3,
+        "slides_per_group_pc": 1
+      },
+      "blocks": [
+        { "type": "zz-flex-layout-block" },
+        { "type": "zz-flex-layout-block" },
+        { "type": "zz-flex-layout-block" }
+      ]
+    }
+  ]
+}
+{% endschema %}

package/blocks/zz-scroll-animate-bg-text.liquid

@@ -265,4 +265,3 @@
     updateOnScroll();
   });
 </script>
-

package/blocks/zz-tag.liquid

@@ -1,4 +1,3 @@
-
 {% schema %}
 {
   "name": "ZZ Tag",

package/blocks/zz-video-button.liquid

@@ -1,4 +1,3 @@
-
 {% schema %}
 {
   "name": "Video Button",
@@ -81,4 +80,3 @@
   text: block.settings.text,
   size: block.settings.size
 %}
-

package/component.config.json

@@ -3,6 +3,8 @@
         "assets/gsap.min.js",
         "assets/jquery.js",
         "assets/lozad.js",
-        "assets/ScrollTrigger.min.js"
+        "assets/ScrollTrigger.min.js",
+        "assets/aliyun-oss-sdk-6.20.0.min.js",
+        "assets/crypto-js.min.js"
     ]
 }

package/docs/zz-normal-swiper.md

@@ -0,0 +1,215 @@
+# ZZ Normal Swiper 组件使用文档
+
+## 概述
+
+`zz-normal-swiper` 是一个基于 Swiper.js 的高性能、可复用轮播组件，支持懒加载初始化、响应式配置、自动播放等功能。
+
+## 特性
+
+- ✅ **懒加载初始化**：仅在进入可视区域时初始化，节省资源
+- ✅ **响应式设计**：支持 PC/Mobile 不同配置
+- ✅ **自动播放**：可配置间隔时间，支持悬停暂停
+- ✅ **多种分页器**：圆点、分式、进度条可选
+- ✅ **灵活导航**：左右导航按钮，移动端可独立控制
+- ✅ **可定制样式**：支持背景色、分页器颜色等自定义
+- ✅ **性能优化**：IntersectionObserver 自动控制播放状态
+
+## 基本使用
+
+### 1. 添加组件
+
+在 Shopify 主题编辑器中：
+1. 找到需要添加轮播的 Section
+2. 点击"添加区块" 
+3. 选择"ZZ Components" → "ZZ Normal Swiper"
+
+### 2. 添加内容
+
+添加组件后，可以在其中插入子区块作为轮播内容：
+- 默认支持所有主题区块（`@theme`）
+- 推荐使用 `zz-flex-layout-block` 等布局组件
+
+## 配置选项
+
+### 基础设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `bg_color` | 颜色 | #ffffff | 组件背景色 |
+| `loop` | 复选框 | true | 是否循环播放 |
+| `speed` | 范围 | 500ms | 切换动画速度 (100-5000ms) |
+| `space_between` | 范围 | 8px | 卡片之间的间距 (0-80px) |
+| `centered_slides` | 复选框 | false | 是否居中显示当前卡片 |
+| `auto_height` | 复选框 | false | 是否自适应内容高度 |
+
+### 自动播放
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `autoplay` | 复选框 | false | 是否开启自动播放 |
+| `autoplay_delay` | 范围 | 4000ms | 自动播放间隔 (1000-9500ms) |
+
+> 💡 **自动播放特性**：
+> - 组件离开可视区域时自动暂停
+> - 鼠标悬停时暂停播放
+> - 用户交互后不会重置计时器
+
+### 分页器设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `pagination_type` | 选择 | bullets | 分页器类型：隐藏/圆点/分式/进度条 |
+| `pagination_color` | 颜色 | #000000 | PC端分页器颜色 |
+| `mb_pagination_color` | 颜色 | #000000 | 移动端分页器颜色 |
+
+### 导航设置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `show_navigation` | 复选框 | true | 是否显示左右导航按钮 |
+| `show_navigation_mobile` | 复选框 | false | 移动端是否显示导航 |
+| `prev_next_type` | 选择 | dark | 导航按钮主题：黑色/白色 |
+
+### 响应式配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `slides_per_view_mb` | 范围 | 1 | 移动端同时显示的卡片数 (1-3，支持小数) |
+| `slides_per_group_mb` | 范围 | 1 | 移动端每次滑动的卡片数 (1-3) |
+| `slides_per_view_pc` | 范围 | 3 | PC端同时显示的卡片数 (1-6，支持小数) |
+| `slides_per_group_pc` | 范围 | 1 | PC端每次滑动的卡片数 (1-6) |
+
+## 使用示例
+
+### 示例 1：基础产品轮播
+
+```liquid
+<!-- 在 Section 中添加 zz-normal-swiper block -->
+<!-- 配置：
+- slides_per_view_pc: 3
+- slides_per_view_mb: 1.2
+- space_between: 16
+- autoplay: true
+- autoplay_delay: 5000
+-->
+```
+
+### 示例 2：全宽图片轮播
+
+```liquid
+<!-- 配置：
+- slides_per_view_pc: 1
+- slides_per_view_mb: 1
+- centered_slides: true
+- pagination_type: bullets
+- loop: true
+-->
+```
+
+### 示例 3：卡片预览轮播
+
+```liquid
+<!-- 配置：
+- slides_per_view_pc: 4.5
+- slides_per_view_mb: 2.2
+- space_between: 12
+- centered_slides: false
+- show_navigation: true
+- pagination_type: none
+-->
+```
+
+## 样式定制
+
+### CSS 变量覆盖
+
+```css
+#shopify-block-[block-id] {
+  /* 自定义分页器位置 */
+  --swiper-pagination-bottom: 20px;
+  
+  /* 自定义导航按钮位置 */
+  --swiper-navigation-size: 44px;
+}
+```
+
+### 自定义分页器样式
+
+```css
+#shopify-block-[block-id] .swiper-pagination-bullet {
+  /* 自定义圆点样式 */
+  background: #ff6b6b;
+  border: 2px solid #fff;
+}
+```
+
+## 性能优化
+
+### 1. 懒加载机制
+- 组件使用 `IntersectionObserver` 实现懒加载
+- 仅在进入可视区域后初始化 Swiper 实例
+- 离开可视区域时自动暂停自动播放
+
+### 2. 内存管理
+- 组件销毁时自动清理事件监听器
+- 避免重复初始化
+
+### 3. 性能建议
+- 当 `slides_per_view` > 实际卡片数时，自动禁用循环
+- 图片使用 `loading="lazy"` 属性
+- 避免在轮播中嵌套过于复杂的内容
+
+## 常见问题
+
+### Q: 轮播不显示？
+A: 检查以下几点：
+1. 确保已添加子区块作为轮播内容
+2. 检查是否正确引入了 Swiper 资源文件
+3. 查看浏览器控制台是否有 JavaScript 错误
+
+### Q: 自动播放不工作？
+A: 确认：
+1. `autoplay` 选项已开启
+2. 组件在可视区域内
+3. 没有用户交互导致暂停
+
+### Q: 移动端显示异常？
+A: 检查：
+1. `slides_per_view_mb` 设置是否合理
+2. `space_between` 是否过大
+3. 内容宽度是否超出容器
+
+### Q: 如何自定义导航按钮？
+A: 导航按钮使用 `zz-prev-next-btn` 组件渲染，可以：
+1. 修改 `prev_next_type` 配置
+2. 自定义 CSS 覆盖样式
+3. 修改 `zz-prev-next-btn.liquid` 模板
+
+## 技术依赖
+
+- **Swiper.js**: 轮播核心库
+- **IntersectionObserver**: 懒加载和性能优化
+- **zz-prev-next-btn**: 导航按钮组件
+
+## 浏览器兼容性
+
+- **现代浏览器**: 完全支持
+- **IE 11**: 需要 IntersectionObserver polyfill
+- **移动端**: iOS 10+, Android 5+
+
+## 更新日志
+
+### v1.0.0
+- 初始版本发布
+- 支持基础轮播功能
+- 懒加载初始化
+- 响应式配置
+- 自动播放功能
+
+---
+
+## 相关组件
+
+- `zz-flex-layout-block`: 推荐的轮播内容布局组件
+- `zz-prev-next-btn`: 导航按钮组件
+- `zz-full-screen-swiper`: 全屏轮播组件

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-shopify-components",
-  "version": "0.3.1-beta.9",
+  "version": "0.4.0",
   "description": "Reusable Shopify components for theme projects",
   "keywords": [
     "shopify",

package/sections/zz-modal.liquid

@@ -147,7 +147,7 @@
   "presets": [
     {
       "name": "ZZ Modal",
-      "category": "Custom"
+      "category": "ZZ Components"
     }
   ]
 }

package/sections/zz-navigation-tab-v3.liquid

@@ -1,4 +1,3 @@
-
 {% schema %}
 {
   "name": "Navigation Tab V3",
@@ -205,7 +204,7 @@
         tab.addEventListener('click', () => {
           const id = tab.dataset.target;
           const target = document.querySelector(`[data-zz-module-name="${id}"]`);
-          const headerHeight = isDesktop ? 64 : 44;
+          const headerHeight = isDesktop ? 64 : 50;
           const offsetTop = target.offsetTop - headerHeight;
           scrollPaginationToCenter();
           window.scrollTo(0, offsetTop);
@@ -247,8 +246,8 @@
               if(isDesktop) {
                 currentSection.style.top = iptipsBoxHeight + 'px';
               } else {
-                // 后期移动端要加上导航栏的高度 44
-                currentSection.style.top = iptipsBoxHeight  + 44 + 'px';
+                // 后期移动端要加上导航栏的高度 50
+                currentSection.style.top = iptipsBoxHeight  + 50 + 'px';
               }
               
             } else {
@@ -256,7 +255,7 @@
                if(isDesktop) {
                 currentSection.style.top = '0px';
                } else {
-                currentSection.style.top = '44px';
+                currentSection.style.top = '50px';
                }
             }
           } else {
@@ -371,7 +370,7 @@
    @media screen and (max-width: 1024px) {
     #shopify-section-{{ section.id }} {
       z-index: 499;
-      top: 44px;
+      top: 50px;
     }
     #shopify-section-{{ section.id }} .{{ btn_class }} {
       height: 28px;

package/sections/zz-navigation-tab.liquid

@@ -1,4 +1,3 @@
-
 {% schema %}
 {
   "name": "Navigation Tab",