docs: traducir AOT compiler (#277)
* translate guide/aot-compiler * fix error in creating libs * fix error w/ anchor link
This commit is contained in:
Nicolas Molina Monroy
GitHub
parent
ebee38994f
commit
a725fe261a
665
aio/content/guide/aot-compile.en.md
Normal file
665
aio/content/guide/aot-compile.en.md
Normal file
@ -0,0 +1,665 @@
|
||||
# Ahead-of-time (AOT) compilation
|
||||
|
||||
An Angular application consists mainly of components and their HTML templates. Because the components and templates provided by Angular cannot be understood by the browser directly, Angular applications require a compilation process before they can run in a browser.
|
||||
|
||||
The Angular [ahead-of-time (AOT) compiler](guide/glossary#aot) converts your Angular HTML and TypeScript code into efficient JavaScript code during the build phase _before_ the browser downloads and runs that code. Compiling your application during the build process provides a faster rendering in the browser.
|
||||
|
||||
This guide explains how to specify metadata and apply available compiler options to compile your applications efficiently using the AOT compiler.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
<a href="https://www.youtube.com/watch?v=anphffaCZrQ">Watch Alex Rickabaugh explain the Angular compiler</a> at AngularConnect 2019.
|
||||
|
||||
</div>
|
||||
|
||||
{@a why-aot}
|
||||
|
||||
Here are some reasons you might want to use AOT.
|
||||
|
||||
* *Faster rendering*
|
||||
With AOT, the browser downloads a pre-compiled version of the application.
|
||||
The browser loads executable code so it can render the application immediately, without waiting to compile the app first.
|
||||
|
||||
* *Fewer asynchronous requests*
|
||||
The compiler _inlines_ external HTML templates and CSS style sheets within the application JavaScript,
|
||||
eliminating separate ajax requests for those source files.
|
||||
|
||||
* *Smaller Angular framework download size*
|
||||
There's no need to download the Angular compiler if the app is already compiled.
|
||||
The compiler is roughly half of Angular itself, so omitting it dramatically reduces the application payload.
|
||||
|
||||
* *Detect template errors earlier*
|
||||
The AOT compiler detects and reports template binding errors during the build step
|
||||
before users can see them.
|
||||
|
||||
* *Better security*
|
||||
AOT compiles HTML templates and components into JavaScript files long before they are served to the client.
|
||||
With no templates to read and no risky client-side HTML or JavaScript evaluation,
|
||||
there are fewer opportunities for injection attacks.
|
||||
|
||||
{@a overview}
|
||||
|
||||
## Choosing a compiler
|
||||
|
||||
Angular offers two ways to compile your application:
|
||||
|
||||
* **_Just-in-Time_ (JIT)**, which compiles your app in the browser at runtime. This was the default until Angular 8.
|
||||
* **_Ahead-of-Time_ (AOT)**, which compiles your app and libraries at build time. This is the default since Angular 9.
|
||||
|
||||
When you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands, the type of compilation (JIT or AOT) depends on the value of the `aot` property in your build configuration specified in `angular.json`. By default, `aot` is set to `true` for new CLI apps.
|
||||
|
||||
See the [CLI command reference](cli) and [Building and serving Angular apps](guide/build) for more information.
|
||||
|
||||
## How AOT works
|
||||
|
||||
The Angular AOT compiler extracts **metadata** to interpret the parts of the application that Angular is supposed to manage.
|
||||
You can specify the metadata explicitly in **decorators** such as `@Component()` and `@Input()`, or implicitly in the constructor declarations of the decorated classes.
|
||||
The metadata tells Angular how to construct instances of your application classes and interact with them at runtime.
|
||||
|
||||
In the following example, the `@Component()` metadata object and the class constructor tell Angular how to create and display an instance of `TypicalComponent`.
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'app-typical',
|
||||
template: '<div>A typical component for {{data.name}}</div>'
|
||||
)}
|
||||
export class TypicalComponent {
|
||||
@Input() data: TypicalData;
|
||||
constructor(private someService: SomeService) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
The Angular compiler extracts the metadata _once_ and generates a _factory_ for `TypicalComponent`.
|
||||
When it needs to create a `TypicalComponent` instance, Angular calls the factory, which produces a new visual element, bound to a new instance of the component class with its injected dependency.
|
||||
|
||||
### Compilation phases
|
||||
|
||||
There are three phases of AOT compilation.
|
||||
* Phase 1 is *code analysis*.
|
||||
In this phase, the TypeScript compiler and *AOT collector* create a representation of the source. The collector does not attempt to interpret the metadata it collects. It represents the metadata as best it can and records errors when it detects a metadata syntax violation.
|
||||
|
||||
* Phase 2 is *code generation*.
|
||||
In this phase, the compiler's `StaticReflector` interprets the metadata collected in phase 1, performs additional validation of the metadata, and throws an error if it detects a metadata restriction violation.
|
||||
|
||||
* Phase 3 is *template type checking*.
|
||||
In this optional phase, the Angular *template compiler* uses the TypeScript compiler to validate the binding expressions in templates. You can enable this phase explicitly by setting the `fullTemplateTypeCheck` configuration option; see [Angular compiler options](guide/angular-compiler-options).
|
||||
|
||||
|
||||
### Metadata restrictions
|
||||
|
||||
You write metadata in a _subset_ of TypeScript that must conform to the following general constraints:
|
||||
|
||||
* Limit [expression syntax](#expression-syntax) to the supported subset of JavaScript.
|
||||
* Only reference exported symbols after [code folding](#code-folding).
|
||||
* Only call [functions supported](#supported-functions) by the compiler.
|
||||
* Decorated and data-bound class members must be public.
|
||||
|
||||
For additional guidelines and instructions on preparing an application for AOT compilation, see [Angular: Writing AOT-friendly applications](https://medium.com/sparkles-blog/angular-writing-aot-friendly-applications-7b64c8afbe3f).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Errors in AOT compilation commonly occur because of metadata that does not conform to the compiler's requirements (as described more fully below).
|
||||
For help in understanding and resolving these problems, see [AOT Metadata Errors](guide/aot-metadata-errors).
|
||||
|
||||
</div>
|
||||
|
||||
### Configuring AOT compilation
|
||||
|
||||
You can provide options in the [TypeScript configuration file](guide/typescript-configuration) that controls the compilation process. See [Angular compiler options](guide/angular-compiler-options) for a complete list of available options.
|
||||
|
||||
## Phase 1: Code analysis
|
||||
|
||||
The TypeScript compiler does some of the analytic work of the first phase. It emits the `.d.ts` _type definition files_ with type information that the AOT compiler needs to generate application code.
|
||||
At the same time, the AOT **collector** analyzes the metadata recorded in the Angular decorators and outputs metadata information in **`.metadata.json`** files, one per `.d.ts` file.
|
||||
|
||||
You can think of `.metadata.json` as a diagram of the overall structure of a decorator's metadata, represented as an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Angular's [schema.ts](https://github.com/angular/angular/blob/master/packages/compiler-cli/src/metadata/schema.ts)
|
||||
describes the JSON format as a collection of TypeScript interfaces.
|
||||
|
||||
</div>
|
||||
|
||||
{@a expression-syntax}
|
||||
### Expression syntax limitations
|
||||
|
||||
The AOT collector only understands a subset of JavaScript.
|
||||
Define metadata objects with the following limited syntax:
|
||||
|
||||
<style>
|
||||
td, th {vertical-align: top}
|
||||
</style>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Syntax</th>
|
||||
<th>Example</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal object </td>
|
||||
<td><code>{cherry: true, apple: true, mincemeat: false}</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal array </td>
|
||||
<td><code>['cherries', 'flour', 'sugar']</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Spread in literal array</td>
|
||||
<td><code>['apples', 'flour', ...the_rest]</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Calls</td>
|
||||
<td><code>bake(ingredients)</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>New</td>
|
||||
<td><code>new Oven()</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Property access</td>
|
||||
<td><code>pie.slice</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Array index</td>
|
||||
<td><code>ingredients[0]</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Identity reference</td>
|
||||
<td><code>Component</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A template string</td>
|
||||
<td><code>`pie is ${multiplier} times better than cake`</code></td>
|
||||
<tr>
|
||||
<td>Literal string</td>
|
||||
<td><code>pi</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal number</td>
|
||||
<td><code>3.14153265</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal boolean</td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal null</td>
|
||||
<td><code>null</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported prefix operator </td>
|
||||
<td><code>!cake</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported binary operator </td>
|
||||
<td><code>a+b</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Conditional operator</td>
|
||||
<td><code>a ? b : c</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Parentheses</td>
|
||||
<td><code>(a+b)</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
If an expression uses unsupported syntax, the collector writes an error node to the `.metadata.json` file.
|
||||
The compiler later reports the error if it needs that piece of metadata to generate the application code.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
If you want `ngc` to report syntax errors immediately rather than produce a `.metadata.json` file with errors, set the `strictMetadataEmit` option in the TypeScript configuration file.
|
||||
|
||||
```
|
||||
"angularCompilerOptions": {
|
||||
...
|
||||
"strictMetadataEmit" : true
|
||||
}
|
||||
```
|
||||
|
||||
Angular libraries have this option to ensure that all Angular `.metadata.json` files are clean and it is a best practice to do the same when building your own libraries.
|
||||
|
||||
</div>
|
||||
|
||||
{@a function-expression}
|
||||
{@a arrow-functions}
|
||||
### No arrow functions
|
||||
|
||||
The AOT compiler does not support [function expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function)
|
||||
and [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), also called _lambda_ functions.
|
||||
|
||||
Consider the following component decorator:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
...
|
||||
providers: [{provide: server, useFactory: () => new Server()}]
|
||||
})
|
||||
```
|
||||
|
||||
The AOT collector does not support the arrow function, `() => new Server()`, in a metadata expression.
|
||||
It generates an error node in place of the function.
|
||||
When the compiler later interprets this node, it reports an error that invites you to turn the arrow function into an _exported function_.
|
||||
|
||||
You can fix the error by converting to this:
|
||||
|
||||
```typescript
|
||||
export function serverFactory() {
|
||||
return new Server();
|
||||
}
|
||||
|
||||
@Component({
|
||||
...
|
||||
providers: [{provide: server, useFactory: serverFactory}]
|
||||
})
|
||||
```
|
||||
|
||||
In version 5 and later, the compiler automatically performs this rewriting while emitting the `.js` file.
|
||||
|
||||
{@a exported-symbols}
|
||||
{@a code-folding}
|
||||
### Code folding
|
||||
|
||||
The compiler can only resolve references to **_exported_** symbols.
|
||||
The collector, however, can evaluate an expression during collection and record the result in the `.metadata.json`, rather than the original expression.
|
||||
This allows you to make limited use of non-exported symbols within expressions.
|
||||
|
||||
For example, the collector can evaluate the expression `1 + 2 + 3 + 4` and replace it with the result, `10`.
|
||||
This process is called _folding_. An expression that can be reduced in this manner is _foldable_.
|
||||
|
||||
{@a var-declaration}
|
||||
The collector can evaluate references to module-local `const` declarations and initialized `var` and `let` declarations, effectively removing them from the `.metadata.json` file.
|
||||
|
||||
Consider the following component definition:
|
||||
|
||||
```typescript
|
||||
const template = '<div>{{hero.name}}</div>';
|
||||
|
||||
@Component({
|
||||
selector: 'app-hero',
|
||||
template: template
|
||||
})
|
||||
export class HeroComponent {
|
||||
@Input() hero: Hero;
|
||||
}
|
||||
```
|
||||
|
||||
The compiler could not refer to the `template` constant because it isn't exported.
|
||||
The collector, however, can fold the `template` constant into the metadata definition by in-lining its contents.
|
||||
The effect is the same as if you had written:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'app-hero',
|
||||
template: '<div>{{hero.name}}</div>'
|
||||
})
|
||||
export class HeroComponent {
|
||||
@Input() hero: Hero;
|
||||
}
|
||||
```
|
||||
|
||||
There is no longer a reference to `template` and, therefore, nothing to trouble the compiler when it later interprets the _collector's_ output in `.metadata.json`.
|
||||
|
||||
You can take this example a step further by including the `template` constant in another expression:
|
||||
|
||||
```typescript
|
||||
const template = '<div>{{hero.name}}</div>';
|
||||
|
||||
@Component({
|
||||
selector: 'app-hero',
|
||||
template: template + '<div>{{hero.title}}</div>'
|
||||
})
|
||||
export class HeroComponent {
|
||||
@Input() hero: Hero;
|
||||
}
|
||||
```
|
||||
|
||||
The collector reduces this expression to its equivalent _folded_ string:
|
||||
|
||||
```
|
||||
'<div>{{hero.name}}</div><div>{{hero.title}}</div>'
|
||||
```
|
||||
|
||||
#### Foldable syntax
|
||||
|
||||
The following table describes which expressions the collector can and cannot fold:
|
||||
|
||||
<style>
|
||||
td, th {vertical-align: top}
|
||||
</style>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Syntax</th>
|
||||
<th>Foldable</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal object </td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal array </td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Spread in literal array</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Calls</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>New</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Property access</td>
|
||||
<td>yes, if target is foldable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Array index</td>
|
||||
<td> yes, if target and index are foldable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Identity reference</td>
|
||||
<td>yes, if it is a reference to a local</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A template with no substitutions</td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A template with substitutions</td>
|
||||
<td>yes, if the substitutions are foldable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal string</td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal number</td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal boolean</td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal null</td>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported prefix operator </td>
|
||||
<td>yes, if operand is foldable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported binary operator </td>
|
||||
<td>yes, if both left and right are foldable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Conditional operator</td>
|
||||
<td>yes, if condition is foldable </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Parentheses</td>
|
||||
<td>yes, if the expression is foldable</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
If an expression is not foldable, the collector writes it to `.metadata.json` as an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) for the compiler to resolve.
|
||||
|
||||
|
||||
## Phase 2: code generation
|
||||
|
||||
The collector makes no attempt to understand the metadata that it collects and outputs to `.metadata.json`.
|
||||
It represents the metadata as best it can and records errors when it detects a metadata syntax violation.
|
||||
It's the compiler's job to interpret the `.metadata.json` in the code generation phase.
|
||||
|
||||
The compiler understands all syntax forms that the collector supports, but it may reject _syntactically_ correct metadata if the _semantics_ violate compiler rules.
|
||||
|
||||
### Public symbols
|
||||
|
||||
The compiler can only reference _exported symbols_.
|
||||
|
||||
* Decorated component class members must be public. You cannot make an `@Input()` property private or protected.
|
||||
* Data bound properties must also be public.
|
||||
|
||||
```typescript
|
||||
// BAD CODE - title is private
|
||||
@Component({
|
||||
selector: 'app-root',
|
||||
template: '<h1>{{title}}</h1>'
|
||||
})
|
||||
export class AppComponent {
|
||||
private title = 'My App'; // Bad
|
||||
}
|
||||
```
|
||||
|
||||
{@a supported-functions}
|
||||
|
||||
### Supported classes and functions
|
||||
|
||||
The collector can represent a function call or object creation with `new` as long as the syntax is valid.
|
||||
The compiler, however, can later refuse to generate a call to a _particular_ function or creation of a _particular_ object.
|
||||
|
||||
The compiler can only create instances of certain classes, supports only core decorators, and only supports calls to macros (functions or static methods) that return expressions.
|
||||
* New instances
|
||||
|
||||
The compiler only allows metadata that create instances of the class `InjectionToken` from `@angular/core`.
|
||||
|
||||
* Supported decorators
|
||||
|
||||
The compiler only supports metadata for the [Angular decorators in the `@angular/core` module](api/core#decorators).
|
||||
|
||||
* Function calls
|
||||
|
||||
Factory functions must be exported, named functions.
|
||||
The AOT compiler does not support lambda expressions ("arrow functions") for factory functions.
|
||||
|
||||
{@a function-calls}
|
||||
### Functions and static method calls
|
||||
|
||||
The collector accepts any function or static method that contains a single `return` statement.
|
||||
The compiler, however, only supports macros in the form of functions or static methods that return an *expression*.
|
||||
|
||||
For example, consider the following function:
|
||||
|
||||
```typescript
|
||||
export function wrapInArray<T>(value: T): T[] {
|
||||
return [value];
|
||||
}
|
||||
```
|
||||
|
||||
You can call the `wrapInArray` in a metadata definition because it returns the value of an expression that conforms to the compiler's restrictive JavaScript subset.
|
||||
|
||||
You might use `wrapInArray()` like this:
|
||||
|
||||
```typescript
|
||||
@NgModule({
|
||||
declarations: wrapInArray(TypicalComponent)
|
||||
})
|
||||
export class TypicalModule {}
|
||||
```
|
||||
|
||||
The compiler treats this usage as if you had written:
|
||||
|
||||
```typescript
|
||||
@NgModule({
|
||||
declarations: [TypicalComponent]
|
||||
})
|
||||
export class TypicalModule {}
|
||||
```
|
||||
The Angular [`RouterModule`](api/router/RouterModule) exports two macro static methods, `forRoot` and `forChild`, to help declare root and child routes.
|
||||
Review the [source code](https://github.com/angular/angular/blob/master/packages/router/src/router_module.ts#L139 "RouterModule.forRoot source code")
|
||||
for these methods to see how macros can simplify configuration of complex [NgModules](guide/ngmodules).
|
||||
|
||||
{@a metadata-rewriting}
|
||||
|
||||
### Metadata rewriting
|
||||
|
||||
The compiler treats object literals containing the fields `useClass`, `useValue`, `useFactory`, and `data` specially, converting the expression initializing one of these fields into an exported variable that replaces the expression.
|
||||
This process of rewriting these expressions removes all the restrictions on what can be in them because
|
||||
the compiler doesn't need to know the expression's value—it just needs to be able to generate a reference to the value.
|
||||
|
||||
You might write something like:
|
||||
|
||||
```typescript
|
||||
class TypicalServer {
|
||||
|
||||
}
|
||||
|
||||
@NgModule({
|
||||
providers: [{provide: SERVER, useFactory: () => TypicalServer}]
|
||||
})
|
||||
export class TypicalModule {}
|
||||
```
|
||||
|
||||
Without rewriting, this would be invalid because lambdas are not supported and `TypicalServer` is not exported.
|
||||
To allow this, the compiler automatically rewrites this to something like:
|
||||
|
||||
```typescript
|
||||
class TypicalServer {
|
||||
|
||||
}
|
||||
|
||||
export const ɵ0 = () => new TypicalServer();
|
||||
|
||||
@NgModule({
|
||||
providers: [{provide: SERVER, useFactory: ɵ0}]
|
||||
})
|
||||
export class TypicalModule {}
|
||||
```
|
||||
|
||||
This allows the compiler to generate a reference to `ɵ0` in the factory without having to know what the value of `ɵ0` contains.
|
||||
|
||||
The compiler does the rewriting during the emit of the `.js` file.
|
||||
It does not, however, rewrite the `.d.ts` file, so TypeScript doesn't recognize it as being an export. and it does not interfere with the ES module's exported API.
|
||||
|
||||
|
||||
{@a binding-expression-validation}
|
||||
|
||||
## Phase 3: Template type checking
|
||||
|
||||
One of the Angular compiler's most helpful features is the ability to type-check expressions within templates, and catch any errors before they cause crashes at runtime.
|
||||
In the template type-checking phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates.
|
||||
|
||||
Enable this phase explicitly by adding the compiler option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's TypeScript configuration file
|
||||
(see [Angular Compiler Options](guide/angular-compiler-options)).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
In [Angular Ivy](guide/ivy), the template type checker has been completely rewritten to be more capable as well as stricter, meaning it can catch a variety of new errors that the previous type checker would not detect.
|
||||
|
||||
As a result, templates that previously compiled under View Engine can fail type checking under Ivy. This can happen because Ivy's stricter checking catches genuine errors, or because application code is not typed correctly, or because the application uses libraries in which typings are inaccurate or not specific enough.
|
||||
|
||||
This stricter type checking is not enabled by default in version 9, but can be enabled by setting the `strictTemplates` configuration option.
|
||||
We do expect to make strict type checking the default in the future.
|
||||
|
||||
For more information about type-checking options, and about improvements to template type checking in version 9 and above, see [Template type checking](guide/template-typecheck).
|
||||
|
||||
</div>
|
||||
|
||||
Template validation produces error messages when a type error is detected in a template binding
|
||||
expression, similar to how type errors are reported by the TypeScript compiler against code in a `.ts`
|
||||
file.
|
||||
|
||||
For example, consider the following component:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '{{person.addresss.street}}'
|
||||
})
|
||||
class MyComponent {
|
||||
person?: Person;
|
||||
}
|
||||
```
|
||||
|
||||
This produces the following error:
|
||||
|
||||
```
|
||||
my.component.ts.MyComponent.html(1,1): : Property 'addresss' does not exist on type 'Person'. Did you mean 'address'?
|
||||
```
|
||||
|
||||
The file name reported in the error message, `my.component.ts.MyComponent.html`, is a synthetic file
|
||||
generated by the template compiler that holds contents of the `MyComponent` class template.
|
||||
The compiler never writes this file to disk.
|
||||
The line and column numbers are relative to the template string in the `@Component` annotation of the class, `MyComponent` in this case.
|
||||
If a component uses `templateUrl` instead of `template`, the errors are reported in the HTML file referenced by the `templateUrl` instead of a synthetic file.
|
||||
|
||||
The error location is the beginning of the text node that contains the interpolation expression with the error.
|
||||
If the error is in an attribute binding such as `[value]="person.address.street"`, the error
|
||||
location is the location of the attribute that contains the error.
|
||||
|
||||
The validation uses the TypeScript type checker and the options supplied to the TypeScript compiler to control how detailed the type validation is.
|
||||
For example, if the `strictTypeChecks` is specified, the error
|
||||
```my.component.ts.MyComponent.html(1,1): : Object is possibly 'undefined'```
|
||||
is reported as well as the above error message.
|
||||
|
||||
### Type narrowing
|
||||
|
||||
The expression used in an `ngIf` directive is used to narrow type unions in the Angular
|
||||
template compiler, the same way the `if` expression does in TypeScript.
|
||||
For example, to avoid `Object is possibly 'undefined'` error in the template above, modify it to only emit the interpolation if the value of `person` is initialized as shown below:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '<span *ngIf="person"> {{person.addresss.street}} </span>'
|
||||
})
|
||||
class MyComponent {
|
||||
person?: Person;
|
||||
}
|
||||
```
|
||||
|
||||
Using `*ngIf` allows the TypeScript compiler to infer that the `person` used in the binding expression will never be `undefined`.
|
||||
|
||||
For more information about input type narrowing, see [Input setter coercion](guide/template-typecheck#input-setter-coercion) and [Improving template type checking for custom directives](guide/structural-directives#directive-type-checks).
|
||||
|
||||
### Non-null type assertion operator
|
||||
|
||||
Use the [non-null type assertion operator](guide/template-expression-operators#non-null-assertion-operator) to suppress the `Object is possibly 'undefined'` error when it is inconvenient to use `*ngIf` or when some constraint in the component ensures that the expression is always non-null when the binding expression is interpolated.
|
||||
|
||||
In the following example, the `person` and `address` properties are always set together, implying that `address` is always non-null if `person` is non-null.
|
||||
There is no convenient way to describe this constraint to TypeScript and the template compiler, but the error is suppressed in the example by using `address!.street`.
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '<span *ngIf="person"> {{person.name}} lives on {{address!.street}} </span>'
|
||||
})
|
||||
class MyComponent {
|
||||
person?: Person;
|
||||
address?: Address;
|
||||
|
||||
setData(person: Person, address: Address) {
|
||||
this.person = person;
|
||||
this.address = address;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The non-null assertion operator should be used sparingly as refactoring of the component might break this constraint.
|
||||
|
||||
In this example it is recommended to include the checking of `address` in the `*ngIf` as shown below:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: 'my-component',
|
||||
template: '<span *ngIf="person && address"> {{person.name}} lives on {{address.street}} </span>'
|
||||
})
|
||||
class MyComponent {
|
||||
person?: Person;
|
||||
address?: Address;
|
||||
|
||||
setData(person: Person, address: Address) {
|
||||
this.person = person;
|
||||
this.address = address;
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,62 +1,59 @@
|
||||
# Ahead-of-time (AOT) compilation
|
||||
# Compilación anticipada (AOT)
|
||||
|
||||
An Angular application consists mainly of components and their HTML templates. Because the components and templates provided by Angular cannot be understood by the browser directly, Angular applications require a compilation process before they can run in a browser.
|
||||
Una aplicación Angular consta principalmente de componentes y sus plantillas HTML. Los componentes y plantillas proporcionados por Angular no pueden ser entendidos por el navegador directamente, las aplicaciones en Angular requieren un proceso de compilación antes de que puedan correr en un navegador.
|
||||
|
||||
The Angular [ahead-of-time (AOT) compiler](guide/glossary#aot) converts your Angular HTML and TypeScript code into efficient JavaScript code during the build phase _before_ the browser downloads and runs that code. Compiling your application during the build process provides a faster rendering in the browser.
|
||||
La [compilación anticipada de Angular (AOT)](guide/glossary#aot) convierte plantillas y código de TypeScript en eficiente código JavaScript durante la fase de construcción _antes_ de que el navegador descargue y corra el código. Compilando tu aplicación durante el proceso de construcción se proporciona una renderización más rápida en el navegador.
|
||||
|
||||
This guide explains how to specify metadata and apply available compiler options to compile your applications efficiently using the AOT compiler.
|
||||
Esta guía explica como especificar metadatos y aplicar las opciones del compilador disponibles para compilar aplicaciones eficientemente usando la compilación anticipada (AOT).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
<a href="https://www.youtube.com/watch?v=anphffaCZrQ">Watch Alex Rickabaugh explain the Angular compiler</a> at AngularConnect 2019.
|
||||
<a href="https://www.youtube.com/watch?v=anphffaCZrQ">Mira a Alex Rickabaugh explicando el compilador de Angular en AngularConnect 2019.
|
||||
|
||||
</div>
|
||||
|
||||
{@a why-aot}
|
||||
|
||||
Here are some reasons you might want to use AOT.
|
||||
Aquí algunas razones por las qué podrías querer usar AOT.
|
||||
|
||||
* *Faster rendering*
|
||||
With AOT, the browser downloads a pre-compiled version of the application.
|
||||
The browser loads executable code so it can render the application immediately, without waiting to compile the app first.
|
||||
* *Renderizado más rápido*
|
||||
Con AOT, el navegador descarga una versión pre compilada de una aplicación.
|
||||
El navegador carga el código ejecutable para que pueda renderizar la aplicación inmediatamente, sin esperar a compilar la aplicación primero.
|
||||
|
||||
* *Fewer asynchronous requests*
|
||||
The compiler _inlines_ external HTML templates and CSS style sheets within the application JavaScript,
|
||||
eliminating separate ajax requests for those source files.
|
||||
* *Menos solicitudes asincrónicas*
|
||||
El compilador _inserta_ plantillas HTML y hojas de estilo CSS externas dentro de la aplicación JavaScript, eliminando solicitudes ajax separadas para esos archivos fuente.
|
||||
|
||||
* *Smaller Angular framework download size*
|
||||
There's no need to download the Angular compiler if the app is already compiled.
|
||||
The compiler is roughly half of Angular itself, so omitting it dramatically reduces the application payload.
|
||||
* *Angular pesa menos*
|
||||
No existe necesidad de incluir el compilador de Angular si la aplicación ya esta compilada.
|
||||
El compilador es aproximadamente la mitad de Angular en si mismo, así que omitíendolo se reduce drásticamente el peso de la aplicación.
|
||||
|
||||
* *Detect template errors earlier*
|
||||
The AOT compiler detects and reports template binding errors during the build step
|
||||
before users can see them.
|
||||
* *Detecte errores en platillas antes*
|
||||
El compilador AOT detecta y reporta errores de enlace de datos en plantillas durante el paso de construcción antes que los usuarios puedan verlos.
|
||||
|
||||
* *Better security*
|
||||
AOT compiles HTML templates and components into JavaScript files long before they are served to the client.
|
||||
With no templates to read and no risky client-side HTML or JavaScript evaluation,
|
||||
there are fewer opportunities for injection attacks.
|
||||
* *Mejor seguridad*
|
||||
AOT compila las plantillas HTML y componentes en archivos JavaScript mucho antes de que se sirvan a el cliente.
|
||||
Sin plantillas para leer y sin evaluaciones de JavaScript o HTML del lado del cliente riesgosas, existen pocas oportunidades para ataques de inyección.
|
||||
|
||||
{@a overview}
|
||||
|
||||
## Choosing a compiler
|
||||
## Eligiendo un compilador.
|
||||
|
||||
Angular offers two ways to compile your application:
|
||||
Angular ofrece dos formas para compilar tu aplicación:
|
||||
|
||||
* **_Just-in-Time_ (JIT)**, which compiles your app in the browser at runtime. This was the default until Angular 8.
|
||||
* **_Ahead-of-Time_ (AOT)**, which compiles your app and libraries at build time. This is the default since Angular 9.
|
||||
* **_Just-in-Time_ (JIT)**, cuando compila tu aplicación en el navegador en tiempo de ejecución. Este fué el modo de compilación por defecto hasta Angular 8.
|
||||
* **_Ahead-of-Time_ (AOT)**, cuando compila tu aplicación y librerías en el tiempo de construcción. Este es el modo de compilación por defecto desde Angular 9.
|
||||
|
||||
When you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands, the type of compilation (JIT or AOT) depends on the value of the `aot` property in your build configuration specified in `angular.json`. By default, `aot` is set to `true` for new CLI apps.
|
||||
Cuando ejecutas los comandos del CLI [`ng build`](cli/build) (solo construcción) o [`ng serve`](cli/serve) (construye y sirve localmente), el tipo de compilación (JIT o AOT) depende del valor de la propiedad `aot` en tu configuración de construcción especificada en el archivo `angular.json`. Por defecto, `aot` esta establecido en `true` para nuevas aplicaciones.
|
||||
|
||||
See the [CLI command reference](cli) and [Building and serving Angular apps](guide/build) for more information.
|
||||
Mira la [referencia de comandos del CLI](cli) y [Construyendo y sirviendo Angular apps](guide/build) para más información.
|
||||
|
||||
## How AOT works
|
||||
## Como funciona AOT
|
||||
|
||||
The Angular AOT compiler extracts **metadata** to interpret the parts of the application that Angular is supposed to manage.
|
||||
You can specify the metadata explicitly in **decorators** such as `@Component()` and `@Input()`, or implicitly in the constructor declarations of the decorated classes.
|
||||
The metadata tells Angular how to construct instances of your application classes and interact with them at runtime.
|
||||
El compilador de Angular AOT extrae **metadatos** para interpretar las partes de la aplicación que se supone que Angular maneja.
|
||||
Puedes especificar los metadatos explícitamente en **decoradores** como `@Component()` y `@Input()`, o implícitamente en las declaraciones del constructor de las clases decoradas.
|
||||
Los metadatos le dicen a Angular como construir instancias de clases e interactuar con ellas en tiempo de ejecución.
|
||||
|
||||
In the following example, the `@Component()` metadata object and the class constructor tell Angular how to create and display an instance of `TypicalComponent`.
|
||||
En el siguiente ejemplo, los metadatos de `@Component()` y el constructor le dicen a Angular como crear y mostrar una instancia de `TypicalComponent`.
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
@ -69,63 +66,63 @@ export class TypicalComponent {
|
||||
}
|
||||
```
|
||||
|
||||
The Angular compiler extracts the metadata _once_ and generates a _factory_ for `TypicalComponent`.
|
||||
When it needs to create a `TypicalComponent` instance, Angular calls the factory, which produces a new visual element, bound to a new instance of the component class with its injected dependency.
|
||||
El compilador de Angular extrae los metadatos _una_ vez y genera una _fabrica_ para `TypicalComponent`.
|
||||
Cuando este necesita crear una instancia de `TypicalComponent`, Angular llama a la fabrica, el cuál produce un nuevo elemento visual, vinculado a una nueva instancia la clase del componente con su dependencia inyectada.
|
||||
|
||||
### Compilation phases
|
||||
### Fases de compilación
|
||||
|
||||
There are three phases of AOT compilation.
|
||||
* Phase 1 is *code analysis*.
|
||||
In this phase, the TypeScript compiler and *AOT collector* create a representation of the source. The collector does not attempt to interpret the metadata it collects. It represents the metadata as best it can and records errors when it detects a metadata syntax violation.
|
||||
Existen tres fases de compilación en AOT.
|
||||
|
||||
* Phase 2 is *code generation*.
|
||||
In this phase, the compiler's `StaticReflector` interprets the metadata collected in phase 1, performs additional validation of the metadata, and throws an error if it detects a metadata restriction violation.
|
||||
* Fase 1: *análisis de código*
|
||||
En esta fase, el compilador de TypeScript y el *recolector AOT* crea una representación de la fuente. El recolector no intenta interpretar los metadatos recopilados. Estos representan los metadatos lo mejor que pueden y registra errores cuando este detecta un violación de sintaxis en los metadatos.
|
||||
|
||||
* Phase 3 is *template type checking*.
|
||||
In this optional phase, the Angular *template compiler* uses the TypeScript compiler to validate the binding expressions in templates. You can enable this phase explicitly by setting the `fullTemplateTypeCheck` configuration option; see [Angular compiler options](guide/angular-compiler-options).
|
||||
* Fase 2: *generación de código*
|
||||
En esta fase, el `StaticReflector` del compilador interpreta los metadatos recolectados en la fase 1, realiza validaciones adicionales de los metadatos y lanza un error si este detecta una violación de la restricción de metadatos.
|
||||
|
||||
* Fase 3: *verificación de tipos en plantillas*
|
||||
Esta fase es opcional, el *compilador de plantillas* de Angular usa el compilador de Typescript para validar las expresiones de enlaces de datos en las plantillas. Puedes habilitar esta fase explícitamente configurando la opción `fullTemplateTypeCheck`; revisa [Opciones del Compilador Angular](guide/angular-compiler-options).
|
||||
|
||||
|
||||
### Metadata restrictions
|
||||
### Restricciones de los metadatos
|
||||
|
||||
You write metadata in a _subset_ of TypeScript that must conform to the following general constraints:
|
||||
Escribe metadatos en un _subconjunto_ de TypeScript que debe cumplir las siguientes restricciones generales:
|
||||
|
||||
* Limit [expression syntax](#expression-syntax) to the supported subset of JavaScript.
|
||||
* Only reference exported symbols after [code folding](#code-folding).
|
||||
* Only call [functions supported](#supported-functions) by the compiler.
|
||||
* Decorated and data-bound class members must be public.
|
||||
* Limita la [sintaxis de expresiones](#expression-syntax) al subconjunto soportado de JavaScript.
|
||||
* Solo haz referencia a los símbolos exportados después del [plegado de código](#code-folding).
|
||||
* Solo llame [funciones compátibles](#supported-functions) por el compilador.
|
||||
* Miembros de clase decorados y con enlaces de datos deben ser públicos.
|
||||
|
||||
For additional guidelines and instructions on preparing an application for AOT compilation, see [Angular: Writing AOT-friendly applications](https://medium.com/sparkles-blog/angular-writing-aot-friendly-applications-7b64c8afbe3f).
|
||||
Para guías e instrucciones adicionales al preparar una aplicación para compilación anticipada (AOT), revise [Angular: Writing AOT-friendly applications](https://medium.com/sparkles-blog/angular-writing-aot-friendly-applications-7b64c8afbe3f).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Errors in AOT compilation commonly occur because of metadata that does not conform to the compiler's requirements (as described more fully below).
|
||||
For help in understanding and resolving these problems, see [AOT Metadata Errors](guide/aot-metadata-errors).
|
||||
Los errores en compilación anticipada (AOT) comúnmente ocurren debido a que los metadatos no se ajustan a los requisitos del compilador (como se describen con más detalle a continuación).
|
||||
Para ayudar a entender y resolver estos problemas, revisa [Errores de metadatos en AOT](guide/aot-metadata-errors).
|
||||
|
||||
</div>
|
||||
|
||||
### Configuring AOT compilation
|
||||
### Configurando la compilación anticipada (AOT).
|
||||
|
||||
You can provide options in the [TypeScript configuration file](guide/typescript-configuration) that controls the compilation process. See [Angular compiler options](guide/angular-compiler-options) for a complete list of available options.
|
||||
Puedes proporcionar opciones en el [archivo de configuración de TypeScript](guide/typescript-configuration) que controlan el proceso de compilación. Revisa [las opciones de compilación de Angular](guide/angular-compiler-options) para una lista completa de opciones disponibles.
|
||||
|
||||
## Phase 1: Code analysis
|
||||
## Fase 1: Análisis de código.
|
||||
|
||||
The TypeScript compiler does some of the analytic work of the first phase. It emits the `.d.ts` _type definition files_ with type information that the AOT compiler needs to generate application code.
|
||||
At the same time, the AOT **collector** analyzes the metadata recorded in the Angular decorators and outputs metadata information in **`.metadata.json`** files, one per `.d.ts` file.
|
||||
El compilador de TypeScript realiza parte del trabajo analítico en la primer fase. Este emite los _archivos de definición de tipos_ `.d.ts` con el tipo de información que el compilador AOT necesita para generar el código de la aplicación.
|
||||
Al mismo tiempo, el **recolector** AOT analiza los metadatos registrados en los decoradores de Angular y genera información de metadatos en archivos **`.metadata.json`**, uno por archivo `.d.ts`.
|
||||
|
||||
You can think of `.metadata.json` as a diagram of the overall structure of a decorator's metadata, represented as an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree).
|
||||
Puedes pensar en `.metadata.json` como un diagrama de la estructura general de los metadatos de un decorador, representados como un [árbol de sintaxis abstracta (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Angular's [schema.ts](https://github.com/angular/angular/blob/master/packages/compiler-cli/src/metadata/schema.ts)
|
||||
describes the JSON format as a collection of TypeScript interfaces.
|
||||
El [schema.ts](https://github.com/angular/angular/blob/master/packages/compiler-cli/src/metadata/schema.ts) de Angular describe el formato JSON como una colección de interfaces de TypeScript.
|
||||
|
||||
</div>
|
||||
|
||||
{@a expression-syntax}
|
||||
### Expression syntax limitations
|
||||
### Limitaciones del sintaxis de expresión.
|
||||
|
||||
The AOT collector only understands a subset of JavaScript.
|
||||
Define metadata objects with the following limited syntax:
|
||||
El recolector de AOT solo entiende un subconjunto de JavaScript.
|
||||
Defina objetos de metadatos con la siguiente sintaxis limitada:
|
||||
|
||||
<style>
|
||||
td, th {vertical-align: top}
|
||||
@ -133,85 +130,84 @@ Define metadata objects with the following limited syntax:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Syntax</th>
|
||||
<th>Example</th>
|
||||
<th>Sintaxis</th>
|
||||
<th>Ejemplo</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal object </td>
|
||||
<td>Objeto literal </td>
|
||||
<td><code>{cherry: true, apple: true, mincemeat: false}</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal array </td>
|
||||
<td>Colección literal </td>
|
||||
<td><code>['cherries', 'flour', 'sugar']</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Spread in literal array</td>
|
||||
<td>Operador spread en colección literal</td>
|
||||
<td><code>['apples', 'flour', ...the_rest]</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Calls</td>
|
||||
<td>Llamadas</td>
|
||||
<td><code>bake(ingredients)</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>New</td>
|
||||
<td>Nuevo</td>
|
||||
<td><code>new Oven()</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Property access</td>
|
||||
<td>Acceso a propiedades</td>
|
||||
<td><code>pie.slice</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Array index</td>
|
||||
<td>Indices de colección</td>
|
||||
<td><code>ingredients[0]</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Identity reference</td>
|
||||
<td>Referencia de identidad</td>
|
||||
<td><code>Component</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A template string</td>
|
||||
<td>Una plantilla de cadena</td>
|
||||
<td><code>`pie is ${multiplier} times better than cake`</code></td>
|
||||
<tr>
|
||||
<td>Literal string</td>
|
||||
<td>Cadena literal</td>
|
||||
<td><code>pi</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal number</td>
|
||||
<td>Numero literal</td>
|
||||
<td><code>3.14153265</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal boolean</td>
|
||||
<td>Booleano literal</td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal null</td>
|
||||
<td>Nulo literal</td>
|
||||
<td><code>null</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported prefix operator </td>
|
||||
<td>Soporte a operador prefijo</td>
|
||||
<td><code>!cake</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported binary operator </td>
|
||||
<td>Soporte a operaciones binarias</td>
|
||||
<td><code>a+b</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Conditional operator</td>
|
||||
<td>Operador condicional</td>
|
||||
<td><code>a ? b : c</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Parentheses</td>
|
||||
<td>Paréntesis</td>
|
||||
<td><code>(a+b)</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
If an expression uses unsupported syntax, the collector writes an error node to the `.metadata.json` file.
|
||||
The compiler later reports the error if it needs that piece of metadata to generate the application code.
|
||||
Si una expresión usa sintaxis no compatible, el recolector escribe un error de nodo en el archivo `.metadata.json`.
|
||||
El compilador luego reporta el error si necesita esa pieza de metadatos para generar el código de la aplicación.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
If you want `ngc` to report syntax errors immediately rather than produce a `.metadata.json` file with errors, set the `strictMetadataEmit` option in the TypeScript configuration file.
|
||||
Si quieres que `ngc` reporte errores de sintaxis inmediatamente en lugar de producir un archivo `.metadata.json` con errores, configurá la opción `strictMetadataEmit` en el archivo de configuración de TypeScript.
|
||||
|
||||
```
|
||||
"angularCompilerOptions": {
|
||||
@ -220,18 +216,17 @@ The compiler later reports the error if it needs that piece of metadata to gener
|
||||
}
|
||||
```
|
||||
|
||||
Angular libraries have this option to ensure that all Angular `.metadata.json` files are clean and it is a best practice to do the same when building your own libraries.
|
||||
Las librerías de Angular tienen esta opción para asegurar que todo los archivos `.metadata.json` están limpios y es una buena practica hacer lo mismo cuando construimos nuestras propias librerías.
|
||||
|
||||
</div>
|
||||
|
||||
{@a function-expression}
|
||||
{@a arrow-functions}
|
||||
### No arrow functions
|
||||
### Sin funciones flecha
|
||||
|
||||
The AOT compiler does not support [function expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function)
|
||||
and [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), also called _lambda_ functions.
|
||||
El compilador AOT no soporta [expresiones de función](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function) y [funciones flecha](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function), tampoco las funciones llamadas _lambda_.
|
||||
|
||||
Consider the following component decorator:
|
||||
Considere el siguiente decorador del componente:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
@ -240,11 +235,11 @@ Consider the following component decorator:
|
||||
})
|
||||
```
|
||||
|
||||
The AOT collector does not support the arrow function, `() => new Server()`, in a metadata expression.
|
||||
It generates an error node in place of the function.
|
||||
When the compiler later interprets this node, it reports an error that invites you to turn the arrow function into an _exported function_.
|
||||
El recolector de AOT no soporta la función tipo flecha, `() => new Server()`, en una expression de los metadatos.
|
||||
Esto genera un error de nodo en lugar de la función.
|
||||
Cuando el compilador posteriormente interpreta este nodo, este reporta un error que invita a convertir la función flecha en una _función exportada_.
|
||||
|
||||
You can fix the error by converting to this:
|
||||
Puedes arreglar este error convirtiendo a esto:
|
||||
|
||||
```typescript
|
||||
export function serverFactory() {
|
||||
@ -257,23 +252,23 @@ export function serverFactory() {
|
||||
})
|
||||
```
|
||||
|
||||
In version 5 and later, the compiler automatically performs this rewriting while emitting the `.js` file.
|
||||
En la version 5 y posterior, el compilador realiza automáticamente esta re escritura mientras emite el archivo `.js`.
|
||||
|
||||
{@a exported-symbols}
|
||||
{@a code-folding}
|
||||
### Code folding
|
||||
### Plegado de código (code folding)
|
||||
|
||||
The compiler can only resolve references to **_exported_** symbols.
|
||||
The collector, however, can evaluate an expression during collection and record the result in the `.metadata.json`, rather than the original expression.
|
||||
This allows you to make limited use of non-exported symbols within expressions.
|
||||
El compilador puede solo resolver referencias a símbolos **_exportados_**.
|
||||
El recolector sin embargo, puede evaluar una expresión durante la recolección y registrar el resultado en el `.metadata.json`, en vez de la expresión original.
|
||||
Esto permite hacer un uso limitado de símbolos no exportados dentro de expresiones.
|
||||
|
||||
For example, the collector can evaluate the expression `1 + 2 + 3 + 4` and replace it with the result, `10`.
|
||||
This process is called _folding_. An expression that can be reduced in this manner is _foldable_.
|
||||
Por ejemplo, el recolector puede evaluar la expresión `1 + 2 + 3 + 4` y remplazarlo con el resultado, `10`.
|
||||
El proceso es llamado _plegado_. Una expresión que puede se reducida de esta manera es _plegable_.
|
||||
|
||||
{@a var-declaration}
|
||||
The collector can evaluate references to module-local `const` declarations and initialized `var` and `let` declarations, effectively removing them from the `.metadata.json` file.
|
||||
El recolector puede evaluar referencias hacia el modulo local, declaraciones `const` e inicializadas en `var` y `let` efectivamente son removidas del archivo `.metadata.json`.
|
||||
|
||||
Consider the following component definition:
|
||||
Considere la siguiente definición del componente:
|
||||
|
||||
```typescript
|
||||
const template = '<div>{{hero.name}}</div>';
|
||||
@ -287,9 +282,9 @@ export class HeroComponent {
|
||||
}
|
||||
```
|
||||
|
||||
The compiler could not refer to the `template` constant because it isn't exported.
|
||||
The collector, however, can fold the `template` constant into the metadata definition by in-lining its contents.
|
||||
The effect is the same as if you had written:
|
||||
El compilador no podría referirse hacia la constante `template` por que esta no ha sido exportada.
|
||||
El recolector sim embargo, puede encontrar la constante `template` dentro de la definición de metadatos insertando su contenido.
|
||||
El efecto es el mismo como si hubieras escrito:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
@ -301,9 +296,9 @@ export class HeroComponent {
|
||||
}
|
||||
```
|
||||
|
||||
There is no longer a reference to `template` and, therefore, nothing to trouble the compiler when it later interprets the _collector's_ output in `.metadata.json`.
|
||||
No hay una referencia a `template` y por lo tanto nada que moleste al compilador cuando posteriormente interprete las salidas del recolector en el archivo `.metadata.json`.
|
||||
|
||||
You can take this example a step further by including the `template` constant in another expression:
|
||||
Puedes tomar este ejemplo un paso más allá para incluir la constante `template` en otra expresión:
|
||||
|
||||
```typescript
|
||||
const template = '<div>{{hero.name}}</div>';
|
||||
@ -317,15 +312,15 @@ export class HeroComponent {
|
||||
}
|
||||
```
|
||||
|
||||
The collector reduces this expression to its equivalent _folded_ string:
|
||||
El recolector reduce esta expresión a su equivalente cadena _plegada_:
|
||||
|
||||
```
|
||||
'<div>{{hero.name}}</div><div>{{hero.title}}</div>'
|
||||
```
|
||||
|
||||
#### Foldable syntax
|
||||
#### Sintaxis plegable
|
||||
|
||||
The following table describes which expressions the collector can and cannot fold:
|
||||
La siguiente tabla describe cuales expresiones el recolector puede y no puede encontrar:
|
||||
|
||||
<style>
|
||||
td, th {vertical-align: top}
|
||||
@ -333,101 +328,101 @@ The following table describes which expressions the collector can and cannot fol
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Syntax</th>
|
||||
<th>Foldable</th>
|
||||
<th>Sintaxis</th>
|
||||
<th>Plegable</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal object </td>
|
||||
<td>yes</td>
|
||||
<td>Objeto literal </td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal array </td>
|
||||
<td>yes</td>
|
||||
<td>Colección literal </td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Spread in literal array</td>
|
||||
<td>Operador spread en colección literal</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Calls</td>
|
||||
<td>Llamadas</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>New</td>
|
||||
<td>Nuevo</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Property access</td>
|
||||
<td>yes, if target is foldable</td>
|
||||
<td>Acceso a propiedades<</td>
|
||||
<td>si, si el objetivo es plegable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Array index</td>
|
||||
<td> yes, if target and index are foldable</td>
|
||||
<td>Indices de colección</td>
|
||||
<td>si, si el objetivo y el indice es plegable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Identity reference</td>
|
||||
<td>yes, if it is a reference to a local</td>
|
||||
<td>Referencia de identidad</td>
|
||||
<td>si, si es una referencia a una local</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A template with no substitutions</td>
|
||||
<td>yes</td>
|
||||
<td>Una plantilla sin sustituciones</td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>A template with substitutions</td>
|
||||
<td>yes, if the substitutions are foldable</td>
|
||||
<td>Una plantilla con sustituciones</td>
|
||||
<td>si, si las sustituciones son plegables</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal string</td>
|
||||
<td>yes</td>
|
||||
<td>Cadena literal</td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal number</td>
|
||||
<td>yes</td>
|
||||
<td>Numero literal</td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal boolean</td>
|
||||
<td>yes</td>
|
||||
<td>Booleano literal</td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Literal null</td>
|
||||
<td>yes</td>
|
||||
<td>Nulo literal</td>
|
||||
<td>si</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported prefix operator </td>
|
||||
<td>yes, if operand is foldable</td>
|
||||
<td>Soporte a operador prefijo </td>
|
||||
<td>si, si el operador es plegable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Supported binary operator </td>
|
||||
<td>yes, if both left and right are foldable</td>
|
||||
<td>Soporte a operador binario </td>
|
||||
<td>si, si ambos tanto el izquierda y derecha con plegables</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Conditional operator</td>
|
||||
<td>yes, if condition is foldable </td>
|
||||
<td>Operador condicional</td>
|
||||
<td>si, si la condición es plegable </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Parentheses</td>
|
||||
<td>yes, if the expression is foldable</td>
|
||||
<td>Paréntesis</td>
|
||||
<td>si, si la expresión es plegable</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
If an expression is not foldable, the collector writes it to `.metadata.json` as an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) for the compiler to resolve.
|
||||
Si es una expresión no plegable, el recolector lo escribe a `.metadata.json` como un [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) para que el compilador lo resuelva.
|
||||
|
||||
|
||||
## Phase 2: code generation
|
||||
## Fase 2: generación de código
|
||||
|
||||
The collector makes no attempt to understand the metadata that it collects and outputs to `.metadata.json`.
|
||||
It represents the metadata as best it can and records errors when it detects a metadata syntax violation.
|
||||
It's the compiler's job to interpret the `.metadata.json` in the code generation phase.
|
||||
El recolector no hace ningún intento para entender los metadatos que se recolectarón y las envía a `.metadata.json`.
|
||||
Esto representa los metadatos lo mejor que puede y registra errores cuando detecta una violación de sintaxis en los metadatos.
|
||||
Es el trabajo del compilador interpretar el `.metadata.json` en la fase de generación de código.
|
||||
|
||||
The compiler understands all syntax forms that the collector supports, but it may reject _syntactically_ correct metadata if the _semantics_ violate compiler rules.
|
||||
El compilador entiende toda las formas de sintaxis que el recolector soporta pero puede rechazar metadatos _sintácticamente_ correctos si la _semántica_ viola reglas del compilador.
|
||||
|
||||
### Public symbols
|
||||
### Símbolos públicos
|
||||
|
||||
The compiler can only reference _exported symbols_.
|
||||
El compilador puede solo referirse a _símbolos exportados_.
|
||||
|
||||
* Decorated component class members must be public. You cannot make an `@Input()` property private or protected.
|
||||
* Data bound properties must also be public.
|
||||
* Los atributos de la clase que tienen un decorador deben ser públicos. No puedes hacer que una propiedad `@Input()` sea privada o protegida.
|
||||
* Las propiedades enlazadas a datos también deben ser publicas.
|
||||
|
||||
```typescript
|
||||
// BAD CODE - title is private
|
||||
@ -442,32 +437,32 @@ export class AppComponent {
|
||||
|
||||
{@a supported-functions}
|
||||
|
||||
### Supported classes and functions
|
||||
### Clases y funciones compatibles
|
||||
|
||||
The collector can represent a function call or object creation with `new` as long as the syntax is valid.
|
||||
The compiler, however, can later refuse to generate a call to a _particular_ function or creation of a _particular_ object.
|
||||
El recolector puede representar una función o la creación de un objeto con `new` mientras la sintaxis sea valida.
|
||||
El compilador, sin embargo, puede posteriormente rechazar a generar una llamada hacia una función _particular_ o la creación de un objeto _particular_.
|
||||
|
||||
The compiler can only create instances of certain classes, supports only core decorators, and only supports calls to macros (functions or static methods) that return expressions.
|
||||
* New instances
|
||||
El compilador puede solo crea instancias de ciertas clases, compatibles solo con decoradores centrales y solo compatibles con llamadas a macros (funciones o métodos estáticos) que retornan expresiones.
|
||||
|
||||
The compiler only allows metadata that create instances of the class `InjectionToken` from `@angular/core`.
|
||||
* Nuevas instancias
|
||||
El compilador solo permite metadatos que crean instancias de las clases `InjectionToken` de `@angular/core`.
|
||||
|
||||
* Supported decorators
|
||||
* Decoradores soportados
|
||||
El compilador solo soporta metadatos del [Modulo de decoradores de Angular en `@angular/core`](api/core#decorators).
|
||||
|
||||
The compiler only supports metadata for the [Angular decorators in the `@angular/core` module](api/core#decorators).
|
||||
* Llamadas a funciones
|
||||
|
||||
* Function calls
|
||||
|
||||
Factory functions must be exported, named functions.
|
||||
The AOT compiler does not support lambda expressions ("arrow functions") for factory functions.
|
||||
Las funciones de fabrica deben ser exportadas.
|
||||
El compilador AOT no soporta expresiones lambda ("funciones flecha") para las funciones de fabrica.
|
||||
|
||||
{@a function-calls}
|
||||
### Functions and static method calls
|
||||
|
||||
The collector accepts any function or static method that contains a single `return` statement.
|
||||
The compiler, however, only supports macros in the form of functions or static methods that return an *expression*.
|
||||
### Llamadas a funciones y métodos estáticos.
|
||||
|
||||
For example, consider the following function:
|
||||
El recolector acepta cualquier función o método estático que contenga una sola declaración de `return`.
|
||||
El compilador sin embargo, solo soporta macros (funciones o métodos estáticos) en la forma de funciones y métodos estáticos que retornan una *expression*.
|
||||
|
||||
Por ejemplo, considere la siguiente función:
|
||||
|
||||
```typescript
|
||||
export function wrapInArray<T>(value: T): T[] {
|
||||
@ -475,9 +470,9 @@ export function wrapInArray<T>(value: T): T[] {
|
||||
}
|
||||
```
|
||||
|
||||
You can call the `wrapInArray` in a metadata definition because it returns the value of an expression that conforms to the compiler's restrictive JavaScript subset.
|
||||
Puedes llamar a `wrapInArray` en una definición de metadatos porque este retorna el valor de una expresiones qué se ajusta al subconjunto de Javascript restringido del compilador.
|
||||
|
||||
You might use `wrapInArray()` like this:
|
||||
Puede usar `wrapInArray()` así:
|
||||
|
||||
```typescript
|
||||
@NgModule({
|
||||
@ -486,7 +481,7 @@ You might use `wrapInArray()` like this:
|
||||
export class TypicalModule {}
|
||||
```
|
||||
|
||||
The compiler treats this usage as if you had written:
|
||||
El compilador trata este uso como si hubieras escrito:
|
||||
|
||||
```typescript
|
||||
@NgModule({
|
||||
@ -494,19 +489,19 @@ The compiler treats this usage as if you had written:
|
||||
})
|
||||
export class TypicalModule {}
|
||||
```
|
||||
The Angular [`RouterModule`](api/router/RouterModule) exports two macro static methods, `forRoot` and `forChild`, to help declare root and child routes.
|
||||
Review the [source code](https://github.com/angular/angular/blob/master/packages/router/src/router_module.ts#L139 "RouterModule.forRoot source code")
|
||||
for these methods to see how macros can simplify configuration of complex [NgModules](guide/ngmodules).
|
||||
|
||||
El [`RouterModule`](api/router/RouterModule) de Angular exporta dos métodos estáticos, `forRoot` y `forChild` para ayudar a declarar rutas raíz e hijas.
|
||||
Revisa el [código fuente](https://github.com/angular/angular/blob/master/packages/router/src/router_module.ts#L139 "RouterModule.forRoot source code") para estos métodos para ver como los macros puede simplificar la configuración de complejos [NgModules](guide/ngmodules).
|
||||
|
||||
{@a metadata-rewriting}
|
||||
|
||||
### Metadata rewriting
|
||||
### Re escribiendo metadatos
|
||||
|
||||
The compiler treats object literals containing the fields `useClass`, `useValue`, `useFactory`, and `data` specially, converting the expression initializing one of these fields into an exported variable that replaces the expression.
|
||||
This process of rewriting these expressions removes all the restrictions on what can be in them because
|
||||
the compiler doesn't need to know the expression's value—it just needs to be able to generate a reference to the value.
|
||||
El compilador trata a los objetos literales que contengan los campos `useClass`, `useValue`, `useFactory` y `data` específicamente, convirtiendo la expresión inicializando uno de estos campos en una variable exportada que reemplaza la expresión
|
||||
|
||||
You might write something like:
|
||||
Este proceso de rescribir estas expresiones remueve todo las restricciones que pueden estar en el, porque el compilador no necesita conocer el valor de las expresiones solo necesita poder generar una referencia al valor.
|
||||
|
||||
Puedes escribir algo como:
|
||||
|
||||
```typescript
|
||||
class TypicalServer {
|
||||
@ -519,8 +514,8 @@ class TypicalServer {
|
||||
export class TypicalModule {}
|
||||
```
|
||||
|
||||
Without rewriting, this would be invalid because lambdas are not supported and `TypicalServer` is not exported.
|
||||
To allow this, the compiler automatically rewrites this to something like:
|
||||
Sin la reescritura, esto sería invalido por que las lambdas no son soportadas y `TypicalServer` no esta exportada.
|
||||
Para permitirlo, el compilador automáticamente re escribe esto a algo como:
|
||||
|
||||
```typescript
|
||||
class TypicalServer {
|
||||
@ -535,40 +530,38 @@ export const ɵ0 = () => new TypicalServer();
|
||||
export class TypicalModule {}
|
||||
```
|
||||
|
||||
This allows the compiler to generate a reference to `ɵ0` in the factory without having to know what the value of `ɵ0` contains.
|
||||
Esto permite que el compilador genere una referencia hacia `ɵ0` en la fabrica sin tener que conocer cual es el valor de `ɵ0`.
|
||||
|
||||
The compiler does the rewriting during the emit of the `.js` file.
|
||||
It does not, however, rewrite the `.d.ts` file, so TypeScript doesn't recognize it as being an export. and it does not interfere with the ES module's exported API.
|
||||
El compilador hace la reescritura durante la emisión de el archivo `.js`.
|
||||
Sin embargo, no reescribe el archivo `.d.ts`, entonces TypeScript no lo reconoce como una exportación y esto no interfiere con la API exportada de los módulos ES.
|
||||
|
||||
|
||||
{@a binding-expression-validation}
|
||||
|
||||
## Phase 3: Template type checking
|
||||
## Fase 3: Verificación de tipos en las plantillas
|
||||
|
||||
One of the Angular compiler's most helpful features is the ability to type-check expressions within templates, and catch any errors before they cause crashes at runtime.
|
||||
In the template type-checking phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates.
|
||||
Una de las características más útiles del compilador de Angular es la habilidad de comprobar el tipado de las expresiones dentro de las plantillas y capturar cualquier error antes de que ellos causen fallas en tiempo de ejecución.
|
||||
|
||||
Enable this phase explicitly by adding the compiler option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's TypeScript configuration file
|
||||
(see [Angular Compiler Options](guide/angular-compiler-options)).
|
||||
En la fase de verificación de tipos en las plantillas, el compilador de plantillas de Angular usa a el compilador de TypeScript para validar las expresiones con enlazadas a datos en las plantillas.
|
||||
|
||||
Habilite esta fase explícitamente agregando la opción del compilador `"fullTemplateTypeCheck"` en las `"angularCompilerOptions"` del archivo de configuración del proyecto TypeScript (mira [Opciones del compilador de Angular](guide/angular-compiler-options)).
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
In [Angular Ivy](guide/ivy), the template type checker has been completely rewritten to be more capable as well as stricter, meaning it can catch a variety of new errors that the previous type checker would not detect.
|
||||
En [Angular Ivy](guide/ivy), la verificación de tipos para las plantillas a sido completamente reescrita para ser más capaz así como más estricto, esto significa poder capturar una variedad de nuevos errores que antes el verificador de tipos no podia detectar.
|
||||
|
||||
As a result, templates that previously compiled under View Engine can fail type checking under Ivy. This can happen because Ivy's stricter checking catches genuine errors, or because application code is not typed correctly, or because the application uses libraries in which typings are inaccurate or not specific enough.
|
||||
Como resultado, las plantillas que previamente se compilarón bajo `View Engine` pueden fallar con el verificador de tipos bajo `Ivy`. Esto puede pasar por que el verificador de Ivy captura errores genuinos o porque el código de la aplicación no esta tipado correctamente o porque la aplicación usa librerías en las cuales el tipado es incorrecto o no es lo suficientemente especifico.
|
||||
|
||||
This stricter type checking is not enabled by default in version 9, but can be enabled by setting the `strictTemplates` configuration option.
|
||||
We do expect to make strict type checking the default in the future.
|
||||
Este verificador de tipos estricto no esta habilitado por defecto el la version 9 pero puedes habilitarlo configurando la opción `strictTemplates`.
|
||||
Nosotros esperamos hacer que el verificador de tipos estricto este habilitado por defecto en el futuro.
|
||||
|
||||
For more information about type-checking options, and about improvements to template type checking in version 9 and above, see [Template type checking](guide/template-typecheck).
|
||||
Para más información acerca de las opciones del verificador de tipos y más acerca de mejoras hacia la verificación de tipos en plantillas en la version 9 en adelante, mira [Verificando tipos en plantillas](guide/template-typecheck).
|
||||
|
||||
</div>
|
||||
|
||||
Template validation produces error messages when a type error is detected in a template binding
|
||||
expression, similar to how type errors are reported by the TypeScript compiler against code in a `.ts`
|
||||
file.
|
||||
La validación de templates produce mensajes de error cuando un error de tipo es detectado en una plantilla con una expresión con enlace de datos, similar a como los errores de tipado son reportados por el compilador de TypeScript contra el código en un archivo `.ts`.
|
||||
|
||||
For example, consider the following component:
|
||||
Por ejemplo, considere el siguiente componente:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
@ -580,32 +573,29 @@ For example, consider the following component:
|
||||
}
|
||||
```
|
||||
|
||||
This produces the following error:
|
||||
Esto produce el siguiente error:
|
||||
|
||||
```
|
||||
my.component.ts.MyComponent.html(1,1): : Property 'addresss' does not exist on type 'Person'. Did you mean 'address'?
|
||||
```
|
||||
|
||||
The file name reported in the error message, `my.component.ts.MyComponent.html`, is a synthetic file
|
||||
generated by the template compiler that holds contents of the `MyComponent` class template.
|
||||
The compiler never writes this file to disk.
|
||||
The line and column numbers are relative to the template string in the `@Component` annotation of the class, `MyComponent` in this case.
|
||||
If a component uses `templateUrl` instead of `template`, the errors are reported in the HTML file referenced by the `templateUrl` instead of a synthetic file.
|
||||
El archivo reporta el mensaje de error, `my.component.ts.MyComponent.html`, es un archivo sintético generado por el compilador de plantillas que espera que tenga contenido de la clase `MyComponent`.
|
||||
El compilador nunca escribe un archivo en el disco.
|
||||
Los números de línea y columna son relativos a la plantilla de cadena en el anotación `@Component` de la clase, `MyComponent` en este caso.
|
||||
Si un componente usa `templateUrl` en vez de `template`, los errores son reportados en el archivo HTML referenciado por el `templateUrl` en vez de un archivo sintético.
|
||||
|
||||
The error location is the beginning of the text node that contains the interpolation expression with the error.
|
||||
If the error is in an attribute binding such as `[value]="person.address.street"`, the error
|
||||
location is the location of the attribute that contains the error.
|
||||
La ubicación del error esta en el inicio del nodo de texto que contiene la expresión interpolada con el error.
|
||||
Si el error esta en un atributo con enlace de datos como `[value]="person.address.street"`, la ubicación del error es la ubicación del atributo que contiene el error.
|
||||
|
||||
La validación usa el verificador de tipos de TypeScript y las opciones suministradas hacia el compilador de TypeScript para controlar qué tan detallada es la validación de tipos.
|
||||
Por ejemplo, si el `strictTypeChecks` es especificado, el error ```my.component.ts.MyComponent.html(1,1): : Object is possibly 'undefined'``` es reportado así como el mensaje de error anterior.
|
||||
|
||||
The validation uses the TypeScript type checker and the options supplied to the TypeScript compiler to control how detailed the type validation is.
|
||||
For example, if the `strictTypeChecks` is specified, the error
|
||||
```my.component.ts.MyComponent.html(1,1): : Object is possibly 'undefined'```
|
||||
is reported as well as the above error message.
|
||||
|
||||
### Type narrowing
|
||||
|
||||
The expression used in an `ngIf` directive is used to narrow type unions in the Angular
|
||||
template compiler, the same way the `if` expression does in TypeScript.
|
||||
For example, to avoid `Object is possibly 'undefined'` error in the template above, modify it to only emit the interpolation if the value of `person` is initialized as shown below:
|
||||
La expresión usada en un directiva `ngIf` es usada para estrechar uniones de tipo en el compilador de plantillas de Angular, de la misma manera que la expresión `if` lo hace en TypeScript.
|
||||
Por ejemplo, para evitar el error `Object is possibly 'undefined'` en la plantilla de arriba, modifícalo para que solo emita la interpolación si el valor de `person` esta inicializado como se muestra en seguida:
|
||||
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
@ -617,16 +607,17 @@ For example, to avoid `Object is possibly 'undefined'` error in the template abo
|
||||
}
|
||||
```
|
||||
|
||||
Using `*ngIf` allows the TypeScript compiler to infer that the `person` used in the binding expression will never be `undefined`.
|
||||
Usando `*ngIf` permite que el compilador de TypeScript infiera que el atributo `person` usado en la expresión enlanzada nunca séra `undefined`.
|
||||
|
||||
For more information about input type narrowing, see [Input setter coercion](guide/template-typecheck#input-setter-coercion) and [Improving template type checking for custom directives](guide/structural-directives#directive-type-checks).
|
||||
Para más información acerca del estrechamiento de tipos de entrada, mira [Coerción del establecedor de entrada](guide/template-typecheck#input-setter-coercion) y [Mejorando el verificar de tipos para directivas personalizadas](guide/structural-directives#directive-type-checks).
|
||||
|
||||
### Non-null type assertion operator
|
||||
### Operador de aserción de tipo nulo
|
||||
|
||||
Use the [non-null type assertion operator](guide/template-expression-operators#non-null-assertion-operator) to suppress the `Object is possibly 'undefined'` error when it is inconvenient to use `*ngIf` or when some constraint in the component ensures that the expression is always non-null when the binding expression is interpolated.
|
||||
Use el [operador de aserción de tipo nulo](guide/template-expression-operators#non-null-assertion-operator) para reprimir el error `Object is possibly 'undefined'` cuando es inconveniente usar `*ngIf` o cuando alguna restricción en el componente asegura que la expresión siempre es no nula cuando la expresión con enlace de datos es interpolada.
|
||||
|
||||
En el siguiente ejemplo, las propiedades `person` y `address` son siempre configuradas juntas, implicando que `address` siempre es no nula si `person` es no nula.
|
||||
No existe una forma conveniente de describir esta restricción a TypeScript y a el compilador de plantillas pero el error es suprimido en el ejemplo por usar `address!.street`.
|
||||
|
||||
In the following example, the `person` and `address` properties are always set together, implying that `address` is always non-null if `person` is non-null.
|
||||
There is no convenient way to describe this constraint to TypeScript and the template compiler, but the error is suppressed in the example by using `address!.street`.
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
@ -644,9 +635,9 @@ There is no convenient way to describe this constraint to TypeScript and the tem
|
||||
}
|
||||
```
|
||||
|
||||
The non-null assertion operator should be used sparingly as refactoring of the component might break this constraint.
|
||||
El operador de aserción de tipo nulo debería usarse con moderación ya que la refactorización del componente podría romper esta restricción.
|
||||
|
||||
In this example it is recommended to include the checking of `address` in the `*ngIf` as shown below:
|
||||
En este ejemplo es recomendable incluir la verificación de `address` en el `*ngIf` como se muestra a continuación:
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
|
||||
245
aio/content/guide/creating-libraries.en.md
Normal file
245
aio/content/guide/creating-libraries.en.md
Normal file
@ -0,0 +1,245 @@
|
||||
# Creating libraries
|
||||
|
||||
This page provides a conceptual overview of how you can create and publish new libraries to extend Angular functionality.
|
||||
|
||||
If you find that you need to solve the same problem in more than one app (or want to share your solution with other developers), you have a candidate for a library.
|
||||
A simple example might be a button that sends users to your company website, that would be included in all apps that your company builds.
|
||||
|
||||
## Getting started
|
||||
|
||||
Use the Angular CLI to generate a new library skeleton in a new workspace with the following commands.
|
||||
|
||||
<code-example language="bash">
|
||||
ng new my-workspace --create-application=false
|
||||
cd my-workspace
|
||||
ng generate library my-lib
|
||||
</code-example>
|
||||
|
||||
The `ng generate` command creates the `projects/my-lib` folder in your workspace, which contains a component and a service inside an NgModule.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
For more details on how a library project is structured, refer to the [Library project files](guide/file-structure#library-project-files) section of the [Project File Structure guide](guide/file-structure).
|
||||
|
||||
You can use the monorepo model to use the same workspace for multiple projects.
|
||||
See [Setting up for a multi-project workspace](guide/file-structure#multiple-projects).
|
||||
|
||||
</div>
|
||||
|
||||
When you generate a new library, the workspace configuration file, `angular.json`, is updated with a project of type 'library'.
|
||||
|
||||
<code-example format="json">
|
||||
"projects": {
|
||||
...
|
||||
"my-lib": {
|
||||
"root": "projects/my-lib",
|
||||
"sourceRoot": "projects/my-lib/src",
|
||||
"projectType": "library",
|
||||
"prefix": "lib",
|
||||
"architect": {
|
||||
"build": {
|
||||
"builder": "@angular-devkit/build-ng-packagr:build",
|
||||
...
|
||||
</code-example>
|
||||
|
||||
You can build, test, and lint the project with CLI commands:
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib
|
||||
ng test my-lib
|
||||
ng lint my-lib
|
||||
</code-example>
|
||||
|
||||
Notice that the configured builder for the project is different from the default builder for app projects.
|
||||
This builder, among other things, ensures that the library is always built with the [AOT compiler](guide/aot-compiler), without the need to specify the `--prod` flag.
|
||||
|
||||
To make library code reusable you must define a public API for it. This "user layer" defines what is available to consumers of your library. A user of your library should be able to access public functionality (such as NgModules, service providers and general utility functions) through a single import path.
|
||||
|
||||
The public API for your library is maintained in the `public-api.ts` file in your library folder.
|
||||
Anything exported from this file is made public when your library is imported into an application.
|
||||
Use an NgModule to expose services and components.
|
||||
|
||||
Your library should supply documentation (typically a README file) for installation and maintenance.
|
||||
|
||||
## Refactoring parts of an app into a library
|
||||
|
||||
To make your solution reusable, you need to adjust it so that it does not depend on app-specific code.
|
||||
Here are some things to consider in migrating application functionality to a library.
|
||||
|
||||
* Declarations such as components and pipes should be designed as stateless, meaning they don’t rely on or alter external variables. If you do rely on state, you need to evaluate every case and decide whether it is application state or state that the library would manage.
|
||||
|
||||
* Any observables that the components subscribe to internally should be cleaned up and disposed of during the lifecycle of those components.
|
||||
|
||||
* Components should expose their interactions through inputs for providing context, and outputs for communicating events to other components.
|
||||
|
||||
* Check all internal dependencies.
|
||||
* For custom classes or interfaces used in components or service, check whether they depend on additional classes or interfaces that also need to be migrated.
|
||||
* Similarly, if your library code depends on a service, that service needs to be migrated.
|
||||
* If your library code or its templates depend on other libraries (such as Angular Material, for instance), you must configure your library with those dependencies.
|
||||
|
||||
* Consider how you provide services to client applications.
|
||||
|
||||
* Services should declare their own providers (rather than declaring providers in the NgModule or a component), so that they are *tree-shakable*. This allows the compiler to leave the service out of the bundle if it never gets injected into the application that imports the library. For more about this, see [Tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers).
|
||||
|
||||
* If you register global service providers or share providers across multiple NgModules, use the [`forRoot()` and `forChild()` design patterns](guide/singleton-services) provided by the [RouterModule](api/router/RouterModule).
|
||||
|
||||
* If your library provides optional services that might not be used by all client applications, support proper tree-shaking for that case by using the [lightweight token design pattern](guide/lightweight-injection-tokens).
|
||||
|
||||
{@a integrating-with-the-cli}
|
||||
|
||||
## Integrating with the CLI using code-generation schematics
|
||||
|
||||
A library typically includes *reusable code* that defines components, services, and other Angular artifacts (pipes, directives, and so on) that you simply import into a project.
|
||||
A library is packaged into an npm package for publishing and sharing.
|
||||
This package can also include [schematics](guide/glossary#schematic) that provide instructions for generating or transforming code directly in your project, in the same way that the CLI creates a generic new component with `ng generate component`.
|
||||
A schematic that is packaged with a library can, for example, provide the Angular CLI with the information it needs to generate a component that configures and uses a particular feature, or set of features, defined in that library.
|
||||
One example of this is Angular Material's navigation schematic which configures the CDK's `BreakpointObserver` and uses it with Material's `MatSideNav` and `MatToolbar` components.
|
||||
|
||||
You can create and include the following kinds of schematics.
|
||||
|
||||
* Include an installation schematic so that `ng add` can add your library to a project.
|
||||
|
||||
* Include generation schematics in your library so that `ng generate` can scaffold your defined artifacts (components, services, tests, and so on) in a project.
|
||||
|
||||
* Include an update schematic so that `ng update` can update your library’s dependencies and provide migrations for breaking changes in new releases.
|
||||
|
||||
What you include in your library depends on your task.
|
||||
For example, you could define a schematic to create a dropdown that is pre-populated with canned data to show how to add it to an app.
|
||||
If you want a dropdown that would contain different passed-in values each time, your library could define a schematic to create it with a given configuration. Developers could then use `ng generate` to configure an instance for their own app.
|
||||
|
||||
Suppose you want to read a configuration file and then generate a form based on that configuration.
|
||||
If that form will need additional customization by the developer who is using your library, it might work best as a schematic.
|
||||
However, if the forms will always be the same and not need much customization by developers, then you could create a dynamic component that takes the configuration and generates the form.
|
||||
In general, the more complex the customization, the more useful the schematic approach.
|
||||
|
||||
To learn more, see [Schematics Overview](guide/schematics) and [Schematics for Libraries](guide/schematics-for-libraries).
|
||||
|
||||
## Publishing your library
|
||||
|
||||
Use the Angular CLI and the npm package manager to build and publish your library as an npm package.
|
||||
|
||||
Before publishing a library to NPM, build it using the `--prod` flag which will use the older compiler and runtime known as View Engine instead of Ivy.
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib --prod
|
||||
cd dist/my-lib
|
||||
npm publish
|
||||
</code-example>
|
||||
|
||||
If you've never published a package in npm before, you must create a user account. Read more in [Publishing npm Packages](https://docs.npmjs.com/getting-started/publishing-npm-packages).
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
For now, it is not recommended to publish Ivy libraries to NPM because Ivy generated code is not backward compatible with View Engine, so apps using View Engine will not be able to consume them. Furthermore, the internal Ivy instructions are not yet stable, which can potentially break consumers using a different Angular version from the one used to build the library.
|
||||
|
||||
When a published library is used in an Ivy app, the Angular CLI will automatically convert it to Ivy using a tool known as the Angular compatibility compiler (`ngcc`). Thus, publishing your libraries using the View Engine compiler ensures that they can be transparently consumed by both View Engine and Ivy apps.
|
||||
|
||||
</div>
|
||||
|
||||
{@a lib-assets}
|
||||
|
||||
## Managing assets in a library
|
||||
|
||||
Starting with version 9.x of the [ng-packagr](https://github.com/ng-packagr/ng-packagr/blob/master/README.md) tool, you can configure the tool to automatically copy assets into your library package as part of the build process.
|
||||
You can use this feature when your library needs to publish optional theming files, Sass mixins, or documentation (like a changelog).
|
||||
|
||||
* Learn how to [copy assets into your library as part of the build](https://github.com/ng-packagr/ng-packagr/blob/master/docs/copy-assets.md).
|
||||
|
||||
* Learn more about how to use the tool to [embed assets in CSS](https://github.com/ng-packagr/ng-packagr/blob/master/docs/embed-assets-css.md).
|
||||
|
||||
|
||||
## Linked libraries
|
||||
|
||||
While working on a published library, you can use [npm link](https://docs.npmjs.com/cli/link) to avoid reinstalling the library on every build.
|
||||
|
||||
The library must be rebuilt on every change.
|
||||
When linking a library, make sure that the build step runs in watch mode, and that the library's `package.json` configuration points at the correct entry points.
|
||||
For example, `main` should point at a JavaScript file, not a TypeScript file.
|
||||
|
||||
## Use TypeScript path mapping for peer dependencies
|
||||
|
||||
Angular libraries should list all `@angular/*` dependencies as peer dependencies.
|
||||
This ensures that when modules ask for Angular, they all get the exact same module.
|
||||
If a library lists `@angular/core` in `dependencies` instead of `peerDependencies`, it might get a different Angular module instead, which would cause your application to break.
|
||||
|
||||
While developing a library, you must install all peer dependencies through `devDependencies` to ensure that the library compiles properly.
|
||||
A linked library will then have its own set of Angular libraries that it uses for building, located in its `node_modules` folder.
|
||||
However, this can cause problems while building or running your application.
|
||||
|
||||
To get around this problem you can use TypeScript path mapping to tell TypeScript that it should load some modules from a specific location.
|
||||
List all the peer dependencies that your library uses in the workspace TypeScript configuration file `./tsconfig.json`, and point them at the local copy in the app's `node_modules` folder.
|
||||
|
||||
```
|
||||
{
|
||||
"compilerOptions": {
|
||||
// ...
|
||||
// paths are relative to `baseUrl` path.
|
||||
"paths": {
|
||||
"@angular/*": [
|
||||
"./node_modules/@angular/*"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This mapping ensures that your library always loads the local copies of the modules it needs.
|
||||
|
||||
|
||||
## Using your own library in apps
|
||||
|
||||
You don't have to publish your library to the npm package manager in order to use it in your own apps, but you do have to build it first.
|
||||
|
||||
To use your own library in an app:
|
||||
|
||||
* Build the library. You cannot use a library before it is built.
|
||||
<code-example language="bash">
|
||||
ng build my-lib
|
||||
</code-example>
|
||||
|
||||
* In your apps, import from the library by name:
|
||||
```
|
||||
import { myExport } from 'my-lib';
|
||||
```
|
||||
|
||||
### Building and rebuilding your library
|
||||
|
||||
The build step is important if you haven't published your library as an npm package and then installed the package back into your app from npm.
|
||||
For instance, if you clone your git repository and run `npm install`, your editor will show the `my-lib` imports as missing if you haven't yet built your library.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
When you import something from a library in an Angular app, Angular looks for a mapping between the library name and a location on disk.
|
||||
When you install a library package, the mapping is in the `node_modules` folder. When you build your own library, it has to find the mapping in your `tsconfig` paths.
|
||||
|
||||
Generating a library with the Angular CLI automatically adds its path to the `tsconfig` file.
|
||||
The Angular CLI uses the `tsconfig` paths to tell the build system where to find the library.
|
||||
|
||||
</div>
|
||||
|
||||
If you find that changes to your library are not reflected in your app, your app is probably using an old build of the library.
|
||||
|
||||
You can rebuild your library whenever you make changes to it, but this extra step takes time.
|
||||
*Incremental builds* functionality improves the library-development experience.
|
||||
Every time a file is changed a partial build is performed that emits the amended files.
|
||||
|
||||
Incremental builds can be run as a background process in your dev environment. To take advantage of this feature add the `--watch` flag to the build command:
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib --watch
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
The CLI `build` command uses a different builder and invokes a different build tool for libraries than it does for applications.
|
||||
|
||||
* The build system for apps, `@angular-devkit/build-angular`, is based on `webpack`, and is included in all new Angular CLI projects.
|
||||
* The build system for libraries is based on `ng-packagr`. It is only added to your dependencies when you add a library using `ng generate library my-lib`.
|
||||
|
||||
The two build systems support different things, and even where they support the same things, they do those things differently.
|
||||
This means that the TypeScript source can result in different JavaScript code in a built library than it would in a built application.
|
||||
|
||||
For this reason, an app that depends on a library should only use TypeScript path mappings that point to the *built library*.
|
||||
TypeScript path mappings should *not* point to the library source `.ts` files.
|
||||
|
||||
</div>
|
||||
@ -1,247 +0,0 @@
|
||||
# Creando librerías
|
||||
|
||||
Está pagina provee una vista conceptual de como puedes crear y publicar nuevas librerías para extender las funcionalidades de Angular.
|
||||
|
||||
Si necesitas resolver el mismo problema en mas de una aplicación (o quiere compartir tu solución con otros desarrolladores), tienes un candidato para una librería.
|
||||
Un ejemplo simple puede ser un botón que envía a los usuarios hacia el sitio web de tu empresa, que sería incluido en todas las aplicaciones que tu empresa crea.
|
||||
|
||||
## Empezando
|
||||
|
||||
Usa el Angular CLI para generar un nuevo esqueleto de librería, en nuevo espacio de trabajo con los siguiente comandos.
|
||||
|
||||
<code-example language="bash">
|
||||
ng new my-workspace --create-application=false
|
||||
cd my-workspace
|
||||
ng generate library my-lib
|
||||
</code-example>
|
||||
|
||||
El comando `ng generate` crea la carpeta `projects/my-lib` en el espacio de trabajo, que contiene un componente y un servicio dentro de un NgModule.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Para más detalles sobre como una librería es estructurada, refiérase a los [Archivos de Librería](guide/file-structure#library-project-files) en la sección de [Guía de estructura de archivos](guide/file-structure).
|
||||
|
||||
Puedes usar un modelo de monorepo para usar el mismo espacio de trabajo con multiples proyectos. Véase [Configuración para espacio de trabajo multiproyecto](guide/file-structure#multiple-projects).
|
||||
|
||||
</div>
|
||||
|
||||
Cuando se genera una nueva librería, el archivo de configuración del espacio de trabajo, `angular.json`, es actualizado con un proyecto de tipo 'library'.
|
||||
|
||||
<code-example format="json">
|
||||
"projects": {
|
||||
...
|
||||
"my-lib": {
|
||||
"root": "projects/my-lib",
|
||||
"sourceRoot": "projects/my-lib/src",
|
||||
"projectType": "library",
|
||||
"prefix": "lib",
|
||||
"architect": {
|
||||
"build": {
|
||||
"builder": "@angular-devkit/build-ng-packagr:build",
|
||||
...
|
||||
</code-example>
|
||||
|
||||
Puedes crear, probar y comprobar con los comandos de CLI:
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib
|
||||
ng test my-lib
|
||||
ng lint my-lib
|
||||
</code-example>
|
||||
|
||||
Puedes notar que el constructor configurado para el proyecto es diferente que el constructor por defecto para proyectos.
|
||||
El constructor, entre otras cosas, asegura que la librería siempre este construida con el [compilador AOT](guide/aot-compiler), sin la necesidad de especificar la bandera `--prod`.
|
||||
|
||||
Para hacer el código de la librería reusable debes definir una API pública para ella. Esta "capa de usuario" define que esta disponible para los consumidores de tu librería. Un usuario de tu librería debería ser capaz de acceder a la funcionalidad publica (como NgModules, servicios, proveedores y en general funciones de utilidad) mediante una sola ruta.
|
||||
|
||||
La API pública para tu librería es mantenida en el archivo `public-api.ts` en tu carpeta de librería.
|
||||
Cualquier cosa exportada desde este archivo se hace publica cuando tu librería es importada dentro de una aplicación.
|
||||
Usa un NgModule para exponer los servicios y componentes.
|
||||
|
||||
Tu libería debería suministrar documentatión (típicamente en el archivo README) para la instalación y mantenimiento.
|
||||
|
||||
## Refactorizando partes de una app dentro de un librería
|
||||
|
||||
Para hacer tu solución reusable, necesitas ajustarla para que no dependa del código específico de la aplicación.
|
||||
Aquí algunas cosas para considerar al migrar la funcionalidad de la aplicación a una librería.
|
||||
|
||||
* Declaraciones tales como componentes y pipes deberían ser diseñados como 'stateless' (sin estado), lo que significa que no dependen ni alteran variables externas. Si tu dependes del estado, necesitas evaluar cada caso y decidir el estado de la aplicación o el estado que la aplicación administraría.
|
||||
|
||||
* Cualquier observable al cual los componentes se suscriban internamente deberían ser limpiados y desechados durante el ciclo de vida de esos componentes.
|
||||
|
||||
* Los componentes deberían exponer sus interacciones a través de 'inputs' para proporcionar contexto y 'outputs' para comunicar los eventos hacia otros componentes.
|
||||
|
||||
* Verifique todas las dependencias internas.
|
||||
* Para clases personalizadas o interfaces usadas en componentes o servicios, verifique si dependen en clases adicionales o interfaces que también necesiten ser migradas.
|
||||
* Del mismo modo, si tu código de librería depende de un servicio, este servicio necesita ser migrado.
|
||||
* Si tu código de librería o sus plantillas dependen de otras librerías (como Angular Material), debes configurar tu librería con esas dependencias.
|
||||
|
||||
* Considere como proporcionar servicios a las aplicaciones cliente.
|
||||
|
||||
* Los servicios deberían declarar sus propios proveedores (en lugar de declarar los proveedores en el NgModule o en un componente). Esto le permite al compilador dejar los servicios fuera del 'bundle' si este nunca fue inyectado dentro de la aplicación que importa la librería, véase [proveedores Tree-shakable](guide/dependency-injection-providers#tree-shakable-providers)
|
||||
* Si registras proveedores globales o compartes proveedores a través de múltiples NgModules, usa el [`forRoot()` y `forChild()` como patrones de diseño](guide/singleton-services) proporcionados por el [RouterModule](api/router/RouterModule).
|
||||
* Si tu librería proporciona servicios opcionales que podrían no ser usados por todos las aplicaciones cliente, soporte apropiadamente el 'tree-shaking' para esos casos usando el [patrón de diseño de token ligero](guide/lightweight-injection-tokens).
|
||||
|
||||
{@a integrating-with-the-cli}
|
||||
|
||||
## Integración con el CLI usando generación de código con los schematics.
|
||||
|
||||
Comúnmente una librería incluye *código reusable* que define componentes, servicios y otros Artefactos de Angular (pipes, directivas y etc.) que tu simplemente importas a un proyecto.
|
||||
Una librería es empaquetada dentro de un paquete npm para publicar y compartir.
|
||||
|
||||
Este paquete también puede incluir [schematics](guide/glossary#schematic) que proporciona instrucciones para generar o transformar código directamente un tu proyecto, de la misma forma que el CLI crea un nuevo componente genérico con `ng generate component`.
|
||||
|
||||
Un 'schematic' empaquetado con una librería puede por ejemplo proporcionar al Angular CLI la información que necesita para generar un componente que configura y usa una particular característica o conjunto de características, definido en la librería.
|
||||
|
||||
Un ejemplo de esto es el 'schematic' de navegación de Angular Material el cual configura los CDK's `BreakpointObserver` y lo usa con los componentes `MatSideNav` y `MatToolbar` de Angular Material.
|
||||
|
||||
Puedes crear e incluir los siguientes tipos de 'schematics'.
|
||||
|
||||
* Incluye un 'schematic' de instalación para que con `ng add` puedas agregar tu libería a un proyecto.
|
||||
|
||||
* Incluye un 'schematic' de generación en tu librería para que con `ng generate` puedas hacer scaffolding de sus artefactos (componentes, servicios, pruebas y etc) en un proyecto.
|
||||
|
||||
* Incluye un 'schematic' de actualización para que con `ng update` puedas actualizar las dependencias de tu librería y proporcionar migraciones para cambios importantes en un nuevo release.
|
||||
|
||||
Lo que incluya tu librería depende de tu tarea.
|
||||
Por ejemplo, podrías definir un 'schematic' para crear un desplegable (dropdown) que esta pre-poblado con datos para mostrar como agregarlo a una aplicación.
|
||||
Si quieres un desplegable (dropdown) que contendrá valores diferentes cada vez, tu librería podría definir un 'schematic' para crearlo con una configuración dada. Los desarrolladores podrán entonces usar `ng generate` para configurar una instancia para sus propias aplicaciones.
|
||||
|
||||
Supón que quieres leer un archivo de configuración y entonces generar una formulario con base a la configuración.
|
||||
Si este formulario necesita personalización adicional por parte del desarrollador que esta usando tu librería, esto podría trabajar mejor como un 'schematic'.
|
||||
Sin embargo, si el formulario siempre será el mismo y no necesita de mucha personalización por parte de los desarrolladores, entonces podría crear un componente dinámico que tome la configuración y genere el formulario.
|
||||
En general, entre más compleja sea personalización, la más util será en enfoque de un 'schematic'.
|
||||
|
||||
Para aprender más, véase [Vista general de Schematics](guide/schematics)
|
||||
|
||||
## Publicando tu librería
|
||||
|
||||
Usa el Angular CLI y el gestor de paquetes npm para construir y publicar tu librería como un paquete npm.
|
||||
|
||||
Antes de publicar una librería a NPM, constrúyela usando la bandera `--prod` la cúal usará el compilador y tiempo de ejecución (runtime) más antiguos como 'View Engine' en vez de 'Ivy'.
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib --prod
|
||||
cd dist/my-lib
|
||||
npm publish
|
||||
</code-example>
|
||||
|
||||
Si nunca has publicado un paquete en npm antes, tu debes crear un cuenta. Lee más en [Publicando paquetes npm](https://docs.npmjs.com/getting-started/publishing-npm-packages).
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
Por ahora, no es recomendando publicar librerías con Ivy hacia NPM por que Ivy genera código que no es retrocompatible con 'View Engine', entonces las aplicaciones usando 'View Engine' no podrán consumirlas. Además, las instrucciones internas de IVY no son estables aun, lo cual puede romper potencialmente a los consumidores que usan una diferente versión de Angular a la que uso para construir la libería.
|
||||
|
||||
Cuando una librería publicada es usada en una aplicación con Ivy, el Angular CLI automáticamente la convertirá a Ivy usando una herramienta conocida como el compilador de compatibilidad Angular (`ngcc`). Por lo tanto, publicar tus librerías usado el compilador 'View Engine' garantiza que ellas puede ser consumidas de forma transparente por ambos motores 'View Engine' y 'Ivy'.
|
||||
|
||||
</div>
|
||||
|
||||
{@a lib-assets}
|
||||
|
||||
## Gestionando activos (assets) en una librería.
|
||||
|
||||
Desde la versión 9.x de la herramienta [ng-packagr](https://github.com/ng-packagr/ng-packagr/blob/master/README.md), puedes configurar la herramienta para que automáticamente copie los activos (assets) dentro de el paquete de librería como parte del proceso de construcción.
|
||||
Puedes usar esta característica cuando tu librería necesite publicar archivos de temas opcionales, funciones de Sass o documentación (como un registro de cambios 'changelog').
|
||||
|
||||
* Aprende como [copiar activos (assets) dentro de tu librería como parte de la construcción](https://github.com/ng-packagr/ng-packagr/blob/master/docs/copy-assets.md).
|
||||
|
||||
* Aprende más acerca de como usar la herramienta para [incrustar activos (assets) de CSS](https://github.com/ng-packagr/ng-packagr/blob/master/docs/embed-assets-css.md).
|
||||
|
||||
|
||||
## Vinculando librerías
|
||||
|
||||
Mientras trabajas en un librería publicada, puedes usar [npm link](https://docs.npmjs.com/cli/link) para evitar re instalar la librería en cada construcción.
|
||||
|
||||
La librería debe ser reconstruida en cada cambio.
|
||||
Cuando vinculas una librería, asegurate que el paso de construir corra en modo vigía (watch mode) y que el `package.json` de la librería configure los puntos de entrada correctos.
|
||||
Por ejemplo, `main` debería apuntar a un archivo JavaScript, no a un archivo TypeScript.
|
||||
|
||||
## Utiliza el mapeo de rutas de TypeScript por las dependencias de pares.
|
||||
|
||||
Las librerías de Angular deben enumerar todas las dependencias `@angular/*` como dependencias de pares.
|
||||
Esto garantiza que cuando los módulos solicitan Angular, todos ellos obtienen exactamente el mismo módulo.
|
||||
Si tu librería lista `@angular/core` en `dependencies` en vez de en `peerDependencies`, podría obtener un módulo Angular diferente, lo qué haría que tu aplicación se rompiera.
|
||||
|
||||
Cuando desarrollas una librería, tu debes instalar todas las dependencias de pares mediante `devDependencies` para garantizar que la librería compile apropiadamente.
|
||||
Una librería vinculada tendrá su propio conjunto de librerías Angular que usa para construir, ubicados en su carpeta `node_modules`.
|
||||
|
||||
Sin embargo, esto puede causar problemas mientras construyes o corres tu aplicación.
|
||||
|
||||
Para evitar este problema tu puedes usar el mapeo de rutas de TypeScript para indicarle a TypeScript que este debería cargar algunos módulos desde una ubicación especifica.
|
||||
|
||||
Enumera todas las dependencias de pares que tu librería usa en el archivo de configuración `./tsconfig.json` del espacio de trabajo de TypeScript, y apúntalos a la copia local en la carpeta `node_modules` de la aplicación.
|
||||
|
||||
```
|
||||
{
|
||||
"compilerOptions": {
|
||||
// ...
|
||||
// paths are relative to `baseUrl` path.
|
||||
"paths": {
|
||||
"@angular/*": [
|
||||
"./node_modules/@angular/*"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Este mapeador garantiza que tu librería siempre cargue las copias locales del módulo que necesita.
|
||||
|
||||
|
||||
## Usando tu propia librería en aplicaciones.
|
||||
|
||||
No tienes que publicar tu librería hacia el gestor de paquetes npm para usarla en tus propias aplicaciones, pero tienes que construirla primero.
|
||||
|
||||
Para usar tu propia librería en tu aplicación:
|
||||
|
||||
* Construye la librería. No puedes usar una librería antes que se construya.
|
||||
<code-example language="bash">
|
||||
ng build my-lib
|
||||
</code-example>
|
||||
|
||||
* En tus aplicaciones, importa la librería por el nombre:
|
||||
```
|
||||
import { myExport } from 'my-lib';
|
||||
```
|
||||
|
||||
### Construyendo y re construyendo tu librería.
|
||||
|
||||
El paso de construir es importante si no tienes publicada tu librería como un paquete npm y luego ha instalado el paquete de nuevo dentro tu aplicación desde npm.
|
||||
Por ejemplo, si clonas tu repositorio git y corres `npm install`, tu editor mostrará la importación de `my-lib` como perdida si no tienes aun construida tu librería.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
Cuando importas algo desde una librería en una aplicación Angular, Angular busca un mapeo entre el nombre de librería y una ubicación en disco.
|
||||
Cuando instalas un paquete de librería, el mapeo esta en la carpeta `node_modules`. Cuando construyes tu propia librería, tiene que encontrar el mapeo en tus rutas de `tsconfig`.
|
||||
|
||||
Generando una librería con el Angular CLI automáticamente agrega su ruta en el archivo `tsconfig`.
|
||||
El Angular CLI usa las rutas `tsconfig` para indicarle al sistema construido donde encontrar la librería.
|
||||
|
||||
</div>
|
||||
|
||||
Si descubres que los cambios en tu librería no son reflejados en tu aplicación, tu aplicación probablemente esta usando una construcción antigua de la librería.
|
||||
|
||||
Puedes re construir tu librería cada vez que hagas cambios en esta, pero este paso extra toma tiempo.
|
||||
Las *construcciones incrementales* funcionalmente mejoran la experiencia de desarrollo de librerías.
|
||||
Cada vez que un archivo es cambiando una construcción parcial es realizada y esta emite los archivos modificados.
|
||||
|
||||
Las *Construcciones incrementales* puede ser ejecutadas como un proceso en segundo plano en tu entorno de desarrollo. Para aprovechar esta característica agrega la bandera `--watch` al comando de construcción:
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib --watch
|
||||
</code-example>
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
El comando `build` del CLI utiliza un constructor diferente e invoca una herramienta de construcción diferente para las librerías que para las aplicaciones.
|
||||
|
||||
* El sistema de construcción para aplicaciones, `@angular-devkit/build-angular`, esta basado en `webpack`, y esta incluida en todos los nuevos proyectos de Angular CLI.
|
||||
* El sistema de construcción esta basado en `ng-packagr`. Este es solo agregado en tus dependencias cuando agregas una librería usando `ng generate library my-lib`.
|
||||
|
||||
Los dos sistemas de construcción soportan diferentes cosas e incluso si ellos soportan las mismas cosas, ellos hacen esas cosas de forma diferente.
|
||||
Esto quiere decir que la fuente de TypeScript puede generar en código JavaScript diferente en una librería construida que en una aplicación construida.
|
||||
|
||||
Por esta razón, una aplicación que depende de una librería debería solo usar el mapeo de rutas de TypeScript que apunte a la *librería construida*.
|
||||
El mapeo de rutas de TypeScript no debería apuntar hacia los archivos `.ts` fuente de la librería.
|
||||
|
||||
</div>
|
||||
@ -1,13 +1,13 @@
|
||||
# Creating libraries
|
||||
# Creando librerías
|
||||
|
||||
This page provides a conceptual overview of how you can create and publish new libraries to extend Angular functionality.
|
||||
Está pagina provee una vista conceptual de como puedes crear y publicar nuevas librerías para extender las funcionalidades de Angular.
|
||||
|
||||
If you find that you need to solve the same problem in more than one app (or want to share your solution with other developers), you have a candidate for a library.
|
||||
A simple example might be a button that sends users to your company website, that would be included in all apps that your company builds.
|
||||
Si necesitas resolver el mismo problema en mas de una aplicación (o quiere compartir tu solución con otros desarrolladores), tienes un candidato para una librería.
|
||||
Un ejemplo simple puede ser un botón que envía a los usuarios hacia el sitio web de tu empresa, que sería incluido en todas las aplicaciones que tu empresa crea.
|
||||
|
||||
## Getting started
|
||||
## Empezando
|
||||
|
||||
Use the Angular CLI to generate a new library skeleton in a new workspace with the following commands.
|
||||
Usa el Angular CLI para generar un nuevo esqueleto de librería, en nuevo espacio de trabajo con los siguiente comandos.
|
||||
|
||||
<code-example language="bash">
|
||||
ng new my-workspace --create-application=false
|
||||
@ -15,18 +15,17 @@ Use the Angular CLI to generate a new library skeleton in a new workspace with t
|
||||
ng generate library my-lib
|
||||
</code-example>
|
||||
|
||||
The `ng generate` command creates the `projects/my-lib` folder in your workspace, which contains a component and a service inside an NgModule.
|
||||
El comando `ng generate` crea la carpeta `projects/my-lib` en el espacio de trabajo, que contiene un componente y un servicio dentro de un NgModule.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
For more details on how a library project is structured, refer to the [Library project files](guide/file-structure#library-project-files) section of the [Project File Structure guide](guide/file-structure).
|
||||
Para más detalles sobre como una librería es estructurada, refiérase a los [Archivos de Librería](guide/file-structure#library-project-files) en la sección de [Guía de estructura de archivos](guide/file-structure).
|
||||
|
||||
You can use the monorepo model to use the same workspace for multiple projects.
|
||||
See [Setting up for a multi-project workspace](guide/file-structure#multiple-projects).
|
||||
Puedes usar un modelo de monorepo para usar el mismo espacio de trabajo con multiples proyectos. Véase [Configuración para espacio de trabajo multiproyecto](guide/file-structure#multiple-projects).
|
||||
|
||||
</div>
|
||||
|
||||
When you generate a new library, the workspace configuration file, `angular.json`, is updated with a project of type 'library'.
|
||||
Cuando se genera una nueva librería, el archivo de configuración del espacio de trabajo, `angular.json`, es actualizado con un proyecto de tipo 'library'.
|
||||
|
||||
<code-example format="json">
|
||||
"projects": {
|
||||
@ -42,7 +41,7 @@ When you generate a new library, the workspace configuration file, `angular.json
|
||||
...
|
||||
</code-example>
|
||||
|
||||
You can build, test, and lint the project with CLI commands:
|
||||
Puedes crear, probar y comprobar con los comandos de CLI:
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib
|
||||
@ -50,75 +49,78 @@ You can build, test, and lint the project with CLI commands:
|
||||
ng lint my-lib
|
||||
</code-example>
|
||||
|
||||
Notice that the configured builder for the project is different from the default builder for app projects.
|
||||
This builder, among other things, ensures that the library is always built with the [AOT compiler](guide/aot-compiler), without the need to specify the `--prod` flag.
|
||||
Puedes notar que el constructor configurado para el proyecto es diferente que el constructor por defecto para proyectos.
|
||||
El constructor, entre otras cosas, asegura que la librería siempre este construida con el [compilador AOT](guide/aot-compiler), sin la necesidad de especificar la bandera `--prod`.
|
||||
|
||||
To make library code reusable you must define a public API for it. This "user layer" defines what is available to consumers of your library. A user of your library should be able to access public functionality (such as NgModules, service providers and general utility functions) through a single import path.
|
||||
Para hacer el código de la librería reusable debes definir una API pública para ella. Esta "capa de usuario" define que esta disponible para los consumidores de tu librería. Un usuario de tu librería debería ser capaz de acceder a la funcionalidad publica (como NgModules, servicios, proveedores y en general funciones de utilidad) mediante una sola ruta.
|
||||
|
||||
The public API for your library is maintained in the `public-api.ts` file in your library folder.
|
||||
Anything exported from this file is made public when your library is imported into an application.
|
||||
Use an NgModule to expose services and components.
|
||||
La API pública para tu librería es mantenida en el archivo `public-api.ts` en tu carpeta de librería.
|
||||
Cualquier cosa exportada desde este archivo se hace publica cuando tu librería es importada dentro de una aplicación.
|
||||
Usa un NgModule para exponer los servicios y componentes.
|
||||
|
||||
Your library should supply documentation (typically a README file) for installation and maintenance.
|
||||
Tu libería debería suministrar documentatión (típicamente en el archivo README) para la instalación y mantenimiento.
|
||||
|
||||
## Refactoring parts of an app into a library
|
||||
## Refactorizando partes de una app dentro de un librería
|
||||
|
||||
To make your solution reusable, you need to adjust it so that it does not depend on app-specific code.
|
||||
Here are some things to consider in migrating application functionality to a library.
|
||||
Para hacer tu solución reusable, necesitas ajustarla para que no dependa del código específico de la aplicación.
|
||||
Aquí algunas cosas para considerar al migrar la funcionalidad de la aplicación a una librería.
|
||||
|
||||
* Declarations such as components and pipes should be designed as stateless, meaning they don’t rely on or alter external variables. If you do rely on state, you need to evaluate every case and decide whether it is application state or state that the library would manage.
|
||||
* Declaraciones tales como componentes y pipes deberían ser diseñados como 'stateless' (sin estado), lo que significa que no dependen ni alteran variables externas. Si tu dependes del estado, necesitas evaluar cada caso y decidir el estado de la aplicación o el estado que la aplicación administraría.
|
||||
|
||||
* Any observables that the components subscribe to internally should be cleaned up and disposed of during the lifecycle of those components.
|
||||
* Cualquier observable al cual los componentes se suscriban internamente deberían ser limpiados y desechados durante el ciclo de vida de esos componentes.
|
||||
|
||||
* Components should expose their interactions through inputs for providing context, and outputs for communicating events to other components.
|
||||
* Los componentes deberían exponer sus interacciones a través de 'inputs' para proporcionar contexto y 'outputs' para comunicar los eventos hacia otros componentes.
|
||||
|
||||
* Check all internal dependencies.
|
||||
* For custom classes or interfaces used in components or service, check whether they depend on additional classes or interfaces that also need to be migrated.
|
||||
* Similarly, if your library code depends on a service, that service needs to be migrated.
|
||||
* If your library code or its templates depend on other libraries (such as Angular Material, for instance), you must configure your library with those dependencies.
|
||||
* Verifique todas las dependencias internas.
|
||||
* Para clases personalizadas o interfaces usadas en componentes o servicios, verifique si dependen en clases adicionales o interfaces que también necesiten ser migradas.
|
||||
* Del mismo modo, si tu código de librería depende de un servicio, este servicio necesita ser migrado.
|
||||
* Si tu código de librería o sus plantillas dependen de otras librerías (como Angular Material), debes configurar tu librería con esas dependencias.
|
||||
|
||||
* Consider how you provide services to client applications.
|
||||
* Considere como proporcionar servicios a las aplicaciones cliente.
|
||||
|
||||
* Services should declare their own providers (rather than declaring providers in the NgModule or a component), so that they are *tree-shakable*. This allows the compiler to leave the service out of the bundle if it never gets injected into the application that imports the library. For more about this, see [Tree-shakable providers](guide/dependency-injection-providers#tree-shakable-providers).
|
||||
|
||||
* If you register global service providers or share providers across multiple NgModules, use the [`forRoot()` and `forChild()` design patterns](guide/singleton-services) provided by the [RouterModule](api/router/RouterModule).
|
||||
|
||||
* If your library provides optional services that might not be used by all client applications, support proper tree-shaking for that case by using the [lightweight token design pattern](guide/lightweight-injection-tokens).
|
||||
* Los servicios deberían declarar sus propios proveedores (en lugar de declarar los proveedores en el NgModule o en un componente). Esto le permite al compilador dejar los servicios fuera del 'bundle' si este nunca fue inyectado dentro de la aplicación que importa la librería, véase [proveedores Tree-shakable](guide/dependency-injection-providers#tree-shakable-providers)
|
||||
* Si registras proveedores globales o compartes proveedores a través de múltiples NgModules, usa el [`forRoot()` y `forChild()` como patrones de diseño](guide/singleton-services) proporcionados por el [RouterModule](api/router/RouterModule).
|
||||
* Si tu librería proporciona servicios opcionales que podrían no ser usados por todos las aplicaciones cliente, soporte apropiadamente el 'tree-shaking' para esos casos usando el [patrón de diseño de token ligero](guide/lightweight-injection-tokens).
|
||||
|
||||
{@a integrating-with-the-cli}
|
||||
|
||||
## Integrating with the CLI using code-generation schematics
|
||||
## Integración con el CLI usando generación de código con los schematics.
|
||||
|
||||
A library typically includes *reusable code* that defines components, services, and other Angular artifacts (pipes, directives, and so on) that you simply import into a project.
|
||||
A library is packaged into an npm package for publishing and sharing.
|
||||
This package can also include [schematics](guide/glossary#schematic) that provide instructions for generating or transforming code directly in your project, in the same way that the CLI creates a generic new component with `ng generate component`.
|
||||
A schematic that is packaged with a library can, for example, provide the Angular CLI with the information it needs to generate a component that configures and uses a particular feature, or set of features, defined in that library.
|
||||
One example of this is Angular Material's navigation schematic which configures the CDK's `BreakpointObserver` and uses it with Material's `MatSideNav` and `MatToolbar` components.
|
||||
Comúnmente una librería incluye *código reusable* que define componentes, servicios y otros Artefactos de Angular (pipes, directivas y etc.) que tu simplemente importas a un proyecto.
|
||||
Una librería es empaquetada dentro de un paquete npm para publicar y compartir.
|
||||
|
||||
You can create and include the following kinds of schematics.
|
||||
Este paquete también puede incluir [schematics](guide/glossary#schematic) que proporciona instrucciones para generar o transformar código directamente un tu proyecto, de la misma forma que el CLI crea un nuevo componente genérico con `ng generate component`.
|
||||
|
||||
* Include an installation schematic so that `ng add` can add your library to a project.
|
||||
Un 'schematic' empaquetado con una librería puede por ejemplo proporcionar al Angular CLI la información que necesita para generar un componente que configura y usa una particular característica o conjunto de características, definido en la librería.
|
||||
|
||||
* Include generation schematics in your library so that `ng generate` can scaffold your defined artifacts (components, services, tests, and so on) in a project.
|
||||
Un ejemplo de esto es el 'schematic' de navegación de Angular Material el cual configura los CDK's `BreakpointObserver` y lo usa con los componentes `MatSideNav` y `MatToolbar` de Angular Material.
|
||||
|
||||
* Include an update schematic so that `ng update` can update your library’s dependencies and provide migrations for breaking changes in new releases.
|
||||
Puedes crear e incluir los siguientes tipos de 'schematics'.
|
||||
|
||||
What you include in your library depends on your task.
|
||||
For example, you could define a schematic to create a dropdown that is pre-populated with canned data to show how to add it to an app.
|
||||
If you want a dropdown that would contain different passed-in values each time, your library could define a schematic to create it with a given configuration. Developers could then use `ng generate` to configure an instance for their own app.
|
||||
* Incluye un 'schematic' de instalación para que con `ng add` puedas agregar tu libería a un proyecto.
|
||||
|
||||
Suppose you want to read a configuration file and then generate a form based on that configuration.
|
||||
If that form will need additional customization by the developer who is using your library, it might work best as a schematic.
|
||||
However, if the forms will always be the same and not need much customization by developers, then you could create a dynamic component that takes the configuration and generates the form.
|
||||
In general, the more complex the customization, the more useful the schematic approach.
|
||||
* Incluye un 'schematic' de generación en tu librería para que con `ng generate` puedas hacer scaffolding de sus artefactos (componentes, servicios, pruebas y etc) en un proyecto.
|
||||
|
||||
To learn more, see [Schematics Overview](guide/schematics) and [Schematics for Libraries](guide/schematics-for-libraries).
|
||||
* Incluye un 'schematic' de actualización para que con `ng update` puedas actualizar las dependencias de tu librería y proporcionar migraciones para cambios importantes en un nuevo release.
|
||||
|
||||
## Publishing your library
|
||||
Lo que incluya tu librería depende de tu tarea.
|
||||
Por ejemplo, podrías definir un 'schematic' para crear un desplegable (dropdown) que esta pre-poblado con datos para mostrar como agregarlo a una aplicación.
|
||||
Si quieres un desplegable (dropdown) que contendrá valores diferentes cada vez, tu librería podría definir un 'schematic' para crearlo con una configuración dada. Los desarrolladores podrán entonces usar `ng generate` para configurar una instancia para sus propias aplicaciones.
|
||||
|
||||
Use the Angular CLI and the npm package manager to build and publish your library as an npm package.
|
||||
Supón que quieres leer un archivo de configuración y entonces generar una formulario con base a la configuración.
|
||||
Si este formulario necesita personalización adicional por parte del desarrollador que esta usando tu librería, esto podría trabajar mejor como un 'schematic'.
|
||||
Sin embargo, si el formulario siempre será el mismo y no necesita de mucha personalización por parte de los desarrolladores, entonces podría crear un componente dinámico que tome la configuración y genere el formulario.
|
||||
En general, entre más compleja sea personalización, la más util será en enfoque de un 'schematic'.
|
||||
|
||||
Before publishing a library to NPM, build it using the `--prod` flag which will use the older compiler and runtime known as View Engine instead of Ivy.
|
||||
Para aprender más, véase [Vista general de Schematics](guide/schematics) y [Schematics para librerías](guide/schematics-for-libraries).
|
||||
|
||||
{@a publishing-your-library}
|
||||
|
||||
## Publicando tu librería
|
||||
|
||||
Usa el Angular CLI y el gestor de paquetes npm para construir y publicar tu librería como un paquete npm.
|
||||
|
||||
Antes de publicar una librería a NPM, constrúyela usando la bandera `--prod` la cúal usará el compilador y tiempo de ejecución (runtime) más antiguos como 'View Engine' en vez de 'Ivy'.
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib --prod
|
||||
@ -126,48 +128,50 @@ cd dist/my-lib
|
||||
npm publish
|
||||
</code-example>
|
||||
|
||||
If you've never published a package in npm before, you must create a user account. Read more in [Publishing npm Packages](https://docs.npmjs.com/getting-started/publishing-npm-packages).
|
||||
Si nunca has publicado un paquete en npm antes, tu debes crear un cuenta. Lee más en [Publicando paquetes npm](https://docs.npmjs.com/getting-started/publishing-npm-packages).
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
For now, it is not recommended to publish Ivy libraries to NPM because Ivy generated code is not backward compatible with View Engine, so apps using View Engine will not be able to consume them. Furthermore, the internal Ivy instructions are not yet stable, which can potentially break consumers using a different Angular version from the one used to build the library.
|
||||
Por ahora, no es recomendando publicar librerías con Ivy hacia NPM por que Ivy genera código que no es retrocompatible con 'View Engine', entonces las aplicaciones usando 'View Engine' no podrán consumirlas. Además, las instrucciones internas de IVY no son estables aun, lo cual puede romper potencialmente a los consumidores que usan una diferente versión de Angular a la que uso para construir la libería.
|
||||
|
||||
When a published library is used in an Ivy app, the Angular CLI will automatically convert it to Ivy using a tool known as the Angular compatibility compiler (`ngcc`). Thus, publishing your libraries using the View Engine compiler ensures that they can be transparently consumed by both View Engine and Ivy apps.
|
||||
Cuando una librería publicada es usada en una aplicación con Ivy, el Angular CLI automáticamente la convertirá a Ivy usando una herramienta conocida como el compilador de compatibilidad Angular (`ngcc`). Por lo tanto, publicar tus librerías usado el compilador 'View Engine' garantiza que ellas puede ser consumidas de forma transparente por ambos motores 'View Engine' y 'Ivy'.
|
||||
|
||||
</div>
|
||||
|
||||
{@a lib-assets}
|
||||
|
||||
## Managing assets in a library
|
||||
## Gestionando activos (assets) en una librería.
|
||||
|
||||
Starting with version 9.x of the [ng-packagr](https://github.com/ng-packagr/ng-packagr/blob/master/README.md) tool, you can configure the tool to automatically copy assets into your library package as part of the build process.
|
||||
You can use this feature when your library needs to publish optional theming files, Sass mixins, or documentation (like a changelog).
|
||||
Desde la versión 9.x de la herramienta [ng-packagr](https://github.com/ng-packagr/ng-packagr/blob/master/README.md), puedes configurar la herramienta para que automáticamente copie los activos (assets) dentro de el paquete de librería como parte del proceso de construcción.
|
||||
Puedes usar esta característica cuando tu librería necesite publicar archivos de temas opcionales, funciones de Sass o documentación (como un registro de cambios 'changelog').
|
||||
|
||||
* Learn how to [copy assets into your library as part of the build](https://github.com/ng-packagr/ng-packagr/blob/master/docs/copy-assets.md).
|
||||
* Aprende como [copiar activos (assets) dentro de tu librería como parte de la construcción](https://github.com/ng-packagr/ng-packagr/blob/master/docs/copy-assets.md).
|
||||
|
||||
* Learn more about how to use the tool to [embed assets in CSS](https://github.com/ng-packagr/ng-packagr/blob/master/docs/embed-assets-css.md).
|
||||
* Aprende más acerca de como usar la herramienta para [incrustar activos (assets) de CSS](https://github.com/ng-packagr/ng-packagr/blob/master/docs/embed-assets-css.md).
|
||||
|
||||
|
||||
## Linked libraries
|
||||
## Vinculando librerías
|
||||
|
||||
While working on a published library, you can use [npm link](https://docs.npmjs.com/cli/link) to avoid reinstalling the library on every build.
|
||||
Mientras trabajas en un librería publicada, puedes usar [npm link](https://docs.npmjs.com/cli/link) para evitar re instalar la librería en cada construcción.
|
||||
|
||||
The library must be rebuilt on every change.
|
||||
When linking a library, make sure that the build step runs in watch mode, and that the library's `package.json` configuration points at the correct entry points.
|
||||
For example, `main` should point at a JavaScript file, not a TypeScript file.
|
||||
La librería debe ser reconstruida en cada cambio.
|
||||
Cuando vinculas una librería, asegurate que el paso de construir corra en modo vigía (watch mode) y que el `package.json` de la librería configure los puntos de entrada correctos.
|
||||
Por ejemplo, `main` debería apuntar a un archivo JavaScript, no a un archivo TypeScript.
|
||||
|
||||
## Use TypeScript path mapping for peer dependencies
|
||||
## Utiliza el mapeo de rutas de TypeScript por las dependencias de pares.
|
||||
|
||||
Angular libraries should list all `@angular/*` dependencies as peer dependencies.
|
||||
This ensures that when modules ask for Angular, they all get the exact same module.
|
||||
If a library lists `@angular/core` in `dependencies` instead of `peerDependencies`, it might get a different Angular module instead, which would cause your application to break.
|
||||
Las librerías de Angular deben enumerar todas las dependencias `@angular/*` como dependencias de pares.
|
||||
Esto garantiza que cuando los módulos solicitan Angular, todos ellos obtienen exactamente el mismo módulo.
|
||||
Si tu librería lista `@angular/core` en `dependencies` en vez de en `peerDependencies`, podría obtener un módulo Angular diferente, lo qué haría que tu aplicación se rompiera.
|
||||
|
||||
While developing a library, you must install all peer dependencies through `devDependencies` to ensure that the library compiles properly.
|
||||
A linked library will then have its own set of Angular libraries that it uses for building, located in its `node_modules` folder.
|
||||
However, this can cause problems while building or running your application.
|
||||
Cuando desarrollas una librería, tu debes instalar todas las dependencias de pares mediante `devDependencies` para garantizar que la librería compile apropiadamente.
|
||||
Una librería vinculada tendrá su propio conjunto de librerías Angular que usa para construir, ubicados en su carpeta `node_modules`.
|
||||
|
||||
To get around this problem you can use TypeScript path mapping to tell TypeScript that it should load some modules from a specific location.
|
||||
List all the peer dependencies that your library uses in the workspace TypeScript configuration file `./tsconfig.json`, and point them at the local copy in the app's `node_modules` folder.
|
||||
Sin embargo, esto puede causar problemas mientras construyes o corres tu aplicación.
|
||||
|
||||
Para evitar este problema tu puedes usar el mapeo de rutas de TypeScript para indicarle a TypeScript que este debería cargar algunos módulos desde una ubicación especifica.
|
||||
|
||||
Enumera todas las dependencias de pares que tu librería usa en el archivo de configuración `./tsconfig.json` del espacio de trabajo de TypeScript, y apúntalos a la copia local en la carpeta `node_modules` de la aplicación.
|
||||
|
||||
```
|
||||
{
|
||||
@ -183,47 +187,47 @@ List all the peer dependencies that your library uses in the workspace TypeScrip
|
||||
}
|
||||
```
|
||||
|
||||
This mapping ensures that your library always loads the local copies of the modules it needs.
|
||||
Este mapeador garantiza que tu librería siempre cargue las copias locales del módulo que necesita.
|
||||
|
||||
|
||||
## Using your own library in apps
|
||||
## Usando tu propia librería en aplicaciones.
|
||||
|
||||
You don't have to publish your library to the npm package manager in order to use it in your own apps, but you do have to build it first.
|
||||
No tienes que publicar tu librería hacia el gestor de paquetes npm para usarla en tus propias aplicaciones, pero tienes que construirla primero.
|
||||
|
||||
To use your own library in an app:
|
||||
Para usar tu propia librería en tu aplicación:
|
||||
|
||||
* Build the library. You cannot use a library before it is built.
|
||||
* Construye la librería. No puedes usar una librería antes que se construya.
|
||||
<code-example language="bash">
|
||||
ng build my-lib
|
||||
</code-example>
|
||||
|
||||
* In your apps, import from the library by name:
|
||||
* En tus aplicaciones, importa la librería por el nombre:
|
||||
```
|
||||
import { myExport } from 'my-lib';
|
||||
```
|
||||
|
||||
### Building and rebuilding your library
|
||||
### Construyendo y re construyendo tu librería.
|
||||
|
||||
The build step is important if you haven't published your library as an npm package and then installed the package back into your app from npm.
|
||||
For instance, if you clone your git repository and run `npm install`, your editor will show the `my-lib` imports as missing if you haven't yet built your library.
|
||||
El paso de construir es importante si no tienes publicada tu librería como un paquete npm y luego ha instalado el paquete de nuevo dentro tu aplicación desde npm.
|
||||
Por ejemplo, si clonas tu repositorio git y corres `npm install`, tu editor mostrará la importación de `my-lib` como perdida si no tienes aun construida tu librería.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
When you import something from a library in an Angular app, Angular looks for a mapping between the library name and a location on disk.
|
||||
When you install a library package, the mapping is in the `node_modules` folder. When you build your own library, it has to find the mapping in your `tsconfig` paths.
|
||||
Cuando importas algo desde una librería en una aplicación Angular, Angular busca un mapeo entre el nombre de librería y una ubicación en disco.
|
||||
Cuando instalas un paquete de librería, el mapeo esta en la carpeta `node_modules`. Cuando construyes tu propia librería, tiene que encontrar el mapeo en tus rutas de `tsconfig`.
|
||||
|
||||
Generating a library with the Angular CLI automatically adds its path to the `tsconfig` file.
|
||||
The Angular CLI uses the `tsconfig` paths to tell the build system where to find the library.
|
||||
Generando una librería con el Angular CLI automáticamente agrega su ruta en el archivo `tsconfig`.
|
||||
El Angular CLI usa las rutas `tsconfig` para indicarle al sistema construido donde encontrar la librería.
|
||||
|
||||
</div>
|
||||
|
||||
If you find that changes to your library are not reflected in your app, your app is probably using an old build of the library.
|
||||
Si descubres que los cambios en tu librería no son reflejados en tu aplicación, tu aplicación probablemente esta usando una construcción antigua de la librería.
|
||||
|
||||
You can rebuild your library whenever you make changes to it, but this extra step takes time.
|
||||
*Incremental builds* functionality improves the library-development experience.
|
||||
Every time a file is changed a partial build is performed that emits the amended files.
|
||||
Puedes re construir tu librería cada vez que hagas cambios en esta, pero este paso extra toma tiempo.
|
||||
Las *construcciones incrementales* funcionalmente mejoran la experiencia de desarrollo de librerías.
|
||||
Cada vez que un archivo es cambiando una construcción parcial es realizada y esta emite los archivos modificados.
|
||||
|
||||
Incremental builds can be run as a background process in your dev environment. To take advantage of this feature add the `--watch` flag to the build command:
|
||||
Las *Construcciones incrementales* puede ser ejecutadas como un proceso en segundo plano en tu entorno de desarrollo. Para aprovechar esta característica agrega la bandera `--watch` al comando de construcción:
|
||||
|
||||
<code-example language="bash">
|
||||
ng build my-lib --watch
|
||||
@ -231,15 +235,15 @@ ng build my-lib --watch
|
||||
|
||||
<div class="alert is-important">
|
||||
|
||||
The CLI `build` command uses a different builder and invokes a different build tool for libraries than it does for applications.
|
||||
El comando `build` del CLI utiliza un constructor diferente e invoca una herramienta de construcción diferente para las librerías que para las aplicaciones.
|
||||
|
||||
* The build system for apps, `@angular-devkit/build-angular`, is based on `webpack`, and is included in all new Angular CLI projects.
|
||||
* The build system for libraries is based on `ng-packagr`. It is only added to your dependencies when you add a library using `ng generate library my-lib`.
|
||||
* El sistema de construcción para aplicaciones, `@angular-devkit/build-angular`, esta basado en `webpack`, y esta incluida en todos los nuevos proyectos de Angular CLI.
|
||||
* El sistema de construcción esta basado en `ng-packagr`. Este es solo agregado en tus dependencias cuando agregas una librería usando `ng generate library my-lib`.
|
||||
|
||||
The two build systems support different things, and even where they support the same things, they do those things differently.
|
||||
This means that the TypeScript source can result in different JavaScript code in a built library than it would in a built application.
|
||||
Los dos sistemas de construcción soportan diferentes cosas e incluso si ellos soportan las mismas cosas, ellos hacen esas cosas de forma diferente.
|
||||
Esto quiere decir que la fuente de TypeScript puede generar en código JavaScript diferente en una librería construida que en una aplicación construida.
|
||||
|
||||
For this reason, an app that depends on a library should only use TypeScript path mappings that point to the *built library*.
|
||||
TypeScript path mappings should *not* point to the library source `.ts` files.
|
||||
Por esta razón, una aplicación que depende de una librería debería solo usar el mapeo de rutas de TypeScript que apunte a la *librería construida*.
|
||||
El mapeo de rutas de TypeScript no debería apuntar hacia los archivos `.ts` fuente de la librería.
|
||||
|
||||
</div>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user