honeymoose/angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add api doc for viewport scroller (#27381)

Browse Source 
PR Close #27381
This commit is contained in:
Judy Bogart 2018-11-30 12:16:35 -08:00 committed by Ben Lesh
parent d1de9ff313
commit c4f7727408
1 changed files with 18 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
packages/common/src/viewport_scroller.ts
View File

@ -11,7 +11,7 @@ import {defineInjectable, inject} from '@angular/core';
import {DOCUMENT} from './dom_tokens'; import {DOCUMENT} from './dom_tokens';
/** /**
* Manages the scroll position. * Defines a scroll position manager. Implemented by `BrowserViewportScroller`.
* *
* @publicApi * @publicApi
*/ */
@ -24,40 +24,40 @@ export abstract class ViewportScroller {
/** /**
* Configures the top offset used when scrolling to an anchor. * Configures the top offset used when scrolling to an anchor.
* @param offset A position in screen coordinates (a tuple with x and y values)
* or a function that returns the top offset position.
* *
* When given a tuple with two number, the service will always use the numbers.
* When given a function, the service will invoke the function every time it restores scroll
* position.
*/ */
abstract setOffset(offset: [number, number]|(() => [number, number])): void; abstract setOffset(offset: [number, number]|(() => [number, number])): void;
/** /**
* Returns the current scroll position. * Retrieves the current scroll position.
* @returns A position in screen coordinates (a tuple with x and y values).
*/ */
abstract getScrollPosition(): [number, number]; abstract getScrollPosition(): [number, number];
/** /**
* Sets the scroll position. * Scrolls to a specified position.
* @param position A position in screen coordinates (a tuple with x and y values).
*/ */
abstract scrollToPosition(position: [number, number]): void; abstract scrollToPosition(position: [number, number]): void;
/** /**
* Scrolls to the provided anchor. * Scrolls to an anchor element.
* @param anchor The ID of the anchor element.
*/ */
abstract scrollToAnchor(anchor: string): void; abstract scrollToAnchor(anchor: string): void;
/** /**
*
* Disables automatic scroll restoration provided by the browser. * Disables automatic scroll restoration provided by the browser.
*
* See also [window.history.scrollRestoration * See also [window.history.scrollRestoration
* info](https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration) * info](https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration).
*/ */
abstract setHistoryScrollRestoration(scrollRestoration: 'auto'|'manual'): void; abstract setHistoryScrollRestoration(scrollRestoration: 'auto'|'manual'): void;
} }
/** /**
* Manages the scroll position. * Manages the scroll position for a browser window.
*/ */
export class BrowserViewportScroller implements ViewportScroller { export class BrowserViewportScroller implements ViewportScroller {
private offset: () => [number, number] = () => [0, 0]; private offset: () => [number, number] = () => [0, 0];
@ -66,10 +66,9 @@ export class BrowserViewportScroller implements ViewportScroller {
/** /**
* Configures the top offset used when scrolling to an anchor. * Configures the top offset used when scrolling to an anchor.
* @param offset A position in screen coordinates (a tuple with x and y values)
* or a function that returns the top offset position.
* *
* * When given a number, the service will always use the number.
* * When given a function, the service will invoke the function every time it restores scroll
* position.
*/ */
setOffset(offset: [number, number]|(() => [number, number])): void { setOffset(offset: [number, number]|(() => [number, number])): void {
if (Array.isArray(offset)) { if (Array.isArray(offset)) {
@ -80,7 +79,8 @@ export class BrowserViewportScroller implements ViewportScroller {
} }
/** /**
* Returns the current scroll position. * Retrieves the current scroll position.
* @returns The position in screen coordinates.
*/ */
getScrollPosition(): [number, number] { getScrollPosition(): [number, number] {
if (this.supportScrollRestoration()) { if (this.supportScrollRestoration()) {
@ -92,6 +92,7 @@ export class BrowserViewportScroller implements ViewportScroller {
/** /**
* Sets the scroll position. * Sets the scroll position.
* @param position The new position in screen coordinates.
*/ */
scrollToPosition(position: [number, number]): void { scrollToPosition(position: [number, number]): void {
if (this.supportScrollRestoration()) { if (this.supportScrollRestoration()) {
@ -100,7 +101,8 @@ export class BrowserViewportScroller implements ViewportScroller {
} }
/** /**
* Scrolls to the provided anchor. * Scrolls to an anchor element.
* @param anchor The ID of the anchor element.
*/ */
scrollToAnchor(anchor: string): void { scrollToAnchor(anchor: string): void {
if (this.supportScrollRestoration()) { if (this.supportScrollRestoration()) {