Permalink
Please
sign in to comment.
Browse files
feat(v-b-visible): make `v-b-visible` directive available for public …
…use (#4318)
- Loading branch information
Showing
with
207 additions
and 18 deletions.
- +2 −0 docs/components/section-toc.vue
- +1 −1 src/components/form-textarea/form-textarea.js
- +1 −1 src/components/image/img-lazy.js
- +3 −2 src/directives/index.d.ts
- +3 −1 src/directives/index.js
- +135 −0 src/directives/visible/README.md
- +11 −0 src/directives/visible/index.d.ts
- +8 −0 src/directives/visible/index.js
- +25 −0 src/directives/visible/package.json
- +4 −4 src/directives/{ → visible}/visible.js
- +14 −9 src/index.js
| @@ -0,0 +1,135 @@ | ||
| # Visible | ||
|
|
||
| > The `v-b-visible` directive allows you to react when an element becomes visible in the viewport. | ||
| The `v-b-visible` directive was added in version `2.1.0`. | ||
|
|
||
| ## Overview | ||
|
|
||
| - `v-b-visible` will call your callback method with a boolean value indicating if the element is | ||
| visible (intersecting) with the viewport. | ||
| - The directive can be placed on almost any element or component. | ||
| - Changes in visibility cqn also be detected (such as `display: none`), as long as the element is | ||
| within (or partially within) the viewport, or within the optional offset. | ||
| - Several BootstrapVue components use `v-b-visible`, such as `<b-img-lazy>`. | ||
| - The `v-b-visible` directive requires browser support of | ||
| [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). | ||
| For older browsers that do not support `IntersectionObserver`, you will need to use a | ||
| [polyfill](/docs/#js). | ||
|
|
||
| ## Directive syntax and usage | ||
|
|
||
| ```html | ||
| <div v-b-visible.[mod].[...]="callback">content</div> | ||
| ``` | ||
|
|
||
| Where `callback` is required: | ||
|
|
||
| - A function reference that will be called whenever visibility changes. The callback is passed a | ||
| single boolean argument. `true` indicates that the element is intersecting (partially or entirely | ||
| visible) in the viewport, or `false` if the element is not visible/intersecting with the viewport. | ||
| The callback will be called each time the element's visibility changes (except when hte `once` | ||
| modifier is used. See below for details) | ||
|
|
||
| Where `[mod]` can be (all optional): | ||
|
|
||
| - A positive number representing the offset (margin) in pixels _away_ from the edge of the viewport | ||
| to determine when the element is considered in (or just about to be in) the viewport. The value | ||
| adds a margin around the view port. The default value is `0`. | ||
| - The keyword `once`. When this modifier is present, the callback will be called once (with the | ||
| argument of `true` indicating the element is intersecting/visible) when the element is | ||
| intersecting with the viewport. Note the callback may be called prior to this with an argument of | ||
| `false` signifying the element is not intersecting/visible. | ||
|
|
||
| ### Usage examples | ||
|
|
||
| Basic: | ||
|
|
||
| ```html | ||
| <template> | ||
| <div v-b-visible="visibleHandler"> ... </div> | ||
| </template> | ||
| <script> | ||
| export default { | ||
| methods: { | ||
| visibleHandler(isVisible) { | ||
| if (isVisible) { | ||
| // Do something | ||
| } else { | ||
| // Do something else | ||
| } | ||
| } | ||
| } | ||
| } | ||
| </script> | ||
| ``` | ||
|
|
||
| With viewport offset modifier of 350px (if the element is outside of the physical viewport by at | ||
| least 350px, then it will be considered "visible"): | ||
|
|
||
| ```html | ||
| <template> | ||
| <div v-b-visible.350="visibleHandler"> ... </div> | ||
| </template> | ||
| <script> | ||
| export default { | ||
| methods: { | ||
| visibleHandler(isVisible) { | ||
| if (isVisible) { | ||
| // Do something | ||
| } else { | ||
| // Do something else | ||
| } | ||
| } | ||
| } | ||
| } | ||
| </script> | ||
| ``` | ||
|
|
||
| With `once` modifier: | ||
|
|
||
| ```html | ||
| <template> | ||
| <div v-b-visible.350="visibleHandler"> ... </div> | ||
| </template> | ||
| <script> | ||
| export default { | ||
| methods: { | ||
| visibleHandler(isVisible) { | ||
| if (isVisible) { | ||
| // This will only ever happen once, when the | ||
| // element has become visible for the first time | ||
| } else { | ||
| // This may happen zero or more times before | ||
| // the element becomes visible, but will never | ||
| // happen after the element has become visible | ||
| } | ||
| } | ||
| } | ||
| } | ||
| </script> | ||
| ``` | ||
|
|
||
| With `once` and offset modifiers: | ||
|
|
||
| ```html | ||
| <template> | ||
| <div v-b-visible.350.once="visibleHandler"> ... </div> | ||
| </template> | ||
| <script> | ||
| export default { | ||
| methods: { | ||
| visibleHandler(isVisible) { | ||
| if (isVisible) { | ||
| // This will only ever happen once, when the | ||
| // element has become visible for the first time | ||
| } else { | ||
| // This may happen zero or more times before | ||
| // the element becomes visible, but will never | ||
| // happen after the element has become visible | ||
| } | ||
| } | ||
| } | ||
| } | ||
| </script> | ||
| ``` |
| @@ -0,0 +1,11 @@ | ||
| // | ||
| // VBVisible | ||
| // | ||
| import Vue, { DirectiveOptions } from 'vue' | ||
| import { BvPlugin } from '../../' | ||
|
|
||
| // Plugin | ||
| export declare const VBVisiblePlugin: BvPlugin | ||
|
|
||
| // Directive: v-b-visible | ||
| export declare const VBVisible: DirectiveOptions |
| @@ -0,0 +1,8 @@ | ||
| import { VBVisible } from './visible' | ||
| import { pluginFactory } from '../../utils/plugins' | ||
|
|
||
| const VBVisiblePlugin = /*#__PURE__*/ pluginFactory({ | ||
| directives: { VBVisible } | ||
| }) | ||
|
|
||
| export { VBVisiblePlugin, VBVisible } |
| @@ -0,0 +1,25 @@ | ||
| { | ||
| "name": "@bootstrap-vue/v-b-visible", | ||
| "version": "0.0.0", | ||
| "meta": { | ||
| "title": "Visible", | ||
| "description": "The `v-b-visible` directive allows you to react when an element becomes visible in the viewport.", | ||
| "directive": "VBVisible", | ||
| "new": true, | ||
| "version": "2.1.0", | ||
| "expression": [ | ||
| "Function" | ||
| ], | ||
| "modifiers": [ | ||
| { | ||
| "name": "once", | ||
| "description": "Only calls the callback once when the element becomes visible in the viewport" | ||
| }, | ||
| { | ||
| "name": "{###}", | ||
| "pattern": "[0-9]+", | ||
| "description": "An offset value in pixels (where `{###}` is the number of pixels) relative to the viewport, defaults to 0. Negative values allowed" | ||
| } | ||
| ] | ||
| } | ||
| } |
0 comments on commit
5fa7e22