5 lines
18 KiB
JSON
5 lines
18 KiB
JSON
{
|
|
"id": "guide/attribute-directives",
|
|
"title": "Attribute directives",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/attribute-directives.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"attribute-directives\">Attribute directives<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#attribute-directives\"><i class=\"material-icons\">link</i></a></h1>\n<p>With attribute directives, you can change the appearance or behavior of DOM elements and Angular components.</p>\n<div class=\"alert is-helpful\">\n<p>See the <live-example></live-example> for a working example containing the code snippets in this guide.</p>\n</div>\n<h2 id=\"building-an-attribute-directive\">Building an attribute directive<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#building-an-attribute-directive\"><i class=\"material-icons\">link</i></a></h2>\n<p>This section walks you through creating a highlight directive that sets the background color of the host element to yellow.</p>\n<ol>\n<li>\n<p>To create a directive, use the CLI command <a href=\"cli/generate\"><code>ng generate directive</code></a>.</p>\n <code-example language=\"sh\" class=\"code-shell\">\nng generate directive highlight\n</code-example>\n<p> The CLI creates <code>src/app/highlight.directive.ts</code>, a corresponding test file <code>src/app/highlight.directive.spec.ts</code>, and declares the directive class in the <code>AppModule</code>.</p>\n<p> The CLI generates the default <code>src/app/highlight.directive.ts</code> as follows:</p>\n<p> <code-example path=\"attribute-directives/src/app/highlight.directive.0.ts\" header=\"src/app/highlight.directive.ts\">\nimport { <a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a> } from '@angular/core';\n\n@<a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>({\n selector: '[appHighlight]'\n})\nexport class HighlightDirective {\n constructor() { }\n}\n\n\n</code-example></p>\n<p> The <code>@<a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>()</code> decorator's configuration property specifies the directive's CSS attribute selector, <code>[appHighlight]</code>.</p>\n</li>\n<li>\n<p>Import <code><a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a></code> from <code>@angular/core</code>.\n<code><a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a></code> grants direct access to the host DOM element through its <code>nativeElement</code> property.</p>\n</li>\n<li>\n<p>Add <code><a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a></code> in the directive's <code>constructor()</code> to <a href=\"guide/dependency-injection\">inject</a> a reference to the host DOM element, the element to which you apply <code>appHighlight</code>.</p>\n</li>\n<li>\n<p>Add logic to the <code>HighlightDirective</code> class that sets the background to yellow.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.1.ts\" header=\"src/app/highlight.directive.ts\">\nimport { <a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>, <a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a> } from '@angular/core';\n\n@<a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>({\n selector: '[appHighlight]'\n})\nexport class HighlightDirective {\n constructor(el: <a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a>) {\n el.nativeElement.style.backgroundColor = 'yellow';\n }\n}\n\n\n</code-example>\n</li>\n</ol>\n<div class=\"alert is-helpful\">\n<p> Directives <em>do not</em> support namespaces.</p>\n<p> <code-example path=\"attribute-directives/src/app/app.component.avoid.html\" header=\"src/app/app.component.avoid.html (unsupported)\" region=\"unsupported\">\n<p app:Highlight>This is invalid</p>\n\n</code-example></p>\n</div>\n<a id=\"apply-directive\"></a>\n<h2 id=\"applying-an-attribute-directive\">Applying an attribute directive<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#applying-an-attribute-directive\"><i class=\"material-icons\">link</i></a></h2>\n<ol>\n<li>\n<p>To use the <code>HighlightDirective</code>, add a <code><p></code> element to the HTML template with the directive as an attribute.</p>\n<code-example path=\"attribute-directives/src/app/app.component.1.html\" header=\"src/app/app.component.html\" region=\"applied\">\n<p appHighlight>Highlight me!</p>\n\n</code-example>\n</li>\n</ol>\n<p>Angular creates an instance of the <code>HighlightDirective</code> class and injects a reference to the <code><p></code> element into the directive's constructor, which sets the <code><p></code> element's background style to yellow.</p>\n<a id=\"respond-to-user\"></a>\n<h2 id=\"handling-user-events\">Handling user events<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#handling-user-events\"><i class=\"material-icons\">link</i></a></h2>\n<p>This section shows you how to detect when a user mouses into or out of the element and to respond by setting or clearing the highlight color.</p>\n<ol>\n<li>\n<p>Import <code><a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a></code> from '@angular/core'.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.2.ts\" header=\"src/app/highlight.directive.ts (imports)\" region=\"imports\">\nimport { <a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>, <a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a>, <a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a> } from '@angular/core';\n\n</code-example>\n</li>\n<li>\n<p>Add two event handlers that respond when the mouse enters or leaves, each with the <code>@<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>()</code> decorator.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.2.ts\" header=\"src/app/highlight.directive.ts (mouse-methods)\" region=\"mouse-methods\">\n@<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>('mouseenter') onMouseEnter() {\n this.highlight('yellow');\n}\n\n@<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>('mouseleave') onMouseLeave() {\n this.highlight(null);\n}\n\nprivate highlight(color: string) {\n this.el.nativeElement.style.backgroundColor = color;\n}\n\n</code-example>\n<p>With the <code>@<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>()</code> decorator, you can subscribe to events of the DOM element that hosts an attribute directive, the <code><p></code> in this case.</p>\n<p>The handlers delegate to a helper method, <code>highlight()</code>, that sets the color on the host DOM element, <code>el</code>.</p>\n</li>\n</ol>\n<p>The complete directive is as follows:</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.2.ts\" header=\"src/app/highlight.directive.ts\">\n\n@<a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>({\n selector: '[appHighlight]'\n})\nexport class HighlightDirective {\n\n constructor(private el: <a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a>) { }\n\n @<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>('mouseenter') onMouseEnter() {\n this.highlight('yellow');\n }\n\n @<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>('mouseleave') onMouseLeave() {\n this.highlight(null);\n }\n\n private highlight(color: string) {\n this.el.nativeElement.style.backgroundColor = color;\n }\n\n}\n\n</code-example>\n<p>The background color appears when the pointer hovers over the paragraph element and disappears as the pointer moves out.</p>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/attribute-directives/highlight-directive-anim.gif\" alt=\"Second Highlight\" width=\"204\" height=\"72\">\n</div>\n<a id=\"bindings\"></a>\n<h2 id=\"passing-values-into-an-attribute-directive\">Passing values into an attribute directive<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#passing-values-into-an-attribute-directive\"><i class=\"material-icons\">link</i></a></h2>\n<p>This section walks you through setting the highlight color while applying the <code>HighlightDirective</code>.</p>\n<ol>\n<li>\n<p>In <code>highlight.directive.ts</code>, import <code><a href=\"api/core/Input\" class=\"code-anchor\">Input</a></code> from <code>@angular/core</code>.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.3.ts\" header=\"src/app/highlight.directive.ts (imports)\" region=\"imports\">\nimport { <a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a>, <a href=\"api/core/ElementRef\" class=\"code-anchor\">ElementRef</a>, <a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>, <a href=\"api/core/Input\" class=\"code-anchor\">Input</a> } from '@angular/core';\n\n</code-example>\n</li>\n<li>\n<p>Add an <code>appHighlight</code> <code>@<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>()</code> property.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.3.ts\" header=\"src/app/highlight.directive.ts\" region=\"input\">\n@<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>() appHighlight: string;\n\n</code-example>\n<p>The <code>@<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>()</code> decorator adds metadata to the class that makes the directive's <code>appHighlight</code> property available for binding.</p>\n</li>\n<li>\n<p>In <code>app.component.ts</code>, add a <code>color</code> property to the <code>AppComponent</code>.</p>\n<code-example path=\"attribute-directives/src/app/app.component.1.ts\" header=\"src/app/app.component.ts (class)\" region=\"class\">\nexport class AppComponent {\n color = 'yellow';\n}\n\n\n</code-example>\n</li>\n<li>\n<p>To simultaneously apply the directive and the color, use property binding with the <code>appHighlight</code> directive selector, setting it equal to <code>color</code>.</p>\n<code-example path=\"attribute-directives/src/app/app.component.html\" header=\"src/app/app.component.html (color)\" region=\"color\">\n<p [appHighlight]=\"color\">Highlight me!</p>\n\n</code-example>\n<p>The <code>[appHighlight]</code> attribute binding performs two tasks:</p>\n<ul>\n<li>applies the highlighting directive to the <code><p></code> element</li>\n<li>sets the directive's highlight color with a property binding</li>\n</ul>\n</li>\n</ol>\n<h3 id=\"setting-the-value-with-user-input\">Setting the value with user input<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#setting-the-value-with-user-input\"><i class=\"material-icons\">link</i></a></h3>\n<p>This section guides you through adding radio buttons to bind your color choice to the <code>appHighlight</code> directive.</p>\n<ol>\n<li>\n<p>Add markup to <code>app.component.html</code> for choosing a color as follows:</p>\n<code-example path=\"attribute-directives/src/app/app.component.html\" header=\"src/app/app.component.html (v2)\" region=\"v2\">\n<h1>My First <a href=\"api/core/Attribute\" class=\"code-anchor\">Attribute</a> <a href=\"api/core/Directive\" class=\"code-anchor\">Directive</a></h1>\n\n<h2>Pick a highlight color</h2>\n<div>\n <input type=\"radio\" name=\"colors\" (click)=\"color='lightgreen'\">Green\n <input type=\"radio\" name=\"colors\" (click)=\"color='yellow'\">Yellow\n <input type=\"radio\" name=\"colors\" (click)=\"color='cyan'\">Cyan\n</div>\n<p [appHighlight]=\"color\">Highlight me!</p>\n\n</code-example>\n</li>\n<li>\n<p>Revise the <code>AppComponent.color</code> so that it has no initial value.</p>\n<code-example path=\"attribute-directives/src/app/app.component.ts\" header=\"src/app/app.component.ts (class)\" region=\"class\">\nexport class AppComponent {\n color: string;\n}\n\n\n</code-example>\n</li>\n<li>\n<p>Serve your application to verify that the user can choose the color with the radio buttons.</p>\n<div class=\"lightbox\">\n <img src=\"generated/images/guide/attribute-directives/highlight-directive-v2-anim.gif\" alt=\"Animated gif of the refactored highlight directive changing color according to the radio button the user selects\" width=\"432\" height=\"172\">\n</div>\n</li>\n</ol>\n<a id=\"second-property\"></a>\n<h2 id=\"binding-to-a-second-property\">Binding to a second property<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#binding-to-a-second-property\"><i class=\"material-icons\">link</i></a></h2>\n<p>This section guides you through configuring your application so the developer can set the default color.</p>\n<ol>\n<li>\n<p>Add a second <code><a href=\"api/core/Input\" class=\"code-anchor\">Input</a>()</code> property to <code>HighlightDirective</code> called <code>defaultColor</code>.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.ts\" header=\"src/app/highlight.directive.ts (defaultColor)\" region=\"defaultColor\">\n@<a href=\"api/core/Input\" class=\"code-anchor\">Input</a>() defaultColor: string;\n\n</code-example>\n</li>\n<li>\n<p>Revise the directive's <code>onMouseEnter</code> so that it first tries to highlight with the <code>highlightColor</code>, then with the <code>defaultColor</code>, and falls back to <code>red</code> if both properties are <code>undefined</code>.</p>\n<code-example path=\"attribute-directives/src/app/highlight.directive.ts\" header=\"src/app/highlight.directive.ts (mouse-enter)\" region=\"mouse-enter\">\n@<a href=\"api/core/HostListener\" class=\"code-anchor\">HostListener</a>('mouseenter') onMouseEnter() {\n this.highlight(this.highlightColor || this.defaultColor || 'red');\n}\n\n</code-example>\n</li>\n<li>\n<p>To bind to the <code>AppComponent.color</code> and fall back to \"violet\" as the default color, add the following HTML.\nIn this case, the <code>defaultColor</code> binding doesn't use square brackets, <code>[]</code>, because it is static.</p>\n<code-example path=\"attribute-directives/src/app/app.component.html\" header=\"src/app/app.component.html (defaultColor)\" region=\"defaultColor\">\n<p [appHighlight]=\"color\" defaultColor=\"violet\">\n Highlight me too!\n</p>\n\n</code-example>\n<p>As with components, you can add multiple directive property bindings to a host element.</p>\n</li>\n</ol>\n<p>The default color is red if there is no default color binding.\nWhen the user chooses a color the selected color becomes the active highlight color.</p>\n <div class=\"lightbox\">\n <img src=\"generated/images/guide/attribute-directives/highlight-directive-final-anim.gif\" alt=\"Animated gif of final highlight directive that shows red color with no binding and violet with the default color set. When user selects color, the selection takes precedence.\" width=\"440\" height=\"212\">\n </div>\n<a id=\"ngNonBindable\"></a>\n<h2 id=\"deactivating-angular-processing-with-ngnonbindable\">Deactivating Angular processing with <code>NgNonBindable</code><a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/attribute-directives#deactivating-angular-processing-with-ngnonbindable\"><i class=\"material-icons\">link</i></a></h2>\n<p>To prevent expression evaluation in the browser, add <code>ngNonBindable</code> to the host element.\n<code>ngNonBindable</code> deactivates interpolation, directives, and binding in templates.</p>\n<p>In the following example, the expression <code>{{ 1 + 1 }}</code> renders just as it does in your code editor, and does not display <code>2</code>.</p>\n<code-example path=\"attribute-directives/src/app/app.component.html\" linenums=\"false\" header=\"src/app/app.component.html\" region=\"ngNonBindable\">\n<p>Use ngNonBindable to stop evaluation.</p>\n<p ngNonBindable>This should not evaluate: {{ 1 + 1 }}</p>\n\n</code-example>\n<p>Applying <code>ngNonBindable</code> to an element stops binding for that element's child elements.\nHowever, <code>ngNonBindable</code> still allows directives to work on the element where you apply <code>ngNonBindable</code>.\nIn the following example, the <code>appHighlight</code> directive is still active but Angular does not evaluate the expression <code>{{ 1 + 1 }}</code>.</p>\n<code-example path=\"attribute-directives/src/app/app.component.html\" linenums=\"false\" header=\"src/app/app.component.html\" region=\"ngNonBindable-with-directive\">\n<h3>ngNonBindable with a directive</h3>\n<div ngNonBindable [appHighlight]=\"'yellow'\">This should not evaluate: {{ 1 +1 }}, but will highlight yellow.\n</div>\n\n</code-example>\n<p>If you apply <code>ngNonBindable</code> to a parent element, Angular disables interpolation and binding of any sort, such as property binding or event binding, for the element's children.</p>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/architecture-components\n - guide/bootstrapping\n - guide/built-in-directives\n - guide/dependency-injection-in-action\n - guide/example-apps-list\n - guide/glossary\n-->\n<!-- links from this doc:\n - api/core/Attribute\n - api/core/Directive\n - api/core/ElementRef\n - api/core/HostListener\n - api/core/Input\n - cli/generate\n - guide/attribute-directives#applying-an-attribute-directive\n - guide/attribute-directives#attribute-directives\n - guide/attribute-directives#binding-to-a-second-property\n - guide/attribute-directives#building-an-attribute-directive\n - guide/attribute-directives#deactivating-angular-processing-with-ngnonbindable\n - guide/attribute-directives#handling-user-events\n - guide/attribute-directives#passing-values-into-an-attribute-directive\n - guide/attribute-directives#setting-the-value-with-user-input\n - guide/dependency-injection\n - https://github.com/angular/angular/edit/master/aio/content/guide/attribute-directives.md?message=docs%3A%20describe%20your%20change...\n-->"
|
|
} |