diff --git a/src/lib/core/ripple/ripple.md b/src/lib/core/ripple/ripple.md index 0cf9f57b724..ecd7be5a575 100644 --- a/src/lib/core/ripple/ripple.md +++ b/src/lib/core/ripple/ripple.md @@ -46,7 +46,7 @@ class MyComponent { /** Shows a centered and persistent ripple. */ launchRipple() { - const rippleRef = this.ripple.launch(0, 0, { + const rippleRef = this.ripple.launch({ persistent: true, centered: true }); @@ -57,13 +57,21 @@ class MyComponent { } ``` -In the example above, the `x` and `y` parameters will be ignored, because the `centered` -ripple option has been set to `true`. +In the example above, no specific coordinates have been passed, because the `centered` +ripple option has been set to `true` and the coordinates would not matter. Ripples that are being dispatched programmatically can be launched with the `persistent` option. This means that the ripples will not fade out automatically, and need to be faded out using the `RippleRef` (*useful for focus indicators*). +In case, developers want to launch ripples at specific coordinates within the element, the +`launch()` method also accepts `x` and `y` coordinates as parameters. Those coordinates +are relative to the ripple container element. + +```ts +const rippleRef = this.ripple.launch(10, 10, {persistent: true}); +``` + ### Global options Developers are able to specify options for all ripples inside of their application. diff --git a/src/lib/core/ripple/ripple.spec.ts b/src/lib/core/ripple/ripple.spec.ts index 618796bd874..285ab692b18 100644 --- a/src/lib/core/ripple/ripple.spec.ts +++ b/src/lib/core/ripple/ripple.spec.ts @@ -390,6 +390,24 @@ describe('MatRipple', () => { expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0); })); + + it('should allow passing only a configuration', fakeAsync(() => { + expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0); + + const rippleRef = rippleDirective.launch({persistent: true}); + + expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1); + + tick(enterDuration + exitDuration); + + expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1); + + rippleRef.fadeOut(); + + tick(exitDuration); + + expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0); + })); }); describe('global ripple options', () => { diff --git a/src/lib/core/ripple/ripple.ts b/src/lib/core/ripple/ripple.ts index 86a98f1b97d..05aaef32e91 100644 --- a/src/lib/core/ripple/ripple.ts +++ b/src/lib/core/ripple/ripple.ts @@ -150,11 +150,6 @@ export class MatRipple implements OnInit, OnDestroy, RippleTarget { this._rippleRenderer._removeTriggerEvents(); } - /** Launches a manual ripple at the specified position. */ - launch(x: number, y: number, config?: RippleConfig): RippleRef { - return this._rippleRenderer.fadeInRipple(x, y, {...this.rippleConfig, ...config}); - } - /** Fades out all currently showing ripple elements. */ fadeOutAll() { this._rippleRenderer.fadeOutAll(); @@ -183,5 +178,28 @@ export class MatRipple implements OnInit, OnDestroy, RippleTarget { this._rippleRenderer.setupTriggerEvents(this.trigger); } } + + /** + * Launches a manual ripple using the specified ripple configuration. + * @param config Configuration for the manual ripple. + */ + launch(config: RippleConfig): RippleRef; + + /** + * Launches a manual ripple at the specified coordinates within the element. + * @param x Coordinate within the element, along the X axis at which to fade-in the ripple. + * @param y Coordinate within the element, along the Y axis at which to fade-in the ripple. + * @param config Optional ripple configuration for the manual ripple. + */ + launch(x: number, y: number, config?: RippleConfig): RippleRef; + + /** Launches a manual ripple at the specified coordinated or just by the ripple config. */ + launch(configOrX: number | RippleConfig, y: number = 0, config?: RippleConfig): RippleRef { + if (typeof configOrX === 'number') { + return this._rippleRenderer.fadeInRipple(configOrX, y, {...this.rippleConfig, ...config}); + } else { + return this._rippleRenderer.fadeInRipple(0, 0, {...this.rippleConfig, ...configOrX}); + } + } }