插件 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
});

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

于2021年离开前端领域,目前重心放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

于2021年离开前端领域,目前从事区块链方面工作了