Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -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> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -0,0 +1,8 @@ | ||
| import { VBVisible } from './visible' | ||
| import { pluginFactory } from '../../utils/plugins' | ||
|
|
||
| const VBVisiblePlugin = /*#__PURE__*/ pluginFactory({ | ||
| directives: { VBVisible } | ||
| }) | ||
|
|
||
| export { VBVisiblePlugin, VBVisible } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| @@ -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" | ||
| } | ||
| ] | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters