docs: new doc for core directives (#26923)

PR Close #26923
This commit is contained in:
Judy Bogart 2018-11-02 08:52:36 -07:00 committed by Andrew Kushnir
parent 1b97971eb7
commit 9741f5b8cf
1 changed files with 66 additions and 83 deletions

View File

@ -136,6 +136,7 @@ export interface Directive {
* id: string;
*
* ```
*
*/
inputs?: string[];
@ -170,6 +171,7 @@ export interface Directive {
* class MainComponent {
* }
* ```
*
*/
outputs?: string[];
@ -201,6 +203,7 @@ export interface Directive {
* class MainComponent {
* }
* ```
*
*/
exportAs?: string;
@ -436,6 +439,67 @@ export interface ComponentDecorator {
*
* ```
*
* ### Preserving whitespace
*
* Removing whitespace can greatly reduce AOT-generated code size and speed up view creation.
* As of Angular 6, the default for `preserveWhitespaces` is false (whitespace is removed).
* To change the default setting for all components in your application, set
* the `preserveWhitespaces` option of the AOT compiler.
*
* By default, the AOT compiler removes whitespace characters as follows:
* * Trims all whitespaces at the beginning and the end of a template.
* * Removes whitespace-only text nodes. For example,
*
* ```
* <button>Action 1</button> <button>Action 2</button>
* ```
*
* becomes:
*
* ```
* <button>Action 1</button><button>Action 2</button>
* ```
*
* * Replaces a series of whitespace characters in text nodes with a single space.
* For example, `<span>\n some text\n</span>` becomes `<span> some text </span>`.
* * Does NOT alter text nodes inside HTML tags such as `<pre>` or `<textarea>`,
* where whitespace characters are significant.
*
* Note that these transformations can influence DOM nodes layout, although impact
* should be minimal.
*
* You can override the default behavior to preserve whitespace characters
* in certain fragments of a template. For example, you can exclude an entire
* DOM sub-tree by using the `ngPreserveWhitespaces` attribute:
*
* ```html
* <div ngPreserveWhitespaces>
* whitespaces are preserved here
* <span> and here </span>
* </div>
* ```
*
* You can force a single space to be preserved in a text node by using `&ngsp;`,
* which is replaced with a space character by Angular's template
* compiler:
*
* ```html
* <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
* <!-->compiled to be equivalent to:</>
* <a>Spaces</a> <a>between</a> <a>links.</a>
* ```
*
* Note that sequences of `&ngsp;` are still collapsed to just one space character when
* the `preserveWhitespaces` option is set to `false`.
*
* ```html
* <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
* <!-->compiled to be equivalent to:</>
* <a>Spaces</a> <a>between</a> <a>links.</a>
* ```
*
* To preserve sequences of whitespace characters, use the
* `ngPreserveWhitespaces` attribute.
*
* @Annotation
*/
@ -553,89 +617,6 @@ export interface Component extends Directive {
/**
* Component decorator and metadata.
*
* @usageNotes
*
* ### Using animations
*
* The following snippet shows an animation trigger in a component's
* metadata. The trigger is attached to an element in the component's
* template, using "@_trigger_name_", and a state expression that is evaluated
* at run time to determine whether the animation should start.
*
* ```typescript
* @Component({
* selector: 'animation-cmp',
* templateUrl: 'animation-cmp.html',
* animations: [
* trigger('myTriggerName', [
* state('on', style({ opacity: 1 }),
* state('off', style({ opacity: 0 }),
* transition('on => off', [
* animate("1s")
* ])
* ])
* ]
* })
* ```
*
* ```html
* <!-- animation-cmp.html -->
* <div @myTriggerName="expression">...</div>
* ```
*
* ### Preserving whitespace
*
* Removing whitespace can greatly reduce AOT-generated code size, and speed up view creation.
* As of Angular 6, default for `preserveWhitespaces` is false (whitespace is removed).
* To change the default setting for all components in your application, set
* the `preserveWhitespaces` option of the AOT compiler.
*
* Current implementation removes whitespace characters as follows:
* - Trims all whitespaces at the beginning and the end of a template.
* - Removes whitespace-only text nodes. For example,
* `<button>Action 1</button> <button>Action 2</button>` becomes
* `<button>Action 1</button><button>Action 2</button>`.
* - Replaces a series of whitespace characters in text nodes with a single space.
* For example, `<span>\n some text\n</span>` becomes `<span> some text </span>`.
* - Does NOT alter text nodes inside HTML tags such as `<pre>` or `<textarea>`,
* where whitespace characters are significant.
*
* Note that these transformations can influence DOM nodes layout, although impact
* should be minimal.
*
* You can override the default behavior to preserve whitespace characters
* in certain fragments of a template. For example, you can exclude an entire
* DOM sub-tree by using the `ngPreserveWhitespaces` attribute:
*
* ```html
* <div ngPreserveWhitespaces>
* whitespaces are preserved here
* <span> and here </span>
* </div>
* ```
*
* You can force a single space to be preserved in a text node by using `&ngsp;`,
* which is replaced with a space character by Angular's template
* compiler:
*
* ```html
* <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
* <!-->compiled to be equivalent to:</>
* <a>Spaces</a> <a>between</a> <a>links.</a>
* ```
*
* Note that sequences of `&ngsp;` are still collapsed to just one space character when
* the `preserveWhitespaces` option is set to `false`.
*
* ```html
* <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
* <!-->compiled to be equivalent to:</>
* <a>Spaces</a> <a>between</a> <a>links.</a>
* ```
*
* To preserve sequences of whitespace characters, use the
* `ngPreserveWhitespaces` attribute.
*
* @Annotation
* @publicApi
*/
@ -769,6 +750,7 @@ export interface Input {
*
* class App {}
* ```
*
*/
bindingPropertyName?: string;
}
@ -888,6 +870,7 @@ export interface HostBindingDecorator {
* prop;
* }
* ```
*
*/
(hostPropertyName?: string): any;
new (hostPropertyName?: string): any;