UNPKG

carbon-components-angular

Version:
1,074 lines (896 loc) 41.7 kB
<!doctype html> <html class="no-js" lang=""> <head> <meta charset="utf-8"> <meta http-equiv="x-ua-compatible" content="ie=edge"> <title>carbon-components-angular documentation</title> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="icon" type="image/x-icon" href="../images/favicon.ico"> <link rel="stylesheet" href="../styles/style.css"> <link rel="stylesheet" href="../styles/dark.css"> <style> footer.carbon { position: absolute; bottom: 0; width: 100%; z-index: 9999; } #root > div { /* * Subtracting the height of the footer to prevent * overlaying the footer ontop of content */ height: calc(100vh - 48px); } </style> </head> <body> <script> // Blocking script to avoid flickering dark mode // Dark mode toggle button var useDark = window.matchMedia('(prefers-color-scheme: dark)'); var darkModeState = useDark.matches; var $darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input'); var $darkModeToggles = document.querySelectorAll('.dark-mode-switch'); var darkModeStateLocal = localStorage.getItem('compodoc_darkmode-state'); function checkToggle(check) { for (var i = 0; i < $darkModeToggleSwitchers.length; i++) { $darkModeToggleSwitchers[i].checked = check; } } function toggleDarkMode(state) { if (window.localStorage) { localStorage.setItem('compodoc_darkmode-state', state); } checkToggle(state); const hasClass = document.body.classList.contains('dark'); if (state) { for (var i = 0; i < $darkModeToggles.length; i++) { $darkModeToggles[i].classList.add('dark'); } if (!hasClass) { document.body.classList.add('dark'); } } else { for (var i = 0; i < $darkModeToggles.length; i++) { $darkModeToggles[i].classList.remove('dark'); } if (hasClass) { document.body.classList.remove('dark'); } } } useDark.addEventListener('change', function (evt) { toggleDarkMode(evt.matches); }); if (darkModeStateLocal) { darkModeState = darkModeStateLocal === 'true'; } toggleDarkMode(darkModeState); </script> <div class="navbar navbar-default navbar-fixed-top d-md-none p-0"> <div class="d-flex"> <a href="../" class="navbar-brand">carbon-components-angular documentation</a> <button type="button" class="btn btn-default btn-menu ion-ios-menu" id="btn-menu"></button> </div> </div> <div class="xs-menu menu" id="mobile-menu"> <div id="book-search-input" role="search"><input type="text" placeholder="Type to search"></div> <compodoc-menu></compodoc-menu> </div> <div class="container-fluid main"> <div class="row main"> <div class="d-none d-md-block menu"> <compodoc-menu mode="normal"></compodoc-menu> </div> <!-- START CONTENT --> <div class="content injectable"> <div class="content-data"> <ol class="breadcrumb"> <li class="breadcrumb-item">Injectables</li> <li class="breadcrumb-item" >DropdownService</li> </ol> <ul class="nav nav-tabs" role="tablist"> <li class="nav-item"> <a href="#info" class="nav-link" class="nav-link active" role="tab" id="info-tab" data-bs-toggle="tab" data-link="info">Info</a> </li> <li class="nav-item"> <a href="#source" class="nav-link" role="tab" id="source-tab" data-bs-toggle="tab" data-link="source">Source</a> </li> </ul> <div class="tab-content"> <div class="tab-pane fade active in" id="info"> <p class="comment"> <h3>File</h3> </p> <p class="comment"> <code>src/dropdown/dropdown.service.ts</code> </p> <section data-compodoc="block-index"> <h3 id="index">Index</h3> <table class="table table-sm table-bordered index-table"> <tbody> <tr> <td class="col-md-4"> <h6><b>Properties</b></h6> </td> </tr> <tr> <td class="col-md-4"> <ul class="index-list"> <li> <span class="modifier">Protected</span> <a href="#_offset" >_offset</a> </li> <li> <span class="modifier">Protected</span> <a href="#animationFrameSubscription" >animationFrameSubscription</a> </li> <li> <span class="modifier">Protected</span> <a href="#menuInstance" >menuInstance</a> </li> </ul> </td> </tr> <tr> <td class="col-md-4"> <h6><b>Methods</b></h6> </td> </tr> <tr> <td class="col-md-4"> <ul class="index-list"> <li> <a href="#appendToBody" >appendToBody</a> </li> <li> <a href="#appendToDropdown" >appendToDropdown</a> </li> <li> <a href="#ngOnDestroy" >ngOnDestroy</a> </li> <li> <span class="modifier">Protected</span> <a href="#positionDropdown" >positionDropdown</a> </li> <li> <a href="#updatePosition" >updatePosition</a> </li> </ul> </td> </tr> <tr> <td class="col-md-4"> <h6><b>Accessors</b></h6> </td> </tr> <tr> <td class="col-md-4"> <ul class="index-list"> <li> <a href="#offset" >offset</a> </li> </ul> </td> </tr> </tbody> </table> </section> <section data-compodoc="block-constructor"> <h3 id="constructor">Constructor</h3> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <code>constructor(placeholderService: <a href="../injectables/PlaceholderService.html" target="_self">PlaceholderService</a>, animationFrameService: <a href="../injectables/AnimationFrameService.html" target="_self">AnimationFrameService</a>)</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="30" class="link-to-prism">src/dropdown/dropdown.service.ts:30</a></div> </td> </tr> <tr> <td class="col-md-4"> <div> <b>Parameters :</b> <table class="params"> <thead> <tr> <td>Name</td> <td>Type</td> <td>Optional</td> </tr> </thead> <tbody> <tr> <td>placeholderService</td> <td> <code><a href="../injectables/PlaceholderService.html" target="_self" >PlaceholderService</a></code> </td> <td> No </td> </tr> <tr> <td>animationFrameService</td> <td> <code><a href="../injectables/AnimationFrameService.html" target="_self" >AnimationFrameService</a></code> </td> <td> No </td> </tr> </tbody> </table> </div> </td> </tr> </tbody> </table> </section> <section data-compodoc="block-methods"> <h3 id="methods"> Methods </h3> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="appendToBody"></a> <span class="name"> <span ><b>appendToBody</b></span> <a href="#appendToBody"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <code>appendToBody(parentRef: HTMLElement, menuRef: HTMLElement, classList)</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="44" class="link-to-prism">src/dropdown/dropdown.service.ts:44</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"><p>Appends the menu to the body, or a <code>cds-placeholder</code> (if defined)</p> </div> <div class="io-description"> <b>Parameters :</b> <table class="params"> <thead> <tr> <td>Name</td> <td>Type</td> <td>Optional</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td>parentRef</td> <td> <code>HTMLElement</code> </td> <td> No </td> <td> <p>container to position relative to</p> </td> </tr> <tr> <td>menuRef</td> <td> <code>HTMLElement</code> </td> <td> No </td> <td> <p>menu to be appended to body</p> </td> </tr> <tr> <td>classList</td> <td> </td> <td> No </td> <td> <p>any extra classes we should wrap the container with</p> </td> </tr> </tbody> </table> </div> <div class="io-description"> <b>Returns : </b> <code>HTMLElement</code> </div> <div class="io-description"> </div> </td> </tr> </tbody> </table> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="appendToDropdown"></a> <span class="name"> <span ><b>appendToDropdown</b></span> <a href="#appendToDropdown"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <code>appendToDropdown(hostRef: HTMLElement)</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="77" class="link-to-prism">src/dropdown/dropdown.service.ts:77</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"><p>Reattach the dropdown menu to the parent container</p> </div> <div class="io-description"> <b>Parameters :</b> <table class="params"> <thead> <tr> <td>Name</td> <td>Type</td> <td>Optional</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td>hostRef</td> <td> <code>HTMLElement</code> </td> <td> No </td> <td> <p>container to append to</p> </td> </tr> </tbody> </table> </div> <div class="io-description"> <b>Returns : </b> <code>HTMLElement</code> </div> <div class="io-description"> </div> </td> </tr> </tbody> </table> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="ngOnDestroy"></a> <span class="name"> <span ><b>ngOnDestroy</b></span> <a href="#ngOnDestroy"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <code>ngOnDestroy()</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="102" class="link-to-prism">src/dropdown/dropdown.service.ts:102</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"> <b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code> </div> </td> </tr> </tbody> </table> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="positionDropdown"></a> <span class="name"> <span class="modifier">Protected</span> <span ><b>positionDropdown</b></span> <a href="#positionDropdown"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <span class="modifier-icon icon ion-ios-reset"></span> <code>positionDropdown(parentRef, menuRef)</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="106" class="link-to-prism">src/dropdown/dropdown.service.ts:106</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"> <b>Parameters :</b> <table class="params"> <thead> <tr> <td>Name</td> <td>Optional</td> </tr> </thead> <tbody> <tr> <td>parentRef</td> <td> No </td> </tr> <tr> <td>menuRef</td> <td> No </td> </tr> </tbody> </table> </div> <div class="io-description"> <b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code> </div> <div class="io-description"> </div> </td> </tr> </tbody> </table> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="updatePosition"></a> <span class="name"> <span ><b>updatePosition</b></span> <a href="#updatePosition"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <code>updatePosition(parentRef)</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="98" class="link-to-prism">src/dropdown/dropdown.service.ts:98</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"><p>position an open dropdown relative to the given parentRef</p> </div> <div class="io-description"> <b>Parameters :</b> <table class="params"> <thead> <tr> <td>Name</td> <td>Optional</td> </tr> </thead> <tbody> <tr> <td>parentRef</td> <td> No </td> </tr> </tbody> </table> </div> <div class="io-description"> <b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code> </div> <div class="io-description"> </div> </td> </tr> </tbody> </table> </section> <section data-compodoc="block-properties"> <h3 id="inputs"> Properties </h3> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="_offset"></a> <span class="name"> <span class="modifier">Protected</span> <span ><b>_offset</b></span> <a href="#_offset"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <i>Default value : </i><code>defaultOffset</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="30" class="link-to-prism">src/dropdown/dropdown.service.ts:30</a></div> </td> </tr> </tbody> </table> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="animationFrameSubscription"></a> <span class="name"> <span class="modifier">Protected</span> <span ><b>animationFrameSubscription</b></span> <a href="#animationFrameSubscription"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <i>Default value : </i><code>new Subscription()</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="28" class="link-to-prism">src/dropdown/dropdown.service.ts:28</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"><p>Maintains an Event Observable Subscription for the global requestAnimationFrame. requestAnimationFrame is tracked only if the <code>Dropdown</code> is appended to the body otherwise we don&#39;t need it</p> </div> </td> </tr> </tbody> </table> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="menuInstance"></a> <span class="name"> <span class="modifier">Protected</span> <span ><b>menuInstance</b></span> <a href="#menuInstance"><span class="icon ion-ios-link"></span></a> </span> </td> </tr> <tr> <td class="col-md-4"> <i>Type : </i> <code>HTMLElement</code> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="22" class="link-to-prism">src/dropdown/dropdown.service.ts:22</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"><p>reference to the body appended menu</p> </div> </td> </tr> </tbody> </table> </section> <section data-compodoc="block-accessors"> <h3 id="accessors"> Accessors </h3> <table class="table table-sm table-bordered"> <tbody> <tr> <td class="col-md-4"> <a name="offset"></a> <span class="name"><b>offset</b><a href="#offset"><span class="icon ion-ios-link"></span></a></span> </td> </tr> <tr> <td class="col-md-4"> <span class="accessor"><b>get</b><code>offset()</code></span> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="16" class="link-to-prism">src/dropdown/dropdown.service.ts:16</a></div> </td> </tr> <tr> <td class="col-md-4"> <span class="accessor"><b>set</b><code>offset(value: literal type)</code></span> </td> </tr> <tr> <td class="col-md-4"> <div class="io-line">Defined in <a href="" data-line="12" class="link-to-prism">src/dropdown/dropdown.service.ts:12</a></div> </td> </tr> <tr> <td class="col-md-4"> <div class="io-description"> <b>Parameters :</b> <table class="params"> <thead> <tr> <td>Name</td> <td>Type</td> <td>Optional</td> </tr> </thead> <tbody> <tr> <td>value</td> <td> <code>literal type</code> </td> <td> No </td> </tr> </tbody> </table> </div> <div> </div> <div class="io-description"> <b>Returns : </b> <code><a href="https://www.typescriptlang.org/docs/handbook/basic-types.html" target="_blank" >void</a></code> </div> </td> </tr> </tbody> </table> </section> </div> <div class="tab-pane fade tab-source-code" id="source"> <pre class="line-numbers compodoc-sourcecode"><code class="language-typescript">import { Injectable, ElementRef, OnDestroy } from &quot;@angular/core&quot;; import { PlaceholderService } from &quot;carbon-components-angular/placeholder&quot;; import { Subscription } from &quot;rxjs&quot;; import { position } from &quot;@carbon/utils-position&quot;; import { AnimationFrameService } from &quot;carbon-components-angular/utils&quot;; import { closestAttr } from &quot;carbon-components-angular/utils&quot;; const defaultOffset &#x3D; { top: 0, left: 0 }; @Injectable() export class DropdownService implements OnDestroy { public set offset(value: { top?: number, left?: number }) { this._offset &#x3D; Object.assign({}, defaultOffset, value); } public get offset() { return this._offset; } /** * reference to the body appended menu */ protected menuInstance: HTMLElement; /** * Maintains an Event Observable Subscription for the global requestAnimationFrame. * requestAnimationFrame is tracked only if the &#x60;Dropdown&#x60; is appended to the body otherwise we don&#x27;t need it */ protected animationFrameSubscription &#x3D; new Subscription(); protected _offset &#x3D; defaultOffset; constructor( protected placeholderService: PlaceholderService, protected animationFrameService: AnimationFrameService ) {} /** * Appends the menu to the body, or a &#x60;cds-placeholder&#x60; (if defined) * * @param parentRef container to position relative to * @param menuRef menu to be appended to body * @param classList any extra classes we should wrap the container with */ appendToBody(parentRef: HTMLElement, menuRef: HTMLElement, classList): HTMLElement { // build the dropdown list container menuRef.style.display &#x3D; &quot;block&quot;; const dropdownWrapper &#x3D; document.createElement(&quot;div&quot;); dropdownWrapper.className &#x3D; &#x60;dropdown ${classList}&#x60;; dropdownWrapper.style.width &#x3D; parentRef.offsetWidth + &quot;px&quot;; dropdownWrapper.style.position &#x3D; &quot;absolute&quot;; dropdownWrapper.appendChild(menuRef); // append it to the placeholder if (this.placeholderService.hasPlaceholderRef()) { this.placeholderService.appendElement(dropdownWrapper); // or append it directly to the body } else { document.body.appendChild(dropdownWrapper); } this.menuInstance &#x3D; dropdownWrapper; this.animationFrameSubscription &#x3D; this.animationFrameService.tick.subscribe(() &#x3D;&gt; { this.positionDropdown(parentRef, dropdownWrapper); }); // run one position in sync, so we&#x27;re less likely to have the view &quot;jump&quot; as we focus this.positionDropdown(parentRef, dropdownWrapper); return dropdownWrapper; } /** * Reattach the dropdown menu to the parent container * @param hostRef container to append to */ appendToDropdown(hostRef: HTMLElement): HTMLElement { // if the instance is already removed don&#x27;t try and remove it again if (!this.menuInstance) { return; } const instance &#x3D; this.menuInstance; const menu &#x3D; instance.firstElementChild as HTMLElement; // clean up the instance this.menuInstance &#x3D; null; menu.style.display &#x3D; &quot;none&quot;; hostRef.appendChild(menu); this.animationFrameSubscription.unsubscribe(); if (this.placeholderService.hasPlaceholderRef() &amp;&amp; this.placeholderService.hasElement(instance)) { this.placeholderService.removeElement(instance); } else if (document.body.contains(instance)) { document.body.removeChild(instance); } return instance; } /** * position an open dropdown relative to the given parentRef */ updatePosition(parentRef) { this.positionDropdown(parentRef, this.menuInstance); } ngOnDestroy() { this.animationFrameSubscription.unsubscribe(); } protected positionDropdown(parentRef, menuRef) { if (!menuRef) { return; } let leftOffset &#x3D; 0; const boxMenu &#x3D; menuRef.querySelector(&quot;.cds--list-box__menu&quot;); if (boxMenu) { // If the parentRef and boxMenu are in a different left position relative to the // window, the the boxMenu position has already been flipped and a check needs to be done // to see if it needs to stay flipped. if (parentRef.getBoundingClientRect().left !&#x3D;&#x3D; boxMenu.getBoundingClientRect().left) { // The getBoundingClientRect().right of the boxMenu if it were hypothetically flipped // back into the original position before the flip. const testBoxMenuRightEdgePos &#x3D; parentRef.getBoundingClientRect().left - boxMenu.getBoundingClientRect().left + boxMenu.getBoundingClientRect().right; if (testBoxMenuRightEdgePos &gt; (window.innerWidth || document.documentElement.clientWidth)) { leftOffset &#x3D; parentRef.offsetWidth - boxMenu.offsetWidth; } // If it has not already been flipped, check if it is necessary to flip, ie. if the // boxMenu is outside of the right viewPort. } else if (boxMenu.getBoundingClientRect().right &gt; (window.innerWidth || document.documentElement.clientWidth)) { leftOffset &#x3D; parentRef.offsetWidth - boxMenu.offsetWidth; } } // If cds-placeholder has a parent with a position(relative|fixed|absolute) account for the parent offset const closestMenuWithPos &#x3D; closestAttr(&quot;position&quot;, [&quot;relative&quot;, &quot;fixed&quot;, &quot;absolute&quot;], menuRef.parentElement); const topPos &#x3D; closestMenuWithPos ? closestMenuWithPos.getBoundingClientRect().top * -1 : this.offset.top; const leftPos &#x3D; closestMenuWithPos ? closestMenuWithPos.getBoundingClientRect().left * -1 : this.offset.left + leftOffset; let pos &#x3D; position.findAbsolute(parentRef, menuRef, &quot;bottom&quot;); pos &#x3D; position.addOffset(pos, topPos, leftPos); position.setElement(menuRef, pos); } } </code></pre> </div> </div> </div><div class="search-results"> <div class="has-results"> <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1> <ul class="search-results-list"></ul> </div> <div class="no-results"> <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1> </div> </div> </div> <!-- END CONTENT --> </div> </div> <label class="dark-mode-switch"> <input type="checkbox"> <span class="slider"> <svg class="slider-icon" viewBox="0 0 24 24" fill="none" height="20" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" width="20" xmlns="http://www.w3.org/2000/svg"> <path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"></path> </svg> </span> </label> <script> var COMPODOC_CURRENT_PAGE_DEPTH = 1; var COMPODOC_CURRENT_PAGE_CONTEXT = 'injectable'; var COMPODOC_CURRENT_PAGE_URL = 'DropdownService.html'; var MAX_SEARCH_RESULTS = 15; </script> <script> $darkModeToggleSwitchers = document.querySelectorAll('.dark-mode-switch input'); checkToggle(darkModeState); if ($darkModeToggleSwitchers.length > 0) { for (var i = 0; i < $darkModeToggleSwitchers.length; i++) { $darkModeToggleSwitchers[i].addEventListener('change', function (event) { darkModeState = !darkModeState; toggleDarkMode(darkModeState); }); } } </script> <script src="../js/libs/custom-elements.min.js"></script> <script src="../js/libs/lit-html.js"></script> <script src="../js/menu-wc.js" defer></script> <script nomodule src="../js/menu-wc_es5.js" defer></script> <script src="../js/libs/bootstrap-native.js"></script> <script src="../js/libs/es6-shim.min.js"></script> <script src="../js/libs/EventDispatcher.js"></script> <script src="../js/libs/promise.min.js"></script> <script src="../js/libs/zepto.min.js"></script> <script src="../js/compodoc.js"></script> <script src="../js/tabs.js"></script> <script src="../js/menu.js"></script> <script src="../js/libs/clipboard.min.js"></script> <script src="../js/libs/prism.js"></script> <script src="../js/sourceCode.js"></script> <script src="../js/search/search.js"></script> <script src="../js/search/lunr.min.js"></script> <script src="../js/search/search-lunr.js"></script> <script src="../js/search/search_index.js"></script> <script src="../js/lazy-load-graphs.js"></script> <footer class="carbon"> <dds-footer-container key="footer" disable-locale-button="true" size="micro" /> </footer> <script key="8" type="module" src="https://1.www.s81c.com/common/carbon-for-ibm-dotcom/tag/v1/latest/footer.min.js"> </script> <!-- Storybook override --> <script> document.title = "Carbon Components Angular"; </script> <script src="//1.www.s81c.com/common/stats/ibm-common.js" type="text/javascript" async="async"> </script> </body> </html>