angular-docs-cn/public/docs/ts/latest/cookbook/ts-to-js.jade

include ../../../../_includes/_util-fns

:marked
  Anything you can do with Angular in _TypeScript_, you can also do
  in JavaScript. Translating from one language to the other is mostly a
  matter of changing the way you organize your code and access Angular APIs.

  _TypeScript_ is a popular language option for Angular development. 
  Most code examples on the Internet as well as on this site are written in _TypeScript_. 
  This cookbook contains recipes for translating _TypeScript_
  code examples to _ES6_ and to _ES5_ so that JavaScript developers
  can read and write Angular apps in their preferred dialect.

a#toc
:marked
  ## Table of contents

  [_TypeScript_ to _ES6_ to _ES5_](#from-ts)

  [Modularity: imports and exports](#modularity)

  [Classes and Class Metadata](#class-metadata)
  
  [Input and Output Metadata](#property-metadata)
  
  [Dependency Injection](#dependency-injection)
  
  [Host and Query Metadata](#host-query-metadata)

  [AoT compilation in _TypeScript_ Only](#aot)

  **Run and compare the live <live-example name="cb-ts-to-js">_TypeScript_</live-example> and <live-example name="cb-ts-to-js" lang="js">JavaScript</live-example>
  code shown in this cookbook.**

a#from-ts
.l-main-section
:marked
  ## _TypeScript_ to _ES6_ to _ES5_
  
  _TypeScript_ 
  <a href="https://www._TypeScript_lang.org" target="_blank" title='"TypeScript is a typed, superset of JavaScript"'>is a typed superset of _ES6 JavaScript_</a>.
  &nbsp; _ES6 JavaScript_ is a superset of _ES5 JavaScript_. &nbsp; _ES5_ is the kind of JavaScript that runs natively in all modern browsers.
  The transformation of _TypeScript_ code all the way down to _ES5_ code can be seen as "shedding" features.

  The downgrade progression is
  * _TypeScript_ to _ES6-with-decorators_
  * _ES6-with-decorators_ to _ES6-without-decorators_ ("_plain ES6_")
  * _ES6-without-decorators_ to _ES5_

  When translating from _TypeScript_ to _ES6-with-decorators_, remove 
  [class property access modifiers](http://www._TypeScript_lang.org/docs/handbook/classes.html#public-private-and-protected-modifiers)
  such as `public` and `private`.
  Remove most of the 
  [type annotations](https://www._TypeScript_lang.org/docs/handbook/basic-types.html), 
  such as `string` and `boolean`
  but **keep type annotations used for dependency injection**.
   

  From _ES6-with-decorators_ to _plain ES6_, remove all 
  [decorators](https://www._TypeScript_lang.org/docs/handbook/decorators.html)
  and the remaining type annotations.
  You must declare properties in the class constructor (`this.title = '...'`) rather than in the body of the class.

  Finally, from _plain ES6_ to _ES5_, the main missing features are `import`
  statements and `class` declarations. 

  For _plain ES6_ transpilation you can _start_ with a setup similar to the 
  [_TypeScript_ quickstart](https://github.com/angular/quickstart) and adjust the application code accordingly. 
  Transpile with [Babel](https://babeljs.io/) using the `es2015` preset. 
  To use decorators and annotations with Babel, install the 
  [`angular2`](https://github.com/shuhei/babel-plugin-angular2-annotations) preset as well.
   

a#modularity
.l-main-section
:marked
  ## Importing and Exporting

  ### Importing Angular Code

  In both _TypeScript_ and _ES6_, you import Angular classes, functions, and other members with _ES6_ `import` statements.

  In _ES5_, you access the Angular entities of the [the Angular packages](../glossary.html#!#scoped-package)
  through the global `ng` object. 
  Everything you would have imported from `@angular` is a nested member of this `ng` object:

+makeTabs(`
    cb-ts-to-js/ts/app/main.ts,
    cb-ts-to-js/js-es6-decorators/app/main.es6,
    cb-ts-to-js/js-es6/app/main.es6,
    cb-ts-to-js/js/app/main.js
  `,`
    ng2import,
    ng2import,
    ng2import,
    ng2import
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)

:marked
  ### Exporting Application Code

  Each file in a _TypeScript_ or _ES6_ Angular application constitutes an _ES6_ module.
  When you want to make something available to other modules, you `export` it.

  _ES5_ lacks native support for modules. 
  In an Angular _ES5_ application, you load each file manually by adding a `<script>` tag to `index.html`. 
.alert.is-important
  :marked
    The order of `<script>` tags is often significant. 
    You must load a file that defines a public JavaScript entity before a file that references that entity.
:marked
  The best practice in _ES5_ is to create a form of modularity that avoids polluting the global scope. 
  Add one application namespace object such as `app` to the global `document`.
  Then each code file "exports" public entities by attaching them to that namespace object, e.g., `app.HeroComponent`.
  You could factor a large application into several sub-namespaces 
  which leads to "exports" along the lines of `app.heroes.HeroComponent`.
  
  Every file should wrap _ES5_ code in an 
  [Immediately Invoked Function Expression (IIFE)](https://en.wikipedia.org/wiki/Immediately-invoked_function_expression)
  to limit unintentional leaking of private symbols into the global scope.
  
  Here is a `HeroComponent` as it might be defined and "exported" in each of the four language variants.

+makeTabs(`
    cb-ts-to-js/ts/app/hero.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero.component.es6,
    cb-ts-to-js/js-es6/app/hero.component.es6,
    cb-ts-to-js/js/app/hero.component.js
  `,`
    appexport,
    appexport,
    appexport,
    appexport
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)

:marked
  ### Importing Application Code

  In _TypeScript_ and _ES6_ apps, you `import` things that have been exported from other modules.

  In _ES5_ you use the shared namespace object to access "exported" entities from other files.

+makeTabs(`
    cb-ts-to-js/ts/app/main.ts,
    cb-ts-to-js/js-es6-decorators/app/main.es6,
    cb-ts-to-js/js-es6/app/main.es6,
    cb-ts-to-js/js/app/main.js
  `,`
    appimport,
    appimport,
    appimport,
    appimport
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)(format='.')

.alert.is-helpful
  :marked
    Alternatively, you can use a module loader such as Webpack or
    Browserify in an Angular JavaScript project. In such a project, you would
    use _CommonJS_ modules and the `require` function to load Angular framework code.
    Then use `module.exports` and `require` to export and import application  code.


a#class-metadata
.l-main-section
:marked
  ## Classes and Class Metadata

  ### Classes

  Most Angular _TypeScript_ and _ES6_ code is written as classes.
  In _ES6-without-decorators_, properties of classes must be assigned inside the constructor.

  _ES5_ JavaScript has no classes. 
  Use the constructor function pattern instead, adding methods to the prototype.

+makeTabs(`
    cb-ts-to-js/ts/app/hero.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero.component.es6,
    cb-ts-to-js/js-es6/app/hero.component.es6,
    cb-ts-to-js/js/app/hero.component.js
  `,`
    class,
    class,
    class,
    constructorproto
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)

:marked
  ### Metadata

  When writing in _TypeScript_ or _ES6-with-decorators_, 
  provide configuration and metadata by adorning a class with one or more *decorators*. 
  For example, you supply metadata to a component class by preceding its definition with a
  [`@Component`](../api/core/index/Component-decorator.html) decorator function whose
  argument is an object literal with metadata properties.

  In _plain ES6_, you provide metadata by attaching an `annotations` array to the _class_.
  Each item in the array is a new instance of a metadata decorator created with a similar metadata object literal.
  
  In _ES5_, you also provide an `annotations` array but you attach it to the _constructor function_ rather than to a class.

  See these variations side-by-side:

+makeTabs(`
    cb-ts-to-js/ts/app/hero.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero.component.es6,
    cb-ts-to-js/js-es6/app/hero.component.es6,
    cb-ts-to-js/js/app/hero.component.js
  `,`
    metadata,
    metadata,
    metadata,
    metadata
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)

:marked
  ***External Template file***

  A large component template is often kept in a separate template file.
+makeExample('cb-ts-to-js/ts/app/title.component.html', '', 'app/title.component.html')(format='.')
:marked
  The component (`TitleComponent` in this case) then references the template file in its metadata `templateUrl` property:
+makeTabs(`
  cb-ts-to-js/ts/app/hero-di-inject-additional.component.ts,
  cb-ts-to-js/js-es6-decorators/app/hero-di-inject-additional.component.es6,
  cb-ts-to-js/js-es6/app/hero-di-inject-additional.component.es6,
  cb-ts-to-js/js/app/hero-di-inject-additional.component.js`,
  'metadata, metadata, metadata, metadata',
  `TypeScript,
  ES6 JavaScript with decorators,
  ES6 JavaScript,
  ES5 JavaScript`)(format='.')

:marked
  Note that the _TypeScript_ and both _ES6_ file `templateUrl` properties identify the location of the template file _relative to the component module_.
  All three metadata configurations specify the `moduleId` property 
  so that Angular can calculate the proper module address.
.l-sub-section
  :marked
    The `moduleId` may not be needed with certain tooling but it's safest to provide it anyway.
:marked
  The _ES5_ approach shown here does not support modules and therefore there is no way to calculate a _module-relative URL_.
  The `templateUrl` for the _ES5_ code must specify the _path from the project root_ and 
  omits the irrelevant `moduleId` property. 
  

  ***Angular class API***

  This _ES5_ pattern of creating a constructor and annotating it with metadata is so common that Angular 
  provides a convenience API to make it a little more compact and locates the metadata above the constructor, 
  as you would if you wrote in _TypeScript_ or _ES6-with-decorators_.

  Set a component variable to the result of an `ng.core.Component` function call.
  Pass the same metadata object to `ng.core.Component` as you did before.
  
  Then chain a call to the `Class` method which takes an object defining the class constructor and instance methods.

  Here is an example of the component class API next to the annotated function version for comparison:

+makeTabs(`
    cb-ts-to-js/js/app/hero-dsl.component.js,
    cb-ts-to-js/js/app/hero.component.js
  `,`
    component,
    metadata
  `,`
    ES5 JavaScript with Class API,
    ES5 JavaScript
  `)
:marked
  There are similar APIs for other decorated classes. 
  You can define a directive with `ng.core.Directive`: 

code-example.
  var MyDirective = ng.core.Directive({
    selector: '[myDirective]'
  }).Class({
    ...
  });
:marked
  and a pipe with `ng.core.Pipe`:
code-example.  
  var MyPipe = ng.core.Pipe({
    name: 'myPipe'
  }).Class({
    ...
  });

:marked
  ### Interfaces

  A _TypeScript_ interface helps ensure that a class implements the interface's members correctly.
  We strongly recommend Angular interfaces where appropriate. 
  For example, a component that implements the `ngOnInit` lifecycle hook method
  should implement the `OnInit` interface.

  _TypeScript_ interfaces exist for developer convenience and are not used by Angular at runtime.
  They have no physical manifestation in the generated JavaScript code.
  Just implement the methods and ignore interfaces when translating code samples from _TypeScript_ to JavaScript.

+makeTabs(`
    cb-ts-to-js/ts/app/hero-lifecycle.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero-lifecycle.component.es6,
    cb-ts-to-js/js-es6/app/hero-lifecycle.component.es6,
    cb-ts-to-js/js/app/hero-lifecycle.component.js
  `,`
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)  

a#property-metadata
.l-main-section
:marked
  ## Input and Output Metadata

  ### Input and Output Decorators

  In _TypeScript_ and _ES6-with-decorators_, you often add metadata to class _properties_ with _property decorators_.
  For example, you apply [`@Input` and `@Output` property decorators](../guide/template-syntax.html#inputs-outputs) 
  to public class properties that will be the target of data binding expressions in parent components.

  There is no equivalent of a property decorator in _ES5_ or _plain ES6_. 
  Fortunately, every property decorator has an equivalent representation in a class decorator metadata property.
  A _TypeScript_ `@Input` property decorator can be represented by an item in the `Component` metadata's `inputs` array.
  
  You already know how to add `Component` or `Directive` class metadata in _any_ JavaScript dialect so
  there's nothing fundamentally new about adding another property. 
  But note that what would have been _separate_ `@Input` and `@Output` property decorators for each class property are
  combined in the metadata `inputs` and `outputs` _arrays_.

+makeTabs(`
    cb-ts-to-js/ts/app/hero-io.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero-io.component.es6,
    cb-ts-to-js/js-es6/app/hero-io.component.es6,
    cb-ts-to-js/js/app/hero-io.component.js
  `,`
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)
:marked
  In the previous example, one of the public-facing binding names (`cancelMsg`) 
  differs from the corresponding class property name (`notOkMsg`).
  That's OK but you must tell Angular about it so that it can map an external binding of `cancelMsg`
  to the component's `notOkMsg` property.
  
  In _TypeScript_ and _ES6-with-decorators_, 
  you specify the special binding name in the argument to the property decorator.
  In _ES5_ and _plain ES6_ code, convey this pairing with the `propertyName: bindingName` syntax in the class metadata.
  
.l-main-section
:marked
  ## Dependency Injection

  ### Injection by Type

  Angular can often use _TypeScript_ type information to determine what needs to be injected.
  _ES6-with-decorators_ can also make use of type information.

  Since no type information is available in _ES5_/_ES6_ JavaScript, you must identify "injectables" in 
  some other way.

  Attach a `parameters` array to the constructor function. 
  Each array item is the dependency injection token that identifies the thing to be injected. 
  Often the token is the constructor function for the class-like dependency.
  
  In _ES6_ the decorators need to be inside a nested array.
  When writing in the _ES5_ class convenience API, you can supply the parameter tokens by wrapping 
  the constructor in an array.

+makeTabs(`
    cb-ts-to-js/ts/app/hero-di.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero-di.component.es6,
    cb-ts-to-js/js-es6/app/hero-di.component.es6,
    cb-ts-to-js/js/app/hero-di.component.js,
    cb-ts-to-js/js/app/hero-di-inline.component.js
  `,`
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript,
    ES5 JavaScript with Class API
  `)

:marked
  ### Injection with the @Inject decorator

  When the thing being injected doesn't correspond directly to a type, you use the 
  `@Inject()` decorator to supply the injection token.
  In this example, you are injecting a string identified by the "heroName" token. 

  In _ES5_/_ES6_ JavaScript you add the token string to the injection parameters array.
  Alternatively, when using the _ES5_ convenience class API you can create a token with the 
  `Inject` method and add that to the constructor array in the annotations.

+makeTabs(`
    cb-ts-to-js/ts/app/hero-di-inject.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero-di-inject.component.es6,
    cb-ts-to-js/js-es6/app/hero-di-inject.component.es6,
    cb-ts-to-js/js/app/hero-di-inject.component.js,
    cb-ts-to-js/js/app/hero-di-inject.component.js
  `,`
  ,
  ,
  ,
  parameters,
  ctor
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript,
    ES5 JavaScript with Class API
  `)

:marked
  ### Additional Injection Decorators

  You can attach additional decorators to constructor parameters to qualify the injection behavior. 
  You can mark optional dependencies with the [`@Optional`](../api/core/index/Optional-decorator.html),
  inject host element attributes with [`@Attribute`](../api/core/index/Attribute-interface.html),
  inject content child queries with [`@ContentChild`](../api/core/index/ContentChild-decorator.html)
  and inject view child queries with [`@ViewChild`](../api/core/index/ViewChild-decorator.html)).

  In ES6 JavaScript you just add the extra decorators to the nested injection parameters array.

  To achieve the same effect in _ES5_ JavaScript, use a nested array with the constructor 
  array notation in which the injection information precedes the constructor function itself.
  
  You can apply other additional parameter decorators such as
  [`@Host`](../api/core/index/Host-decorator.html) and
  [`@SkipSelf`](../api/core/index/SkipSelf-decorator.html) in the same way -
  by adding `new ng.core.Host()` or `ng.core.SkipSelf()` in the
  parameters array.
+makeTabs(`
    cb-ts-to-js/ts/app/hero-di-inject-additional.component.ts,
    cb-ts-to-js/js-es6-decorators/app/hero-di-inject-additional.component.es6,
    cb-ts-to-js/js-es6/app/hero-di-inject-additional.component.es6,
    cb-ts-to-js/js/app/hero-di-inject-additional.component.js
  `,`
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)  

a#host-query-metadata
.l-main-section
:marked
  ## Host and Query Metadata

  ### Host Decorators

  In _TypeScript_ and _ES6-with-decorators_ you can use host property decorators to bind a host
  element to a component or directive.
  The [`@HostBinding`](../api/core/index/HostBinding-interface.html) decorator
  binds host element properties to component data properties. 
  The [`@HostListener`](../api/core/index/HostListener-interface.html) decorator binds
  host element events to component event handlers.

  When using _ES5_/_ES6_, add a `host` attribute to the component metadata to achieve the
  same effect as `@HostBinding` and `@HostListener`. 
  
  The  `host` value is an object whose properties are host property and listener bindings:
  
  * Each key follows regular Angular binding syntax: `[property]` for host bindings
    or `(event)` for host listeners.
  * Each value identifies the corresponding component property or method.

+makeTabs(`
    cb-ts-to-js/ts/app/heroes-bindings.component.ts,
    cb-ts-to-js/js-es6-decorators/app/heroes-bindings.component.es6,
    cb-ts-to-js/js-es6/app/heroes-bindings.component.es6,
    cb-ts-to-js/js/app/heroes-bindings.component.js
  `,`
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)
.alert.is-helpful
  :marked
    In _TypeScript_ and _ES6-with-decorators_ you can also use the `queries` metadata 
    instead of the `@ViewChild` and `@ContentChild` property decorators.    

:marked
  ### Query Decorators
  
  There are several property decorators for querying the descendants of
  a component or directive.
  
  The [`@ViewChild`](../api/core/index/ViewChild-decorator.html) and
  [`@ViewChildren`](../api/core/index/ViewChildren-decorator.html) property decorators
  allow a component to query instances of other components that are used in
  its view. 

  In _ES5_/_ES6_ JavaScript you access a component's view children by adding a `queries` attribute to
  the component metadata. It should be an object where:
  
  * Each key is the name of a component property that will hold the view children
  * Each value is an instance of either `ViewChild` or `ViewChildren`.

+makeTabs(`
    cb-ts-to-js/ts/app/heroes-queries.component.ts,
    cb-ts-to-js/js-es6-decorators/app/heroes-queries.component.es6,
    cb-ts-to-js/js-es6/app/heroes-queries.component.es6,
    cb-ts-to-js/js/app/heroes-queries.component.js
  `,`
    view,
    view,
    view,
    view
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)

:marked
  The [`@ContentChild`](../api/core/index/ContentChild-decorator.html) and
  [`@ContentChildren`](../api/core/index/ContentChildren-decorator.html) property decorators
  allow a component to query instances of other components that have been projected
  into its view from elsewhere.

  They can be added in the same way as [`@ViewChild`](../api/core/index/ViewChild-decorator.html) and
  [`@ViewChildren`](../api/core/index/ViewChildren-decorator.html).

+makeTabs(`
    cb-ts-to-js/ts/app/heroes-queries.component.ts,
    cb-ts-to-js/js-es6-decorators/app/heroes-queries.component.es6,
    cb-ts-to-js/js-es6/app/heroes-queries.component.es6,
    cb-ts-to-js/js/app/heroes-queries.component.js
  `,`
    content,
    content,
    content,
    content
  `,`
    TypeScript,
    ES6 JavaScript with decorators,
    ES6 JavaScript,
    ES5 JavaScript
  `)

a#aot
.l-main-section
:marked
  ## AoT Compilation in _TypeScript_ only

  Angular offers two modes of template compilation, JiT (_Just-in-Time_) and 
  [AoT (_Ahead-of-Time_)](aot-compiler.html).
  Currently the AoT compiler only works with _TypeScript_ applications because, in part, it generates
  _TypeScript_ files as an intermediate result.
  **AoT is not an option for pure JavaScript applications** at this time.