README

安装

Composer

composer require gaomingcode/is-in-viewport

原始 ReadMe

一个超轻量级的 jQuery 插件，可以告诉你元素是否在视口中，但有所创新。

你说了 演示 吗？（包括测试）

对于性能更好的替代方案，请查看 observe-element-in-viewport，它使用新的 IntersectionObserver API。请注意，你可能需要根据你支持的浏览器发送一个 polyfill 以支持 IntersectionObserver。

注意：如果您需要在 React 应用中使用，请使用 use-is-in-viewport 钩子。

安装

在模块中使用

npm install --save is-in-viewport

然后您可以在您的代码中 require('is-in-viewport') 或 import 'is-in-viewport'。它将自动与您选择的打包器一起工作。如果它不起作用，请随时提交问题。

在 examples/es6-example 文件夹中展示了 ES6/ES2015 模块的示例用法 在此。

注意：isInViewport 是一个有副作用的模块。它导入您已安装的 jquery 并将其附加到它上面。因此，isInViewport 需要 jquery 作为依赖项安装。如果您没有将 jquery 作为依赖项安装，您的打包将失败，因为 is-in-viewport import 了 jquery。

在 script 标签中直接使用

• 从 releases/tags（或 bower install isInViewport 或 npm install --save is-in-viewport）获取您想要的版本
• 将 isInViewport.js 或 isInViewport.min.js 以及相应的 sourcemap 从 lib 文件夹复制/链接到包含您的脚本的文件夹中
• 在包含 jQuery 之后添加它
• 您已经准备好了！

用法

$( 'selector:in-viewport' )

当用作选择器时，它返回所有匹配的元素。因为它返回元素，所以它可以 因此与其它 jQuery 方法链式调用。它也可以与 jQuery 的 .is 一起使用。

示例

$( 'div:in-viewport' ).css( 'background-color', 'red' );
// same as
var $div = $( 'div' );
if ( $div.is( ':in-viewport' ) ) {
  $div.css( 'background-color', 'red' );
}

上面的两个都会将所有在视口中的 div 的 background-color 设置为 red。

高级用法

使用 in-viewport 伪选择器

$( 'selector:in-viewport( tolerance[, viewport selector] )' )

这会返回所有在视口中的元素，同时考虑到 tolerance 标准。

因为它返回元素，所以它可以 因此与其它 jQuery 方法链式调用。

当指定视口选择器时，它使用该选择器来计算元素是否在 该 视口中。

当未指定视口选择器时，它默认为 窗口 作为视口。

视口选择器是任何有效的 jQuery 选择器。

默认值

• tolerance 默认为 0
• viewport 默认为 window

示例

//example 1
//the height of tolerance region is 100px from top of viewport
$( 'div:in-viewport( 100 )' ).css( 'background-color', 'red' );

//example 2
//the height of tolerance region is (viewport.height - 100px) from top of viewport
$( 'div:in-viewport( -100 )' ).css( 'background-color', 'green' );

//example 3
$('#viewport > div.box:in-viewport( 100, #viewport )').css( 'background-color', 'blue' )
                                                      .text( 'in viewport' );

示例 1 将设置所有位于视口且容差为 100px 的 div 的 background-color 为 red。

示例 2 将设置所有位于视口且容差为 viewport height - 100px 的 div 的 background-color 为 green。这允许用户方便地提供一个更接近视口高度的 tolerance 值，而无需每次都调用 $(viewport).height()。

示例 3 将设置所有位于自定义视口 #viewport 且容差为 100px 的 div 的 background-color 为 blue 和 text 为 in viewport。

在高级使用中，构建类似于根据当前所在部分自动高亮显示项的菜单、元素进入视口时的过渡效果等东西变得非常容易。

请参阅 examples 目录中的示例以获得更清晰的说明。

注意

• 当 tolerance 为 0 或 undefined 时，它实际上是 等于 tolerance: $(viewport).height()，而不是 0。

这使得开发者更容易将整个 viewport 作为有效的 viewport 使用。

使用暴露的 isInViewport 函数

$( 'selector' ).isInViewport({ tolerance: tolerance, viewport: viewport })

这会返回所有在视口中的元素，同时考虑到 tolerance 标准。

因为它返回元素，所以它可以 因此与其它 jQuery 方法链式调用。

当指定视口时，它使用该视口来计算元素是否在 该 视口中。

当未指定视口时，它默认为 window 作为视口。

视口是一个有效的 DOM 元素或 jQuery 包装的 DOM 元素，而不是选择器字符串。

默认值

• tolerance 默认为 0
• viewport 默认为 window

示例

//example 1
//the height of tolerance region is 100px from top of viewport
$( 'div' ).isInViewport({ tolerance: 100 }).css( 'background-color', 'red' );

//example 2
//the height of tolerance region is (viewport.height - 100px) from top of viewport
$( 'div' ).isInViewport({ tolerance: -100 }).css( 'background-color', 'green' );

//example 3
var $viewport = $('#viewport');

$viewport
  .find('div.box')
  .isInViewport({ tolerance: 100, viewport: $viewport })
  .css( 'background-color', 'blue' )
  .text( 'in viewport' );

支持

Chrome，Firefox 3.5+，IE9+，Safari 5+，Opera 10.5+

注意

• :in-viewport 选择器 支持 连接。

变更日志

3.0.3

• 当发现 jQuery.expr.pseudos 时使用，因为 jQuery.expr[':'] 已弃用

3.0.2

• 支持新的 rollup 属性，并删除已删除的 rollup 属性（moduleId，moduleName 等）

3.0.1

• 修复 jQuery 无冲突模式问题 (#39)

3.0.0

• 删除已弃用的 $(el).do 方法
• 删除对浏览器 < { IE9，Safari 5，Opera 10.5，Firefox 3.5 } 的支持
• 添加对模块和打包器的支持。您现在可以在项目中 import 'is-in-viewport'/require('is-in-viewport')（太好了！）
• 添加正确工作的 sourcemaps 以便于调试

2.4.2

• 删除会破坏构建的 postInstall 脚本

2.4.1

• 撤销 2.4.0，因为 is-in-viewport 已经存在于 bower 中，并且不属于我

2.4.0

• 更新 bower.json 以符合新的验证
• 在 bower 上重命名包以与 npm 上的包匹配，即 is-in-viewport

2.3.1

• 删除不必要的布尔强制转换

2.3.0

• 重新暴露 isInViewport 以具有更合理的语义。您现在可以将选项作为 JS 对象传递给 isInViewport，因此您现在可以执行如下操作：

  var $viewport = $(<viewport selector>);
  
  $viewport
    .find(<selector for elements>)
    .isInViewport({ tolerance: 100, viewport: $viewport }) // <- passing the viewport jQuery object in directly
    .css(color: 'red');

• 弃用 do 以支持 run
• 当可用时，isInViewport 现在使用 Sizzle.selectors.createPseudo

2.2.5

• 更新说明以指向新的示例。主要是为了使 npm 能够获取新的说明。

2.2.4

• 拉取 #15（修复了水平视口检查）

2.2.3

• 允许使用 CommonJS -> #19
• 修复了 gruntfile。现在在构建过程中生成正确的文件名。

2.2.2

• 发布到 npm
• 更新安装说明以包括 npm

2.2.1

• 拉取了一些错误修复
• 修复 ie8 错误

2.2.0

• 将 .do 方法别名为 .run，因为 do 是保留字，并且在 IE 中用作属性时会出错。为了安全起见，请使用 .run 来连接任何任意函数或函数数组。

2.1.0

• 添加了一个 .do 方法，允许用户连接任何任意函数或函数数组。示例

//usage 1: pass a function
$( 'div:in-viewport' )
  .do(function(){
    console.log( this ); //will log the current jQuery element object it's being called on
  })
  .css( 'background-color', 'red' );

//usage 2: pass an array of functions
var fnArray = [
                function(){ console.log("Fn 1: %o", this); },
                function(){ console.log("Fn 2: %o", this); }
                //or say another function that maybe adds
                //elements to be tracked when in viewport
              ];
$( 'div:in-viewport' ).do(fnArray);

2.0.0

• 添加了对负 tolerance 值的支持，这些值现在是相对于 viewport 高度的
• 添加了对自定义视口选择器的支持（见 高级使用）
• 增加了同时检查元素是否在视口内（水平和垂直方向）的支持。（现在同时检查）
• 为了支持新的:in-viewport选择器，移除了旧的使用语法。

//removed
$( selector ).isInViewport( {"tolerance" :100, "debug": true} )

//current usage
$( 'selector:in-viewport( 100 )' )

• 移除了debug选项，因为坦白讲，没有人真正使用它。
• 移除了处理页面底部条件的奇怪代码。当用户的页面滚动到页面底部时，他们有权决定要做什么。

1.1.1

• 增加了对bower的支持。

1.1.0

• 根据joeframbach的建议，增加了对:in-viewport选择器的支持。