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

docs: fix and add decorator api doc (#28986) 

PR Close #28986
This commit is contained in:
Judy Bogart 2019-02-26 08:25:01 -08:00 committed by Andrew Kushnir
parent c5f1d08a43
commit 95989a12dd
5 changed files with 98 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
packages/core/src/di/metadata.ts
View File

@ -237,12 +237,10 @@ export const Host: HostDecorator = makeParamDecorator('Host');
*/
export interface AttributeDecorator {
/**
* Specifies that a constant attribute value should be injected.
*
* The directive can inject constant string literals of host element attributes.
* A parameter decorator for a directive constructor that designates
* a host-element attribute whose value is injected as a constant string literal.
*
* @usageNotes
* ### Example
*
* Suppose we have an `<input>` element and want to know its `type`.
*
@ -250,7 +248,7 @@ export interface AttributeDecorator {
* <input type="text">
* ```
*
* A decorator can inject string literal `text` like so:
* The following example uses the decorator to inject the string literal `text`.
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*
@ -258,20 +256,6 @@ export interface AttributeDecorator {
*
* {@example core/ts/metadata/metadata.ts region='attributeFactory'}
*
* ### Example as ES5 annotation
*
* ```
* var MyComponent = function(title) {
* ...
* };
*
* MyComponent.annotations = [
* new ng.Component({...})
* ]
* MyComponent.parameters = [
* [new ng.Attribute('title')]
* ]
* ```
*/
(name: string): any;
new (name: string): Attribute;
@ -282,7 +266,12 @@ export interface AttributeDecorator {
*
* @publicApi
*/
export interface Attribute { attributeName?: string; }
export interface Attribute {
/**
* The name of the attribute whose value can be injected.
*/
attributeName?: string;
}
/**
* Attribute decorator and metadata.

2
packages/core/src/metadata.ts
View File

@ -22,6 +22,6 @@ export {Attribute} from './di';
export {AfterContentChecked, AfterContentInit, AfterViewChecked, AfterViewInit, DoCheck, OnChanges, OnDestroy, OnInit} from './interface/lifecycle_hooks';
export {ANALYZE_FOR_ENTRY_COMPONENTS, ContentChild, ContentChildDecorator, ContentChildren, ContentChildrenDecorator, Query, ViewChild, ViewChildDecorator, ViewChildren, ViewChildrenDecorator} from './metadata/di';
export {Component, ComponentDecorator, Directive, DirectiveDecorator, HostBinding, HostBindingDecorator, HostListener, HostListenerDecorator, Input, InputDecorator, Output, OutputDecorator, Pipe, PipeDecorator} from './metadata/directives';
export {DoBootstrap, ModuleWithProviders, NgModule} from './metadata/ng_module';
export {DoBootstrap, ModuleWithProviders, NgModule, NgModuleDecorator} from './metadata/ng_module';
export {CUSTOM_ELEMENTS_SCHEMA, NO_ERRORS_SCHEMA, SchemaMetadata} from './metadata/schema';
export {ViewEncapsulation} from './metadata/view';

149
packages/core/src/metadata/directives.ts
View File

@ -317,7 +317,7 @@ export interface ComponentDecorator {
*
* A component must belong to an NgModule in order for it to be available
* to another component or application. To make it a member of an NgModule,
* list it in the `declarations` field of the `@NgModule` metadata.
* list it in the `declarations` field of the `NgModule` metadata.
*
* Note that, in addition to these options for configuring a directive,
* you can control a component's runtime behavior by implementing
@ -443,7 +443,7 @@ export interface ComponentDecorator {
*/
(obj: Component): TypeDecorator;
/**
* See the `@Component` decorator.
* See the `Component` decorator.
*/
new (obj: Component): Component;
}
@ -572,7 +572,22 @@ export const Component: ComponentDecorator = makeDecorator(
*/
export interface PipeDecorator {
/**
* Declares a reusable pipe function, and supplies configuration metadata.
*
* Decorator that marks a class as pipe and supplies configuration metadata.
*
* A pipe class must implement the `PipeTransform` interface.
* For example, if the name is "myPipe", use a template binding expression
* such as the following:
*
* ```
* {{ exp | myPipe }}
* ```
*
* The result of the expression is passed to the pipe's `transform()` method.
*
* A pipe must belong to an NgModule in order for it to be available
* to a template. To make it a member of an NgModule,
* list it in the `declarations` field of the `NgModule` metadata.
*
*/
(obj: Pipe): TypeDecorator;
@ -622,23 +637,48 @@ export const Pipe: PipeDecorator = makeDecorator(
*/
export interface InputDecorator {
/**
* Decorator that marks a class as pipe and supplies configuration metadata.
*
* A pipe class must implement the `PipeTransform` interface.
* For example, if the name is "myPipe", use a template binding expression
* such as the following:
*
* ```
* {{ exp | myPipe }}
* ```
*
* The result of the expression is passed to the pipe's `transform()` method.
*
* A pipe must belong to an NgModule in order for it to be available
* to a template. To make it a member of an NgModule,
* list it in the `declarations` field of the `@NgModule` metadata.
*
*/
* Decorator that marks a class field as an input property and supplies configuration metadata.
* The input property is bound to a DOM property in the template. During change detection,
* Angular automatically updates the data property with the DOM property's value.
*
* @usageNotes
*
* You can supply an optional name to use in templates when the
* component is instantiated, that maps to the
* name of the bound property. By default, the original
* name of the bound property is used for input binding.
*
* The following example creates a component with two input properties,
* one of which is given a special binding name.
*
* ```typescript
* @Component({
* selector: 'bank-account',
* template: `
* Bank Name: {{bankName}}
* Account Id: {{id}}
* `
* })
* class BankAccount {
* // This property is bound using its original name.
* @Input() bankName: string;
* // this property value is bound to a different property name
* // when this component is instantiated in a template.
* @Input('account-id') id: string;
*
* // this property is not bound, and is not automatically updated by Angular
* normalizedBankName: string;
* }
*
* @Component({
* selector: 'app',
* template: `
* <bank-account bankName="RBC" account-id="4747"></bank-account>
* `
* })
* class App {}
* ```
*/
(bindingPropertyName?: string): any;
new (bindingPropertyName?: string): any;
}
@ -650,49 +690,7 @@ export interface InputDecorator {
*/
export interface Input {
/**
* Decorator that marks a class field as an input property and supplies configuration metadata.
* Declares a data-bound input property, which Angular automatically updates
* during change detection.
*
* @usageNotes
*
* You can supply an optional name to use in templates when the
* component is instantiated, that maps to the
* name of the bound property. By default, the original
* name of the bound property is used for input binding.
*
* The following example creates a component with two input properties,
* one of which is given a special binding name.
*
* ```typescript
* @Component({
* selector: 'bank-account',
* template: `
* Bank Name: {{bankName}}
* Account Id: {{id}}
* `
* })
* class BankAccount {
* // This property is bound using its original name.
* @Input() bankName: string;
* // this property value is bound to a different property name
* // when this component is instantiated in a template.
* @Input('account-id') id: string;
*
* // this property is not bound, and is not automatically updated by Angular
* normalizedBankName: string;
* }
*
* @Component({
* selector: 'app',
* template: `
* <bank-account bankName="RBC" account-id="4747"></bank-account>
* `
* })
*
* class App {}
* ```
*
* The name of the DOM property to which the input property is bound.
*/
bindingPropertyName?: string;
}
@ -715,7 +713,7 @@ const initializeBaseDef = (target: any): void => {
};
/**
* Does the work of creating the `ngBaseDef` property for the @Input and @Output decorators.
* Does the work of creating the `ngBaseDef` property for the `Input` and `Output` decorators.
* @param key "inputs" or "outputs"
*/
const updateBaseDefFromIOProp = (getProp: (baseDef: {inputs?: any, outputs?: any}) => any) =>
@ -747,8 +745,7 @@ export const Input: InputDecorator = makePropDecorator(
export interface OutputDecorator {
/**
* Decorator that marks a class field as an output property and supplies configuration metadata.
* Declares a data-bound output property, which Angular automatically updates
* during change detection.
* The DOM property bound to the output property is automatically updated during change detection.
*
* @usageNotes
*
@ -757,7 +754,7 @@ export interface OutputDecorator {
* name of the bound property. By default, the original
* name of the bound property is used for output binding.
*
* See `@Input` decorator for an example of providing a binding name.
* See `Input` decorator for an example of providing a binding name.
*
*/
(bindingPropertyName?: string): any;
@ -769,7 +766,12 @@ export interface OutputDecorator {
*
* @publicApi
*/
export interface Output { bindingPropertyName?: string; }
export interface Output {
/**
* The name of the DOM property to which the output property is bound.
*/
bindingPropertyName?: string;
}
/**
* @Annotation
@ -825,7 +827,12 @@ export interface HostBindingDecorator {
*
* @publicApi
*/
export interface HostBinding { hostPropertyName?: string; }
export interface HostBinding {
/**
* The DOM property that is bound to a data property.
*/
hostPropertyName?: string;
}
/**
* @Annotation
@ -841,6 +848,10 @@ export const HostBinding: HostBindingDecorator =
* @publicApi
*/
export interface HostListenerDecorator {
/**
* Decorator that declares a DOM event to listen for,
* and provides a handler method to run when that event occurs.
*/
(eventName: string, args?: string[]): any;
new (eventName: string, args?: string[]): any;
}

4
packages/core/src/metadata/ng_module.ts
View File

@ -91,10 +91,12 @@ export interface ModuleWithProviders<
/**
* Type of the NgModule decorator / constructor function.
*
* @publicApi
*/
export interface NgModuleDecorator {
/**
* Marks a class as an NgModule and supplies configuration metadata.
* Decorator that marks a class as an NgModule and supplies configuration metadata.
*/
(obj?: NgModule): TypeDecorator;
new (obj?: NgModule): NgModule;

5
tools/public_api_guard/core/core.d.ts vendored
View File

@ -574,6 +574,11 @@ export interface NgModule {
export declare const NgModule: NgModuleDecorator;
export interface NgModuleDecorator {
(obj?: NgModule): TypeDecorator;
new (obj?: NgModule): NgModule;
}
export declare abstract class NgModuleFactory<T> {
abstract readonly moduleType: Type<T>;
abstract create(parentInjector: Injector | null): NgModuleRef<T>;