卷轴展开组件 (vue3-handscroll-animation)

一、组件概述

组件功能

该组件实现了类似古代卷轴展开的动画效果，包含左右两侧画轴、中间底图及内容区域。通过动画控制画轴滑动和底图展开，适用于展示图文内容、古风界面或需要动态展开效果的场景。

二、安装与引入

安装

npm install vue3-handscroll-animation

引入方式

1. 局部引入（在目标组件中）：

import { HandscrollAnimation } from 'vue3-handscroll-animation'
import 'vue3-handscroll-animation/style:style.css'

<HandscrollAnimation
    ref="handscrollRef"

    initialState="middle"
    animationDuration="5000ms"
    width="800px"
    height="400px"
    scrollImageWidth="20px"

>
  <!-- 自定义内容 -->
  <div class="custom-content">
    <div>
      <h2>富春山居图</h2>
      <p>还不赶紧点赞收藏加关注吗？！@球球不吃虾</p>
    </div>
  </div>
</HandscrollAnimation>

三、Props 配置

| 参数名 | 类型 | 默认值 | 说明 | |-----------------------|---------------|-----------------|----------------------------------------------------------------------| | width | String | '800px' | 容器宽度（支持 CSS 单位，如 px、%） | | height | String | '400px' | 容器高度（支持 CSS 单位，如 px、%） | | leftScrollImage | String | 左侧画轴图片路径 | 左侧画轴图片地址（需传入图片 URL 或 require 路径） | | rightScrollImage | String | 右侧画轴图片路径 | 右侧画轴图片地址（需传入图片 URL 或 require 路径） | | scrollImageWidth | String | '20px' | 画轴图片宽度（控制卷轴粗细） | | contentImage | String | 底图图片路径 | 中间底图背景图片地址（支持重复平铺，通过 CSS background-repeat 控制）| | initialState | String | 'middle' | 初始状态（可选值：'middle'/折叠，'left'/左展开，'right'/右展开）| | animationDuration | String | '2000ms' | 展开动画持续时间（支持 CSS 时间单位，如 ms、s） |

四、方法与事件

公开方法

| 方法名 | 参数 | 返回值 | 说明 | |----------|------|--------|--------------------------| | play() | 无 | 无 | 触发卷轴展开动画（从中间向两侧展开） |

五、使用示例

基础用法（默认折叠状态，点击按钮展开）

<template>
  <div>
    <div>
      <button @click="play">play</button>
    </div>
    <HandscrollAnimation
        ref="handscrollRef"

        initialState="middle"
        animationDuration="5000ms"
        width="800px"
        height="400px"
        scrollImageWidth="20px"

    >
      <!-- 自定义内容 -->
      <div class="custom-content">
        <div>
          <h2>富春山居图</h2>
          <p>还不赶紧点赞收藏加关注吗？！@球球不吃虾</p>
        </div>
      </div>
    </HandscrollAnimation>
  </div>

</template>

<script setup>
  import { HandscrollAnimation } from 'vue3-handscroll-animation'
  import 'vue3-handscroll-animation/style:style.css'
  import endImage from '@/assets/Snipaste_2025-05-23_14-13-39(1)(1).png'
  import backgroundImage from '@/assets/Snipaste_2025-05-23_14-13-39(1)(2).png'
  import {ref} from 'vue'

  const handscrollRef = ref(null)
  const play = () => {
    handscrollRef.value.play()
  }
</script>
<style scoped>
  .custom-content {
    display: flex;
    justify-content: center;
    align-items: center;
    height: 100%;
    font-size: 24px;
    color: #333;
  }
</style>

六、样式定制

可修改的 CSS 变量

| 类名/属性 | 说明 | 修改方式 | |-------------------------|--------------------------|----------------------------------------| | .scroll-bg-img | 底图背景样式 | 通过 background-* 系列属性调整（如颜色、平铺方式） | | clip-path | 剪裁效果 | 修改 inset() 值控制展开区域（需配合动画） | | @keyframes 关键帧 | 动画速度曲线 | 添加 animation-timing-function 属性（如 ease-in-out） | | .scroll-image | 画轴图片样式 | 修改 width、height 或添加 box-shadow 等效果 |

七、注意事项

1. 图片路径：确保 leftScrollImage、rightScrollImage、contentImage 的路径正确（开发环境建议使用 require 引入，打包后需注意静态资源路径）。
2. 响应式布局：若使用百分比单位（如 width: 100%），需确保父容器有明确的尺寸，避免布局异常。
3. 内容区域：通过插槽传入的内容会被包裹在 .scroll-content 中，如需自定义样式，可针对该类名进行调整。

八、效果预览

（实际效果以组件运行时为准，支持从中间向两侧平滑展开，画轴伴随滑动动画）

九、更新日志

• v1.0.0（2025-05-28）：初始版本发布，实现基础卷轴展开功能。
• 待优化：支持自定义展开方向（如从左到右或单向展开）、添加暂停/回退动画功能。