阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 jQuery.backstretch 中文API文档

      插件 jQuery.backstretch 中文API文档

      源码 & 下载

      Backstretch是一个简单的jQuery插件,允许您将动态调整大小,支持幻灯片的背景图像添加到任何页面或元素。图像将拉伸以适合页面/元素,并在窗口/元素大小更改时自动调整大小。

      建立

      在您的网页中包含jQuery库(1.7或更新版本)和Backstretch插件文件(最好在页面底部,在结束BODY标记之前):

      <script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
      <script src="jquery.backstretch.min.js"></script>
      <script>
        // To attach Backstrech as the body's background
        $.backstretch("path/to/image.jpg");
      
        // You may also attach Backstretch to a block-level element
        $(".foo").backstretch("path/to/image.jpg");
      
        // If your element defines a background image with CSS, you can omit the argement altogether
        $(".foo").backstretch();
      
        // Or, to start a slideshow, just pass in an array of images
        $(".foo").backstretch([
          "path/to/image.jpg",
          "path/to/image2.jpg",
          "path/to/image3.jpg"    
        ], {duration: 4000});
      
        // Or, to load from a url that can accept a resolution and provide the best image for that resolution
        $(".foo").backstretch([
          "path/to/image.jpg?width={width}&height={height}"
        ]);
      
        // Or, to automatically choose from a set of resolutions.
        // The width is the width of the image, and the algorithm chooses the best fit.
        $(".foo").backstretch([
          [
            { width: 1080, url: "path/to/image1_1080.jpg" },
            { width: 720, url: "path/to/image1_720.jpg" },
            { width: 320, url: "path/to/image1_320.jpg" }
          ],
          [
            { width: 1080, url: "path/to/image2_1080.jpg" },
            { width: 720, url: "path/to/image2_720.jpg" },
            { width: 320, url: "path/to/image2_320.jpg" }
          ]
        ]);
      
        // If we wanted to specify different images for different pixel-ratios:
        $(".foo").backstretch([
          [
            // Will only be chosed for a @2x device
            { width: 1080, url: "path/to/image1_1080@2x.jpg", pixelRatio: 2 },
            
            // Will only be chosed for a @1x device
            { width: 1080, url: "path/to/image1_1080.jpg", pixelRatio: 1 },
            
            { width: 720, url: "path/to/image1_720@2x.jpg", pixelRatio: 2 },
            { width: 720, url: "path/to/image1_720.jpg", pixelRatio: 1 },
            { width: 320, url: "path/to/image1_320@2x.jpg",  pixelRatio: 2 },
            { width: 320, url: "path/to/image1_320.jpg", pixelRatio: 1 }
          ]
        ]);
      
        // If we wanted the browser to automatically choose from a set of resolutions,
        // While considering the pixel-ratio of the device
        $(".foo").backstretch([
          [
            // Will be chosen for a 2160 device or a 1080*2 device
            { width: 2160, url: "path/to/image1_2160.jpg", pixelRatio: "auto" }, 
            
            // Will be chosen for a 1080 device or a 540*2 device
            { width: 1080, url: "path/to/image1_1080.jpg", pixelRatio: "auto" },
            
            // Will be chosen for a 1440 device or a 720*2 device
            { width: 1440, url: "path/to/image1_1440.jpg", pixelRatio: "auto" },
            { width: 720, url: "path/to/image1_720.jpg", pixelRatio: "auto" },
            { width: 640, url: "path/to/image1_640.jpg", pixelRatio: "auto" },
            { width: 320, url: "path/to/image1_320.jpg", pixelRatio: "auto" }
          ]
        ]);
      </script>
      

      自动分辨率选择

      自动分辨率选择算法有多个选项可供选择。 默认行为是它将元素的逻辑宽度与指定的图像大小相匹配。这意味着@ 2x设备上宽度为320px的元素仍被视为320px。 如果要将@ 2x设备上的320px视为640px,则可以指定pixelRatio: “auto"特定的图像分辨率。 但是,如果要限制特定图像仅在设备具有特定像素比率时才被选择 - 您可以指定像素比率,即pixelRatio: 2.5。

      选项

      名称描述类型默认
      alignX *此参数控制图像的水平对齐方式。可以是’center'/‘left’/‘right’或0.0到1.0之间的任何数字。整数或字符串0.5
      alignY *此参数控制图像的垂直对齐方式。可以是’center’/‘top’/‘bottom’或介于0.0和1.0之间的任何数字。整数或字符串0.5
      scale *控制缩放模式。可以’覆盖’/‘适合’/‘适合更小’/‘填充’‘覆盖’
      transition *要使用的过渡类型。如果指定了多个,则将随机选择字符串或数组‘褪色’
      transitionDuration *这是图像转换的持续时间。接受以毫秒为单位的整数,以及标准的jQuery速度字符串(慢速,正常,快速)。整数或字符串0
      transitionEasing *将用于动画的缓动功能。任何受支持的jQuery缓动值jQuery默认
      animateFirst如果true,第一张图像将像所有其他图像一样过渡。布尔true
      fade *设置transition为’fade’和transitionDuration指定的任何值。整数或字符串
      fadeFirst同义词 animateFirst布尔true
      duration *使用Backstretch作为幻灯片时,幻灯片之间的时间量,以毫秒数表示。整数5000
      paused对于幻灯片:禁用幻灯片之间的更改布尔false
      start要开始幻灯片放映的阵列中图像的索引。整数0
      preload一次预加载多少张图片?即,可以通过指定0来启用延迟加载。整数2
      preloadSize要并行预加载多少个图像?如果我们为下一张幻灯片预加载5张图片,我们可能仍希望根据预期的可用带宽将其限制为仅预加载2或3。整数1
      bypassCss避免将任何CSS添加到IMG元素。即如果你想要一个与内容一起布局的动态IMG标签。布尔false
      alwaysTestWindowResolution始终测试窗口的宽度而不是元素的宽度。布尔false
      resolutionRefreshRate在切换图像分辨率之前等待多长时间的阈值?整数2500
      resolutionChangeRatioThreshold在切换图像之前,分辨率的差异应该是多少的阈值0.1(10%)
      centeredX已过时。仍然有效,但请不要使用它。布尔true
      centeredY已过时。仍然有效,但请不要使用它。布尔true

      *可以为单个图像指定标有a的选项

      图像定义

      集合中的每个图像都可以是指定图像URL的字符串,或具有以下选项的对象,或者是可供选择的不同分辨率的图像数组。网址也可以是视频的网址。目前,该插件将自动识别youtube网址。如果您将网址传递给原始视频,则必须指定isVideo: true。

      名称描述类型默认
      url图片或视频的网址
      alt此图像的替代文字(如果您想与屏幕阅读器一起播放)“”
      alignX此参数控制图像的水平对齐方式。可以是’center'/‘left’/‘right’或0.0到1.0之间的任何数字。整数或字符串0.5
      alignY此参数控制图像的垂直对齐方式。可以是’center’/‘top’/‘bottom’或介于0.0和1.0之间的任何数字。整数或字符串0.5
      scale控制缩放模式。可以’覆盖’/‘适合’/‘适合更小’/‘填充’‘覆盖’
      transition要使用的过渡类型。如果指定了多个,则将随机选择字符串或数组‘褪色’
      transitionDuration这是图像转换的持续时间。接受以毫秒为单位的整数,以及标准的jQuery速度字符串(慢速,正常,快速)。整数或字符串0
      transitionEasing将用于动画的缓动功能。任何受支持的jQuery缓动值jQuery默认
      fade设置transition为’fade’和transitionDuration指定的任何值。整数或字符串
      duration使用Backstretch作为幻灯片时,幻灯片之间的时间量,以毫秒数表示。整数5000
      isVideo告诉插件这是一个视频(如果无法自动识别)布尔false
      loop视频应该循环播放吗?如果是,则持续时间将用于确定何时停止。布尔false
      mute视频应该静音吗?布尔true
      poster这用于poster在标准标记中指定属性

      每分辨率图像定义

      如果您为单个图像指定了一系列分辨率,那么这些是可用选项:

      名称描述类型默认
      url图像的网址
      url 对于url可以指定源数组而不是单个。每个源都有一个src和type属性。数组 { src, type }
      alt此图像的替代文字(如果您想与屏幕阅读器一起播放)“”
      width图像的宽度整数
      pixelRatio严格的规则只能选择指定的设备像素比率。如果设置为“auto”,则在评估之前,元素的宽度将首先乘以设备的像素比率。数字或“自动”未定义
      deviceOrientation将图像选择限制为特定的设备方向‘landscape’ 要么 ‘portrait’未定义
      windowOrientation将图像选择限制为特定窗口方向(基于当前窗口的内部宽度/高度)‘landscape’/ ‘portrait’/‘square’未定义
      orientation根据元素的当前内部宽度/高度将图像选择限制为元素的方向‘landscape’/ ‘portrait’/‘square’未定义
      alignX此参数控制图像的水平对齐方式。可以是’center'/‘left’/‘right’或0.0到1.0之间的任何数字。整数或字符串0.5
      alignY此参数控制图像的垂直对齐方式。可以是’center’/‘top’/‘bottom’或介于0.0和1.0之间的任何数字。整数或字符串0.5
      scale控制缩放模式。可以’覆盖’/‘适合’/‘适合更小’/‘填充’‘覆盖’
      fade这是图像淡入的速度。接受以毫秒为单位的整数,以及标准的jQuery速度字符串(慢速,正常,快速)。整数或字符串0
      duration使用Backstretch作为幻灯片时,幻灯片之间的时间量,以毫秒数表示。整数5000

      Transitions

      • ‘fade’
      • ‘fade_in_out’ / ‘fadeInOut’
      • ‘push_left’ / ‘pushLeft’
      • ‘push_right’ / ‘pushRight’
      • ‘push_up’ / ‘pushUp’
      • ‘push_down’ / ‘pushDown’
      • ‘cover_left’ / ‘coverLeft’
      • ‘cover_right’ / ‘coverRight’
      • ‘cover_up’ / ‘coverUp’
      • ‘cover_down’ / ‘coverDown’

      有关视频支持的说明:

      • 如果视频未处于loop模式,则它将一直播放到结束。您必须指定特定视频的持续时间才能限制其播放持续时间。
      • 移动浏览器不允许在没有用户点击播放按钮的情况下播放视频…因此您可能想要检测这些视频并为这些浏览器提供不同的媒体阵列。

      幻灯片API

      一旦您实例化了Backstretch幻灯片,您可以执行许多操作:

      // Start a slideshow
      $('.foo').backstretch([
        'path/to/image.jpg',
        'path/to/image2.jpg',
        'path/to/image3.jpg'
      ]);
      
      // Slideshow with granular control
      $('.foo').backstretch([
        { url: 'path/to/image.jpg', duration: 3000 }
        { url: 'path/to/image2.jpg', fade: 250 },
        { url: 'path/to/image3.jpg', alignY: 0.2 }
      ]);
      
      // Pause the slideshow
      $('.foo').backstretch("pause");
      
      // Advance to the next slide
      $('.foo').backstretch("next");
      
      方法描述
      .backstretch(“show”, n)跳转到给定索引处的幻灯片,其中n是您要显示的图像的编号。幻灯片编号从0开始。
      .backstretch(“prev”)以幻灯片形式显示上一张图像。
      .backstretch(“next”)以幻灯片形式前进到下一个图像。
      .backstretch(“pause”)暂停幻灯片放映。
      .backstretch(“resume”)恢复暂停的幻灯片。
      .backstretch(“destroy”, preserveBackground)销毁Backstretch实例。(可选)您可以传入布尔参数preserveBackground,以确定是否要将当前图像拉伸为背景图像。
      .backstretch(“resize”)调整容器(窗口或块级元素)大小时会自动调用此方法,但是如果需要,您始终可以手动调用此方法。
      .backstretch(“current”)此函数返回当前幻灯片的索引

      公共变量

      有时,在实例化插件后,您将需要访问Backstretch的图像。例如,您可能希望能够在幻灯片中添加更多图像。这样做很容易。您可以按如下方式访问images阵列:

      $('.foo').backstretch([
        'path/to/image.jpg',
        'path/to/image2.jpg',
        'path/to/image3.jpg'
      ]);
      
      // Access the instance
      var instance = $('.foo').data('backstretch');
      
      // Then, you can manipulate the images array directly
      instance.images.push('path/to/image4.jpg')
      

      此外,幻灯片的当前索引也可通过实例获得:

      $("body").data("backstretch").index;
      

      活动

      backstretch.before

      Backstretch将在加载新图像之前触发“backstretch.before”事件,触发传递事件的函数,Backstretch实例以及将显示的图像的索引。如果您收听该事件,则可以协调其他更改以与幻灯片放映一致。

      $(window).on("backstretch.before", function (e, instance, index) {
        // If we wanted to stop the slideshow after it reached the end
        if (index === instance.images.length - 1) {
          instance.pause();
        };
      });
      

      backstretch.after

      在新图像完成加载后,Backstretch还将发出“backstretch.after”事件。

      $(window).on("backstretch.after", function (e, instance, index) {
        // Do something
      });
      
      目录
      目录