`expandoInstructions` uses negative numbers by `-x`. This has lead to
issues in the paste as `-0` is processed as float rather than integer
leading to de-optimization.
PR Close#39233
IMPORTANT: `HEADER_OFFSET` should only be refereed to the in the `ɵɵ*` instructions to translate
instruction index into `LView` index. All other indexes should be in the `LView` index space and
there should be no need to refer to `HEADER_OFFSET` anywhere else.
PR Close#39233
- Made `*OpCodes` array branded for safer type checking.
- Simplify `I18NRemoveOpCodes` encoding.
- Broke out `IcuCreateOpCodes` from `I18nMutableOpCodes`.
PR Close#39233
`COMMENT_MARKER` is a generic name which does not make it obvious that
it is used for ICU use case. `ICU_MARKER` is more explicit as it is used
exclusively with ICUs.
PR Close#39233
When looking at `TView` debug template only Element nodes were displayed
as `TNode.Element` was used for both `RElement` and `RText`.
Additionally no text was stored in `TNode.value`. The result was that
the whole template could not be reconstructed. This refactoring creates
`TNodeType.Text` and store the text value in `TNode.value`.
The refactoring also changes `TNodeType` into flag-like structure make
it more efficient to check many different types at once.
PR Close#39233
Remove casting where we stored `TIcu` in `TNode.tagName` which was of
type `string` rather than `TIcu'. (renamed to `TNode.value` in previous
commit.)
PR Close#39233
Before this refactoring/fix the ICU would store the current selected
index in `TView`. This is incorrect, since if ICU is in `ngFor` it will
cause issues in some circumstances. This refactoring properly moves the
state to `LView`.
closes#37021closes#38144closes#38073
PR Close#39233
`TemplateFixture` used to have positional parameters and many tests got
hard to read as number of parameters reach 10+ with many of them `null`.
This refactoring changes `TemplateFixture` to take named parameters
which improves usability and readability in tests.
PR Close#39233
This commit fixes a bug when `useAbsoluteUrl` is set to true and
`ServerPlatformLocation` infers the base url from the supplied
`url`. User should explicitly set the `baseUrl` when they turn on
`useAbsoluteUrl`.
Breaking change:
If you use `useAbsoluteUrl` to setup `platform-server`, you now need to
also specify `baseUrl`.
We are intentionally making this a breaking change in a minor release,
because if `useAbsoluteUrl` is set to `true` then the behavior of the
application could be unpredictable, resulting in issues that are hard to
discover but could be affecting production environments.
PR Close#39334
Upgrade the karma dependency to version 4.4.0 in the root package.json
and in integration tests. Compared to version 4.3.0, which most of the
packages were previously depending on, it has the following changes:
Bug Fixes
- runner: remove explicit error on all tests failed
Features
- client: Add trusted types support
- Preprocessor can return Promise
- config: add failOnSkippedTests option.
- config: clientDisplayNone sets client elements display none.
- deps: Remove core-js dependency.
The motivation for upgrading the package is the Trusted Types support
that it adds, which is necessary to enable Trusted Types in Angular's
unit tests.
PR Close#39180
The type of the `navigationExtras` param was accidetally changed to the wrong symbol
in 783a5bd7bb.
These changes revert it to the correct one.
PR Close#39347
Revert back to downloading cldr-data directly as the npm package seems
to no longer be maintained and additionally, it carries a ~350mb cost
in our node modules that is unnecessarily downloaded by most developers
and on CI.
PR Close#39341
Perviously, it was not immediately clear what branches a PR would merge
into during the merge process. This prompt allows for caretakers to
understand and acknowledge where the PR will merge to.
PR Close#39333
This commit adds the basic building blocks for linking partial declarations.
In particular it provides a generic `FileLinker` class that delegates to
a set of (not yet implemented) `PartialLinker` classes.
The Babel plugin makes use of this `FileLinker` providing concrete classes
for `AstHost` and `AstFactory` that work with Babel AST. It can be created
with the following code:
```ts
const plugin = createEs2015LinkerPlugin({ /* options */ });
```
PR Close#39116
Zone.js 0.11.0 release an empty bundle, and now the npm_package tests all target
bazel rule `npm_package`, but not `npm_package.pack`, and these two rules may
generate different results, for example, Zone.js 0.11.0's issue is `package.json`
define files array which make the bundle only include the files in the files array.
So this PR install the zone.js package from the archive generated from `npm_package.pack` rule.
PR Close#38649
Because the compiler-cli tests modify node_modules, this can cause
failures on windows CI specifically as node_modules are symlinked
to rather than copied. By running the test and build actions in
separate commands, all of the tests are built to be executed before
and tests are executed and modify the node_modules content.
PR Close#39289
Constructing a project service is expensive. Making it a singleton could
speed up tests considerably.
On my MacBook Pro, test execution went from 24.4s to 14.5s (~40% improvement).
PR Close#39308
Test harness `setup()` is expensive, in the order of ~2.5 seconds.
We could speed up `fit()` tests considerably if `setup()` is wrapped
in `beforeAll()` to avoid running it unnecessarily.
PR Close#39305
This commit enables the Ivy Language Service to 'go to definition' of a
templateUrl or styleUrl, which would jump to the template/style file
itself.
PR Close#39202
These functions will be useful to the Ivy language service as well to
provide 'go to definition' functionality for template and style urls.
PR Close#39202
This commit edits the copy of the attribute binding documentation, moves the
colspan section that is primarily about property binding to the property
binding document, and adds a docregion to the attribute-binding
example to help clarify a point in the document.
Part of the copy edit reformats the style precedence list in tabular format
so that it is easier to read and understand.
PR Close#38860
This tool can be run from anywhere in the aio folder as:
```sh
yarn create-example <example-name>
```
It will create some basic scaffold files to get the example started.
After creation the developer should then use `yarn boilerplate:add`
or similar to ensure that the example can be run and tested.
You can optionally provide an absolute path to a pre-existing CLI
project and it will copy over appropriate files (ignoring boilerplate)
to the newly created example.
```sh
yarn create-example <example-name> /path/to/other/cli/project
```
Fixes#39275
PR Close#39283
Use the bypass-specific Trusted Types policy for automatically upgrade
any values from custom sanitizers or the bypassSecurityTrust functions
to a Trusted Type. Update tests to reflect the new behavior.
PR Close#39218
When an application uses a custom sanitizer or one of the
bypassSecurityTrust functions, Angular has no way of knowing whether
they are implemented in a secure way. (It doesn't even know if they're
introduced by the application or by a shady third-party dependency.)
Thus using Angular's main Trusted Types policy to bless values coming
from these two sources would undermine the security that Trusted Types
brings.
Instead, introduce a Trusted Types policy called angular#unsafe-bypass
specifically for blessing values from these sources. This allows an
application to enforce Trusted Types even if their application uses a
custom sanitizer or the bypassSecurityTrust functions, knowing that
compromises to either of these two sources may lead to arbitrary script
execution. In the future Angular will provide a way to implement
custom sanitizers in a manner that makes better use of Trusted Types.
PR Close#39218
Make Angular's HTML sanitizer return a TrustedHTML, as its output is
trusted not to cause XSS vulnerabilities when used in a context where a
browser may parse and evaluate HTML. Also update tests to reflect the
new behaviour.
PR Close#39218
Sanitizers in Angular currently return strings, which will then
eventually make their way down to the DOM, e.g. as the value of an
attribute or property. This may cause a Trusted Types violation. As a
step towards fixing that, make it possible to return Trusted Types from
the SanitizerFn interface, which represents the internal sanitization
pipeline. DOM renderer interfaces are also updated to reflect the fact
that setAttribute and setAttributeNS must be able to accept Trusted
Types.
PR Close#39218
The JIT compiler uses the Function constructor to compile arbitrary
strings into executable code at runtime, which causes Trusted Types
violations. To address this, JitEvaluator is instead made to use the
Trusted Types compatible Function constructor introduced by Angular's
Trusted Types policy for JIT.
PR Close#39210
Introduce a Trusted Types policy for use by Angular's JIT compiler named
angular#unsafe-jit. As the compiler turns arbitrary untrusted strings
into executable code at runtime, using Angular's main Trusted Types
policy does not seem appropriate, unless it can be ensured that the
provided strings are indeed trusted. Until then, this JIT policy can be
allowed by applications that rely on the JIT compiler but want to
enforce Trusted Types, knowing that a compromise of the JIT compiler can
lead to arbitrary script execution. In particular, this is required for
enabling Trusted Types in Angular unit tests, since they make use of the
JIT compiler.
Also export the internal Trusted Types definitions from the core package
so that they can be used in the compiler package.
PR Close#39210
When reading globals such as `ngDevMode` the read should be guarded by `typeof ngDevMode` otherwise it will throw if not
defined in `"use strict"` mode.
PR Close#36055
getCheckNoChangesMode was discovered to be unclear as to the purpose of
it. This refactor is a simple renaming to make it much clearer what that
method and property does.
PR Close#39277
When an input name is part of the directive selector, it would be good to return the directive as well
when performing 'go to definition' or 'go to type definition'. As an example, this would allow
'go to type definition' for ngIf to take the user to the NgIf directive.
'Go to type definition' would otherwise return no results because the
input is a generic type. This would also be the case for all primitive
input types.
PR Close#39243
Previously, temporary branches were created to be used for comparison to
the g3 branch, instead comparisons are now done using the branches
latest shas.
PR Close#39137
The Displaying Data in Views topic is actually a small tutorial
that describes Angular features such as interpolation and
structural directives. These content is already covered in
our getting started tutorial and in Tour of Heroes.
This change adds redirects to the Template Syntax section
of the Getting Started tutorial and deletes displaying-data.md.
PR Close#38885
Since the `11.0.x` branch was created, we change the master branch version to be 11.1.0-next.0
(i.e. next minor version after v11.0.0 release).
PR Close#39292
Angular treats constant values of attributes and properties in templates
as secure. This means that these values are not sanitized, and are
instead passed directly to the corresponding setAttribute or setProperty
function. In cases where the given attribute or property is
security-sensitive, this causes a Trusted Types violation.
To address this, functions for promoting constant strings to each of the
three Trusted Types are introduced to Angular's private codegen API. The
compiler is updated to wrap constant strings with calls to these
functions as appropriate when constructing the `consts` array. This is
only done for security-sensitive attributes and properties, as
classified by Angular's dom_security_schema.
PR Close#39211
The @types/trusted-types type definitions are currently imported in
types.d.ts, which causes them to eventually be imported in core.d.ts.
This forces anyone compiling against @angular/core to provide the
@types/trusted-types package in their compilation unit, which we don't
want.
To address this, get rid of the @types/trusted-types and instead import
a minimal version of the Trusted Types type definitions directly into
Angular's codebase.
Update the existing references to Trusted Types to point to the new
definitions.
PR Close#39211
Zone.js support `Angular package format` since `0.11`, but the `fesm2015` bundles
are not `esm` format, it still use `umd` bundle which is not correct, in this PR,
a new `esm` bundle output is added in `rollup_bundle` rule under `tools`, so
zone.js can use the new rule to generate `esm` bundles.
PR Close#39203
Previously, inline exports of the form `exports.foo = <implementation>;` were
being interpreted (by the ngtsc `PartialInterpeter`) as `Reference` objects.
This is not what is desired since it prevents the value of the export
from being unpacked, such as when analyzing `NgModule` declarations:
```
exports.directives = [Directive1, Directive2];
@NgImport({declarations: [exports.directives]})
class AppModule {}
```
In this example the interpreter would think that `exports.directives`
was a reference rather than an array that needs to be unpacked.
This bug was picked up by the ngcc-validation repository. See
https://github.com/angular/ngcc-validation/pull/1990 and
https://circleci.com/gh/angular/ngcc-validation/17130
PR Close#39267
Some inline declarations are of the form:
```
exports.<name> = <implementation>;
```
In this case the declaration `node` is `exports.<name>`.
When interpreting such inline declarations we actually want
to visit the `implementation` expression rather than visiting
the declaration `node`.
This commit adds `implementation?: ts.Expression` to the
`InlineDeclaration` type and updates the interpreter to visit
these expressions as described above.
PR Close#39267
Support for IE<11 is being removed in v11. PR #39090 removed some code
that was no longer needed.
Now that there are no longer multiple code-paths (which was previously
needed for IE<11 support), this commit simplifies the code further (for
example, to avoid unnecessary functions calls and to avoid iterating
over a component's inputs multiple times).
PR Close#39265
This commit fixes a bug in which a new Ivy Compiler is created every time
language service receives a new request. This is not needed if the
`ts.Program` has not changed.
A new class `CompilerFactory` is created to manage Compiler lifecycle and
keep track of template changes so that it knows when to override them.
With this change, we no longer need the method `getModifiedResourceFile()`
on the adapter. Instead, we call `overrideComponentTemplate` on the
template type checker.
This commit also changes the incremental build strategy from
`PatchedIncrementalBuildStrategy` to `TrackedIncrementalBuildStrategy`.
PR Close#39231
This commit updates micro benchmarks to use relative path to Ivy runtime code. Keeping absolute
locations caused issues with build optimizer that retained certain symbols and they appeared in the
output twice.
PR Close#39142
This commit adds micro benchmarks to run micro benchmarks for i18n-related logic in the
following scenarios:
- i18n static attributes
- i18n attributes with interpolations
- i18n blocks of static text
- i18n blocks of text + interpolations
- simple ICUs
- nested ICUs
First 4 scenarios also have baseline scenarios (non-i18n) so that we can compare i18n perf with
non-i18n logic.
PR Close#39142
Rather than setting up windows by relying on attaching the saved workspace
failes from the previous step, instead checkout and install the yarn items
within the windows steps. Additionally, since the bazel remote cache is
used and relied on, saving the cached results of the bazel runs to be resumed
on subsequent runs does not provide enough value to make it worth the time
consumed.
PR Close#39139
Previously windows CI jobs were only run on upstream branches, with the addition
of larger Windows executors as well as the improvement of setup speed in the
windows environment setup script allows for the windows tests to pass in a
reasonable timeframe.
PR Close#39139
Add a schematic to update users to the new v11 `initialNavigation`
options for `RouterModule`. This replaces the deprecated/removed
`true`, `false`, `legacy_disabled`, and `legacy_enabled` options
with the newer `enabledBlocking` and `enabledNonBlocking` options.
PR Close#36926
As of Angular v4, four of the options for
`ExtraOptions#initialNavigation` have been deprecated. We intend
to remove them in v11. The final state for these options is:
`enabledBlocking`, `enabledNonBlocking`, and `disabled`. We plan
to remove and deprecate the remaining option in the next two
major releases.
New options:
- `enabledNonBlocking`: same as legacy_enabled
- `enabledBlocking`: same as enabled
BREAKING CHANGE:
* The `initialNavigation` property for the options in
`RouterModule.forRoot` no longer supports `legacy_disabled`,
`legacy_enabled`, `true`, or `false` as valid values.
`legacy_enabled` (the old default) is instead `enabledNonBlocking`
* `enabled` is deprecated as a valid value for the
`RouterModule.forRoot` `initialNavigation` option. `enabledBlocking`
has been introduced to replace it
PR Close#37480
Remove preserveQueryParams as it was deprecated for removal in v4, use
queryParamsHandling="preserve" instead.
BREAKING CHANGE: preserveQueryParams has been removed, use
queryParamsHandling="preserve" instead
PR Close#38762
When ngcc is configured to run with the `--use-program-dependencies`
flag, as is the case in the CLI's asynchronous processing, it will scan
all source files in the program, starting from the program's root files
as configured in the tsconfig. Each individual root file could
potentially rescan files that had already been scanned for an earlier
root file, causing a severe performance penalty if the number of root
files is large. This would be the case if glob patterns are used in the
"include" specification of a tsconfig file.
This commit avoids the performance penalty by keeping track of the files
that have been scanned across all root files, such that no source file
is scanned multiple times.
Fixes#39240
PR Close#39254
Address a Trusted Types violation that occurs in createNamedArrayType
during development mode. Instead of passing strings directly to "new
Function", use the Trusted Types compatible function constructor exposed
by the Trusted Types policy.
PR Close#39209
Chrome currently does not support passing TrustedScript to the Function
constructor, and instead fails with a Trusted Types violation when
called. As the Function constructor is used in a handful of places
within Angular, such as in the JIT compiler and named_array_type, the
workaround proposed on the following page is implemented:
https://github.com/w3c/webappsec-trusted-types/wiki/Trusted-Types-for-function-constructor
To be precise, it constructs a string representing an anonymous function
in a way that is equivalent to what the Function constructor does,
promotes it to a TrustedScript and then calls eval.
To facilitate backwards compatibility, new Function is used directly in
environments that do not support Trusted Types.
PR Close#39209
- The current initial triage does not include PRs. This includes them by removing the issue filter
- The merge assistance label is often applied to PRs that do not have
status=success. Caretaker should handle these as well
PR Close#39257
In `FakeAsyncZoneSpec`, there are several variables and APIs to identify
different times, and the names are confusing, in this commit, they are
renamed for more clear understandings.
1. currentTickTime, the tick millis advanced.
2. getFakeBaseSystemTime(), return the fake base system time.
3. setFakeBaseSystemTime(), set the fake base system time.
4. getRealSystemTime(), get the underlying native system time.
PR Close#39127
`jest.getRealSystemTime()` should return native `Date.now()`, the
current implemenation return the wrong value which is the fixed
number.
PR Close#39127
This commit removes a workaround previously used for IE 9 and 10 to identify whether InjectableDef
was defined on a given class instance. Since support for IE 9 and 10 is removed, this fallback is
no longer needed.
PR Close#39090
This commit removes IE 9 and IE 10 checks from the browser detection spec.
Also unblocks tests that were previously disabled due to issues in IE10.
PR Close#39090
This commit updates core tests and removes the code needed to support IE 9 and IE 10 only.
The code is no longer needed since IE 9 and IE 10 support is removed in v11.
PR Close#39090
When Angular is used in an environment that enforces Trusted Types, the
inert DOM builder raises a Trusted Types violation due to its use of
DOMParser and element.innerHTML with plain strings. Since it is only
used internally (in the HTML sanitizer and for i18n ICU parsing), we
update it to use Angular's Trusted Types policy to promote the provided
HTML to TrustedHTML.
PR Close#39208
Since we are merged https://github.com/angular/angular/issues/38851 PR
about integration of jest.useFakeTimers with fakeAsync, so the
new release should also include this feature, this PR updated the zone.js
0.11.2 changelog.
PR Close#39126
Add a module that provides a Trusted Types policy for use internally by
Angular. The policy is created lazily and stored in a module-local
variable. For now the module does not allow configuring custom policies
or policy names, and instead creates its own policy with 'angular' as a
fixed policy name. This is to more easily support tree-shakability.
Helper functions for unsafely converting strings to each of the three
Trusted Types are also introduced, with documentation that make it clear
that their use requires a security review. When Trusted Types are not
available, these helper functions fall back to returning strings.
PR Close#39207
To facilitate the upcoming Trusted Types support being added to Angular,
add the TypeScript type definitions for the Trusted Types browser API as
a dependency in the root package.json and types.d.ts since they're
needed for compiling the Angular packages.
PR Close#39207
Adds a migration that finds all imports and calls to the deprecated `async` function from
`@angular/core/testing` and replaces them with `waitForAsync`.
These changes also move a bit of code out of the `Renderer2` migration so that it can be reused.
PR Close#39212
For directives/components, it would be generally more appropriate for
"go to type definition" to be the function which navigates to the class
definition. However, for a better user experience, we should do this
for "go to definition" as well.
PR Close#39228
This make it coherent with typing of Router.createUrlTree to which
those inputs are directly forwarded to. And hence it allow to pass
`undefined`, `null` or a value to the routerLink directive.
BREAKING CHANGE: in most cases this should not break, but if you were
accessing the values of `queryParams`, `fragment` or `queryParamsHandling`
you might need to relax the typing to also accept `undefined` and `null`.
Signed-off-by: Adrien Crivelli <adrien.crivelli@gmail.com>
PR Close#39151
Previously, the `isCommitClosingPullRequest()` method (used in
`ng-dev release` to detect whether a commit is closing a PR based on
keywords found in the commit message) was only able to detect a subset
of the keywords supported by GitHub.
This is fine currently, because the merge script adds `PR Close #XYZ`
when merging a PR, but it might break in the future.
This commit makes the code more robust by ensuring the method can detect
all keywords supported by GitHub for automatically closing a PR based on
a commit message.
Original discussion:
https://github.com/angular/angular/pull/39135#discussion_r503440973
PR Close#39229
In #39135, the commit message string was accidentally changed from a
template literal to a regular string literal. This prevented the
`npmDistTag` variable from being correctly displayed in the error
message.
This commit fixes it by switching it back to a template literal.
NOTE:
This was pointed out in
https://github.com/angular/angular/pull/39135#discussion_r503361412, but
the PR was accidentally merged before the review feedback had been
addressed.
PR Close#39229
The `ng-dev release publish` command needs to check whether a commit
closed a pull request. This is implemented via checking the commit
message for specific closing keywords referencing the pull request
number.
The regex used previously failed to correctly ensure that the specified
pull request was referenced. For example, it would allow `#12345` to
also match for `#1234`.
This commit fixes the regex.
PR Close#39135
This should not change behavior, but it prevents false-positive warnings in various static analysis
tools, including tools used internally at Google.
PR Close#37397
Previously the `node.name` property was only checked to ensure it was
defined. But that meant that it was a `ts.BindingName`, which also includes
`ts.BindingPattern`, which we do not support. But these helper methods were
forcefully casting the value to `ts.Identifier.
Now we also check that the `node.name` is actually an `ts.Identifier`.
PR Close#38959
Previously directive "queries" that relied upon a namespaced type
```ts
queries: {
'mcontent': new core.ContentChild('test2'),
}
```
caused an error to be thrown. This is now supported.
PR Close#38959
Previously, any declarations that were defined "inline" were not
recognised by the `UmdReflectionHost`.
For example, the following syntax was completely unrecognized:
```ts
var Foo_1;
exports.Foo = Foo_1 = (function() {
function Foo() {}
return Foo;
})();
exports.Foo = Foo_1 = __decorate(SomeDecorator, Foo);
```
Such inline classes were ignored and not processed by ngcc.
This lack of processing led to failures in Ivy applications that relied
on UMD formats of libraries such as `syncfusion/ej2-angular-ui-components`.
Now all known inline UMD exports are recognized and processed accordingly.
Fixes#38947
PR Close#38959
Previously these tests were checking multiple specific expression
types. The new helper function is more general and will also support
`PropertyAccessExpression` nodes for `InlineDeclaration` types.
PR Close#38959
Previously the `ConcreteDeclaration` and `InlineDeclaration` had
different properties for the underlying node type. And the `InlineDeclaration`
did not store a value that represented its declaration.
It turns out that a natural declaration node for an inline type is the
expression. For example in UMD/CommonJS this would be the `exports.<name>`
property access node.
So this expression is now used for the `node` of `InlineDeclaration` types
and the `expression` property is dropped.
To support this the codebase has been refactored to use a new `DeclarationNode`
type which is a union of `ts.Declaration|ts.Expression` instead of `ts.Declaration`
throughout.
PR Close#38959
This makes these tests more resilient to changes in the test code
structure. For example switching from
```
var SomeClass = <implementation>;
exports.SomeClass = SomeClass;
```
to
```
exports.SomeClass = <implementation>;
```
PR Close#38959
Previously `getDeclaration()` would only return the first node that matched
the name passed in and then assert the predicate on this single node.
It also only considered a subset of possible declaration types that we might
care about.
Now the function will parse the whole tree collecting an array of all the
nodes that match the name. It then filters this array based on the predicate
and only errors if the filtered array is empty.
This makes this function much more resilient to more esoteric code formats
such as UMD.
PR Close#38959
The new function does not try to restrict the kind of AST node that it
finds, leaving that to the caller. This will make it more resuable in the
UMD reflection host.
PR Close#38959
Sometimes UMD exports appear in the following form:
```
exports.MyClass = alias1 = alias2 = <<declaration>>
```
Previously the declaration of the export would have been captured
as `alias1 = alias2 = <<declaration>>`, which the `PartialInterpreter`
would have failed on, since it cannot handle assignments.
Now we skip over these aliases capturing only the `<<declaration>>`
expression.
Fixes#38947
PR Close#38959
UMD files export values by assigning them to an `exports` variable.
When evaluating expressions ngcc was failing to cope with expressions
like `exports.MyComponent`.
This commit fixes the `UmdReflectionHost.getDeclarationOfIdentifier()`
method to map the `exports` variable to the current source file.
PR Close#38959
The `SIMPLE_CLASS_FILE` contained a `ChildClass` that had an
internal aliases implementation and extended a `SuperClass` base
class. The call to `__extends` was using the wrong argument for
the child class.
PR Close#38959
This clarifies that this is specifically about statements of the form
`exports.<name> = <declaration>`, rather than a general export
statement such as `export class <ClassName> { ... }`.
PR Close#38959
There is no need to check that the `ref.node` is of any particular type
because immediately after this check the entry is tested to see if it passes
`isClassDeclarationReference()`.
The only difference is that the error that is reported is slightly different
in the case that it is a `ref` but not one of the TS node types.
Previously:
```
`Value at position ${idx} in the NgModule.${arrayName} of ${
className} is not a reference`
```
now
```
`Value at position ${idx} in the NgModule.${arrayName} of ${
className} is not a class`
```
Arguably the previous message was wrong, since this entry IS a reference
but is not a class.
PR Close#38959
Since IE 9 and IE 10 were deprecated and support is removed in v11, this commit updates ZoneJs
configs to avoid running tests in these browsers.
PR Close#39189
When working on the docs, it is helpful to run a local instance of the
angular.io app and run scripts that watch both the docs contents and the
app build artifacts to automatically update the running instance on
changes. Typically, this is achieved via the `start` and `docs-watch`
npm scripts. As a convenience, one can run the `serve-and-sync` script,
which runs both in one terminal.
Previously, it was not possible to pass arguments to `ng nerve` (which
is what the `start` script runs under the hood) when running it via
`serve-and-sync`.
This commit adds support for passing any arguments passed to
`serve-and-sync` through to the `start` script. This can be useful for
things like specifying a custom host or port.
PR Close#39201
A common review request is updating the commit message of a commit.
Since this is something that is not straight forward for inexperienced
contributors, it is useful to be able to point a contributor to some
docs outlining the process.
This commit adds such a section in `CONTRIBUTING.md` (as discussed in
https://github.com/angular/angular/pull/39110#discussion_r499935502).
PR Close#39215
Although in SSR we patch the global prototypes with DOM globals
like Element and Node, this patch does not occur before the
matches function is called in Angular Elements. This is similar
to the behavior in @angular/upgrade.
Fixes#24551
PR Close#37799
At a high level, the current shadow DOM shim logic works by escaping the content of a CSS rule
(e.g. `div {color: red;}` becomes `div {%BLOCK%}`), using a regex to parse out things like the
selector and the rule body, and then re-adding the content after the selector has been modified.
The problem is that the regex has to be very broad in order capture all of the different use cases,
which can cause it to match strings suffixed with a semi-colon in some places where it shouldn't,
like this URL from Google Fonts `https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap`.
Most of the time this is fine, because the logic that escapes the rule content to `%BLOCK%` will
have converted it to something that won't be matched by the regex. However, it breaks down for rules
like `@import` which don't have a body, but can still have quoted content with characters that can
match the regex.
These changes resolve the issue by making a second pass over the escaped string and replacing all
of the remaining quoted content with `%QUOTED%` before parsing it with the regex. Once everything
has been processed, we make a final pass where we restore the quoted content.
In a previous iteration of this PR, I went with a shorter approach which narrowed down the
regex so that it doesn't capture rules without a body. It fixed the issue, but it also ended
up breaking some of the more contrived unit test cases. I decided not to pursue it further, because
we would've ended up with a very long and brittle regex that likely would've broken in even weirder
ways.
Fixes#38587.
PR Close#38716
Bump Chrome to the next stable release (84.0.4147) by following the
instructions in dev-infra/browsers/README.md.
With Chrome 86 about to be released as stable, the current local version
(Chrome 83) is starting to lag behind. It also contains a bug that
blocks Angular unit and integration tests from using Trusted Types.
PR Close#39179
Removes `ViewEncapsulation.Native` which has been deprecated for several major versions.
BREAKING CHANGES:
* `ViewEncapsulation.Native` has been removed. Use `ViewEncapsulation.ShadowDom` instead. Existing
usages will be updated automatically by `ng update`.
PR Close#38882
Expressions within ICU expressions in templates were not previously
type-checked, as they were skipped while traversing the elements
within a template. This commit enables type checking of these
expressions by actually visiting the expressions.
BREAKING CHANGE:
Expressions within ICUs are now type-checked again, fixing a regression
in Ivy. This may cause compilation failures if errors are found in
expressions that appear within an ICU. Please correct these expressions
to resolve the type-check errors.
Fixes#39064
PR Close#39072
Prior to this change, expressions within ICUs would have a source span
corresponding with the whole ICU. This commit narrows down the source
spans of these expressions to the exact location in the source file, as
a prerequisite for reporting type check errors within these expressions.
PR Close#39072
Updates to rules_nodejs 2.2.0. This is the first major release in 7 months and includes a number of features as well
as breaking changes.
Release notes: https://github.com/bazelbuild/rules_nodejs/releases/tag/2.0.0
Features of note for angular/angular:
* stdout/stderr/exit code capture; this could be potentially be useful
* TypeScript (ts_project); a simpler tsc rule that ts_library that can be used in the repo where ts_library is too
heavy weight
Breaking changes of note for angular/angular:
* loading custom rules from npm packages: `ts_library` is no longer loaded from `@npm_bazel_typescript//:index.bzl`
(which no longer exists) but is now loaded from `@npm//@bazel/typescript:index.bzl`
* with the loading changes above, `load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies")` is
no longer needed in the WORKSPACE which also means that yarn_install does not need to run unless building/testing
a target that depends on @npm. In angular/angular this is a minor improvement as almost everything depends on @npm.
* @angular/bazel package is also updated in this PR to support the new load location; Angular + Bazel users that
require it for ng_package (ng_module is no longer needed in OSS with Angular 10) will need to load from
`@npm//@angular/bazel:index.bzl`. I investigated if it was possible to maintain backward compatability for the old
load location `@npm_angular_bazel` but it is not since the package itself needs to be updated to load from
`@npm//@bazel/typescript:index.bzl` instead of `@npm_bazel_typescript//:index.bzl` as it depends on ts_library
internals for ng_module.
* runfiles.resolve will now throw instead of returning undefined to match behavior of node require
Other changes in angular/angular:
* integration/bazel has been updated to use both ng_module and ts_libary with use_angular_plugin=true.
The latter is the recommended way for rules_nodejs users to compile Angular 10 with Ivy. Bazel + Angular ViewEngine is
supported with @angular/bazel <= 9.0.5 and Angular <= 8. There is still Angular ViewEngine example on rules_nodejs
https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_view_engine on these older versions but users
that want to update to Angular 10 and are on Bazel must switch to Ivy and at that point ts_library with
use_angular_plugin=true is more performant that ng_module. Angular example in rules_nodejs is configured this way
as well: https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular. As an aside, we also have an
example of building Angular 10 with architect() rule directly instead of using ts_library with angular plugin:
https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_bazel_architect.
NB: ng_module is still required for angular/angular repository as it still builds ViewEngine & @angular/bazel
also provides the ng_package rule. ng_module can be removed in the future if ViewEngine is no longer needed in
angular repo.
* JSModuleInfo provider added to ng_module. this is for forward compat for future rules_nodejs versions.
PR Close#39182
This is a roll forward of #39082, using `ts.createIdentifier(`'legacy'`)` as a cross-version compatible way of making
a single quoted string literal.
Migrated code now uses single quotes, which is in line with the default linting options, so there is no lint error after
migration.
PR Close#39102
This PR enables `getSemanticDiagnostics()` to be called on external templates.
Several changes are needed to land this feature:
1. The adapter needs to implement two additional methods:
a. `readResource()`
Load the template from snapshot instead of reading from disk
b. `getModifiedResourceFiles()`
Inform the compiler that external templates have changed so that the
loader could invalidate its internal cache.
2. Create `ScriptInfo` for external templates in MockHost.
Prior to this, MockHost only track changes in TypeScript files. Now it
needs to create `ScriptInfo` for external templates as well.
For (1), in order to make sure we don't reload the template if it hasn't
changed, we need to keep track of its version. Since the complexity has
increased, the adapter is refactored into its own class.
PR Close#39065
With this change we add a short url to strict mode guide
(angular.io/strict -> angular.io/guide/strict-mode). This is important because
of two reasons.
1) Reduce the clutter in the terminal when we include the strict mode guide url in a prompt.
2) Easiler to share in conferences, slides etc..
PR Close#39129
Temporarily disable the //packages/compiler-cli/integrationtest:integrationtest
target while continuing to investigate its unknown failures
PR Close#39168
The right needs to be wrapped in parens or we cannot accurately match its
span to just the RHS. For example, the span in `e = $event /*0,10*/` is ambiguous.
It could refer to either the whole binary expression or just the RHS.
We should instead generate `e = ($event /*0,10*/)` so we know the span 0,10 matches RHS.
This is specifically needed for the TemplateTypeChecker/Language Service
when mapping template positions to items in the TCB.
PR Close#39143
Decorator API pages list all their available options in an overview
table and also in a detailed view. Now the rendered syntax of each
option will show a `?` after the name if the option is not required.
This is inline with how class and interface members are rendered.
PR Close#39167
This commit changes the heading of the section
`Use TypeScript path mapping for peer dependencies` to a sub-heading of
`Linked Libraries`.
Fixes#39130
PR Close#39131
As of #32671, the type of `AbstractControl.parent` can be null which can cause
compilation errors in existing apps. These changes add a migration that will append
non-null assertions to existing unsafe accesses.
````
// Before
console.log(control.parent.value);
// After
console.log(control.parent!.value);
```
The migration also tries its best to avoid cases where the non-null assertions aren't
necessary (e.g. if the `parent` was null checked already).
PR Close#39009
This commit introduces a new API for the `TemplateTypeChecker` which allows
for autocompletion in a global expression context (for example, in a new
interpolation expression such as `{{|}}`). This API returns instances of the
type `GlobalCompletion`, which can represent either a completion result from
the template's component context or a declaration such as a local reference
or template variable. The Language Service will use this API to implement
autocompletion within templates.
PR Close#39048
The template binding API in @angular/compiler exposes information about a
template that is synthesized from the template structure and its scope
(associated directives and pipes).
This commit introduces a new API, `getEntitiesInTemplateScope`, which
accepts a `Template` object (or `null` to indicate the root template) and
returns all `Reference` and `Variable` nodes that are visible at that level
of the template, including those declared in parent templates.
This API is needed by the template type-checker to support autocompletion
APIs for the Language Service.
PR Close#39048
Previously the value passed to `AstFactory.attachComments()` could be
`undefined` which is counterintuitive, since why attach something that
doesn't exist? Now it expects there to be a defined array. Further it no
longer returns a statement. Both these aspects of the interface were designed
to make the usage simpler but has the result of complicating the implemenation.
The `ExpressionTranslatorVisitor` now has a helper function (`attachComments()`)
to handle `leadingComments` being undefined and also returning the statement.
This keeps the usage in the translator simple, while ensuring that the `AstFactory`
API is not influenced by how it is used.
PR Close#39076
Fixed a boolean logic error that prevented hybrid visitor from returning
undefined when a variable does not have value and cursor is not in the
key span.
PR Close#39061
Prior to this change, the `validators` and `asyncValidators` fields of a few Forms directives
were typed as `any[]`. This commit updates the types and makes them consistent for all directives
in the Forms package.
BREAKING CHANGE:
Directives in the `@angular/forms` package used to have `any[]` as a type of `validators` and
`asyncValidators` arguments in constructors. Now these arguments are properly typed, so if your
code relies on directive constructor types it may require some updates to improve type safety.
PR Close#38944
In the `packages/examples/common/ngif/module.ts` file, the field `show` is given an explicit
boolean type. Since typescript infers boolean type, it is redundant and this commit removes it.
PR Close#39081
Using fixup commits when addressing review feedback can considerably
improve the review experience on subsequent reviews.
This commit adds information and guidelines for contributors on how to
work with fixup commits.
Fixes#33042
PR Close#39110
Migrates to using larger resource classes for windows CI runs as well as updating
the bazel rcs for windows and linux to use all/more of the resources available in
the executors
PR Close#39124
Previously, RouterTestingModule only assigned two of the options within ExtraOptions to the Router.
Now, it assigns the same options as RouterModule does (with the exception of enableTracing) via a
new shared function assignExtraOptionsToRouter.
Fixes#23347
PR Close#39096
Rather than having the Ivy implementation add the VE code to the deps
list, create a new common package that both Ivy and VE depend on. This
will make it more straightforward in the future to remove the VE code
completely.
PR Close#39098
This is needed so that the Language Service can provide the module name
in the quick info for a directive/component.
To accomplish this, the compiler's `LocalModuleScope` is provided to the
`TemplateTypeCheckerImpl`. This will also allow the `TemplateTypeChecker` to
provide more completions in the future, giving it a way to determine all the
directives/pipes/etc. available to a template.
PR Close#39099
The expression parser already has support for recovering on malformed
property reads, but did not have tests describing the recovered ast in
such cases. This commit adds tests to demonstrate such cases; in
particular, the recovered ast is a full PropertyRead but with an empty
property name. This is likely the most preferred option, as it does not
constrain consumers of the AST to what the property name should look
like. Furthermore, we cannot mark the property name as empty in any
other way (e.g. an EmptyExpr) because the property name, as of present,
is a string field rather than an AST itself.
Note that tokens past a malformed property read are not preserved in the
AST (for example in `foo.1234`, `1234` is not preserved in the AST).
This is because the extra tokens do not belong to the singular
expression created by the property read, and there is not a meaningful
way to interpret a secondary expression in a single parsed expression.
Part of #38596
PR Close#38998
Close#38851, support `jest` fakeTimers APIs' integration with `fakeAsync()`.
After enable this feature, calling `jest.useFakeTimers()` will make all test
run into `fakeAsync()` automatically.
```
beforeEach(() => {
jest.useFakeTimers('modern');
});
afterEach(() => {
jest.useRealTimers();
});
test('should run into fakeAsync() automatically', () => {
const fakeAsyncZoneSpec = Zone.current.get('FakeAsyncTestZoneSpec');
expect(fakeAsyncZoneSpec).toBeTruthy();
});
```
Also there are mappings between `jest` and `zone` APIs.
- `jest.runAllTicks()` will call `flushMicrotasks()`.
- `jest.runAllTimers()` will call `flush()`.
- `jest.advanceTimersByTime()` will call `tick()`
- `jest.runOnlyPendingTimers()` will call `flushOnlyPendingTimers()`
- `jest.advanceTimersToNextTimer()` will call `tickToNext()`
- `jest.clearAllTimers()` will call `removeAllTimers()`
- `jest.getTimerCount()` will call `getTimerCount()`
PR Close#39016
It's perfectly valid for an abstract control not to have a defined parent; yet previously the
types were asserting that AbstractControl#parent is not a null value. This changes correctly
reflects the run-time behavior through the types.
BREAKING CHANGE: Type of AbstractFormControl.parent now includes null
`null` is now included in the types of .parent. If you don't already have a check for this case,
the TypeScript compiler might compain. A v11 migration exists which adds the not-null assertion
operator where necessary.
In an unlikely case your code was testing the parnet against undefined with sitrct equality,
you'll need to change this to `=== null` instead, since the parent is not explicily initialized
with `null` instead of being left `undefined`.
Fixes#16999
PR Close#32671
This patch refactors the interpolation parser to do so iteratively
rather than using a regex. Doing so prepares us for supporting granular
recovery on poorly-formed interpolations, for example when an
interpolation does not terminate (`{{ 1 + 2`) or is not terminated
properly (`{{ 1 + 2 {{ 2 + 3 }}`).
Part of #38596
PR Close#38977
The compiler maintains an internal dependency graph of all resource
dependencies for application source files. This information can be useful
for tools that integrate the compiler and need to support file watching.
This change adds a `getResourceDependencies` method to the
`NgCompiler` class that allows compiler integrations to access resource
dependencies of files within the compilation.
PR Close#38048
This patch adds support for recovering well-formed (and near-complete)
ASTs for semantically malformed keyed reads and keyed writes. See the
added tests for details on the types of semantics we can now recover;
in particular, notice that some assumptions are made about the form of
a keyed read/write intended by a user. For example, in the malformed
expression `a[1 + = 2`, we assume that the user meant to write a binary
expression for the key of `a`, and assign that key the value `2`. In
particular, we now parse this as `a[1 + <empty expression>] = 2`. There
are some different interpretations that can be made here, but I think
this is reasonable.
The actual changes in the parser code are fairly minimal (a nice
surprise!); the biggest addition is a `writeContext` that marks whether
the `=` operator can serve as a recovery point after error detection.
Part of #38596
PR Close#39004
Previously, when a heading was longer than the Table of Content's (TOC)
width and it had to be wrapped into multiple lines, it was hard to
distinguish the subsequent lines from other TOC entries (i.e. other
headings).
This commit makes it easier to visually distinguish wrapped heading
lines from other headings by reducing the spacing between wrapped lines
of the same heading (making it more obvious that they belong together).
PR Close#39092
Updates to rules_nodejs 2.2.0. This is the first major release in 7 months and includes a number of features as well
as breaking changes.
Release notes: https://github.com/bazelbuild/rules_nodejs/releases/tag/2.0.0
Features of note for angular/angular:
* stdout/stderr/exit code capture; this could be potentially be useful
* TypeScript (ts_project); a simpler tsc rule that ts_library that can be used in the repo where ts_library is too
heavy weight
Breaking changes of note for angular/angular:
* loading custom rules from npm packages: `ts_library` is no longer loaded from `@npm_bazel_typescript//:index.bzl`
(which no longer exists) but is now loaded from `@npm//@bazel/typescript:index.bzl`
* with the loading changes above, `load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies")` is
no longer needed in the WORKSPACE which also means that yarn_install does not need to run unless building/testing
a target that depends on @npm. In angular/angular this is a minor improvement as almost everything depends on @npm.
* @angular/bazel package is also updated in this PR to support the new load location; Angular + Bazel users that
require it for ng_package (ng_module is no longer needed in OSS with Angular 10) will need to load from
`@npm//@angular/bazel:index.bzl`. I investigated if it was possible to maintain backward compatability for the old
load location `@npm_angular_bazel` but it is not since the package itself needs to be updated to load from
`@npm//@bazel/typescript:index.bzl` instead of `@npm_bazel_typescript//:index.bzl` as it depends on ts_library
internals for ng_module.
* runfiles.resolve will now throw instead of returning undefined to match behavior of node require
Other changes in angular/angular:
* integration/bazel has been updated to use both ng_module and ts_libary with use_angular_plugin=true.
The latter is the recommended way for rules_nodejs users to compile Angular 10 with Ivy. Bazel + Angular ViewEngine is
supported with @angular/bazel <= 9.0.5 and Angular <= 8. There is still Angular ViewEngine example on rules_nodejs
https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_view_engine on these older versions but users
that want to update to Angular 10 and are on Bazel must switch to Ivy and at that point ts_library with
use_angular_plugin=true is more performant that ng_module. Angular example in rules_nodejs is configured this way
as well: https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular. As an aside, we also have an
example of building Angular 10 with architect() rule directly instead of using ts_library with angular plugin:
https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_bazel_architect.
NB: ng_module is still required for angular/angular repository as it still builds ViewEngine & @angular/bazel
also provides the ng_package rule. ng_module can be removed in the future if ViewEngine is no longer needed in
angular repo.
* JSModuleInfo provider added to ng_module. this is for forward compat for future rules_nodejs versions.
@josephperrott, this touches `packages/bazel/src/external.bzl` which will make the sync to g3 non-trivial.
PR Close#37727
This commit adds a new command to the `ng-dev` suite, which verifies that the NgBot YAML config is
correct. It also adds this command to the `lint` CircleCI job so that we execute this check while
running CI.
This should help prevent syntax errors similar to the one introduced in:
393ce5574b
PR Close#39071
This updates the migration to align with the style guide and work with default lint rules. It avoids a lint error on
newly migrated projects and fixes a test in the CLI repo.
PR Close#39070
This commit adds some TODO comments in `tslint.json` regardling rules
that need to be enabled or removed to more closely align `tslint.json`
with the one generated by the latest Angular CLI for new apps.
Updating these rules generates a lot of linting failures, so fixing
them is outside the scope of this PR.
PR Close#39018
This commit removes the `only-arrow-functions: false` tslint rule to
more closely align `tslint.json` with the one generated by the latest
Angular CLI for new apps.
PR Close#39018
This commit updates the `object-literal-key-quotes` tslint rule to more
closely align `tslint.json` with the one generated by the latest Angular
CLI for new apps.
PR Close#39018
This commit removes the `no-string-literal: false` tslint rule to
more closely align `tslint.json` with the one generated by the latest
Angular CLI for new apps.
PR Close#39018
This commit enables the `no-redundant-jsdoc` tslint rule to more closely
align `tslint.json` with the one generated by the latest Angular CLI for
new apps.
PR Close#39018
This commit re-organizes the `tslint.json` configuration file to more
closely align with the one generated by the latest Angular CLI for new
apps. This makes it easier to see the difference with new CLI versions
in the future and keep our `tslint.json` up-to-date (while keeping our
own rules).
NOTE:
This commit only re-orders rules and removes redundant ones. It does not
change the linting behavior.
PR Close#39018
This commit adds the `AstHost` interface, along with implementations for
both Babel and TS.
It also implements the Babel vesion of the `AstFactory` interface, along
with a linker specific implementation of the `ImportGenerator` interface.
These classes will be used by the new "ng-linker" to transform prelinked
library code using a Babel plugin.
PR Close#38866
The `AstFactory.createFunctionDeclaration()` was allowing `null` to be
passed as the function `name` value. This is not actually possible, since
function declarations must always have a name.
PR Close#38866
The tests were assuming that newlines were `\n` characters but this is not
the case on Windows. This was fixed in #38925, but a better solution is to
configure the TS printer to always use `\n` characters for newlines.
PR Close#38866
Issue triage _currently_ requires a component to be set and one of the following to be true for an issue to be
considered triaged:
* Marked as a bug _and_ has a severity _and_ has a frequency
* Mark as a feature
* Marked as a refactor
* Marked as a discussion
* Marked as "confusing"
* Marked as "use-case"
This PR changes the rules so that (in addition to the component), triage
requires:
* A priority label (P0 through P5)
* Marked as a feature
* Marked as a discussion
Triage may also apply additional, optional info labels to issues.
[This document outlines the new priority
scheme](https://docs.google.com/document/d/1mN2zWsr1pxChSTHC7UkOgl4PhhuoFONtG_zcMWeqLwA/preview).
While this PR is focused on issue triage and not PR triage, I have
changed the PR section triage to remove reference to the "effort: *" and
"risk: *" labels. Looking through recent PRs, Kapunahele is the only
person applying these, so it's clear that this bit is no longer widely
practiced.
This is just one step in the always-ongoing process of managing GitHub
labels. More adjustments will come over time. In writing this PR, I have
already unearthed a few more areas that can be polished in follow-ups.
PR Close#38932
In certain circumstances (errors during component constructor) the router outlet may not be activated before
redirecting to a new route. If the new route requires running guards and resolvers the current logic will throw
when accessing outlet.component due to an isActivated check within the property getter. This update brings the
logic inline with deactivateRouterAndItsChildren, namely checking outlet.isActivated before trying to access
outlet.component.
Fixes#39030
PR Close#39049
With this change we update the strict mode documentation to reflect the
changes done in the CLI. (https://github.com/angular/angular-cli/pull/18931)
Changes effect
- Removing `no-any` tslint rule
- The special sideEffects package.json
- Added `strictTemplates` NGC option
PR Close#39054
These free standing functions rely upon the "current" `FileSystem`,
but it is safer to explicitly pass the `FileSystem` into functions or
classes that need it.
Fixes#38711
PR Close#39006
These free standing functions rely upon the "current" `FileSystem`,
but it is safer to explicitly pass the `FileSystem` into functions or
classes that need it.
PR Close#39006
To verify the correctness of the linker output, we leverage the existing
compliance tests. The plan is to test the linker by running all compliance
tests using a full round trip of pre-linking and subsequently post-linking,
where the generated code should be identical to a full AOT compile.
This commit adds an additional Bazel target that runs the compliance
tests in partial mode. Follow-up work is required to implement the logic
for running the linker round trip.
PR Close#38938
This is a precursor to introducing the Angular linker. As an initial
step, a compiler option to configure the compilation mode is introduced.
This option is initially internal until the linker is considered ready.
PR Close#38938
It used to be the case that all microsyntax bindings share the same source
span, so the second bound attribute would overwrite the first.
This has been fixed in #39036, this case is added to prevent regression.
PR Close#39062
Create stubs for getTypeDefinitionAtPosition for both VE and Ivy Language Service implementations.
This will prevent failed requests when it is implemented on the vscode plugin side
PR Close#39050
* Add `templateNode` to `ElementSymbol` and `TemplateSymbol` so callers
can use the information about the attributes on the
`TmplAstElement`/`TmplAstTemplate` for directive matching
* Remove helper function `getSymbolOfVariableDeclaration` and favor
more specific handling for scenarios. The generic function did not
easily handle different scenarios for all types of variable declarations
in the TCB
PR Close#39047
Currently it is impossible to determine the source of a binding that
generates `BoundAttribute` because all bound attributes generated from a
microsyntax expression share the same source span.
For example, in
```html
<div *ngFor="let item of items; trackBy: trackByFn"></div>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
source span for all `BoundAttribute`s generated from microsyntax
```
the `BoundAttribute` for both `ngForOf` and `ngForTrackBy`
share the same source span.
A lot of hacks were necessary in View Engine language service to work
around this limitation. It was done by inspecting the whole source span
then figuring out the relative position of the cursor.
With this change, we introduce a flag to set the binding span as the
source span of the `ParsedProperty` in Ivy AST.
This flag is needed so that we don't have to change VE ASTs.
Note that in the binding parser, we already set `bindingSpan` as the
source span for a `ParsedVariable`, and `keySpan` as the source span for
a literal attribute. This change makes the Ivy AST more consistent by
propagating the binding span to `ParsedProperty` as well.
PR Close#39036
This commit updates ngbot config to avoid requesting google3 presubmit for the changes in
the `packages/compiler-cli/src/ngtsc/sourcemaps` folder (which is not synced into google3).
PR Close#39035
In preparation for the Ivy Language service, add the same properties to AppComponent that appear in
TemplateReference so the inline template can be tested thoroughly.
PR Close#39033
This commit adds an API to `NgCompiler`, a method called
`getComponentsWithTemplateFile`. Given a filesystem path to an external
template file, it retrieves a `Set` (actually a `ReadonlySet`) of component
declarations which are using this template. In most cases, this will only be
a single component.
This information is easily determined by the compiler during analysis, but
is hard for a lot of Angular tooling (e.g. the language service) to infer
independently. Therefore, it makes sense to expose this as a compiler API.
PR Close#39002
Previously, when updating the dependency versions in
`aio/tools/examples/shared/package.json` (which contains all
dependencies used in docs examples projects), one had to manually go
through all boilerplate directories and update the `package.json` files
with the same versions.
This commit simplifies this task by automating it via a Node.js script.
PR Close#38992
When updating the boilerplate for CLI-based docs examples, one needed to
install dependencies inside the
`aio/tools/examples/shared/boilerplate/cli/` directory, which resulted
in a `node_modules/` directory and a `yarn.lock` file. These were not
supposed to be part of the boilerplate, so they had to be manually
removed after the boilerplate was updated.
This commit simplifies the workflow by allowing boilerplate files to be
ignored (both by git and the `example-boilerplate.js` script) via a
`.gitignore` file. This way, it is no longer necessary to manually
remove the unneeded directories/files.
PR Close#38992
This commit updates the Markdown files inside the `aio/tools/` directory
to contain one sentence per line in order to be consistent with how
Markdown files are formatted in the rest of the repo.
PR Close#38992
Instead of doing all sorts of checks in the `visit()` method, move checks
that are specific to `BoundEvent` to the `visitBoundEvent()` method.
PR Close#38985
Remove @angular/platform-webworker and @angular/platform-webworker-dynamic
as they were deprecated in v8
BREAKING CHANGE: @angular/platform-webworker and @angular/platform-webworker-dynamic
have been removed as they were deprecated in v8
PR Close#38846
- reducir CI_AIO_MIN_PWA_SCORE
- se desconoce por qué la puntuación es 62 en CircleCI y 3/3, 3/3, 7/8 en Chrome
- comience a agregar IDs de proyectos y URLs de Angular Hispano
- elimine `test_docs_examples` ya que consume demasiados recursos
y no necesitamos verificar que los ejemplos pasen las pruebas
Relates to #3
Notes Paul and Pawel as OOO through commenting out their usernames in users
entries throughout the pullapprove configs which could result in their review
being requested by pullapprove.
PR Close#39028
This commit updates TypeScript and other dependencies used in angular.io
to more closely align with new apps created with the latest Angular CLI.
It also updates `tsconfig.json`, re-ordering some properties around and
introducing some more checks (again to more closely match new CLI apps).
NOTE:
I skipped updating RxJS from 6.5.4 to 6.6.3, because it increased the
main bundle by ~500B.
NOTE:
`tslint.json` will be updated in a subsequent PR, because it requires
more extensive changes.
PR Close#39017
This commit updates the version of Angular Components used in angular.io
to version 10.2.2.
NOTE:
The actual size increase for the main bundle in ViewEngine mode is 1.3KB
(because the actual size before this commit was 430423B, not 430008B as
seen in `aio-payloads.json`).
PR Close#39017
This commit updates the version of Angular framework used in angular.io
to version 10.1.3.
NOTE:
The actual size decrease for the main bundle is 3KB (because the actual
size before this commit was 451226B, not 450952B as seen in
`aio-payloads.json`).
PR Close#39017
With the introduction of incremental type checking in #36211, an
intermediate `ts.Program` for type checking is only created if there are
any templates to check. This rendered some tests ineffective at avoiding
regressions, as the intermediate `ts.Program` was required for the tests
to fail if the scenario under test would not be accounted for. This
commit adds a single component to these tests, to ensure the
intermediate `ts.Program` is in fact created.
PR Close#39011
Prior to this fix, incremental rebuilds could fail to type check due to
missing ambient types from auto-discovered declaration files in @types
directories, or type roots in general. This was caused by the
intermediary `ts.Program` that is created for template type checking,
for which a `ts.CompilerHost` was used which did not implement the
optional `directoryExists` methods. As a result, auto-discovery of types
would not be working correctly, and this would retain into the
`ts.Program` that would be created for an incremental rebuild.
This commit fixes the issue by forcing the custom `ts.CompilerHost` used
for type checking to properly delegate into the original
`ts.CompilerHost`, even for optional methods. This is accomplished using
a base class `DelegatingCompilerHost` which is typed in such a way that
newly introduced `ts.CompilerHost` methods must be accounted for.
Fixes#38979
PR Close#39011
We weren't resolving a path correctly which resulted in an error on Windows.
For reference, here's the error. Note the extra slash before `C:`:
```
Error: ENOENT: no such file or directory, scandir '/C:/bazel_output_root/yxvwd24o/external/npm/node_modules/typescript'
at Object.readdirSync (fs.js:854:3)
```
PR Close#39005
In the past, the docs examples were configured to not use AOT
compilation in development mode (only in production mode). This was an
artifact of when JIT was the default in development mode.
Now that AOT is the default (even in development mode) for new CLI apps,
this commit configures all docs examples to always use AOT compilation.
(This has been made possible by fixing the `component-interaction` docs
example to correctly run in AOT mode in an earlier commit.)
PR Close#39001
Previously, some of the e2e tests of the `component-interaction` docs
example were disabled because they were failing.
This commit fixes and re-enables them.
PR Close#39001
This commit refactors the e2e tests of the `component-interaction` docs
example to improve readability and make them easier to maintain.
Changes include:
- Switch from `element.all().get(0)` to `element()` when there is only
one such element on the page.
- Switch from `Promise#then()` to `async/await`.
- Move `ElementFinder`s at the top of the test (instead of having them
interleaved with expectations).
- Load the page before every test (i.e. in a `beforeEach()` instead of
`beforeAll()`) to prevent state from each test leaking into the
subsequent tests.
- Order imports alphabetically.
PR Close#39001
Previously, the `component-interaction` docs example was configured to
run e2e tests on CI in development mode (in contrast to the default for
all docs examples, which is to run e2e tests in production mode). This
was necessary due to the following reasons:
- One of the components, `CountdownTimerComponent`, which is used by
`CountdownLocalVarParentComponent` and
`CountdownViewChildParentComponent`, was triggering a periodic
asynchronous task (via `setInterval()`), which prevented the app from
stabilizing and caused tests to fail.
- In order to prevent this from happening, the example's `AppModule` had
special provisioning to not include the problematic components in its
declarations when testing.
- Since this had to be determined dynamically at runtime (via inspecting
the URL query params), the `AppModule`'s config could not be
statically evaluated in AOT compilation.
This commit fixes the example to make it compatible with AOT compilation
and removes the custom test command from its `example-config.json`
(allowing it to be run with the default e2e test command, i.e. in
production mode).
PR Close#39001
This commit updates the docs examples to Angular v10.1.3. In addition to
updating the dependencies versions, it also updates the project's
structure and config to more closely match what a new v10 CLI app would
look like. See, also, the [diff][1] between a basic v9.1.4 CLI app and a
v10.1.3 one.
[1]: https://github.com/cexbrayat/angular-cli-diff/compare/9.1.4..10.1.3
PR Close#38993
BlacklistedStackFrames to InternalZoneJsStackFrames along with other related
symbols renamed with the same changes (with appropriate casing style).
PR Close#38978
Previously, the `retry` example did not work as intended. The `retry`
operator was called before the exception occured, thus not retrying the
`ajax` request.
This commit moves the `retry` operator into the correct order to ensure
that the failed request is retried.
PR Close#38905
This commit updates the symbols in the TemplateTypeCheck API and methods
for retrieving them:
* Include `isComponent` and `selector` for directives so callers can determine which
attributes on an element map to the matched directives.
* Add a new `TextAttributeSymbol` and return this when requesting a symbol for a `TextAttribute`.
* When requesting a symbol for `PropertyWrite` and `MethodCall`, use the
`nameSpan` to retrieve symbols.
* Add fix to retrieve generic directives attached to elements/templates.
PR Close#38844
`NodeInjector` is store in expando as a list of values in an array. The
offset constant into the array have been brought together into a single
`NodeInjectorOffset` enum with better documentation explaining their usage.
PR Close#38707
This change makes `getPreviousOrParentTNode` return `TNode|null` (rather
than just `TNode`) which is more reflective of the reality. The
`getPreviousOrParentTNode` can be `null` upon entering the `LView`.
PR Close#38707
`TNodeType.View` was created to support inline views. That feature did
not materialize and we have since removed the instructions for it, leave
an unneeded `TNodeType.View` which was still used in a very
inconsistent way. This change no longer created `TNodeType.View` (and
there will be a follow up chang to completely remove it.)
Also simplified the mental model so that `LView[HOST]`/`LView[T_HOST]`
always point to the insertion location of the `LView`.
PR Close#38707
Host `TNode` was passed into `getOrCreateTNode` just so that we can
compute weather or not we are a root node. This was needed because
`previousOrParentTNode` could have `TNode` from `TView` other then
current `TView`. This is confusing mental model. Previous change
ensured that `previousOrParentTNode` must always be part of `TView`,
which enabled this change to remove the unneeded argument.
PR Close#38707
`previousOrParentTNode` stores current `TNode`. Due to inconsistent
implementation the value stored would sometimes belong to the current
`TView` and sometimes to the parent. We have extra logic which accounts
for it. A better solution is to just ensure that `previousOrParentTNode`
always belongs to current `TNode`. This simplifies the mental model
and cleans up some code.
PR Close#38707
Creates a tool for staging and publishing releases as per the
new branching and versioning that has been outlined in the following
document. The tool is intended to be used across the organization to
ensure consistent branching/versioning and labeling:
https://docs.google.com/document/d/197kVillDwx-RZtSVOBtPb4BBIAw0E9RT3q3v6DZkykU/edit#heading=h.s3qlps8f4zq7dd
The tool implements the actions as outlined in the following
initial plan: https://hackmd.io/2Le8leq0S6G_R5VEVTNK9A.
The implementation slightly diverged in so far that it performs
staging and publishing together so that releasing is a single
convenient command. In case of errors for which re-running the
full command is not sufficient, we want to consider adding
recover functionality. e.g. when the staging completed, but the
actual NPM publishing aborted unexpectedly due to build errors.
PR Close#38656
Introduces a new command for `ng-dev release`, so that the NPM
dist tag can be set for all configured NPM packages. This command
can be useful in case a manual tag needs to be set, but it is
primarily used by the release tooling when a new stable version
is cut, and when the previous patch branch needs to be set as LTS
version through a `v{major}-lts` dist tag.
It is necessary to have this as a command so that the release tool
can execute it for old branches where other packages might have been
configured. This is similar to the separate `ng-dev build` command
that we created.
Note that we also added logic for spawning a process conveniently
with different "console output" modes. This will be useful for
other command invocations in the release tool and it's generally
better than directly using native `child_process` as that one doesn't
log to the dev-infra debug log file.
PR Close#38656
Adds a command for building all release packages. This command
is primarily used by the release tool for building release output
in version branches. The release tool cannot build the release packages
configured in `master` as those packages could differ from the
packages available in a given version branch. Also, the build process
could have changed, so we want to have an API for building
release packages that is guaranteed to be consistent across branches.
PR Close#38656
Moves the existing `ng-dev release env-stamp` command into a
subfolder so that the staging/publish tool can have its own
dedicated folder (without being polluted by the env-stamp logic).
Every subcommand should be in its own folder.
PR Close#38656
Adds a new folder to dev-infra where shared testing utilities
could be placed in. This commit already adds initial testing
utilities for dealing with the `GitClient` and SemVer versions.
The `GitClient` in the testing utilities simulates actual Git
behavior in a virtual manner. It's not complete at all, but can
be extended based on our needs. The currently implemented commands
are the most basic ones that we'd need for our release tooling.
PR Close#38656
Adds a method for printing active release trains for a configured
project. This is helpful for the release tool that will print
the active release trains. Also this can be useful for the
caretaker status command, where we could print the active
version branches (i.e. "is there currently a feature-freeze branch").
PR Close#38656
Adds logic for determining active LTS branches for a given
release configuration. The active LTS branches can be determined
by querying NPM and matching dist tags against a specific
pattern. i.e. `v{major}-lts`.
This logic will be useful for the release tool that supports
publishing of active LTS version branches.
PR Close#38656
Cleans up outdated comments in the shared dev-infra Git
utilities. We also export the Graphql client for consistency
as we expose the `GithubClient` and `GitClient` too.
PR Close#38656
We initially added logic for determining active release trains into
the merge script. Given we now build more tools that rely on this
information, we move the logic into a more general "versioning" folder
that can contain common logic following the versioning document for the
Angular organization.
PR Close#38656
Introduces a new configuration for the `ng-dev release` command. This
configuration will be the source of truth for all release packages
and how they can be built.
Additionally, in a temporary manner where each project has its own
way of generating the changelog, the changelog generation can be
configured. This will be removed in the future when there is
canonical changelog generation in the dev-infra shared package.
PR Close#38656
Exposes logic for dealing with LTS branches, so that the release
tool can re-use it for cutting LTS patch releases.
Eventually, we can move all of this logic to a more dedicated
folder instead of having it inside the merge folder.
PR Close#38656
Instead of maintaining multiple interface for grouping
owner name and repo name, we expose a shared interface
describing a Github repository.
One unfortunate downside is that the GraphQL Github
and Rest API diverge slightly with the key for the
repository name. i.e. rest uses `repo` for the name
of a repository, while GraphQL uses `name` for the name.
If that would be consistent, we could use the rest operator
to pass a repository to the Octokit REST or GraphQL API. This
does not work, so we have a small manual overhead as seen
in the `branches.ts` file.
PR Close#38656
The dev-infra package is currently built with Bazel and ts-node.
In Bazel, the shared tsconfig from the `packages/` folder is used.
This means that the code is built in strict mode, but IDEs and
ts-node do not know about the strictness. This is because the tsconfig
is part of the `packages` folder and not accessible from the
dev-infra package. We fix this by adding an IDE and ts-node specific
tsconfig to the dev-infra package.
This helps with spotting compilation failures before building
with Bazel / waiting for CI to check build state.
PR Close#38656
Previously, the logic for determing the active release trains did not
return the resolved version of a release train. With the publish script
being created, we need this information and can just pass it through,
so that we do not need to fetch and parse the package.json of given
branches multiple times.
PR Close#38656
Sets up the NPM `ora` package in the project and in dev-infra,
so that we can show progress spinners when needed. This is useful
in the publish release script when we wait for a pull request to
be merged.
PR Close#38656
The git client respects the `SpawnSyncOptions` when a command
is executed. Currently it does not hide the command info
messages when commands are run in silent mode.
We fix this as part of this commit, so that the command info
is only printed to `debug` if `stdio` is set to `ignore`.
Additonally, the github token is made public so that it can be
used by commands if other repositories like forks are targeted.
PR Close#38656
Instead of repeating the logic for adding the github token to
a repository git url, we add a shared function for automatically
computing the URls with token.
Additionally, URLs for updating/generating tokens have been moved
to a dedicated file in the `utils` folder. Also while being at it,
the yargs github token helper is also moved into the dedicated
Git/Github related util folder.
PR Close#38656
Even in the overloads, state that it can accept `null` and
`undefined`, in order to ensure easy composition with `async`.
Additionally, change the implementation to return `null` on an
`undefined` input, for consistency with other pipes.
BREAKING CHANGE:
The `slice` pipe now returns `null` for the `undefined` input value,
which is consistent with the behavior of most pipes. If you rely on
`undefined` being the result in that case, you now need to check for it
explicitly.
PR Close#37447
As shown in the tests, `KeyValuePipe.transform` can accept
`undefined`, in which case it always returns `null`.
Additionally, the typing for `string` keys can be made generic, so the
comparison function is only required to accept the relevant cases.
Finally, the typing for `number` records now shows that the comparison
function and the result entries will actually receive the string version
of the numeric keys, just as shown in the tests.
BREAKING CHANGE:
The typing of the `keyvalue` pipe has been fixed to report that for
input objects that have `number` keys, the result will contain the
string representation of the keys. This was already the case and the
code has simply been updated to reflect this. Please update the
consumers of the pipe output if they were relying on the incorrect
types. Note that this does not affect use cases where the input values
are `Map`s, so if you need to preserve `number`s, this is an effective
way.
PR Close#37447
I18nPluralPipe can actually accept `null` and `undefined` (which are
convenient for composing it with the async pipe), but it is currently
typed to only accept `number`.
PR Close#37447
Make typing of number pipes stricter to catch some misuses (such as
passing an Observable or an array) at compile time.
BREAKING CHANGE:
The signatures of the number pipes now explicitly state which types are
accepted. This should only cause issues in corner cases, as any other
values would result in runtime exceptions.
PR Close#37447
Make typing of DatePipe stricter to catch some misuses (such as passing
an Observable or an array) at compile time.
BREAKING CHANGE:
The signature of the `date` pipe now explicitly states which types are
accepted. This should only cause issues in corner cases, as any other
values would result in runtime exceptions.
PR Close#37447
`AsyncPipe.transform` will never return `undefined`, even when passed
`undefined` in input, in contrast with what was declared in the
overloads.
Additionally the "actual" method signature can be updated to match the
most generic case, since the implementation does not rely on wrappers
anymore.
BREAKING CHANGE:
The async pipe no longer claims to return `undefined` for an input that
was typed as `undefined`. Note that the code actually returned `null` on
`undefined` inputs. In the unlikely case you were relying on this,
please fix the typing of the consumers of the pipe output.
PR Close#37447
The old implementation of case conversion types can handle several
values which are not strings, but the signature did not reflect this.
The new one reports errors when falsy non-string inputs are given to
the pipe (such as `false` or `0`) and has a new signature which
instead reflects the behaviour on `null` and `undefined`.
Fixes#36259
BREAKING CHANGE:
The case conversion pipes no longer let falsy values through. They now
map both `null` and `undefined` to `null` and raise an exception on
invalid input (`0`, `false`, `NaN`) just like most "common pipes". If
your code required falsy values to pass through, you need to handle them
explicitly.
PR Close#37447
For the following example, the cursor is between `keySpan` and `valueSpan`
of the `BoundAttribute`.
```html
<test-cmp [foo]¦="bar"></test-cmp>
```
Our hybrid visitor will return `Element`in this case, which is the parent
node of the `BoundAttribute`.
This is because we only look at the `keySpan` and `valueSpan`, and not
the source span. The last element in the AST path is `Element`, so it gets
returned.
In this PR, I propose fixing this by adding a sentinel value `undefined`
to the AST path to signal that we've found a source span but the cursor is
neither in the key span nor the value span.
PR Close#38995
Now that we have `keySpan` for `BoundAttribute` (implemented in
https://github.com/angular/angular/pull/38898) we could do the same
for `Variable`.
This would allow us to distinguish the LHS and RHS from the whole source
span.
PR Close#38965
This commit removes polyfills that were needed to run tests on IE 9 and IE 10.
BREAKING CHANGE:
In v10, IE 9, 10, and IE mobile support was deprecated. In v11, Angular framework removes IE 9,
10, and IE mobile support completely.
Supporting outdated browsers like these increases bundle size, code complexity, and test load,
and also requires time and effort that could be spent on improvements to the framework.
For example, fixing issues can be more difficult, as a straightforward fix for modern browsers
could break old ones that have quirks due to not receiving updates from vendors.
PR Close#38931
This commit removes IE 9 and IE 10 from the browser configuration that is used by CI, so tests
would no longer be executed in these browsers.
PR Close#38931
In v10, framework support for IE 9, 10, and IE mobile was deprecated. In v11 we remove support
for these browsers.
This commit updates angular.io docs to exclude references to IE 9, 10, and IE mobile as well as
polyfills that were needed to run Angular-based apps in these browsers.
PR Close#38931
Prior to this change, each invocation of `loadStandardTestFiles` would
load the necessary files from disk. This function is typically called
at the top-level of a test module in order to share the result across
tests. The `//packages/compiler-cli/test/ngtsc` target has 8 modules
where this call occurs, each loading their own copy of
`node_modules/typescript` which is ~60MB in size, so the memory overhead
used to be significant. This commit loads the individual packages into
a standalone `Folder` and mounts this folder into the filesystem of
standard test files, such that all file contents are no longer
duplicated in memory.
PR Close#38909
Some compiler tests take a long time to run, even using multiple
executors. A profiling session revealed that most time is spent in
parsing source files, especially the default libraries are expensive to
parse.
The default library files are constant across all tests, so this commit
introduces a shared cache of parsed source files of the default
libraries. This achieves a significant improvement for several targets
on my machine:
//packages/compiler-cli/test/compliance: from 23s to 5s.
//packages/compiler-cli/test/ngtsc: from 115s to 11s.
Note that the number of shards for the compliance tests has been halved,
as the extra shards no longer provide any speedup.
PR Close#38909
`router.navigateByUrl` and `router.createUrlTree` only use a subset of the `NavigationExtras`. This commit
changes the parameter type to use new interfaces that only specify the properties used by
those function implementations. `NavigationExtras` extends both of those interfaces.
Fixes#18798
BREAKING CHANGE: While the new parameter types allow a variable of type
`NavigationExtras` to be passed in, they will not allow object literals,
as they may only specify known properties. They will also not accept
types that do not have properties in common with the ones in the `Pick`.
To fix this error, only specify properties from the `NavigationExtras` which are
actually used in the respective function calls or use a type assertion
on the object or variable: `as NavigationExtras`.
PR Close#38227
We are changing the default value from 'legacy' to 'corrected' so that new
applications are automatically opted-in to the corrected behavior from #22394.
BREAKING CHANGE: This commit changes the default value of
`relativeLinkResolution` from `'legacy'` to `'default'`. If your
application previously used the default by not specifying a value in the
`ExtraOptions` and uses relative links when navigating from children of
empty path routes, you will need to update your `RouterModule` to
specifically specify `'legacy'` for `relativeLinkResolution`.
See https://angular.io/api/router/ExtraOptions#relativeLinkResolution
for more details.
PR Close#25609
The keySpan in bound attributes provides more fine-grained location information and can be used
to disambiguate multiple bound attributes in a single microsyntax binding. Previously,
this case could not distinguish between the two different attributes because
the sourceSpans were identical and valueSpans would not match if the cursor
was located in a key.
PR Close#38955
Previously, the `backoff()` example did not work as intended. More
specifically, the `range(1, maxTries)` observable would complete
immediately after emitting the `maxTries`th value, causing the overall
observable to also complete. As a result, it would only make
`maxTries - 1` attempts to recover from an error. More importantly, the
outer observable would complete successfully instead of erroring.
This commit fixes the `backoff()` operator by ensuring it makes exactly
`maxTries` attempts to recover and it propagates the actual error to the
outer observable.
The test for this change is added in the next commit.
PR Close#38896
Close#38334.
zone.js provides a flag DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION to let zone.js
throw the original error instead of wrap it when uncaught promise rejection found.
But the rejection value could be anything includes primitive value such as number.
In that case, we should not attach any additional properties to the value.
PR Close#38476
In Ivy, template type-checking has 3 modes: basic, full, and strict. The
primary difference between basic and full modes is that basic mode only
checks the top-level template, whereas full mode descends into nested
templates (embedded views like ngIfs and ngFors). Ivy applies this approach
to all of its template type-checking, including the DOM schema checks which
validate whether an element is a valid component/directive or not.
View Engine has both the basic and the full mode, with the same distinction.
However in View Engine, DOM schema checks happen for the full template even
in the basic mode.
Ivy's behavior here is technically a "fix" as it does not make sense for
some checks to apply to the full template and others only to the top-level
view. However, since g3 relies exclusively on the basic mode of checking and
developers there are used to DOM checks applying throughout their template,
this commit re-enables the nested schema checks even in basic mode only in
g3. This is done by enabling the checks only when Closure Compiler
annotations are requested.
Outside of g3, it's recommended that applications use at least the full mode
of checking (controlled by the `fullTemplateTypeCheck` flag), and ideally
the strict mode (`strictTemplates`).
PR Close#38943
The default value for `relativeLinkResolution` is changing from 'legacy' to 'corrected'.
This migration updates `RouterModule` configurations that use the default value to
now specifically use 'legacy' to prevent breakages when updating.
PR Close#38698
Though we currently have the knowledge of where the `key` for an
attribute binding appears during parsing, we do not propagate this
information to the output AST. This means that once we produce the
template AST, we have no way of mapping a template position to the key
span alone. The best we can currently do is map back to the
`sourceSpan`. This presents problems downstream, specifically for the
language service, where we cannot provide correct information about a
position in a template because the AST is not granular enough.
PR Close#38898
There is an inconsistency in overrideProvider behaviour. Testing documentation says
(https://angular.io/guide/testing-components-basics#createcomponent) that all override...
methods throw error if TestBed is already instantiated. However overrideProvider doesn't throw any error, but (same as
other override... methods) doesn't replace providers if TestBed is instantiated. Add TestBed instantiation check to
overrideProvider method to make it consistent.
BREAKING CHANGE:
If you call `TestBed.overrideProvider` after TestBed initialization, provider overrides are not applied. This
behavior is consistent with other override methods (such as `TestBed.overrideDirective`, etc) but they
throw an error to indicate that, when the check was missing in the `TestBed.overrideProvider` function.
Now calling `TestBed.overrideProvider` after TestBed initialization also triggers an
error, thus there is a chance that some tests (where `TestBed.overrideProvider` is
called after TestBed initialization) will start to fail and require updates to move `TestBed.overrideProvider` calls
before TestBed initialization is completed.
Issue mentioned here: https://github.com/angular/angular/issues/13460#issuecomment-636005966
Documentation: https://angular.io/guide/testing-components-basics#createcomponent
PR Close#38717
This commit introduces a new option for the service worker, called
`navigationRequestStrategy`, which adds the possibility to force the service worker
to always create a network request for navigation requests.
This enables the server redirects while retaining the offline behavior.
Fixes#38194
PR Close#38565
This commit refactors the `ExpressionTranslatorVisitor` so that it
is not tied directly to the TypeScript AST. Instead it uses generic
`TExpression` and `TStatement` types that are then converted
to concrete types by the `TypeScriptAstFactory`.
This paves the way for a `BabelAstFactory` that can be used to
generate Babel AST nodes instead of TypeScript, which will be
part of the new linker tool.
PR Close#38775
Previously each identifier was being imported individually, which made for a
very long import statement, but also obscurred, in the code, which identifiers
came from the compiler.
PR Close#38775
This file contains a number of classes making it long and hard to work with.
This commit splits the `ImportManager`, `Context` and `TypeTranslatorVisitor`
classes, along with associated functions and types into their own files.
PR Close#38775
When the target of the compiler is ES2015 or newer then we should
be generating `let` and `const` variable declarations rather than `var`.
PR Close#38775
Using an interface makes the code cleaner and more readable.
This change also adds the `range` property to the type to be used
for source-mapping.
PR Close#38775
The cast to `ts.Identifier` was a hack that "just happened to work".
The new approach is more robust and doesn't have to undermine
the type checker.
PR Close#38775
Let's say we have a code like
```html
<div<span>123</span>
```
Currently this gets parsed into a tree with the element tag `div<span`.
This has at least two downsides:
- An incorrect diagnostic that `</span>` doesn't close an element is
emitted.
- A consumer of the parse tree using it for editor services is unable to
provide correct completions for the opening `<span>` tag.
This patch attempts to fix both issues by instead parsing the code into
the same tree that would be parsed for `<div></div><span>123</span>`.
In particular, we do this by optimistically scanning an open tag as
usual, but if we do not notice a terminating '>', we mark the tag as
"incomplete". A parser then emits an error for the incomplete tag and
adds a synthetic (recovered) element node to the tree with the
incomplete open tag's name.
What's the downside of this? For one, a breaking change.
<ol>
<li>
The first breaking change is that `<` symbols that are ambiguously text
or opening tags will be parsed as opening tags instead of text in
element bodies. Take the code
```html
<p>a<b</p>
```
Clearly we cannot have the best of both worlds, and this patch chooses
to swap the parsing strategy to support the new feature. Of course, `<`
can still be inserted as text via the `<` entity.
</li>
</ol>
Part of #38596
PR Close#38681
This commit re-enables some tests that were temporarily disabled on Windows,
as they failed on native Windows CI. The Windows filesystem emulation has
been corrected in an earlier commit, such that the original failure would
now also occur during emulation on Linux CI.
PR Close#37782
In native windows, the drive letter is a capital letter, while our Windows
filesystem emulation would use lowercase drive letters. This difference may
introduce tests to behave differently in native Windows versus emulated
Windows, potentially causing unexpected CI failures on Windows CI after a PR
has been merged.
Resolves FW-2267
PR Close#37782
NG_VALUE_ACCESSOR is a multi injection token, users can and
should expect more than one ControlValueAccessor to be
available (and this is how it is used in @angular/forms).
This is now reflected in the definition of the injection token
by typing it as an array of ControlValueAccessor. The motivating
reason is that using the programmatic Injector api will now
type Injector#get correspondingly.
fixes#29351
BREAKING CHANGES
NG_VALUE_ACCESSOR is now typed as a readonly array rather than
a mutable scalar. It is used as a multi injection token and as
such it should always be expected that more than one accessor
may be returned.
PR Close#29723
In bootstrapping.md the default AppModule has some extra imports which are not generated
by default in ng new removed those extra imports and add them at appropriate place.
PR Close#38549
The logic for computing identifiers, specifically for bound attributes
can be simplified by using the value span of the binding rather than the
source span.
PR Close#38899
This commit removes the scrollbar styles so that the default
styles in the browser render. This widens the webkit scroll bar.
This makes it easier to grab the scrollbar using assistive
technology and devices, and provides a wider target for
those who have dexterity issues. By removing these styles,
We will no longer have to maintain custom scrollbars specific to WebKit
and they will be accessible by default.
PR Close#38852
The current tests print out the span numbers, which are really difficult to verify
since it requires manually going to the template string and looking at what
characters appear within those indexes. The better humanization would be
to use the toString method of the spans, which prints the span text itself
PR Close#38902
Changed several period into colons to be consistent throughout the doc.
Changed "If don't add the interface..." to "If _you_ don't add the interface..."
PR Close#38900
This commit updates ngbot config to avoid requesting google3 presubmit for the changes in
the `packages/zone.js/dist` folder (which is not synced into google3).
PR Close#38901
Currently, when we call jsonp method without importing HttpClientJsonpModule, an error message appears saying
'Attempted to construct Jsonp request without JsonpClientModule installed.' instance of 'Attempted to
construct Jsonp request without HttpClientJsonpModule installed.'
PR Close#38756
This commit adds a logic to ouput the number of new and fixed cycles after running circular
dependency checker. This information is useful to better understand an impact of changes in case
the number of new/fixed cycles is relatively big.
PR Close#38805
This commit updates several import statements in the core package to decrease the number of
cycles detected by the dependency checker tool.
PR Close#38805
Close#38795
in the XMLHttpRequest patch, when get `readystatechange` event, zone.js try to
invoke `load` event listener first, then call `invokeTask` to finish the
`XMLHttpRequest::send` macroTask, but if the request failed because the
server can not be reached, the `load` event listener will not be invoked,
so the `invokeTask` of the `XMLHttpRequest::send` will not be triggered either,
so we will have a non finished macroTask there which will make the Zone
not stable, also memory leak.
So in this PR, if the `XMLHttpRequest.status = 0` when we get the `readystatechange`
event, that means something wents wrong before we reached the server, we need to
invoke the task to finish the macroTask.
PR Close#38836
During the merge process, all validations have already been completed so git commit
hooks can be safely skipped. This additionally, prevents errors from occuring which
would be caused the commit hooks executing, such as when yarn updates and then yarn
commands are unable to run within the same process.
PR Close#38888
In #38666 we changed how ngcc deals with type expressions, where it
would now always emit the original type expression into the generated
code as a "local" type value reference instead of synthesizing new
imports using an "imported" type value reference. This was done as a fix
to properly deal with renamed symbols, however it turns out that the
compiler has special handling for certain imported symbols, e.g.
`ChangeDetectorRef` from `@angular/core`. The "local" type value
reference prevented this special logic from being hit, resulting in
incorrect compilation of pipe factories.
This commit fixes the issue by manually inspecting the import of the
type expression, in order to return an "imported" type value reference.
By manually inspecting the import we continue to handle renamed symbols.
Fixes#38883
PR Close#38892
Common AST formats such as TS and Babel do not use a separate
node for comments, but instead attach comments to other AST nodes.
Previously this was worked around in TS by creating a `NotEmittedStatement`
AST node to attach the comment to. But Babel does not have this facility,
so it will not be a viable approach for the linker.
This commit refactors the output AST, to remove the `CommentStmt` and
`JSDocCommentStmt` nodes. Instead statements have a collection of
`leadingComments` that are rendered/attached to the final AST nodes
when being translated or printed.
PR Close#38811
Close#38561, #38669
zone.js 0.11.1 introduces a breaking change to adpat Angular package format,
and it breaks the module loading order, before 0.11, in IE11, the `zone.js` es5
format bundle will be imported, but after 0.11, the `fesm2015` format bundle will
be imported, which causes error.
And since the only purpose of the `dist` folder of zone.js bundles is to keep backward
compatibility, in the original commit, I use package redirect to implement that, but
it is not fully backward compatible, we should keep the same dist structure as `0.10.3`.
PR Close#38797
Because PhantomJS has been deprecated since March 2018, and `newEvent`
is very confusing for newcomers that read the testing documentation,
we remove it entirely, and instead assume most, if not all, newcomers
will run tests in Chrome as it is the default.
Fixes#23370
PR Close#37251
When the response type is JSON, the `put()` overload signature did not have `reportProgress`
and `params` options. This makes it difficult to type-check this overload.
This commit adds them to the overload signature.
Fixes#23600
PR Close#37873
This change prevents comments from a resolved node from appearing at
each location the resolved expression is used and also prevents callers
of `Scope#resolve` from accidentally modifying / adding comments to the
declaration site.
PR Close#38857
Before Zone.js `v0.11.1`, Zone.js provides two format of bundles under `dist` folder,
`ES5` bundle `zone.js` and `ES2015` bundle `zone-evergreen.js`, these bundles are used
for `differential loading` of Angular. By default, the following code
```
import 'zone.js';
```
loads the `ES5` bundle `zone.js`.
From `v0.11.1`, Zone.js follows the [Angular Package Format]
(https://docs.google.com/document/d/1CZC2rcpxffTDfRDs6p1cfbmKNLA6x5O-NtkJglDaBVs),
so the folder structure of the Zone.js bundles is updated to match `Angular Package Format`.
So the same code
```
import 'zone.js';
```
loads the `ES2015` bundle.
This is a breaking change, so if the apps import zone.js in this way,
the apps will not work in legacy browsers such as `IE11`.
Zone.js still provides the same bundles under `dist` folder to keep backward
compatibility after `v0.11.1`. So the following code in `polyfills.ts` generated
by `Angular CLI` still works.
```
import 'zone.js/dist/zone';
```
For details, please refer the [changelog](./CHANGELOG.md) and
the [PR](https://github.com/angular/angular/pull/36540).
PR Close#38821
In #38227 the signatures of `navigateByUrl` and `createUrlTree` were updated to exclude unsupported
properties from their `extras` parameter. This migration looks for the relevant method calls that
pass in an `extras` parameter and drops the unsupported properties.
**Before:**
```
this._router.navigateByUrl('/', {skipLocationChange: false, fragment: 'foo'});
```
**After:**
```
this._router.navigateByUrl('/', {
/* Removed unsupported properties by Angular migration: fragment. */
skipLocationChange: false
});
```
These changes also move the method call detection logic out of the `Renderer2` migration and into
a common place so that it can be reused in other migrations.
PR Close#38825
This commit simplifies the tests of `EventsComponent` (by introducing a
`createMockEvent()` helper and getting rid of the irrelevant `Event`
fields) and adds tests for some more usecases. It also makes the tests
more robust by using Jasmine's `Clock` to mock the current date.
PR Close#36517
In the events.json file most of tooltips are same as name so there
were of no use, as they were providing no extra information. So,
removed them from the events.json file
PR Close#36517
Data in events page was hardcoded and it is manually moved in the table.
Created a new events widget which will automatically move past and upcoming
events from events.json (`aio/content/marketing/events.json`) file to the
relevant table in the events tab
PR Close#36517
This commit improves the typeahead example, by using the emitted input
value. It also adds a unit test to ensure that the example is working
as intended.
PR Close#34190
The `createOrReuseChildren` function calls shouldReuseRoute with the
previous child values use as the future and the future child value used
as the current argument. This is incosistent with the argument order in
`createNode`. This inconsistent order can make it difficult/impossible
to correctly implement the `shouldReuseRoute` function. Usually this
order doesn't matter because simple equality checks are made on the
args and it doesn't matter which is which.
More detail can be found in the bug report: #16192.
Fix#16192
BREAKING CHANGE: This change corrects the argument order when calling
RouteReuseStrategy#shouldReuseRoute. Previously, when evaluating child
routes, they would be called with the future and current arguments would
be swapped. If your RouteReuseStrategy relies specifically on only the future
or current snapshot state, you may need to update the shouldReuseRoute
implementation's use of "future" and "current" ActivateRouteSnapshots.
PR Close#26949
ngc angular compiler was not mentioned in the glossary.
Glossary should contain the relevant terms in angular
which are hard to get. So, added a small defination of
ngc to the glossary
PR Close#36781
In the integration test suite of ngcc, we load a set of files from
`node_modules` into memory. This includes the `typescript` package and
`@angular` scoped packages, which account for a large number of large
files that needs to be loaded from disk. This commit moves this work
to the top-level, such that it doesn't have to be repeated in all tests.
PR Close#38840
Recent optimizations to ngcc have significantly reduced the total time
it takes to process `node_modules`, to such extend that sharding across
multiple processes has become less effective. Previously, running
ngcc asynchronously would allow for up to 8 workers to be allocated,
however these workers have to repeat work that could otherwise be shared.
Because ngcc is now able to reuse more shared computations, the overhead
of multiple workers is increased and therefore becomes less effective.
As an additional benefit, having fewer workers requires less memory and
less startup time.
To give an idea, using the following test setup:
```bash
npx @angular/cli new perf-test
cd perf-test
yarn ng add @angular/material
./node_modules/.bin/ngcc --properties es2015 module main \
--first-only --create-ivy-entry-points
```
We observe the following figures on CI:
| | 10.1.1 | PR #38840 |
| ----------------- | --------- | --------- |
| Sync | 85s | 25s |
| Async (8 workers) | 22s | 16s |
| Async (4 workers) | - | 11s |
In addition to changing the default number of workers, ngcc will now
use the environment variable `NGCC_MAX_WORKERS` that may be configured
to either reduce or increase the number of workers.
PR Close#38840
ngcc creates typically two `ts.Program` instances for each entry-point,
one for processing sources and another one for processing the typings.
The creation of these programs is somewhat expensive, as it concerns
module resolution and parsing of source files.
This commit implements several layers of caching to optimize the
creation of programs:
1. A shared module resolution cache across all entry-points within a
single invocation of ngcc. Both the sources and typings program
benefit from this cache.
2. Sharing the parsed `ts.SourceFile` for a single entry-point between
the sources and typings program.
3. Sharing parsed `ts.SourceFile`s of TypeScript's default libraries
across all entry-points within a single invocation. Some of these
default library typings are large and therefore expensive to parse,
so sharing the parsed source files across all entry-points offers
a significant performance improvement.
Using a bare CLI app created using `ng new` + `ng add @angular/material`,
the above changes offer a 3-4x improvement in ngcc's processing time
when running synchronously and ~2x improvement for asynchronous runs.
PR Close#38840
As part of the commit message conformance check, local commit message checks are
made to be warnings rather than failures. An additional local option is also in
place to allow for the commit message validation failures to be considered errors
instead.
PR Close#38784
When type-checking a component, the declaring NgModule scope is used
to create a directive matcher that contains flattened directive metadata,
i.e. the metadata of a directive and its base classes. This computation
is done for all components, whereas the type-check scope is constant per
NgModule. Additionally, the flattening of metadata is constant per
directive instance so doesn't necessarily have to be recomputed for
each component.
This commit introduces a `TypeCheckScopes` class that is responsible
for flattening directives and computing the scope per NgModule. It
caches the computed results as appropriate to avoid repeated computation.
PR Close#38539
For the compilation of a component, the compiler has to prepare some
information about the directives and pipes that are used in the template.
This information includes an expression for directives/pipes, for usage
within the compilation output. For large NgModule compilation scopes
this has shown to introduce a performance hotspot, as the generation of
expressions is quite expensive. This commit reduces the performance
overhead by only generating expressions for the directives/pipes that
are actually used within the template, significantly cutting down on
the compiler's resolve phase.
PR Close#38539
Currently we validate the configuration file on each `getConfig`
invocation. We can only validate once since the configuration
is cached.
Also while being at it, renames the cache variables to lower-case as those
do not represent constants (which are convention-wise upper case).
PR Close#38808
This commit creates a sample router test application to introduce the
symbol tests. It serves as a guard to ensure that any future work on the
router package does not unintentionally increase the payload size.
PR Close#38714
Recent work on compiler internals in #38539 led to an unexpected failure,
where a pipe used exclusively inside of an ICU would no longer be
emitted into the compilation output. This caused runtime errors due to
missing pipes.
The issue occurred because the change in #38539 would determine the set
of used pipes up-front, independent from the template compilation using
the `R3TargetBinder`. However, `R3TargetBinder` did not consider
expressions within ICUs, so any pipe usages within those expressions
would not be detected. This fix unblocks #38539 and also concerns
upcoming linker work, given that prelink compilations would not go
through full template compilation but only `R3TargetBinder`.
PR Close#38810
Close#38584
In zone.js 0.11.1, the `types` field is missing in the `package.json`,
the reason is in zone.js 0.11.0, the `files` field is used to specify the
types, but it cause the npm package not contain any bundles issue, so zone.js
0.11.1 remove the `files` field, which cause the `type` definition gone.
This PR concat the `zone.js.d.ts`, `zone.configurations.api.ts`, `zone.api.extensions.ts`
types into a single `zone.d.ts` file.
PR Close#38585
To discourage developers from mutating the arrays returned
from the following methods, their return types have been marked
as readonly.
* `getLocaleDayPeriods()`
* `getLocaleDayNames()`
* `getLocaleMonthNames()`
* `getLocaleEraNames()`
Fixes#27003
BREAKING CHANGE:
The locale data API has been marked as returning readonly arrays, rather
than mutable arrays, since these arrays are shared across calls to the
API. If you were mutating them (e.g. calling `sort()`, `push()`, `splice()`, etc)
then your code will not longer compile. If you need to mutate the array, you
should now take a copy (e.g. by calling `slice()`) and mutate the copy.
PR Close#30397
In a microsyntax expressions, some attributes are not bound after
desugaring. For example,
```html
<div *ngFor="let item of items">
</div>
```
gets desugared to
```html
<ng-template ngFor let-items [ngForOf]="items">
</ngtemplate>
```
In this case, `ngFor` should be a literal attribute with no RHS value.
Therefore, its source span should be just the `keySpan` and not the
source span of the original template node.
This allows language service to precisely pinpoint different spans in a
microsyntax to provide accurate information.
PR Close#38766
Adds `TemplateTypeChecker` operation to retrieve the `Symbol` of a
`TmplAstVariable` or `TmplAstReference` in a template.
Sometimes we need to traverse an intermediate variable declaration to arrive at
the correct `ts.Symbol`. For example, loop variables are declared using an intermediate:
```
<div *ngFor="let user of users">
{{user.name}}
</div>
```
Getting the symbol of user here (from the expression) is tricky, because the TCB looks like:
```
var _t0 = ...; // type of NgForOf
var _t1: any; // context of embedded view for NgForOf structural directive
if (NgForOf.ngTemplateContextGuard(_t0, _t1)) {
// _t1 is now NgForOfContext<...>
var _t2 = _t1.$implicit; // let user = '$implicit'
_t2.name; // user.name expression
}
```
Just getting the `ts.Expression` for the `AST` node `PropRead(ImplicitReceiver, 'user')`
via the sourcemaps will yield the `_t2` expression. This function recognizes that `_t2`
is a variable declared locally in the TCB, and actually fetch the `ts.Symbol` of its initializer.
These special handlings show the versatility of the `Symbol`
interface defined in the API. With this, when we encounter a template variable,
we can provide the declaration node, as well as specific information
about the variable instance, such as the `ts.Type` and `ts.Symbol`.
PR Close#38618
Adds support to the `TemplateTypeChecker` to get a `Symbol` of an AST
expression in a component template.
Not all expressions will have `ts.Symbol`s (e.g. there is no `ts.Symbol`
associated with the expression `a + b`, but there are for both the a and b
nodes individually).
PR Close#38618
Adds support to the `TemplateTypeChecker` for retrieving a `Symbol` for
`TmplAstTemplate` and `TmplAstElement` nodes in a component template.
PR Close#38618
Specifically, this commit adds support for retrieving a `Symbol` from a
`TmplAstBoundEvent` or `TmplAstBoundAttribute`. Other template nodes
will be supported in following commits.
PR Close#38618
The statements generated in the TCB are optimized for performance and producing diagnostics.
These optimizations can result in generating a TCB that does not have all the information
needed by the `TemplateTypeChecker` for retrieving `Symbol`s. For example, as an optimization,
the TCB will not generate variable declaration statements for directives that have no
references, inputs, or outputs. However, the `TemplateTypeChecker` always needs these
statements to be present in order to provide `ts.Symbol`s and `ts.Type`s for the directives.
This commit adds logic to the TCB generation to ensure the required
information is available in a form that the `TemplateTypeChecker` can
consume. It also adds an option to the `NgCompiler` that makes this
generation configurable.
PR Close#38618
This commit defines the interfaces which outline the information the
`TemplateTypeChecker` can return when requesting a Symbol for an item in the
`TemplateAst`.
Rather than providing the `ts.Symbol`, `ts.Type`, etc.
information in several separate functions, the `TemplateTypeChecker` can
instead provide all the useful information it knows about a particular
node in the `TemplateAst` and allow the callers to determine what to do
with it.
PR Close#38618
Currently, the `DatePipe` (via `formatDate()`) rounds fractions of a millisecond to the
nearest millisecond. This can cause dates that are less than a millisecond before midnight
to be incremented to the following day.
The [ECMAScript specification](https://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.11)
defines that `DateTime` milliseconds should always be rounded down, so that `999.9ms`
becomes `999ms`.
This change brings `formatDate()` and so `DatePipe` inline with the ECMAScript
specification.
Fixes#37989
BREAKING CHANGE:
When passing a date-time formatted string to the `DatePipe` in a format that contains
fractions of a millisecond, the milliseconds will now always be rounded down rather than
to the nearest millisecond.
Most applications will not be affected by this change. If this is not the desired behaviour
then consider pre-processing the string to round the millisecond part before passing
it to the `DatePipe`.
PR Close#38009
Some lower level APIs are used by CLI, and requiring
the `formatOpions` argument at that level is a
breaking change. This commit makes it optional
at every level to avoid the breaking change.
PR Close#38787
The `RefreshTransplantedView` flag is used to indicate that the view or one of its children
is transplanted and dirty, so it should still be refreshed as part of change detection.
This flag is set on the transplanted view itself as well setting a
counter on as its parents.
When a transplanted view is detached and still has this flag, it means
it got detached before it was refreshed. This can happen for "backwards
references" or transplanted views that are inserted at a location that
was already checked. In this case, we should decrement the parent
counters _and_ clear the flag on the detached view so it's not seen as
"transplanted" anymore (it is detached and has no parent counters to
adjust).
fixes#38619
PR Close#38768
This commit adds `ngDevMode` guard to throw some errors only in dev mode
The ngDevMode flag helps to tree-shake these error messages from production
builds (in dev mode everything will work as it works right now) to decrease
production bundle size.
PR Close#38674
This change contains the test from #38780 and also removes `defer` from
the `apply_redirects` logic because the change that introduced
`concatMap` instead of `map`...`concatAll` makes `defer` unnecessary.
PR Close#38781
This commit improves the error thrown by the downgrade module with a more
descriptive message on why the downgrade is failing.
Closes#37579
PR Close#38671
As not all users, particularly contributors consistently contributing with a deep
understanding of our commit message guidelines, will not want to rely on the
commit message wizard, we allow a user to opt out of using this wizard during
commit message creation.
PR Close#38701
Create a utility for loading a local user configuration object to describe
local configuration values, such as skipping the commit message wizard.
PR Close#38701
Previously, the validateCommitMessage function ran validation and logged the results.
The validateCommitMessage function now returns an object containing the validation
results and the cli action functions are instead responsible for logging the results.
This is being done as a prefactor for a change which allows for commit message
hook validation to be either a blocking error or a warning.
PR Close#38703
In the test project there are no longer reference markers and location
markers, so there's no need to "pre-process" the source files to remove
them. This will make the Ivy tests cleaner and faster.
PR Close#38777
Add the new podcast called The Deep Dive to the list of Podcast resources.
Also replace the name and URL for Angular inDepth as the old URL is deprecated.
PR Close#37621
When type-checking a component, the declaring NgModule scope is used
to create a directive matcher that contains flattened directive metadata,
i.e. the metadata of a directive and its base classes. This computation
is done for all components, whereas the type-check scope is constant per
NgModule. Additionally, the flattening of metadata is constant per
directive instance so doesn't necessarily have to be recomputed for
each component.
This commit introduces a `TypeCheckScopes` class that is responsible
for flattening directives and computing the scope per NgModule. It
caches the computed results as appropriate to avoid repeated computation.
PR Close#38539
For the compilation of a component, the compiler has to prepare some
information about the directives and pipes that are used in the template.
This information includes an expression for directives/pipes, for usage
within the compilation output. For large NgModule compilation scopes
this has shown to introduce a performance hotspot, as the generation of
expressions is quite expensive. This commit reduces the performance
overhead by only generating expressions for the directives/pipes that
are actually used within the template, significantly cutting down on
the compiler's resolve phase.
PR Close#38539
Whitespace can be relevant in extracted XLIFF translation files.
Some i18n tools - e.g. CAT tool (OmegaT) - will reformat
the file to collapse whitespace if there is no indication to tell it
not to.
This commit adds the ability to specify "format options" that are passed
to the translation file serializer. The XLIFF 1.2 and 2.0 seralizers have
been updated to accept `{"xml:space":"preserve"}` format option which will
by added to the `<file>` element in the serialized translation file during
extraction.
Fixes#38679
PR Close#38737
In most browsers, clicking links with the Alt key has a special behavior, for example, Chrome
downloads the target resource. As with other modifier keys, the router should stop the original
navigation to avoid preventing the browser’s default behavior.
When users click a link while holding the Alt key together, the browsers behave as follows.
Windows 10:
| Browser | Behavior |
|:-----------|:--------------------------------------------|
| Chrome 84 | Download the target resource |
| Firefox 79 | Prevent navigation and therefore do nothing |
| Edge 84 | Download the target resource |
| IE 11 | No impact |
macOS Catalina:
| Browser | Behavior |
|:-----------|:--------------------------------------------|
| Chrome 84 | Download the target resource |
| Firefox 79 | Prevent navigation and therefore do nothing |
| Safari 13 | Download the target resource |
PR Close#38375
The type-to-value conversion could previously crash if a symbol was
resolved that does not have any declarations, e.g. because it's imported
from a missing module. This would typically result in a semantic
TypeScript diagnostic and halt further compilation, therefore not
reaching the type-to-value conversion logic. In Bazel however, it turns
out that Angular semantic diagnostics are requested even if there are
semantic TypeScript errors in the program, so it would then reach the
type-to-value conversation and crash.
This commit fixes the unsafe access and adds a test that ignores the
TypeScript semantic error, effectively replicating the situation as
experienced under Bazel.
Fixes#38670
PR Close#38684
This commit updates (reduces) the payload size limit for a couple test apps. This is a result of
adding the `ngDevMode` to tree-shake more dev-mode-only error messages from the core package within
1150649139.
PR Close#38746
Previously, localized strings had very limited or incorrect source-mapping
information available.
Now the i18n AST nodes and related output AST nodes include source-span
information about message-parts and placeholders - including closing tag
placeholders.
This information is then used when generating the final localized string
ASTs to ensure that the correct source-mapping is rendered.
See #38588 (comment)
PR Close#38645
The `MessagePiece` and derived classes, `LiteralPiece` and `PlaceholderPiece`
need to be referenced in the `LocalizedString` output AST class, so that we
can render the source-spans of each piece.
PR Close#38645
The `TagPlaceholder` can contain children, in which case there are two source
spans of interest: the opening tag and the closing tag. This commit now allows
the closing tag source-span to be tracked, so that it can be used later in
source-mapping.
PR Close#38645
The expression parser will split the expression up at the interpolation markers
into expressions and static strings. This commit also captures the positions of
these strings in the expression to be used in source-mapping later.
PR Close#38645
Since the `defineProperty` not swallow error any longer, now the tests compile
source code in `commonjs` mode, and the code generated includes the code like this
```
Object.defineProperty(exports, "__esModule", {value: true});
```
And the `exports` is undefined in some browsers, but the error is swallowed before
this PR, and all tests run successfully, but it is not correct behavior. After this PR,
the code above failed. So we need to compile the source code in `umd` mode.
PR Close#37582
Close#37432
zone.js monkey patches the `Object.defineProperty` API long time ago
angular/zone.js@383b479
to resolve issues in very old version of Chrome web which override the
property of `CustomElements`, and this is not an issue any longer, so
we want to remove this monkey patch, since it may swallow the errors when the user
want to define property on unconfigurable or frozen object properties.
But currently there are several apps and tests depends on this patch, since
it also change the `configurable` property to `true` by default, so
in this PR we update the logic to not to swallow error any longer unless the property
is the callbacks of `document.registerElements`.
BREAKING CHANGE:
ZoneJS no longer swallows errors produced by `Object.defineProperty` calls.
Prior to this change, ZoneJS monkey patched `Object.defineProperty` and if there is an error
(such as the property is not configurable or not writable) the patched logic swallowed it
and only console.log was produced. This behavior used to hide real errors,
so the logic is now updated to trigger original errors (if any). One exception
where the patch remains in place is `document.registerElement`
(to allow smooth transition for code/polyfills that rely on old behavior in legacy browsers).
If your code relies on the old behavior (where errors were not thrown before),
you may need to update the logic to handle the errors that are no longer masked by ZoneJS patch.
PR Close#37582
Previously this interface was mostly stored in compiler-cli, but it
contains some properties that would be useful for compiling the
"declare component" prelink code.
This commit moves some of the interface over to the compiler
package so that it can be referenced there without creating a
circular dependency between the compiler and compiler-cli.
PR Close#38594
The `R3TargetBinder` accepts an interface for directive metadata which
declares types for `input` and `output` objects. These types convey the
mapping between the property names for an input or output and the
corresponding property name on the component class. Due to
`R3TargetBinder`'s requirements, this mapping was specified with property
names as keys and field names as values.
However, because of duck typing, this interface was accidentally satisifed
by the opposite mapping, of field names to property names, that was produced
in other parts of the compiler. This form more naturally represents the data
model for inputs.
Rather than accept the field -> property mapping and invert it, this commit
introduces a new abstraction for such mappings which is bidirectional,
eliminating the ambiguous plain object type. This mapping uses new,
unambiguous terminology ("class property name" and "binding property name")
and can be used to satisfy both the needs of the binder as well as those of
the template type-checker (field -> property).
A new test ensures that the input/output metadata produced by the compiler
during analysis is directly compatible with the binder via this unambiguous
new interface.
PR Close#38685
This commit adds `ngDevMode` guard to throw some errors only in dev mode
(similar to how things work in other parts of Ivy runtime code). The
`ngDevMode` flag helps to tree-shake these error messages from production
builds (in dev mode everything will work as it works right now) to decrease
production bundle size.
PR Close#38612
If a type has been renamed when it was exported, we need to
reference the external public alias name rather than the internal
original name for the type. Otherwise we will try to import the
type by its internal name, which is not publicly accessible.
Fixes#38238
PR Close#38666
A recent change to `@angular/localize` brought in the `AbsoluteFsPath` type
from the `@angular/compiler-cli`. But this brought along with it a reference
to NodeJS typings - specifically the `FileSystem` interface refers to the
`Buffer` type from NodeJS.
This affects compilation of `@angular/localize` code that will be run in
the browser - for example projects that reference `loadTranslations()`.
The compilation breaks if the NodeJS typings are not included in the build.
Clearly it is not desirable to have these typings included when the project
is not targeting NodeJS.
This commit replaces references to the NodeJS `Buffer` type with `Uint8Array`,
which is available across all platforms and is actually the super-class of
`Buffer`.
Fixes#38692
PR Close#38700
Previously, the location of a translation message, in XLIFF 2, was only
rendered if there were also notes for meaning or description. Now the
location will be rendered even if the other metadata is not provided.
Fixes#38705
PR Close#38713
In general, the router only matches and loads a single Route config tree. However,
named outlets with empty paths are a special case where the router can
and should actually match two different `Route`s and ensure that the
modules are loaded for each match.
This change updates the "ApplyRedirects" stage to ensure that named
outlets with empty paths finish loading their configs before proceeding
to the next stage in the routing pipe. This is necessary because if the
named outlet has `loadChildren` but the associated lazy config is not loaded
before following stages attempt to match and activate relevant `Route`s,
an error will occur.
fixes#12842
PR Close#38379
This commit upgrades all dependencies in `aio/aio-builds-setup/scripts-js/`
to latest versions and also includes all necessary code changes to
ensure the tests are passing with the new dependency versions.
In particular:
- We ensure `nock`'s `Scope#done()` is not called before receiving a
response to account for a breaking change introduced in
nock/nock#1960.
- The use of `nock`'s `Scope#log()` method was removed, because the
method is no longer available since nock/nock#1966. See
https://github.com/nock/nock#debugging for more info on debugging
failed matches.
See also
e23ba31b13/migration_guides/migrating_to_13.md
for more info on migrating from `nock` v12 to v13.
PR Close#38736
Previously, the compiler was not able to display template parsing errors as
true `ts.Diagnostic`s that point inside the template. Instead, it would
throw an actual `Error`, and "crash" with a stack trace containing the
template errors.
Not only is this a poor user experience, but it causes the Language Service
to also crash as the user is editing a template (in actuality the LS has to
work around this bug).
With this commit, such parsing errors are converted to true template
diagnostics with appropriate span information to be displayed contextually
along with all other diagnostics. This majorly improves the user experience
and unblocks the Language Service from having to deal with the compiler
"crashing" to report errors.
PR Close#38576
The template type-checking engine includes utilities for creating
`ts.Diagnostic`s for component templates. Previously only the template type-
checker itself created such diagnostics. However, the template parser also
produces errors which should be represented as template diagnostics.
This commit prepares for that conversion by extracting the machinery for
producing template diagnostics into its own sub-package, so that other parts
of the compiler can depend on it without depending on the entire template
type-checker.
PR Close#38576
`tView` that is stored on a component def contains information about directives and pipes
that are available in the scope of this component. Patching component scope causes `tView` to be
updated. Prior to this commit, the `tView` information was not restored/reset in case component
class is not declared in the `declarations` field while calling `TestBed.configureTestingModule`,
thus causing `tView` to be reused between tests (thus preserving scopes information between tests).
This commit updates TestBed logic to preserve `tView` value before applying scope changes and
reset it back to the previous state between tests.
Closes#38600.
PR Close#38659
Previously this package was installed in the default `dependencies` section
of `package.json`, but this meant that its own dependencies are treated as
dependencies of the main project: Babel, for example.
Generally, $localize` is not used at runtime - it is compiled out by the
translation tooling, so there is no need for it to be a full dependency.
In fact, even if it is used at runtime, the package itself is only used
at dev-time since the runtime bits will be bundled into a distributable.
So putting this package in `devDependencies` would only prevent libraries
from bringing the package into application projects that used them. This
is probably good in itself, since it should be up to the downstream project
to decide if it wants to include `@angular/localize` at runtime.
This commit changes the default location of the package to be the
`devDependencies` section, but gives an option `useAtRuntime` to choose
otherwise.
Fixes#38329
PR Close#38680
Remove CollectionChangeRecord as it was deprecated for removal in v4, use
IterableChangeRecord instead.
BREAKING CHANGE: CollectionChangeRecord has been removed, use IterableChangeRecord
instead
PR Close#38668
Previously, the `sourceSpan` and `startSourceSpan` were the same
object, which meant that you had the following situation:
```
element = <div>some content</div>
sourceSpan = <div>
startSourceSpan = <div>
endSourceSpan = </div>
```
This made `sourceSpan` redundant and meant that if you
wanted a span for the whole element including its content
and closing tag, it had to be computed.
Now `sourceSpan` is separated from `startSourceSpan`
resulting in:
```
element = <div>some content</div>
sourceSpan = <div>some content</div>
startSourceSpan = <div>
endSourceSpan = </div>
```
PR Close#38581
Previously, the `startSourceSpan` property could be null
but in reality it is always well defined - except for a legacy
case in the old i18n extraction/merging code, where the
typings for source-spans are already being undermined.
Making this property non-null, simplifies code elsewhere
in the project.
PR Close#38581
Previously the lexer was responsible for deciding whether an "inline"
template should also have its line-endings normalized.
Now this decision is made higher up in the call stack to allow more
flexibility in the parser/lexer.
PR Close#38581
Previously the position of the error in a translation file when parsing
it was not displayed. Just the error message.
Now the position (line and column) and some context is displayed
along with the error messages.
Fixes#38377
PR Close#38673
The angular team relies on a number of services for hosting code, running CI, etc. This
tool allows for checking the operational status of all services at once as well as the current
state of the repository with respect to merge and triage ready issues and prs.
PR Close#38601
This commit ensures that the `updateValueAndValidity` method takes the
`asyncValidator` into consideration to emit on the `statusChanges` observables.
This is necessary so that any subsequent changes are emitted properly to any
subscribers.
Closes#20424Closes#14542
BREAKING CHANGE:
Previously if FormControl, FormGroup and FormArray class instances had async validators
defined at initialization time, the status change event was not emitted once async validator
completed. After this change the status event is emitted into the `statusChanges` observable.
If your code relies on the old behavior, you can filter/ignore this additional status change
event.
PR Close#38354
The HTML parser gets an element's namespace either from the tag name
(e.g. `<svg:rect>`) or from its parent element `<svg><rect></svg>`) which
breaks down when an element is inside of an SVG `foreignElement`,
because foreign elements allow nodes from a different namespace to be
inserted into an SVG.
These changes add another flag to the tag definitions which tells child
nodes whether to try to inherit their namespaces from their parents.
It also adds a definition for `foreignObject` with the new flag,
allowing elements placed inside it to infer their namespaces instead.
Fixes#37218.
PR Close#38477
Creates a mixin for requiring a github token to be provided to a command. This mixin
allows for a centralized management of the requirement and handling of the github-token.
PR Close#38630
In several occasions it has been observed when the browser has evicted
eagerly cached assets from the cache and which can also not be found on the
server anymore. This can lead to broken state where only parts of the application
will load and others will fail.
This commit fixes this issue by checking for the missing asset in the cache
and on the server. If this condition is true, the broken client will be
notified about the current state through the `UnrecoverableStateError`.
Closes#36539
PR Close#36847
Previously, the condition to make the cache busted was executing although
the network request was successful. However, this is not valid. The cache
should only be marked as busted when the request failed. This commit fixes
the invalid condition.
PR Close#36847
Currently the merge script default branch configuration throws an error
if an unexpected version branch is discovered. The error right now
assumes to much knowledge of the logic and the document outlining
the release trains conceptually.
We change it to something more easy to understand that doesn't require
full understanding of the versioning/labeling/branching document that
has been created for the Angular organization.
PR Close#38622
Creates infrastructure to write outputs of command runs to ng-dev log file.
Additionally, on commands which fail with an exit code greater than 1, an
error log file is created with the posix timestamp of the commands run time
as an identifier.
PR Close#38599
Update the API used to request a timestamp. The previous API we relied on for this
test application, worldclockapi.com no longer serves times and simply 403s on all
requests. This caused our test to timeout as the HTTP request did not handle a failure
case. By moving to a new api, the HTTP request responds as expected and timeouts
are corrected as there is not longer a pending microtask in the queue.
PR Close#38629
Prior to this commit, a lot of internal-only class properties and methods (such as `ngOnChanges`)
of the Forms package directives were exposed on angular.io website. These fields are not expected
to be called externally (they are used/invoked by framework only), since they are part of internal
implementations of the following interfaces:
* Angular lifecycle hook interfaces
* ControlValueAccessor interface
* Validator interface
Having these internal-only fields in docs creates unnecessary noise on directive detail pages.
This commit adds the `@nodoc` annotation to these properties and methods to keep fields in the
golden files, but hide them in docs.
PR Close#38583
Updates the Github robot to reflect the updated target
labels that are used as part of the canonical versioning
and labeling for the Angular organization.
PR Close#38428
We introduced a new shared configuration for merge script
labels that follow the proposal of:
https://docs.google.com/document/d/197kVillDwx-RZtSVOBtPb4BBIAw0E9RT3q3v6DZkykU
These label semantics and the branching are set up for the Angular
framework with this commit. The goal is that labeling and merging
is consistent between all Angular projects and that clear rules
are defined for branching. This was previously not the case.
PR Close#38428
As part of the migration to a common strategy/method for branching and releasing across
the main angular repositories, updates need to be made to the documentation. These changes
reflect the updates made and is based on the following document which describes the
merging label expectations: https://docs.google.com/document/d/197kVillDwx-RZtSVOBtPb4BBIAw0E9RT3q3v6DZkykU
PR Close#38401
CircleCI updated their UI and now the URLs are different (and cannot be
constructed based on the build number alone). This commit removes a
reference of the obsolete URL pattern to avoid confusion.
Example old URL:
https://circleci.com/gh/angular/angular/<build-number>#artifacts
Example new URL:
https://app.circleci.com/pipelines/github/angular/angular/<build-number>/workflows/<workflow-id>/jobs/<job-id>/artifacts
PR Close#38554
- aclarar que el trabajo de bugs / características debe realizarse upstream
- cambiar los enlaces para que apunten dentro del repositorio en lugar de a la web
Within an angular template, when a character entity is unable to be parsed, previously a generic
unexpected character error was thrown. This does not properly express the issue that was discovered
as the issue is actually caused by the discovered character making the whole of the entity unparsable.
The compiler will now instead inform via the error message what string was attempted to be parsed
and what it was attempted to be parsed as.
Example, for this template:
```
<p>
ģp
</p>
```
Before this change:
`Unexpected character "p"`
After this change:
`Unable to parse entity "ģp" - hexadecimal character reference entities must end with ";"`
Fixes#26067
PR Close#38319
This commit updates the `tslint.json` configuration file, that is used
to lint the docs examples, to match the one generated for new Angular
CLI apps. There are some minimal differences (marked with `TODO`
comments) for things, such as component selector prefix, that would
require extensive and/or difficult to validate changes in guides.
This commit also includes the final adjustments to make the docs
examples code compatible with the new tslint rules. (The bulk of the
work has been done in previous commits.)
PR Close#38143
This commit updates the docs examples to be compatible with the
following Angular-specific tslint rules:
- `component-selector`
- `directive-selector`
- `no-conflicting-lifecycle`
- `no-host-metadata-property`
- `no-input-rename`
- `no-output-native`
- `no-output-rename`
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`prefer-const` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`variable-name` tslint rule without requiring the
`allow-leading-underscore` and `allow-trailing-underscore` options.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`no-shadowed-variable` and `variable-name` tslint rules.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`member-ordering` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`no-angle-bracket-type-assertion` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`no-string-literal`, `object-literal-key-quotes` and
`object-literal-shorthand` tslint rules.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`only-arrow-functions` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`jsdoc-format` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`semicolon` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the `align`,
`space-before-function-paren` and `typedef-whitespace` tslint rules.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
This commit updates the docs examples to be compatible with the
`import-spacing` tslint rule.
This is in preparation of updating the docs examples `tslint.json` to
match the one generated for new Angular CLI apps in a future commit.
PR Close#38143
The `03-*` code style rule have been removed from the style guide in
be0bc799f3.
This commit removes the corresponding files and related unused code from
the`styleguide` example project.
PR Close#38143
This commit removes compiler instantiation at startup.
This is because the constructor is invoked during the plugin loading phase,
in which the project has not been completely loaded.
Retrieving `ts.Program` at startup will trigger an `updateGraph` operation,
which could only be called after the Project has loaded completely.
Without this change, the Ivy LS cannot be loaded as a tsserver plugin.
Note that the whole `Compiler` class is temporary, so changes made there are
only for development. Once we have proper integration with ngtsc the
`Compiler` class would be removed.
PR Close#38120
Currently the `getInheritedFactory` function is implemented to allow
closure to remove the call if the base factory is unused. However, this
method does not work with terser. By adding the PURE annotation,
terser will also be able to remove the call when unused.
PR Close#38291
This commit fixes a bug in View Engine whereby the compiler errorneously
thinks that a method of a component has decorator metadata when that
method is one of those in `Object.prototype`, for example `toString`.
This bug is discovered in v10.0.4 of `@angular/language-service` after
the default bundle format was switched from ES5 to ES2015.
ES5 output:
```js
if (propMetadata[propName]) {
decorators.push.apply(decorators, __spread(propMetadata[propName]));
}
```
ES2015 output:
```js
if (propMetadata[propName]) {
decorators.push(...propMetadata[propName]);
}
```
The bug was not discovered in ES5 because the polyfill for the spread
operator happily accepts parameters that do not have the `iterable`
symbol:
```js
function __spread() {
for (var ar = [], i = 0; i < arguments.length; i++)
ar = ar.concat(__read(arguments[i]));
return ar;
}
```
whereas in es2015 it’ll fail since the iterable symbol is not present in
`propMetadata['toString']` which evaluates to a function.
Fixes https://github.com/angular/vscode-ng-language-service/issues/859
PR Close#38292
This reverts commit 7f8c2225f2.
This commit caused test failures internally, which were traced back to the
optimizer removing NgModuleFactory constructor calls when those calls caused
side-effectful registration of NgModules by their ids.
PR Close#38303
This commit disables one TypeChecker test (added as a part of
https://github.com/angular/angular/pull/38105) which make assertions about the filename while
running on Windows.
Such assertions are currently suffering from a case sensitivity issue.
PR Close#38294
The documentation is not clear on how the base href and APP_BASE_HREF are used. This commit
should help clarify more complicated use-cases beyond the most common one of just a '/'
PR Close#38123
This allows Closure compiler to tree shake unused constructor calls to `NgModuleFactory`, which is otherwise considered
side-effectful. The Angular compiler generates factory objects which are exported but typically not used, as they are
only needed for compatibility with View Engine. This results in top-level constructor calls, such as:
```typescript
export const FooNgFactory = new NgModuleFactory(Foo);
```
`NgModuleFactory` has a side-effecting constructor, so this statement cannot be tree shaken, even if `FooNgFactory` is
never imported. The `NgModuleFactory` continues to reference its associated `NgModule` and prevents the module and all
its unused dependencies from being tree shaken. This effectively prevents all components from being tree shaken, making
Closure builds significantly larger than they should be.
The fix here is to wrap `NgModuleFactory` constructor with `noSideEffects(() => /* ... */)`, which tricks the Closure
compiler into assuming that the invoked function has no side effects. This allows it to tree-shake unused
`NgModuleFactory()` constructors when they aren't imported. Since the factory can be removed, the module can also be
removed (if nothing else references it), thus tree shaking unused components as expected.
PR Close#38147
Large strings constants are now wrapped in a function which is called whenever used. This works around a unique
limitation of Closure, where it will **always** inline string literals at **every** usage, regardless of how large the
string literal is or how many times it is used.The workaround is to use a function rather than a string literal.
Closure has differently inlining semantics for functions, where it will check the length of the function and the number
of times it is used before choosing to inline it. By using a function, `ngtsc` makes Closure more conservative about
inlining large strings, and avoids blowing up the bundle size.This optimization is only used if the constant is a large
string. A wrapping function is not included for other use cases, since it would just increase the bundle size and add
unnecessary runtime performance overhead.
PR Close#38253
Prior to this commit, SVG icons were all loaded in the constructor
of the `CustomIconRegistry`. This commit avoids that, and loads SVG
icons on demand.
PR Close#38268
This commit simplifies the creation of the temporary, hidden
`<textarea>` element used by `CopierService` by switching from absolute
to fixed positioning and not requiring page's scroll offset.
It also makes the following minor improvements:
- Make the element invisible (via `opacity: 0`).
- Instruct screen-readers to ignore the element (via
`aria-hidden: true`).
NOTE: These improvements are based on Angular CDK's [PendingCopy][1]
class and the changes proposed in PR angular/components#20073.
[1]: https://github.com/angular/components/blob/89b5fa89d1437c3054c5/src/cdk/clipboard/pending-copy.ts
PR Close#38244
The `CopierService` is used for copying text to the user's clipboard. It
is, for example, used in `CodeComponent` to copy example code snippets.
This is implemented by creating a temporary, hidden `<textarea>`
elements, setting its value to the text that needs to be copied,
executing the `copy` command and finally removing the element from the
DOM.
Previously, as a result of `CopierService`'s implementation, the focused
element would lose focus, while the temporary `<textarea>` element would
implicitly gain focus when selecting its contents. This had an even
worse side-effect on IE11, which seems to scroll to the bottom of the
containing element (here `<body>`) when the focused element is removed.
This commit fixes these issues by keeping track of the previously
focused element and restoring its focus after the copy operation.
NOTE: This fix is inspired by Angular CDK's [PendingCopy][1] class.
[1]: https://github.com/angular/components/blob/89b5fa89d1437c3054c5/src/cdk/clipboard/pending-copy.tsFixes#37796
PR Close#38244
This commit improves the code readability of the `CopierService` by:
- Adding/Improving JSDoc comments for methods.
- Avoiding unnecessary instance-wide properties.
- Fixing indentation to be consistent (at two spaces).
- Clearly separating the logic for creating and populating a
`<textarea>` from the logic for selecting and copying its contents.
PR Close#38244
This commit adds a method `getDiagnosticsForComponent` to the
`TemplateTypeChecker`, which does the minimum amount of work to retrieve
diagnostics for a single component.
With the normal `ReusedProgramStrategy` this offers virtually no improvement
over the standard `getDiagnosticsForFile` operation, but if the
`TypeCheckingProgramStrategy` supports separate shims for each component,
this operation can yield a faster turnaround for components that are
declared in files with many other components.
PR Close#38105
Previously, a stable template id was implemented for each component in a
file. This commit adds this id to each `TemplateDiagnostic` generated from
the template type-checker, so it can potentially be used for filtration.
PR Close#38105
This commit adds an `overrideComponentTemplate` operation to the template
type-checker. This operation changes the template used during template
type-checking operations.
Overriding a template causes any previous work for it to be discarded, and
the template type-checking engine will regenerate the TCB for that template
on the next request.
This operation can be used by a consumer such as the language service to
get rapid feedback or diagnostics as the user is editing a template file,
without the need for a full incremental build iteration.
Closes#38058
PR Close#38105
Previously, the `TemplateTypeChecker` abstraction allowed fetching
diagnostics for a single file, but under the hood would generate type
checking code for the entire program to satisfy the request.
With this commit, an `OptimizeFor` hint is passed to `getDiagnosticsForFile`
which indicates whether the user intends to request diagnostics for the
whole program or is truly interested in just the single file. If the latter,
the `TemplateTypeChecker` can perform only the work needed to produce
diagnostics for just that file, thus returning answers more efficiently.
PR Close#38105
The template type-checking engine relies on the abstraction interface
`TypeCheckingProgramStrategy` to create updated `ts.Program`s for
template type-checking. The basic API is that the type-checking engine
requests changes to certain files in the program, and the strategy provides
an updated `ts.Program`.
Typically, such changes are made to 'ngtypecheck' shim files, but certain
conditions can cause template type-checking to require "inline" operations,
which change user .ts files instead. The strategy used by 'ngc' (the
`ReusedProgramStrategy`) supports these kinds of updates, but other clients
such as the language service might not always support modifying user files.
To accommodate this, the `TypeCheckingProgramStrategy` interface was
modified to include a `supportsInlineOperations` flag. If an implementation
specifies `false` for inline support, the template type-checking system will
return diagnostics on components which would otherwise require inline
operations.
Closes#38059
PR Close#38105
This commit significantly refactors the 'typecheck' package to introduce a
new abstraction, the `TemplateTypeChecker`. To achieve this:
* a 'typecheck:api' package is introduced, containing common interfaces that
consumers of the template type-checking infrastructure can depend on
without incurring a dependency on the template type-checking machinery as
a whole.
* interfaces for `TemplateTypeChecker` and `TypeCheckContext` are introduced
which contain the abstract operations supported by the implementation
classes `TemplateTypeCheckerImpl` and `TypeCheckContextImpl` respectively.
* the `TemplateTypeChecker` interface supports diagnostics on a whole
program basis to start with, but the implementation is purposefully
designed to support incremental diagnostics at a per-file or per-component
level.
* `TemplateTypeChecker` supports direct access to the type check block of a
component.
* the testing utility is refactored to be a lot more useful, and new tests
are added for the new abstraction.
PR Close#38105
Previously in the template type-checking engine, it was assumed that every
input file would have an associated type-checking shim. The type check block
code for all components in the input file would be generated into this shim.
This is fine for whole-program type checking operations, but to support the
language service's requirements for low latency, it would be ideal to be
able to check a single component in isolation, especially if the component
is declared along with many others in a single file.
This commit removes the assumption that the file/shim mapping is 1:1, and
introduces the concept of component-to-shim mapping. Any
`TypeCheckingProgramStrategy` must provide such a mapping.
To achieve this:
* type checking record information is now split into file-level data as
well as per-shim data.
* components are now assigned a stable `TemplateId` which is unique to the
file in which they're declared.
PR Close#38105
When the `NgIf` directive is used in a template, its context variables
can be used to capture the bound value. This is sometimes used in
complex expressions, where the resulting value is captured in a
context variable. There's two syntax forms available:
1. Binding to `NgIfContext.ngIf` using the `as` syntax:
```html
<span *ngIf="enabled && user as u">{{u.name}}</span>
```
2. Binding to `NgIfContext.$implicit` using the `let` syntax:
```html
<span *ngIf="enabled && user; let u">{{u.name}}</span>
```
Because of the semantics of `ngIf`, it is known that the captured
context variable is truthy, however the template type checker
would not consider them as such and still report errors when
`strict` is enabled.
This commit updates `NgIf`'s context guard to make the types of the
context variables truthy, avoiding the issue.
Based on https://github.com/angular/angular/pull/35125
PR Close#36627
```
export const __core_private_testing_placeholder__ = '';
```
This API should be removed. But doing so seems to break `google3` and
so it requires a bit of investigation. A work around is to mark it as
`@codeGenApi` for now and investigate later.
PR Close#38274
Since PullApprove starts all inactive groups as a pending state, to properly
assess if any groups we care about are pending we must only check the active
groups. We additionally do this with rejected because the intention of the
reusable checks is around checking active rules only.
PR Close#38259
`Attribute` decorator has defined `attributeName` as optional but actually its
mandatory and compiler throws an error if `attributeName` is undefined. Made
`attributeName` mandatory in the `Attribute` decorator to reflect this functionality
Fixes#32658
PR Close#38131
It was determined that the list of 'pending' groups also included inactive groups.
That means that the 'no-groups-above-this-pending' would generally fail because
there's almost always some inactive group above it.
This commit removes the conditions for phased review while we
investigate if the inactive groups can be excluded.
PR Close#38257
Project DOCS-736 to rewrite headings to focus on user tasks,
verify that the content is up-to-date and complete, and
add relevant links to other NgModule topics to improve readability.
Also addresses one of many issues in GitHub issue 21531.
PR Close#38206
* Add alxhub, atscott, and AndrewKushnir to code owners
* Add atscott & AndrewKushnir to public-api and size-tracking
Follow-up to #37994
PR Close#38170
Project DOCS-734 to rewrite headings to focus on user tasks,
verify that the content is up-to-date and complete, and
add relevant links to other NgModule topics to improve readability.
Also addresses one of many issues in GitHub issue 21531.
PR Close#38148
Now we have two implementations of Zone in Angular, one is NgZone, the other is NoopZone.
They should have the same signatures, includes
1. properties
2. methods
In this PR, unify the signatures of the two implementations, and remove the unnecessary cast.
PR Close#37581
The current implementation of the TypeScriptReflectionHost does not account for members that
are string literals, i.e. `class A { 'string-literal-prop': string; }`
PR Close#38226
This commit refactors the argument of the `parseEventName` function
to use an object with named properties instead of using an object indexer.
PR Close#38089
Previously the instructions were included in the golden files to monitor the frequency and rate of
the instruction API changes for the purpose of understanding the stability of this API (as it was
considered for becoming a public API and deployed to npm via generated code).
This experiment has confirmed that the instruction API is not stable enough to be used as public
API. We've since also came up with an alternative plan to compile libraries with the Ivy compiler
for npm deployment and this plan does not rely on making Ivy instructions public.
For these reasons, I'm removing the instructions from the golden files as it's no longer important
to track them.
The are three instructions that are still being included: `ɵɵdefineInjectable`, `ɵɵinject`, and
`ɵɵInjectableDef`.
These instructions are already generated by the VE compiler to support tree-shakable providers, and
code depending on these instructions is already deployed to npm. For this reason we need to treat
them as public api.
This change also reduces the code review overhead, because changes to public api golden files now
require multiple approvals.
PR Close#38224
Close#31684.
In some rxjs operator, such as `retryWhen`, rxjs internally will set
`Subscription._unsubscribe` method to null, and the current zone.js monkey patch
didn't handle this case correctly, even rxjs set _unsubscribe to null, zone.js
still return a function by finding the prototype chain.
This PR fix this issue and the following test will pass.
```
const errorGenerator = () => {
return throwError(new Error('error emit'));
};
const genericRetryStrategy = (finalizer: () => void) => (attempts: Observable<any>) =>
attempts.pipe(
mergeMap((error, i) => {
const retryAttempt = i + 1;
if (retryAttempt > 3) {
return throwError(error);
}
return timer(retryAttempt * 1);
}),
finalize(() => finalizer()));
errorGenerator()
.pipe(
retryWhen(genericRetryStrategy(() => {
expect(log.length).toBe(3);
done();
})),
catchError(error => of(error)))
.subscribe()
```
PR Close#37091
This commit clarifies some of the language regarding pipes in the pipes guide.
This commit also specifies the term transforming rather than formatting.
PR Close#37950
Prior to this commit, duplicated styles defined in multiple components in the same file were not
shared between components, thus causing extra payload size. This commit updates compiler logic to
use `ConstantPool` for the styles (while generating the `styles` array on component def), which
enables styles sharing when needed (when duplicates styles are present).
Resolves#38204.
PR Close#38213
Prior to this commit, the `ConstantPool` ignored all primitive values. It turned out that it's
beneficial to include strings above certain length to the pool as well. This commit updates the
`ConstantPool` logic to allow such strings to be shared across multiple instances if needed.
For instance, this is helpful for component styles that might be reused across multiple components
in the same file.
PR Close#38213
This commit splits the transformation into 2 separate steps: Ivy compilation and actual transformation
of corresponding TS nodes. This is needed to have all `o.Expression`s generated before any TS transforms
happen. This allows `ConstantPool` to properly identify expressions that can be shared across multiple
components declared in the same file.
Resolves#38203.
PR Close#38213
This commit refactors Router package to move config utils to a separate file for better
organization and to resolve the problem with circular dependency issue.
Resolves#38212.
PR Close#38229
There are a few changes in this PR to ensure conditions that are based
on groups (i.e. `- groups.pending.length == 0`) do not fail the verify
task:
* Remove the warning when a condition is encountered that depends on the
`groups` state. The warning will otherwise be printed once for every
file that triggers the execution of the condition (400,000+ times)
* Add an `unverifiable` flag to `GroupCondition` interface and set it to
true when an error is encountered due to attempting to get the state of
`groups` in a condition
* Ignore any unverifiable conditions when gathering unmatched
conditions. These should not be considered `unmatched` for verification
purposes.
* Print the unverifiable conditions by group in the results
Sample output:
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ PullApprove results by group │
└──────────────────────────────────────────────────────────────────────────────┘
Groups skipped (4 groups)
Matched conditions by Group (37 groups)
Unmatched conditions by Group (0 groups)
Unverifiable conditions by Group (3 groups)
[public-api]
len(groups.pending.exclude("required-minimum-review")...
len(groups.rejected.exclude("required-minimum-review")...
[size-tracking]
len(groups.pending.exclude("required-minimum-review")...
len(groups.rejected.exclude("required-minimum-review")...
[circular-dependencies]
len(groups.pending.exclude("required-minimum-review")...
len(groups.rejected.exclude("required-minimum-review")...
```
PR Close#37798
The size-tracking, public-api, and circular-dependencies groups can get a lot of
PRs to review. In addition, the members of these groups do not always
have the necessary context to fully review the PR in question. This
change ensures that the owners in the groups where the changes are being
made have approve the changes (ie, the aren't pending or rejected)
before requesting final sign-off from these three critical groups.
PR Close#37798
global-approvers, global-docs-approvers, and required-minimum-review groups are always active. It's useful
to have aliases for getting groups that are active/pending/rejected while excluding these few.
PR Close#37798
Since the PR #36540 change the zone.js bundles to Angular Package Format, the
bundle name/location are changed, so this PR updated the `README.md` doc for the
zone bundles.
Also add the recent added new bundles `zone-patch-message-port` doc.
PR Close#37919
Close#35473
zone.js nodejs patch should also patch `EventEmitter.prototype.off` as `removeListener`.
So `off` can correctly remove the listeners added by `EventEmitter.prototype.addListener`
PR Close#37863
Close#37333
`clearTimeout` is patched by `zone.js`, and it finally calls the native delegate of `clearTimeout`,
the current implemention only call `clearNative(id)`, but it should call on object `global` like
`clearNative.call(global, id)`. Otherwise in some env, it will throw error
`clearTimeout called on an object that does not implement interface Window`
PR Close#37858
Separate `EventTarget`, `FileReader`, `MutationObserver` and `IntersectionObserver` patches into different module.
So the user can disable those modules separately.
PR Close#31657
Previously, `ExampleZipper` (the tool used for creating ZIP archives
from our docs examples) used the `PackageJsonCustomizer` to generate
`package.json` files for each example type. This had the following
drawbacks:
- The generated files had to be kept up-to-date with the corresponding
boilerplate files in `aio/tools/examples/shared/boilerplate/` and
there was no easy way to find out when the files got out-of-sync.
- The `PackageJsonCustomizer` logic was non-trivial and difficult to
reason about.
- The same information was duplicated in the boilerplate files and the
customizer configuration files.
This setup was useful when we used a single `package.json` file for all
docs examples. Now, however, each example type can have its own
boilerplate `package.json` file, including scripts and dependencies
relevant to the example type. Therefore, it is no longer necessary to
generate `package.json` files for ZIP archives.
This commit eliminates the drawbacks mentioned above and simplifies the
`ExampleZipper` tool by removing `PackageJsonCustomizer` and re-using
the boilerplate `package.json` files for ZIP archives.
The changes in this commit also fix some ZIP archives that were
previously broken (for example due to missing dependencies).
PR Close#38192
Conditions can refer to the groups array that is a list of the preceding groups.
This commit adds support to the verification for those conditions.
This commit also adds some tests to the parsing and condition matching
to ensure everything works as expected.
PR Close#38164
This commit creates a sample forms test application to introduce the symbol
tests. It serves as a guard to ensure that any future work on the
forms package does not unintentionally increase the payload size.
PR Close#38044
A util file is added to forms test package:
- it exposes simpleAsyncValidator, asyncValidator and asyncValidatorReturningObservable validators
- it refactors simpleAsyncValidator and asyncValidator to use common promise creation code
- it exposes currentStateOf allowing to get the validation state of a list of AbstractControl
Closes#37831
PR Close#38020
Default change detection fails in some cases for @angular/elements where
component events are called from the wrong zone.
This fixes the issue by running all ComponentNgElementStrategy methods
in the same zone it was created in.
Fixes#24181
PR Close#37814
Create initial document for Angular framework coding standards. This
document will evolve over time. This version contains all
non-controversial rules as discussed in a recent team meeting. Some text
and examples were copied from angular/components.
PR Close#37700
To avoid unnecessary code duplication in docs examples, we have some
boilerplate files for various example types (in
`aio/tools/examples/shared/boilerplate/`). These files are copied to
each example project in `aio/content/examples/` (according to the
example's type, as specified in its `example-config.json` file).
Previously, the `example-boilerplate.js`, which is responsible for
copying the boilerplate files, had lists for files to be copied for each
project type and only copied the listed files from the boilerplate
directory to the example directory. This approach had some drawbacks:
- Files need to be updated in two separate locations: in the boilerplate
directory that includes the files and the file list in
`example-boilerplate.js`.
- It is easy to add a file in the boilerplate directory but forget to
add it in `example-boilerplate.js` and not realize that it is not
being included in the example project (including the generated
StackBlitz project and ZIP archive).
This commit changes the approach by removing the boilerplate file
listings from `example-boilerplate.js` and copying all files from a
boilerplate directory to example directories. This addresses the above
drawbacks and simplifies the `example-boilerplate.js` script.
I have verified that the resulting code example doc regions as well as
the generated StackBlitz projects and ZIP archives are identical to the
ones generated before this commit.
PR Close#38173
Previously, the `.gitignore` file that is part of the boilerplate files
for CLI-based docs examples (located in
`aio/tools/examples/shared/boilerplate/cli/`) was not added to the
example projects, because it was not included in the boilerplate file
list in `example-boilerplate.js`.
This commit fixes it by adding the `.gitignore` file to the list. This
ensures that docs examples more closely match CLI-generated projects.
PR Close#38173
Docs examples of type `i18n` need a slightly modified version of
`polyfills.ts` that imports `@angular/localize/init`. Previously, this
file was not included in `i18n` example projects for two reasons:
- While the file was included in the `i18n` boilerplate files (at
`aio/tools/examples/shared/boilerplate/i18n/`), it was not included in
the boilerplate file list in `example-boilerplate.js`.
- The file was in the wrong location: It was located at the project root
instead of inside the `src/` directory.
This commit addresses the above issues (i.e. adds the file to the
boilerplate file list for `i18n` projects and moves the file inside the
`src/` directory).
PR Close#38173
There were some `systemjs.config.web[.build].js` files in the `systemjs`
boilerplate directory that are not used any more. In the past, these
files were used in the Plunker-based live examples, but we no longer use
Plunker for live examples.
This commit removes these obsolete files.
PR Close#38173
There were two `typings.d.ts` files with SystemJS module definitions in
`aio/src/` and `aio/tools/examples/shared/boilerplate/cli/`. These are
remnants from old CLI versions that used SystemJS and are no longer
needed. For docs examples specifically, these files were never copied
over to example projects and thus not included in StackBlitz projects
and ZIP archives.
This commit removes these obsolete files.
PR Close#38173
Developer docs previously stated to use `yarn bazel test //packages/...` which attempts to test all packages with View
Engine (the default), even though not all support View Engine. This updates the doc to use `yarn test-ivy-aot` and
`yarn test-non-ivy` which tests both Ivy and View Engine while filtering out tests which are not compatible with each
renderer.
PR Close#38149
This commit fixes the spelling of the singular form
of the word function to the plural spelling in
packages/core/src/application_init.ts
PR Close#36586
* **common:** update locales using new CLDR data ([#39343](https://github.com/angular/angular/issues/39343)) ([3738233](https://github.com/angular/angular/commit/3738233))
* **compiler:** promote constants in templates to Trusted Types ([#39211](https://github.com/angular/angular/issues/39211)) ([6e18d2d](https://github.com/angular/angular/commit/6e18d2d))
* **core:** guard reading of global `ngDevMode` for undefined. ([#36055](https://github.com/angular/angular/issues/36055)) ([f541e5f](https://github.com/angular/angular/commit/f541e5f))
* **language-service:** [Ivy] create compiler only when program changes ([#39231](https://github.com/angular/angular/issues/39231)) ([8f1317f](https://github.com/angular/angular/commit/8f1317f))
* **ngcc:** ensure that "inline exports" can be interpreted correctly ([#39267](https://github.com/angular/angular/issues/39267)) ([822b838](https://github.com/angular/angular/commit/822b838))
* **platform-server:** Resolve absolute URL from baseUrl ([#39334](https://github.com/angular/angular/issues/39334)) ([b4e8399](https://github.com/angular/angular/commit/b4e8399))
* **router:** incorrect signature for createUrlTree ([#39347](https://github.com/angular/angular/issues/39347)) ([161b278](https://github.com/angular/angular/commit/161b278))
### Code Refactoring
* **compiler:** remove support for TypeScript 3.9 ([#39313](https://github.com/angular/angular/issues/39313)) ([736e064](https://github.com/angular/angular/commit/736e064))
### BREAKING CHANGES
* **platform-server:** If you use `useAbsoluteUrl` to setup `platform-server`, you now need to
also specify `baseUrl`.
We are intentionally making this a breaking change in a minor release,
because if `useAbsoluteUrl` is set to `true` then the behavior of the
application could be unpredictable, resulting in issues that are hard to
discover but could be affecting production environments.
* **compiler:** TypeScript 3.9 is no longer supported, please upgrade to TypeScript 4.0.
<aname="10.2.0"></a>
# 10.2.0 (2020-10-21)
### Bug Fixes
* **core:** guard reading of global `ngDevMode` for undefined. ([#36055](https://github.com/angular/angular/issues/36055)) ([02405f1](https://github.com/angular/angular/commit/02405f1))
* **platform-server:** Resolve absolute URL from baseUrl ([#39334](https://github.com/angular/angular/issues/39334)) ([71fb99f](https://github.com/angular/angular/commit/71fb99f))
### BREAKING CHANGES
* **platform-server:** If you use `useAbsoluteUrl` to setup `platform-server`, you now need to
also specify `baseUrl`.
We are intentionally making this a breaking change in a minor release,
because if `useAbsoluteUrl` is set to `true` then the behavior of the
application could be unpredictable, resulting in issues that are hard to
discover but could be affecting production environments.
<aname="11.0.0-next.6"></a>
# 11.0.0-next.6 (2020-10-14)
### Bug Fixes
* **compiler-cli:** type checking of expressions within ICUs ([#39072](https://github.com/angular/angular/issues/39072)) ([0a16e60](https://github.com/angular/angular/commit/0a16e60)), closes [#39064](https://github.com/angular/angular/issues/39064)
* **core:** migrate relative link resolution with single quotes ([#39102](https://github.com/angular/angular/issues/39102)) ([049b453](https://github.com/angular/angular/commit/049b453)), closes [#39082](https://github.com/angular/angular/issues/39082)
* **core:** use Trusted Types policy in inert DOM builder ([#39208](https://github.com/angular/angular/issues/39208)) ([7d49299](https://github.com/angular/angular/commit/7d49299))
* **core:** use Trusted Types policy in named_array_type ([#39209](https://github.com/angular/angular/issues/39209)) ([f6d5cdf](https://github.com/angular/angular/commit/f6d5cdf))
* **router:** Allow undefined inputs on routerLink ([#39151](https://github.com/angular/angular/issues/39151)) ([b0b4953](https://github.com/angular/angular/commit/b0b4953))
* **router:** create schematic for preserveQueryParams ([#38762](https://github.com/angular/angular/issues/38762)) ([93ee05d](https://github.com/angular/angular/commit/93ee05d))
* **router:** remove preserveQueryParams symbol ([#38762](https://github.com/angular/angular/issues/38762)) ([783a5bd](https://github.com/angular/angular/commit/783a5bd))
### Features
* **core:** add automated migration to replace async with waitForAsync ([#39212](https://github.com/angular/angular/issues/39212)) ([5ce71e0](https://github.com/angular/angular/commit/5ce71e0))
* **core:** add automated migration to replace ViewEncapsulation.Native ([#38882](https://github.com/angular/angular/issues/38882)) ([0e733f3](https://github.com/angular/angular/commit/0e733f3))
* **core:** depend on type definitions for Trusted Types ([#39207](https://github.com/angular/angular/issues/39207)) ([c4266fb](https://github.com/angular/angular/commit/c4266fb))
* **language-service:** [Ivy] getSemanticDiagnostics for external templates ([#39065](https://github.com/angular/angular/issues/39065)) ([63624a2](https://github.com/angular/angular/commit/63624a2))
* **language-service:** Add getTypeDefinitionAtPosition (go to type definition) ([#39145](https://github.com/angular/angular/issues/39145)) ([a84976f](https://github.com/angular/angular/commit/a84976f))
* **language-service:** Add module name to directive quick info ([#39121](https://github.com/angular/angular/issues/39121)) ([4604fe9](https://github.com/angular/angular/commit/4604fe9))
* **router:** add new initialNavigation options to replace legacy ([#37480](https://github.com/angular/angular/issues/37480)) ([c4becca](https://github.com/angular/angular/commit/c4becca))
### BREAKING CHANGES
* **router:** * The `initialNavigation` property for the options in
`RouterModule.forRoot` no longer supports `legacy_disabled`,
`legacy_enabled`, `true`, or `false` as valid values.
`legacy_enabled` (the old default) is instead `enabledNonBlocking`
* **ngcc:** ensure that "inline exports" can be interpreted correctly ([#39272](https://github.com/angular/angular/issues/39272)) ([e08d021](https://github.com/angular/angular/commit/e08d021))
* **ngcc:** map `exports` to the current module in UMD files ([#38959](https://github.com/angular/angular/issues/38959)) ([#39272](https://github.com/angular/angular/issues/39272)) ([13c4a7b](https://github.com/angular/angular/commit/13c4a7b))
* **ngcc:** support inline export declarations in UMD files ([#38959](https://github.com/angular/angular/issues/38959)) ([#39272](https://github.com/angular/angular/issues/39272)) ([9c875b3](https://github.com/angular/angular/commit/9c875b3)), closes [#38947](https://github.com/angular/angular/issues/38947)
### build
* upgrade angular build, integration/bazel and [@angular](https://github.com/angular)/bazel package to rule_nodejs 2.2.0 ([#39182](https://github.com/angular/angular/issues/39182)) ([7628c36](https://github.com/angular/angular/commit/7628c36))
### Performance Improvements
* **ngcc:** do not rescan program source files when referenced from multiple root files ([#39254](https://github.com/angular/angular/issues/39254)) ([5221df8](https://github.com/angular/angular/commit/5221df8)), closes [#39240](https://github.com/angular/angular/issues/39240)
<aname="11.0.0-next.5"></a>
# 11.0.0-next.5 (2020-10-07)
### Bug Fixes
* **common:** add boolean to valid json for testing ([#37893](https://github.com/angular/angular/issues/37893)) ([3c474ec](https://github.com/angular/angular/commit/3c474ec)), closes [#20690](https://github.com/angular/angular/issues/20690)
* **core:** use single quotes for relative link resolution migration to align with style guide ([#39070](https://github.com/angular/angular/issues/39070)) ([8894706](https://github.com/angular/angular/commit/8894706))
* **forms:** improve types of directive constructor arguments ([#38944](https://github.com/angular/angular/issues/38944)) ([246de9a](https://github.com/angular/angular/commit/246de9a))
* **forms:** include null in .parent of abstract control ([#32671](https://github.com/angular/angular/issues/32671)) ([f4f1bcc](https://github.com/angular/angular/commit/f4f1bcc)), closes [#16999](https://github.com/angular/angular/issues/16999)
* **language-service:** [Ivy] hybrid visitor should not locate let keyword ([#39061](https://github.com/angular/angular/issues/39061)) ([70e13dc](https://github.com/angular/angular/commit/70e13dc))
* **router:** properly assign ExtraOptions to Router in RouterTestingModule ([#39096](https://github.com/angular/angular/issues/39096)) ([d8c0534](https://github.com/angular/angular/commit/d8c0534)), closes [#23347](https://github.com/angular/angular/issues/23347)
### Features
* **compiler-cli:** support getting resource dependencies for a source file ([#38048](https://github.com/angular/angular/issues/38048)) ([5dbf357](https://github.com/angular/angular/commit/5dbf357))
* **language-service:** Add getDefinitionAndBoundSpan (go to definition) ([#39101](https://github.com/angular/angular/issues/39101)) ([3975dd9](https://github.com/angular/angular/commit/3975dd9))
* **language-service:** add quick info for inline templates in ivy ([#39060](https://github.com/angular/angular/issues/39060)) ([904adb7](https://github.com/angular/angular/commit/904adb7))
### BREAKING CHANGES
* **forms:** Directives in the `@angular/forms` package used to have `any[]` as a type of `validators` and
`asyncValidators` arguments in constructors. Now these arguments are properly typed, so if your
code relies on directive constructor types it may require some updates to improve type safety.
* **forms:** Type of AbstractFormControl.parent now includes null
`null` is now included in the types of .parent. If you don't already have a check for this case,
the TypeScript compiler might compain. A v11 migration exists which adds the not-null assertion
operator where necessary.
In an unlikely case your code was testing the parnet against undefined with sitrct equality,
you'll need to change this to `=== null` instead, since the parent is not explicily initialized
with `null` instead of being left `undefined`.
<aname="10.1.5"></a>
## 10.1.5 (2020-10-07)
@ -9,6 +178,92 @@
<aname="11.0.0-next.4"></a>
# 11.0.0-next.4 (2020-09-30)
### Bug Fixes
* **common:** correct and simplify typing of `KeyValuePipe` ([#37447](https://github.com/angular/angular/issues/37447)) ([4dfe0fa](https://github.com/angular/angular/commit/4dfe0fa))
* **common:** correct and simplify typing of AsyncPipe ([#37447](https://github.com/angular/angular/issues/37447)) ([5f815c0](https://github.com/angular/angular/commit/5f815c0))
* **common:** correct and simplify typing of I18nPluralPipe ([#37447](https://github.com/angular/angular/issues/37447)) ([3b919ef](https://github.com/angular/angular/commit/3b919ef))
* **common:** correct typing and implementation of `SlicePipe` ([#37447](https://github.com/angular/angular/issues/37447)) ([4744c22](https://github.com/angular/angular/commit/4744c22))
* **common:** let case conversion pipes accept type unions with `null` ([#36259](https://github.com/angular/angular/issues/36259)) ([#37447](https://github.com/angular/angular/issues/37447)) ([c7d5555](https://github.com/angular/angular/commit/c7d5555))
* **compiler-cli:** perform DOM schema checks even in basic mode in g3 ([#38943](https://github.com/angular/angular/issues/38943)) ([40975e0](https://github.com/angular/angular/commit/40975e0))
* **packaging:** remove polyfills needed to run tests on IE9 and IE 10 ([#38931](https://github.com/angular/angular/issues/38931)) ([4ca1c73](https://github.com/angular/angular/commit/4ca1c73))
* **platform-webworker:** remove platform-webworker and platform-webworker-dynamic ([#38846](https://github.com/angular/angular/issues/38846)) ([93c3d8f](https://github.com/angular/angular/commit/93c3d8f))
* **router:** make relativeLinkResolution corrected by default ([#25609](https://github.com/angular/angular/issues/25609)) ([837889f](https://github.com/angular/angular/commit/837889f)), closes [#22394](https://github.com/angular/angular/issues/22394)
### Code Refactoring
* **router:** Adjust type of parameter in navigateByUrl and createUrlTree to be more accurate ([#38227](https://github.com/angular/angular/issues/38227)) ([e4f4d18](https://github.com/angular/angular/commit/e4f4d18)), closes [#18798](https://github.com/angular/angular/issues/18798)
### Features
* **common:** stricter types for DatePipe ([#37447](https://github.com/angular/angular/issues/37447)) ([daf8b7f](https://github.com/angular/angular/commit/daf8b7f))
* **common:** stricter types for number pipes ([#37447](https://github.com/angular/angular/issues/37447)) ([7b2aac9](https://github.com/angular/angular/commit/7b2aac9))
* **compiler:** Add keySpan to Variable Node ([#38965](https://github.com/angular/angular/issues/38965)) ([239968d](https://github.com/angular/angular/commit/239968d))
* **router:** Add `relativeLinkResolution` migration to update default value ([#38698](https://github.com/angular/angular/issues/38698)) ([15ea811](https://github.com/angular/angular/commit/15ea811))
### BREAKING CHANGES
* **packaging:** In v10, IE 9, 10, and IE mobile support was deprecated. In v11, Angular framework removes IE 9,
10, and IE mobile support completely.
Supporting outdated browsers like these increases bundle size, code complexity, and test load,
and also requires time and effort that could be spent on improvements to the framework.
For example, fixing issues can be more difficult, as a straightforward fix for modern browsers
could break old ones that have quirks due to not receiving updates from vendors.
* **platform-webworker:** @angular/platform-webworker and @angular/platform-webworker-dynamic
have been removed as they were deprecated in v8
* **common:** The `slice` pipe now returns `null` for the `undefined` input value,
which is consistent with the behavior of most pipes. If you rely on
`undefined` being the result in that case, you now need to check for it
explicitly.
* **common:** The typing of the `keyvalue` pipe has been fixed to report that for
input objects that have `number` keys, the result will contain the
string representation of the keys. This was already the case and the
code has simply been updated to reflect this. Please update the
consumers of the pipe output if they were relying on the incorrect
types. Note that this does not affect use cases where the input values
are `Map`s, so if you need to preserve `number`s, this is an effective
way.
* **common:** The signatures of the number pipes now explicitly state which types are
accepted. This should only cause issues in corner cases, as any other
values would result in runtime exceptions.
* **common:** The signature of the `date` pipe now explicitly states which types are
accepted. This should only cause issues in corner cases, as any other
values would result in runtime exceptions.
* **common:** The async pipe no longer claims to return `undefined` for an input that
was typed as `undefined`. Note that the code actually returned `null` on
`undefined` inputs. In the unlikely case you were relying on this,
please fix the typing of the consumers of the pipe output.
* **common:** The case conversion pipes no longer let falsy values through. They now
map both `null` and `undefined` to `null` and raise an exception on
invalid input (`0`, `false`, `NaN`) just like most "common pipes". If
your code required falsy values to pass through, you need to handle them
explicitly.
* **router:** While the new parameter types allow a variable of type
`NavigationExtras` to be passed in, they will not allow object literals,
as they may only specify known properties. They will also not accept
types that do not have properties in common with the ones in the `Pick`.
To fix this error, only specify properties from the `NavigationExtras` which are
actually used in the respective function calls or use a type assertion
on the object or variable: `as NavigationExtras`.
* **router:** This commit changes the default value of
`relativeLinkResolution` from `'legacy'` to `'default'`. If your
application previously used the default by not specifying a value in the
`ExtraOptions` and uses relative links when navigating from children of
empty path routes, you will need to update your `RouterModule` to
specifically specify `'legacy'` for `relativeLinkResolution`.
See https://angular.io/api/router/ExtraOptions#relativeLinkResolution
for more details.
<aname="10.1.4"></a>
## 10.1.4 (2020-09-30)
@ -19,6 +274,38 @@
<aname="11.0.0-next.3"></a>
# 11.0.0-next.3 (2020-09-23)
### Bug Fixes
* **common:** add `params` and `reportProgress` options to `HttpClient.put()` overload ([#37873](https://github.com/angular/angular/issues/37873)) ([dd8d8c8](https://github.com/angular/angular/commit/dd8d8c8)), closes [#23600](https://github.com/angular/angular/issues/23600)
* **compiler-cli:** generate `let` statements in ES2015+ mode ([#38775](https://github.com/angular/angular/issues/38775)) ([123bff7](https://github.com/angular/angular/commit/123bff7))
* **core:** ensure TestBed is not instantiated before override provider ([#38717](https://github.com/angular/angular/issues/38717)) ([c8f056b](https://github.com/angular/angular/commit/c8f056b))
* **forms:** type NG_VALUE_ACCESSOR injection token as array ([#29723](https://github.com/angular/angular/issues/29723)) ([2b1b718](https://github.com/angular/angular/commit/2b1b718)), closes [#29351](https://github.com/angular/angular/issues/29351)
### Features
* **common:** Add ISO week-numbering year formats support to formatDate ([#38828](https://github.com/angular/angular/issues/38828)) ([984ed39](https://github.com/angular/angular/commit/984ed39))
* **compiler:** Parse and recover on incomplete opening HTML tags ([#38681](https://github.com/angular/angular/issues/38681)) ([6ae3b68](https://github.com/angular/angular/commit/6ae3b68)), closes [#38596](https://github.com/angular/angular/issues/38596)
* **router:** add migration to update calls to navigateByUrl and createUrlTree with invalid parameters ([#38825](https://github.com/angular/angular/issues/38825)) ([7849fdd](https://github.com/angular/angular/commit/7849fdd)), closes [#38227](https://github.com/angular/angular/issues/38227)
* **service-worker:** add the option to prefer network for navigation requests ([#38565](https://github.com/angular/angular/issues/38565)) ([a206852](https://github.com/angular/angular/commit/a206852)), closes [#38194](https://github.com/angular/angular/issues/38194)
### BREAKING CHANGES
* **core:** If you call `TestBed.overrideProvider` after TestBed initialization, provider overrides are not applied. This
behavior is consistent with other override methods (such as `TestBed.overrideDirective`, etc) but they
throw an error to indicate that, when the check was missing in the `TestBed.overrideProvider` function.
Now calling `TestBed.overrideProvider` after TestBed initialization also triggers an
error, thus there is a chance that some tests (where `TestBed.overrideProvider` is
called after TestBed initialization) will start to fail and require updates to move `TestBed.overrideProvider` calls
before TestBed initialization is completed.
<aname="10.1.3"></a>
## 10.1.3 (2020-09-23)
@ -35,6 +322,57 @@
<aname="11.0.0-next.2"></a>
# 11.0.0-next.2 (2020-09-16)
### Bug Fixes
* **common:** do not round up fractions of a millisecond in `DatePipe` ([#38009](https://github.com/angular/angular/issues/38009)) ([26f2820](https://github.com/angular/angular/commit/26f2820)), closes [/www.ecma-international.org/ecma-262/5.1/#sec-15](https://github.com//www.ecma-international.org/ecma-262/5.1//issues/sec-15) [#37989](https://github.com/angular/angular/issues/37989)
* **common:** mark locale data arrays as readonly ([#30397](https://github.com/angular/angular/issues/30397)) ([6acea54](https://github.com/angular/angular/commit/6acea54)), closes [#27003](https://github.com/angular/angular/issues/27003)
* **compiler:** source span for microsyntax text att should be key span ([#38766](https://github.com/angular/angular/issues/38766)) ([8f349b2](https://github.com/angular/angular/commit/8f349b2))
* **router:** Fix arguments order for call to shouldReuseRoute ([#26949](https://github.com/angular/angular/issues/26949)) ([3817e5f](https://github.com/angular/angular/commit/3817e5f)), closes [#16192](https://github.com/angular/angular/issues/16192) [#16192](https://github.com/angular/angular/issues/16192)
### Features
* **compiler-cli:** `TemplateTypeChecker` operation to get `Symbol` from a template node ([#38618](https://github.com/angular/angular/issues/38618)) ([c4556db](https://github.com/angular/angular/commit/c4556db))
* **compiler-cli:** Add ability to get `Symbol` of `Template`s and `Element`s in component template ([#38618](https://github.com/angular/angular/issues/38618)) ([cf2e8b9](https://github.com/angular/angular/commit/cf2e8b9))
* **compiler-cli:** Add ability to get `Symbol` of AST expression in component template ([#38618](https://github.com/angular/angular/issues/38618)) ([f56ece4](https://github.com/angular/angular/commit/f56ece4))
* **compiler-cli:** add ability to get symbol of reference or variable ([#38618](https://github.com/angular/angular/issues/38618)) ([19598b4](https://github.com/angular/angular/commit/19598b4))
* **compiler-cli:** define interfaces to be used for TemplateTypeChecker ([#38618](https://github.com/angular/angular/issues/38618)) ([9e77bd3](https://github.com/angular/angular/commit/9e77bd3))
### Performance Improvements
* **compiler-cli:** only emit directive/pipe references that are used ([#38539](https://github.com/angular/angular/issues/38539)) ([077f516](https://github.com/angular/angular/commit/077f516))
* **compiler-cli:** optimize computation of type-check scope information ([#38539](https://github.com/angular/angular/issues/38539)) ([297c060](https://github.com/angular/angular/commit/297c060))
* **router:** use `ngDevMode` to tree-shake error messages in router ([#38674](https://github.com/angular/angular/issues/38674)) ([db21c4f](https://github.com/angular/angular/commit/db21c4f))
### BREAKING CHANGES
* **router:** This change corrects the argument order when calling
RouteReuseStrategy#shouldReuseRoute. Previously, when evaluating child
routes, they would be called with the future and current arguments would
be swapped. If your RouteReuseStrategy relies specifically on only the future
or current snapshot state, you may need to update the shouldReuseRoute
implementation's use of "future" and "current" ActivateRouteSnapshots.
* **common:** The locale data API has been marked as returning readonly arrays, rather
than mutable arrays, since these arrays are shared across calls to the
API. If you were mutating them (e.g. calling `sort()`, `push()`, `splice()`, etc)
then your code will not longer compile. If you need to mutate the array, you
should now take a copy (e.g. by calling `slice()`) and mutate the copy.
* **common:** When passing a date-time formatted string to the `DatePipe` in a format that contains
fractions of a millisecond, the milliseconds will now always be rounded down rather than
to the nearest millisecond.
Most applications will not be affected by this change. If this is not the desired behaviour
then consider pre-processing the string to round the millisecond part before passing
* **core:** remove CollectionChangeRecord symbol ([#38668](https://github.com/angular/angular/issues/38668)) ([fdea180](https://github.com/angular/angular/commit/fdea180))
* **router:** support lazy loading for empty path named outlets ([#38379](https://github.com/angular/angular/issues/38379)) ([926ffcd](https://github.com/angular/angular/commit/926ffcd)), closes [#12842](https://github.com/angular/angular/issues/12842)
### BREAKING CHANGES
* **core:** CollectionChangeRecord has been removed, use IterableChangeRecord
instead
<aname="10.1.1"></a>
## 10.1.1 (2020-09-09)
@ -82,6 +438,31 @@
<aname="11.0.0-next.0"></a>
# 11.0.0-next.0 (2020-09-02)
### Bug Fixes
* **forms:** ensure to emit `statusChanges` on subsequent value update/validations ([#38354](https://github.com/angular/angular/issues/38354)) ([d9fea85](https://github.com/angular/angular/commit/d9fea85)), closes [#20424](https://github.com/angular/angular/issues/20424) [#14542](https://github.com/angular/angular/issues/14542)
* **service-worker:** fix condition to check for a cache-busted request ([#36847](https://github.com/angular/angular/issues/36847)) ([5be4edf](https://github.com/angular/angular/commit/5be4edf))
As contributors and maintainers of the Angular project, we pledge to respect everyone who contributes by posting issues, updating documentation, submitting pull requests, providing feedback in comments, and any other activities.
## 1. Propósito
Communication through any of Angular's channels (GitHub, Gitter, IRC, mailing lists, Google+, Twitter, etc.) must be constructive and never resort to personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
“Prometemos brindar cortesía y respeto a cualquier persona involucrada en esta comunidad, sin importar el género con el que se identifique, su orientación sexual, limitación física, edad, raza, etnia, religión o nivel de conocimiento. Esperamos que cualquiera que desee contribuir en este proyecto brinde el mismo comportamiento”
We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, disability, age, race, ethnicity, religion, or level of experience. We expect anyone contributing to the Angular project to do the same.
Bajo ese principio queremos enfocar esta comunidad, una comunidad de respeto por el otro, donde cualquiera que sienta pasión por Angular y desee involucrarse con cualquier tipo de actividad deberá ayudar a mantener una atmósfera de cortesía por el otro, respetando los pensamientos, acciones, ideales y propuestas del otro.
If any member of the community violates this code of conduct, the maintainers of the Angular project may take action, removing issues, comments, and PRs or blocking accounts as deemed appropriate.
## 2. Comportamiento esperado
If you are subject to or witness unacceptable behavior, or have any other concerns, please email us at [conduct@angular.io](mailto:conduct@angular.io).
- Evitar usar expresiones o gestos insultantes, humillantes o intimidatorios para referirnos a otros.
- Ejercita la consideración y el respeto en tus comunicaciones y acciones.
- Absténte de adoptar una conducta y un lenguaje degradantes, discriminatorios, abusivos o acosadores.
- Evitar comportamientos que agredan las expresiones de identidad, género, creencias religiosas, acciones que lastimen o los aíslen a otros.
- Evitar comentarios sobre ideas políticas.
- No se toleran conductas físicas y actitudes dirigidas al descrédito personal, físico o emocional de cualquier persona.
- No se toleran chistes y comentarios excluyentes, sexistas y racistas.
- Se rechaza actitudes de hostigamiento.
- Se rechaza el acoso: este se entiende como cualquier tipo de comentario verbal que refuerce discriminación por género, identidad y expresión de género, orientación sexual, discapacidad, apariencia física, tamaño corporal, raza, edad o religión en contextos laborales o sociales.
- No se tolera el contacto físico y/o la atención sexual no deseada.
- Promover la igualdad de oportunidades de formación, educación, intercambio y retroalimentación antes, durante y después de los eventos.
- Intenta colaborar en lugar de generar conflicto.
- Sé consciente de tu entorno y de tus compañeros participantes. Alerta a líderes de la comunidad si notas una situación peligrosa, alguien en apuros, o violaciones de este Código de Conducta, incluso si parecen intrascendentes.
## 3. Comportamiento inaceptable
Comportamientos inaceptables incluyen: intimidación, acoso, abuso, discriminación, comunicación despectiva o degradante o acciones por cualquier participante en nuestra comunidad ya sea virtual, o en las comunicaciones uno-a-uno que se realizan en el contexto de la comunidad. Por favor ser respetuoso con todos.
El acoso incluye: comentarios nocivos o perjudiciales, verbales o escritos relacionados con el género, la orientación sexual, raza, religión, discapacidad; uso inadecuado de desnudos y / o imágenes sexuales en espacios públicos (incluyendo la presentación diapositivas); intimidación deliberada, acecho o seguimiento; fotografías o grabaciones acosadoras; interrupción sostenida de charlas y otros eventos; contacto físico inapropiado, y atención sexual no deseada.
## 4. Consecuencias de comportamiento inaceptable
Se espera que personas a quienes se les solicite que detengan su comportamiento inaceptable lo hagan de manera inmediata esto será válido para cualquier miembro de la comunidad.
En caso de presentarse una violación al código de conducta de manera repetida se tendrá cero tolerancia a este comportamiento por parte de los organizadores.
Si un miembro de la comunidad participa en una conducta inaceptable, los organizadores pueden tomar cualquier acción que consideren apropiada, hasta e incluyendo una prohibición temporal o expulsión permanente de la comunidad, sin previo aviso.
Priorizamos la seguridad de las personas marginadas sobre la comodidad de las personas privilegiadas. Nos reservamos el derecho de no actuar sobre las quejas relacionadas con:
- El "racismo inverso", "sexismo inverso" y "cisfobia".
- Comunicación razonable de límites, como "déjame en paz", "vete" o "no estoy discutiendo esto contigo".
- Al comunicarse en un "tono", no se encuentra agradable.
- Identificando comportamientos o suposiciones racistas, sexistas, cissexistas u opresivas.
## 5. ¿Qué hacer si se incumple el código de conducta?
Si eres víctima o testigo de una conducta inaceptable, o tienes cualquier inquietud, por favor comunícate con el equipo organizador lo antes posible:
- Mensaje directo: Michael Prentice (@splaktar)
- Mensaje directo: Jorge Cano (@jorgeucano)
- Mensaje directo: Andrés Villanueva (@villanuevand)
- Una vez haya sido notificada el no cumplimiento de la norma, el equipo de liderazgo se reunirán y analizarán el caso.
- Los incidentes presentados se manejarán con discreción.
- Los organizadores se comunicarán con la persona que incumplió la norma y tomarán las medidas respectivas.
- Se realizará un acompañamiento a la persona agredida y se apoyará.
- Si el incidente se hace público, Angular Hispano no se hace responsable de los perjuicios que esto pueda ocasionar en el agresor o el agredido.
## 6. Alcance
Esperamos que todos los participantes de la comunidad (organizadores, voluntarios, contribuyentes pagados o de otro modo; patrocinadores; y otros invitados) se atengan a este Código de Conducta en todos los espacios virtuales y presenciales, así como en todas las comunicaciones de uno-a-uno pertinentes la comunidad.
We would love for you to contribute to Angular and help make it even better than it is today!
As a contributor, here are the guidelines we would like you to follow:
- [Code of Conduct](#coc)
- [Question or Problem?](#question)
- [Issues and Bugs](#issue)
- [Feature Requests](#feature)
- [Submission Guidelines](#submit)
- [Coding Rules](#rules)
- [Commit Message Guidelines](#commit)
- [Signing the CLA](#cla)
## <a name="coc"></a> Code of Conduct
Help us keep Angular open and inclusive.
Please read and follow our [Code of Conduct][coc].
## <a name="question"></a> Got a Question or Problem?
Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests.
Instead, we recommend using [Stack Overflow](https://stackoverflow.com/questions/tagged/angular) to ask support-related questions. When creating a new question on Stack Overflow, make sure to add the `angular` tag.
Stack Overflow is a much better place to ask questions since:
- there are thousands of people willing to help on Stack Overflow
- questions and answers stay available for public viewing so your question/answer might help someone else
- Stack Overflow's voting system assures that the best answers are prominently visible.
To save your and our time, we will systematically close all issues that are requests for general support and redirect people to Stack Overflow.
If you would like to chat about the question in real-time, you can reach out via [our gitter channel][gitter].
## <a name="issue"></a> Found a Bug?
If you find a bug in the source code, you can help us by [submitting an issue](#submit-issue) to our [GitHub Repository][github].
Even better, you can [submit a Pull Request](#submit-pr) with a fix.
## <a name="feature"></a> Missing a Feature?
You can *request* a new feature by [submitting an issue](#submit-issue) to our GitHub Repository.
If you would like to *implement* a new feature, please consider the size of the change in order to determine the right steps to proceed:
* For a **Major Feature**, first open an issue and outline your proposal so that it can be discussed.
This process allows us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
**Note**: Adding a new topic to the documentation, or significantly re-writing a topic, counts as a major feature.
* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr).
## <a name="submit"></a> Submission Guidelines
### <a name="submit-issue"></a> Submitting an Issue
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it.
In order to reproduce bugs, we require that you provide a minimal reproduction.
Having a minimal reproducible scenario gives us a wealth of important information without going back and forth to you with additional questions.
A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem) as well as confirm that we are fixing the right problem.
We require a minimal reproduction to save maintainers' time and ultimately be able to fix more bugs.
Often, developers find coding problems themselves while preparing a minimal reproduction.
We understand that sometimes it might be hard to extract essential bits of code from a larger codebase but we really need to isolate the problem before we can fix it.
Unfortunately, we are not able to investigate / fix bugs without a minimal reproduction, so if we don't hear back from you, we are going to close an issue that doesn't have enough info to be reproduced.
You can file new issues by selecting from our [new issue templates](https://github.com/angular/angular/issues/new/choose) and filling out the issue template.
### <a name="submit-pr"></a> Submitting a Pull Request (PR)
Before you submit your Pull Request (PR) consider the following guidelines:
1. Search [GitHub](https://github.com/angular/angular/pulls) for an open or closed PR that relates to your submission.
You don't want to duplicate existing efforts.
2. Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add.
Discussing the design upfront helps to ensure that we're ready to accept your work.
The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is optional.
##### Type
Must be one of the following:
* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
* **ci**: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs)
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* **test**: Adding missing tests or correcting existing tests
##### Scope
The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages).
The following is the list of supported scopes:
* `animations`
* `bazel`
* `benchpress`
* `common`
* `compiler`
* `compiler-cli`
* `core`
* `elements`
* `forms`
* `http`
* `language-service`
* `localize`
* `platform-browser`
* `platform-browser-dynamic`
* `platform-server`
* `platform-webworker`
* `platform-webworker-dynamic`
* `router`
* `service-worker`
* `upgrade`
* `zone.js`
There are currently a few exceptions to the "use package name" rule:
* `packaging`: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc.
* `changelog`: used for updating the release notes in CHANGELOG.md
* `dev-infra`: used for dev-infra related changes within the directories /scripts, /tools and /dev-infra
* `docs-infra`: used for docs-app (angular.io) related changes within the /aio directory of the repo
* `migrations`: used for changes to the `ng update` migrations.
* `ngcc`: used for changes to the [Angular Compatibility Compiler](./packages/compiler-cli/ngcc/README.md)
* `ve`: used for changes specific to ViewEngine (legacy compiler/renderer).
* none/empty string: useful for `style`, `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons`) and for docs changes that are not related to a specific package (e.g. `docs: fix typo in tutorial`).
##### Summary
Use the summary field to provide a succinct description of the change:
* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize the first letter
* no dot (.) at the end
#### Commit Message Body
Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are making the change.
You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
#### Commit Message Footer
The footer can contain information about breaking changes and is also the place to reference GitHub issues, Jira tickets, and other PRs that this commit closes or is related to.
Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.
### Revert commits
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
The content of the commit message body should contain:
- information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`,
- a clear description of the reason for reverting the commit message.
## <a name="cla"></a> Signing the CLA
Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code
changes to be accepted, the CLA must be signed. It's a quick process, we promise!
* For individuals, we have a [simple click-through form][individual-cla].
* For corporations, we'll need you to
[print, sign and one of scan+email, fax or mail the form][corporate-cla].
If you have more than one GitHub accounts, or multiple email addresses associated with a single GitHub account, you must sign the CLA using the primary email address of the GitHub account used to author Git commits and send pull requests.
The following documents can help you sort out issues with GitHub accounts and multiple email addresses:
We would love for you to contribute to Angular and help make it even better than it is today!
As a contributor, here are the guidelines we would like you to follow:
¡Nos encantaría que contribuyeras a Angular y que ayudaras a hacerlo aún mejor de lo que es hoy!
Como colaborador, estos son los lineamientos que nos gustaría que siguieras:
- [Code of Conduct](#coc)
- [Question or Problem?](#question)
- [Issues and Bugs](#issue)
- [Feature Requests](#feature)
- [Submission Guidelines](#submit)
- [Coding Rules](#rules)
- [Commit Message Guidelines](#commit)
- [Signing the CLA](#cla)
- [Código de conducta](#coc)
- [¿Preguntas o problemas?](#question)
- [_Issues_ y _bugs_](#issue)
- [Solicitud de funcionalidades](#feature)
- [Guía para la creación de issues y PRs](#submit)
- [Reglas del código](#rules)
- [Convención para el mensaje de los _commits_](#commit)
- [Firma del Acuerdo de Licencia de Colaborador (CLA)](#cla)
## <a name="coc"></a> Code of Conduct
## <a name="coc"></a> Código de conducta
Help us keep Angular open and inclusive.
Please read and follow our [Code of Conduct][coc].
Ayúdanos a mantener Angular abierto e inclusivo.
Por favor lee y sigue nuestro [Código de conducta][coc].
## <a name="question"></a> Got a Question or Problem?
## <a name="question"></a> ¿Tienes alguna pregunta o problema?
Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests.
Instead, we recommend using [Stack Overflow](https://stackoverflow.com/questions/tagged/angular) to ask support-related questions. When creating a new question on Stack Overflow, make sure to add the `angular` tag.
No abras *issues* para preguntas de soporte general ya que queremos mantener los *issues* de GitHub para reporte de *bugs* y solicitud de funcionalidades.
En su lugar, recomendamos utilizar [Stack Overflow](https://stackoverflow.com/questions/tagged/angular) para hacer preguntas relacionadas con soporte. Al crear una nueva pregunta en Stack Overflow, asegúrate de agregar el etiqueta (tag) de `angular`.
Stack Overflow is a much better place to ask questions since:
Stack Overflow es mucho mejor para hacer preguntas ya que:
-there are thousands of people willing to help on Stack Overflow
- questions and answers stay available for public viewing so your question/answer might help someone else
-Stack Overflow's voting system assures that the best answers are prominently visible.
-Hay miles de personas dispuestas a ayudar en preguntas y respuestas de Stack Overflow
que permanecen disponibles para el público, por lo que tu pregunta o respuesta podría ayudar a otra persona.
-El sistema de votación de Stack Overflow asegura que las mejores respuestas sobresalgan y sean visibles.
To save your and our time, we will systematically close all issues that are requests for general support and redirect people to Stack Overflow.
Para ahorrar tu tiempo y el nuestro, cerraremos sistemáticamente todos los *issues* que sean solicitudes de soporte general y redirigiremos a las personas a Stack Overflow.
If you would like to chat about the question in real-time, you can reach out via [our gitter channel][gitter].
Si deseas chatear sobre alguna pregunta en tiempo real, puedes hacerlo a través de nuestro [canal de Gitter][gitter].
## <a name="issue"></a> Found a Bug?
## <a name="issue"></a> ¿Encontraste un Bug?
If you find a bug in the source code, you can help us by [submitting an issue](#submit-issue) to our [GitHub Repository][github].
Even better, you can [submit a Pull Request](#submit-pr) with a fix.
Si encontraste un error en el código fuente, puedes ayudarnos [creando un *issue*](#submit-issue) en nuestro [repositorio de GitHub][github].
O incluso mejor, puedes [crear un *Pull Request*](#submit-pr) con la solución.
## <a name="feature"></a> Missing a Feature?
You can *request* a new feature by [submitting an issue](#submit-issue) to our GitHub Repository.
If you would like to *implement* a new feature, please consider the size of the change in order to determine the right steps to proceed:
Puedes solicitar una nueva funcionalidad [creando un *issue*](#submit-issue) en nuestro repositorio de GitHub.
Si deseas implementar una nueva funcionalidad, por favor considera el tamaño del cambio para determinar los pasos correctos para continuar:
*For a **Major Feature**, first open an issue and outline your proposal so that it can be discussed.
This process allows us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
*Para un **cambio significativo**, primero abre un *issue* y describe tu propuesta para que pueda ser discutida.
Este proceso nos permite coordinar mejor nuestros esfuerzos, evitar trabajo duplicado y ayudarte a diseñar el cambio para que sea aceptado con éxito en el proyecto.
**Note**: Adding a new topic to the documentation, or significantly re-writing a topic, counts as a major feature.
**Nota**: Agregar un nuevo tema a la documentación o reescribir significativamente un tema, también cuenta como *cambio significativo*.
* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr).
* **Cambios pequeños** pueden ser elaborados y directamente [creados como un _pull request_](#submit-pr).
## <a name="submit"></a> Submission Guidelines
## <a name="submit"></a> Guía para la creación de issues y PRs
### <a name="submit-issue"></a> Submitting an Issue
### <a name="submit-issue"></a> Creación de _issues_
Before you submit an issue, please search the issue tracker, maybe an issue for your problem already exists and the discussion might inform you of workarounds readily available.
Antes de crear un *issue*, por favor busca en el el *issue tracker*, quizá un *issue* para tu problema ya existe y la discusión puede informarte sobre soluciones alternativas disponibles.
We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce and confirm it.
In order to reproduce bugs, we require that you provide a minimal reproduction.
Having a minimal reproducible scenario gives us a wealth of important information without going back and forth to you with additional questions.
Queremos solucionar todos los problemas lo antes posible, pero antes de corregir un bug necesitamos reproducirlo y confirmarlo.
Para reproducir errores, requerimos que proporciones una reproducción mínima.
Tener un escenario reproducible mínimo nos brinda una gran cantidad de información importante sin tener que ir y venir con preguntas adicionales.
A minimal reproduction allows us to quickly confirm a bug (or point out a coding problem) as well as confirm that we are fixing the right problem.
Una reproducción mínima nos permite confirmar rápidamente un bug (o señalar un problema de código), así también confirmar que estamos solucionando el problema correcto.
We require a minimal reproduction to save maintainers' time and ultimately be able to fix more bugs.
Often, developers find coding problems themselves while preparing a minimal reproduction.
We understand that sometimes it might be hard to extract essential bits of code from a larger codebase but we really need to isolate the problem before we can fix it.
Requerimos una reproducción mínima para ahorrar tiempo a los encargados del mantenimiento y en última instancia, poder corregir más bugs.
A menudo los desarrolladores encuentran problemas de código mientras preparan una reproducción mínima.
Entendemos que a veces puede ser difícil extraer porciones esenciales de código de un código más grande, pero realmente necesitamos aislar el problema antes de poder solucionarlo.
Unfortunately, we are not able to investigate / fix bugs without a minimal reproduction, so if we don't hear back from you, we are going to close an issue that doesn't have enough info to be reproduced.
Desafortunadamente no podemos investigar/corregir errores sin una reproducción mínima, por lo que si no tenemos tu retroalimentación del bug, vamos a cerrar el *issue* ya que no tiene suficiente información para reproducirse.
You can file new issues by selecting from our [new issue templates](https://github.com/angular/angular/issues/new/choose) and filling out the issue template.
Puedes presentar nuevos *issues* seleccionando nuestra [plantilla de _issues_](https://github.com/angular/angular/issues/new/choose) y complentando la plantilla.
### <a name="submit-pr"></a> Submitting a Pull Request (PR)
### <a name="submit-pr"></a> Creación de un Pull Requests (PR)
Before you submit your Pull Request (PR) consider the following guidelines:
Antes de crear tu Pull Request (PR) considera los siguientes lineamientos:
1.Search [GitHub](https://github.com/angular/angular/pulls) for an open or closed PR that relates to your submission.
You don't want to duplicate existing efforts.
1.Busca en [GitHub](https://github.com/angular/angular/pulls) PRs que estén abiertos o cerrados y que estén relacionados con el que vas a crear.
No deseas duplicar los esfuerzos existentes.
2.Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add.
Discussing the design upfront helps to ensure that we're ready to accept your work.
2.Asegúrate de que el PR describa el problema que estás solucionando o que documente el diseño de la funcionalidad que deseas agregar.
Discutir el diseño por adelantado ayuda a garantizar que estemos listos para aceptar tu trabajo.
Make sure you author all contributed Git commits with email address associated with your CLA signature.
3. Por favor firma nuestro [Acuerdo de Licencia de Colaborador (CLA)](#cla) antes de crear PRs.
No podemos aceptar el código sin el Acuerdo de Licencia de Colaborador (CLA) firmado.
Asegúrate de crear todas las contribuciones de Git con la dirección de correo electrónico asociada con tu firma del Acuerdo de Licencia de Colaborador (CLA).
4.Fork the angular/angular repo.
4.Haz *fork* del repositorio angular/angular.
5.Make your changes in a new git branch:
5.Haz tus cambios en una nueva rama de Git:
```shell
git checkout -b my-fix-branch master
```
6. Create your patch, **including appropriate test cases**.
6. Crea tu correción, **incluyendo casos de prueba apropiados**.
7. Follow our [Coding Rules](#rules).
7. Sigue nuestras [Reglas de código](#rules).
8. Run the full Angular test suite, as described in the [developer documentation][dev-doc], and ensure that all tests pass.
8. Ejecuta todo el conjunto de pruebas de Angular, tal como está descrito en la [documentación del desarrollador][dev-doc], y asegúrate de que todas las pruebas pasen.
9. Commit your changes using a descriptive commit message that follows our [commit message conventions](#commit).
Adherence to these conventions is necessary because release notes are automatically generated from these messages.
9. Crea un commit de tus cambios utilizando un mensaje de commit descriptivo que siga nuestra [convención para el mensaje de los commits](#commit).
Es necesario cumplir con estas convenciones porque las notas de las versiones se generan automáticamente a partir de estos mensajes.
```shell
git commit --all
git commit -a
```
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
Nota: la opción de la línea de comandos de Git `-a` automaticamente hará "add" y "rm" a los archivos editados.
10. Push your branch to GitHub:
10. Haz push de tu rama a GitHub:
```shell
git push origin my-fix-branch
```
11. In GitHub, send a pull request to `angular:master`.
11. En GitHub, crea un pull request a `angular:master`.
Si solicitamos cambios a través de revisiones de código, sigue las siguientes indicaciones:
* Haz los cambios requeridos.
* Ejecuta nuevamente el conjunto de pruebas de Angular para asegurar que todas las pruebas aún están pasando.
* Haz rebase de tu rama a la rama master y haz push con la opción `-f` a tu repositorio de Github (esto actualizará tu Pull Request):
```shell
git rebase master -i
git push -f
```
¡Es todo! ¡Muchas gracias por tu contribución!
#### Addressing review feedback
#### Después del merge de tu pull request
If we ask for changes via code reviews then:
Después de que se hizo merge de tu pull request, puedes eliminar de forma segura tu rama y hacer pull de los cambios del repositorio principal (upstream):
1. Make the required updates to the code.
2. Re-run the Angular test suites to ensure tests are still passing.
3. Create a fixup commit and push to your GitHub repository (this will update your Pull Request):
```shell
git commit --all --fixup HEAD
git push
```
For more info on working with fixup commits see [here](docs/FIXUP_COMMITS.md).
> Fixup commits (as shown above) are preferred when addressing review feedback, but in some cases you may need to amend the original commit instead of creating a fixup commit (for example, if you want to update the commit message).
> To amend the last commit and update the Pull Request:
>
> ```shell
> git commit --all --amend
> git push --force-with-lease
> ```
That's it! Thank you for your contribution!
#### After your pull request is merged
After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:
* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
* Elimina la rama remota en GitHub a través de la interfaz de usuario web de GitHub o en tu línea de comandos de la siguiente manera:
```shell
git push origin --delete my-fix-branch
```
* Check out the master branch:
* Muévete a la rama master:
```shell
git checkout master -f
```
* Delete the local branch:
* Elimina tu rama local:
```shell
git branch -D my-fix-branch
```
* Update your master with the latest upstream version:
* Actualiza tu rama master con la última versión del fork (upstream):
```shell
git pull --ff upstream master
```
## <a name="rules"></a> Coding Rules
To ensure consistency throughout the source code, keep these rules in mind as you are working:
## <a name="rules"></a> Reglas del código
Para garantizar la coherencia en todo el código fuente, ten en cuenta estas reglas mientras trabajas:
* All features or bug fixes **must be tested** by one or more specs (unit-tests).
* All public API methods **must be documented**.
* We follow [Google's JavaScript Style Guide][js-style-guide], but wrap all code at **100 characters**.
* Todas las funcionalidades o solución de bugs **deben ser probadas** por una o más pruebas (pruebas unitarias).
* Todos los métodos públicos del API **deben ser documentados**.
* Seguimos la [guía de estilo JavaScript de Google][js-style-guide], pero cada línea no debe exceder **100 caracteres**.
An automated formatter is available, see [DEVELOPER.md](docs/DEVELOPER.md#clang-format).
Un formateador automatizado está disponible, revisar [DEVELOPER.md](docs/DEVELOPER.md#clang-format).
## <a name="commit"></a> Commit Message Format
## <a name="commit"></a> Formato para el mensaje de los commits
*This specification is inspired and supersedes the [AngularJS commit message format][commit-message-format].*
*Esta especificación está inspirada y reemplaza el [Formato de mensaje de commits de AngularJS][commit-message-format].*
We have very precise rules over how our Git commit messages must be formatted.
This format leads to **easier to read commit history**.
Tenemos reglas muy precisas sobre cómo deben formatearse nuestros mensajes de los commits de Git.
Este formato permite tener **un historial de commits más facil de leer**.
Each commit message consists of a **header**, a **body**, and a **footer**.
Cada mensaje de un commit consta del **header**, el **body**, y el **footer**.
```
<header>
<BLANK LINE>
<LINEA VACIA>
<body>
<BLANK LINE>
<LINEA VACIA>
<footer>
```
The `header` is mandatory and must conformto the [Commit Message Header](#commit-header) format.
El `header` es obligatorio y debe ajustarse al formato del [mensaje del header del commit](#commit-header).
The `body` is mandatory for all commits except for those of scope "docs".
When the body is required it must be at least 20 characters long.
El `body` es obligatorio para todos los commits excepto los que tenga scope "docs".
Cuando el body es requerido debe tener al menos 20 caracteres.
The `footer` is optional.
El `footer` es opcional.
Any line of the commit message cannot be longer than 100 characters.
Cualquier línea del mensaje del commit no puede tener más de 100 caracteres.
└─⫸ Tipo de commit: build|ci|docs|feat|fix|perf|refactor|style|test
```
The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is optional.
El `<tipo>` y `<resumen>` son obligatorios, el `(<alcance>)` es opcional.
##### Type
##### Tipo
Must be one of the following:
El tipo debe ser uno de los siguientes:
* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
* **ci**: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs)
* **docs**: Documentation only changes
* **feat**: A new feature
* **fix**: A bug fix
* **perf**: A code change that improves performance
* **refactor**: A code change that neither fixes a bug nor adds a feature
* **test**: Adding missing tests or correcting existing tests
* **build**: cambios que afectan el sistema de compilación o dependencias externas (ejemplos de scopes: gulp, broccoli, npm)
* **ci**: cambios en nuestros archivos y scripts de configuración de CI (ejemplos de scopes: Circle, BrowserStack, SauceLabs)
* **docs**: cambios en la documentación
* **feat**: una nueva funcionalidad
* **fix**: una solución de un bug
* **perf**: un cambio de código que mejora el rendimiento.
* **refactor**: un cambio de código que no corrige ningún error ni agrega ninguna funcionalidad
* **style**: cambios que no afectan el significado del código (espacios en blanco, formato, falta de punto y coma, etc.)
* **test**: se agregan pruebas faltantes o se corrigen pruebas existentes
##### Scope
The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages).
##### Alcance
El alcance debe ser el nombre del paquete npm afectado (tal como lo percibe la persona que lee el registro de cambios generado a partir de los mensajes de commit).
The following is the list of supported scopes:
La siguiente es la lista de alcances permitidos:
* `animations`
* `bazel`
@ -275,80 +261,73 @@ The following is the list of supported scopes:
* `upgrade`
* `zone.js`
There are currently a few exceptions to the "use package name" rule:
Actualmente hay algunas excepciones a la regla "usar el nombre de paquete":
* `packaging`: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc.
* `packaging`: usado para cambios que cambian el diseño de los paquetes de npm en todos nuestros paquetes. Ejemplos: cambios de la ruta públic, package.json cambios hechos a todos los paquetes, cambios a archivos o formatos d.ts, cambios a bundles, etc.
* `changelog`: used for updating the release notes in CHANGELOG.md
* `changelog`: utilizado para actualizar las notas de la versión en CHANGELOG.md
* `dev-infra`: used for dev-infra related changes within the directories /scripts, /tools and /dev-infra
* `dev-infra`: utilizado para cambios relacionados con dev-infra dentro de los directorios /scripts, /tools y /dev-infra
* `docs-infra`: used for docs-app (angular.io) related changes within the /aio directory of the repo
* `docs-infra`: utilizado para cambios relacionados con la documentación (angular.io) dentro del directorio /aio del repositorio
* `migrations`: used for changes to the `ng update` migrations.
* `migrations`: utilizado para los cambios en las migraciones `ng update`.
* `ngcc`: used for changes to the [Angular Compatibility Compiler](./packages/compiler-cli/ngcc/README.md)
* `ngcc`: usado para los cambios del [Compilador de compatibilidad de Angular](./packages/compiler-cli/ngcc/README.md)
* `ve`: used for changes specific to ViewEngine (legacy compiler/renderer).
* `ve`: utilizado para cambios específicos de ViewEngine (legacy compiler/renderer).
* none/empty string: useful for `style`, `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons`) and for docs changes that are not related to a specific package (e.g. `docs: fix typo in tutorial`).
* alcance vacío: útil para cambios de `style`, `test` y `refactor` que se realizan en todos los paquetes (ejemplo: `style: add missing semicolons`) y para cambios de la documentación que no están relacionados a un paquete en específico(ejemplo: `docs: corrige error gramatical en el tutorial`).
##### Summary
##### Resumen
Use the summary field to provide a succinct description of the change:
Usa el campo resumen para proporcionar una descripción breve del cambio:
* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize the first letter
* no dot (.) at the end
* usa el modo imperativo, tiempo presente: "cambia" no "cambió" o "cambios"
* no debe de contener ninguna letra mayúscula
* no debe de conter punto (.) al final
#### Commit Message Body
#### Mensaje del cuerpo del commit
Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
Tal como en el resumen, usa el modo imperativo, tiempo presente: "cambia" no "cambió" o "cambios".
Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are making the change.
You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
Explica la razón del cambio en el el mensaje del cuerpo del commit. Este mensaje de confirmación debe explicar _por qué_ está realizando el cambio.
Puedes incluir una comparación del comportamiento anterior con el nuevo comportamiento para ilustrar el impacto del cambio.
#### Commit Message Footer
#### Mensaje del footer del commit
The footer can contain information about breaking changes and is also the place to reference GitHub issues, Jira tickets, and other PRs that this commit closes or is related to.
El footer puede contener información sobre cambios significativos y también es el lugar para hacer referencia a issues de GitHub, tickets de Jira y otros PRs que están relacionados con el commit.
CAMBIO SIGNIFICATIVO: <resumen del cambio significativo>
<LINEA VACIA>
<descripción del cambio significativo + instrucciones para la migración>
<LINEA VACIA>
<LINEA VACIA>
Fix #<issue número>
```
Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.
La sección de cambios significativos debería comenzar con la frase "CAMBIO SIGNIFICATIVO: " seguido de un resumen del cambio significativo, una línea en blanco y una descripción detallada del cambio significativo que también incluya instrucciones de migración.
### Revert commits
### Revirtiendo commits
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
Si el commit revierte un commit previo, el commit debería comenzar con `revert: `, seguido por el header del commit revertido.
The content of the commit message body should contain:
El contenido del mensaje del commit debería contener:
- information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`,
-a clear description of the reason for reverting the commit message.
- Información sobre el SHA del commit que se revierte en el siguiente formato: `Esto revierte el commit <SHA>`,
-Una descripción clara de la razón para revertir el mensaje del _commit_.
## <a name="cla"></a> Signing the CLA
## <a name="cla"></a> Firma del Acuerdo de Licencia de Colaborador (CLA)
Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code
changes to be accepted, the CLA must be signed. It's a quick process, we promise!
Por favor firma nuestro Acuerdo de Licencia de Colaborador (CLA) cuando creas tu primer pull request. Para que cualquier cambio de código sea aceptado, el Acuerdo de Licencia de Colaborador (CLA) debe ser firmado. Es un proceso rápido con nuestro CLA assistant que está integrado con nuestro CI.
* For individuals, we have a [simple click-through form][individual-cla].
* For corporations, we'll need you to
[print, sign and one of scan+email, fax or mail the form][corporate-cla].
If you have more than one GitHub accounts, or multiple email addresses associated with a single GitHub account, you must sign the CLA using the primary email address of the GitHub account used to author Git commits and send pull requests.
The following documents can help you sort out issues with GitHub accounts and multiple email addresses:
Los siguientes documentos pueden ayudarte a resolver problemas con cuentas de GitHub y múltiples direcciones de correo electrónico:
[](https://gitter.im/angular/angular?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Angular is a development platform for building mobile and desktop web applications using TypeScript/JavaScript and other languages.
## Quickstart
[Get started in 5 minutes][quickstart].
## Changelog
[Learn about the latest improvements][changelog].
## Want to help?
Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our
guidelines for [contributing][contributing] and then check out one of our issues in the [hotlist: community-help](https://github.com/angular/angular/labels/hotlist%3A%20community-help).
[](https://gitter.im/angular/angular?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
La colaboración para corregir errores y agregar funciones en el framework debe realizarse en inglés a través
del repositorio [angular/angular](https://github.com/angular/angular) upstream.
[Learn about the latest improvements][changelog].
## Guía rápida
## Want to help?
[Comienza a usarlo en 5 minutos](https://docs.angular.lat/start).
Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our
guidelines for [contributing][contributing] and then check out one of our issues in the [hotlist: community-help](https://github.com/angular/angular/labels/hotlist%3A%20community-help).
# Proyecto de documentación Angular (https://docs.angular.lat)
Everything in this folder is part of the documentation project. This includes
Todo en esta carpeta es parte del proyecto de documentación. Esto incluye:
*the web site for displaying the documentation
*the dgeni configuration for converting source files to rendered files that can be viewed in the web site.
*the tooling for setting up examples for development; and generating live-example and zip files from the examples.
*El sitio web para mostrar la documentación
*La configuración de dgeni para convertir los archivos de origen a archivos renderizados que se pueden vizualizar en el sitio web.
*Las herramientas para establecer ejemplos para el desarrollo; y generar archivos en tiempo real y archivos zip desde los ejemplos.
<aname="developer-tasks"></a>
## Developer tasks
## Tareas de desarrollador
We use [Yarn](https://yarnpkg.com) to manage the dependencies and to run build tasks.
You should run all these tasks from the`angular/aio` folder.
Here are the most important tasks you might need to use:
Nosotros usamos [Yarn](https://yarnpkg.com) para gestionar las dependencias y crear tareas de compilación.
Debes ejecutar todas estas tareas desde la carpeta`angular/aio`.
Aquí están las tareas más importantes que podrías necesitar usar:
*`yarn` - install all the dependencies.
*`yarn setup` - install all the dependencies, boilerplate, stackblitz, zips and run dgeni on the docs.
*`yarn setup-local` - same as`setup`, but build the Angular packages from the source code and use these locally built versions (instead of the ones fetched from npm) for aio and docs examples boilerplate.
*`yarn` - instalar todas las dependencias.
*`yarn setup` - instalar todas las dependencias, boilerplate, stackblitz, zips y ejecuta dgeni en los documentos.
*`yarn setup-local` - igual que`setup`, pero crea los paquetes de Angular a partir del código y usa estas versiones construidas localmente (en lugar de las recuperadas desde npm) para aio y ejemplos de documentos boilerplate.
*`yarn build` - create a production build of the application (after installing dependencies, boilerplate, etc).
*`yarn build-local` - same as`build`, but use`setup-local`instead of`setup`.
*`yarn build-local-with-viewengine` - same as`build-local`, but in addition also turns on`ViewEngine` (pre-Ivy) mode in aio.
(Note: To turn on `ViewEngine` mode in docs examples, see`yarn boilerplate:add:viewengine`below.)
*`yarn build` - crear una compilación de producción de la aplicación (después de instalar dependencias, boilerplate, etc).
*`yarn build-local` - igual que`build`, pero usa`setup-local`en lugar de`setup`.
*`yarn build-local-with-viewengine` - igual que`build-local`, pero además también enciende el modo`ViewEngine` (pre-Ivy) en aio.
(Nota: Encender el modo `ViewEngine` en ejemplos de documentos, ver`yarn boilerplate:add:viewengine`abajo.)
*`yarn start` - run a development web server that watches the files; then builds the doc-viewer and reloads the page, as necessary.
*`yarn serve-and-sync` - run both the`docs-watch`and`start`in the same console.
*`yarn lint` - check that the doc-viewer code follows our style rules.
*`yarn test` - watch all the source files, for the doc-viewer, and run all the unit tests when any change.
*`yarn test --watch=false` - run all the unit tests once.
*`yarn e2e` - run all the e2e tests for the doc-viewer.
*`yarn start` - ejecutar un servidor web de desarrollo que observa los archivos; luego crea el doc-viewer y vuelve a cargar la página, según sea necesario.
*`yarn serve-and-sync` - ejecutar ambos, el`docs-watch`y`start`en la misma consola.
*`yarn lint` - comprobar que el código del doc-viewer sigue nuestras reglas de estilo.
*`yarn test` - observar todos los archivos de origen, para el doc-viewer, y ejecuta todas las pruebas unitarias cuando haya algún cambio.
*`yarn test --watch=false` -ejecutar todas las pruebas unitarias una sola vez.
*`yarn e2e` - ejecutar todas las pruebas de e2e para el doc-viewer.
*`yarn docs` - generate all the docs from the source files.
*`yarn docs-watch` - watch the Angular source and the docs files and run a short-circuited doc-gen for the docs that changed.
*`yarn docs-lint` - check that the doc gen code follows our style rules.
*`yarn docs-test` - run the unit tests for the doc generation code.
*`yarn docs` - generar toda la documentación desde los archivos fuente.
*`yarn docs-watch` - observar el código Angular, los archivos de documentación y ejecutar un 'doc-gen' en corto circuito para los documentos que fueron cambiados.
*`yarn docs-lint` - comprobar que el código del documento generado sigue nuestras reglas de estilo.
*`yarn docs-test` - ejecutar las pruebas unitarias para el código de generación de doc.
*`yarn boilerplate:add` - generate all the boilerplate code for the examples, so that they can be run locally.
*`yarn boilerplate:add:viewengine` - same as`boilerplate:add`but also turns on`ViewEngine` (pre-Ivy) mode.
*`yarn boilerplate:add` - generar todo el código boilerplate para los ejemplos, para que puedan ejecutarse localmente.
*`yarn boilerplate:add:viewengine` - igual que`boilerplate:add`pero también enciende el modo`ViewEngine` (pre-Ivy).
*`yarn boilerplate:remove` - eliminar todo el código boilerplate que fue añadido a través`yarn boilerplate:add`.
*`yarn create-example` - crear un nuevo directorio de ejemplo que contenga los archivos fuente iniciales.
*`yarn boilerplate:remove` - remove all the boilerplate code that was added via `yarn boilerplate:add`.
*`yarn generate-stackblitz` - generate the stackblitz files that are used by the`live-example`tags in the docs.
*`yarn generate-zips` - generate the zip files from the examples. Zip available via the `live-example` tags in the docs.
*`yarn generate-stackblitz` - generar los archivos stackblitz que están usados por la etiqueta `live-example` en documentos.
*`yarn generate-zips` - generar los archivos zip desde los ejemplos. Zip está disponible a través de la etiqueta`live-example`en los documentos.
*`yarn example-e2e` - run all e2e tests for examples. Available options:
-`--setup`: generate boilerplate, force webdriver update & other setup, then run tests.
-`--local`: run e2e tests with the local version of Angular contained in the "dist" folder.
_Requires `--setup` in order to take effect._
-`--viewengine`: run e2e tests in`ViewEngine` (pre-Ivy) mode.
-`--filter=foo`: limit e2e tests to those containing the word "foo".
*`yarn example-e2e` - ejecutar todas las pruebas e2e para ejemplos. Opciones disponibles:
-`--setup`: generar boilerplate, forzar la actualización del controlador web y otras configuraciones, luego ejecutar las pruebas.
-`--local`: ejecutar pruebas e2e con la versión local de Angular contenida en la carpeta "dist".
_Requiere `--setup` para que surta efecto._
-`--viewengine`: ejecutar pruebas e2e en modo`ViewEngine` (pre-Ivy).
-`--filter=foo`: limitar pruebas e2e a las que contienen la palabra "foo".
> **Note for Windows users**
> **Nota para usuarios Windows**
>
> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](./tools/examples/README.md#symlinked-node_modules) for details). On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator.
> Configurar los ejemplos implica crear algunos [enlaces simbólicos](https://es.wikipedia.org/wiki/Enlace_simb%C3%B3lico) (ver [Aquí](./tools/examples/README.md#symlinked-node_modules) para más detalles). En Windows, esto requiere tener [Habilitado el Modo de desarrollador ](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (compatible con Windows 10 o más reciente) o ejecutar los comandos de configuración cómo administrador.
>
> The affected commands are:
> Los comandos afectados son:
> - `yarn setup` / `yarn setup-*`
> - `yarn build` / `yarn build-*`
> - `yarn boilerplate:add`
> - `yarn example-e2e --setup`
## Using ServiceWorker locally
## Usando ServiceWorker localmente
Running`yarn start` (even when explicitly targeting production mode) does not set up the
ServiceWorker. If you want to test the ServiceWorker locally, you can use`yarn build`and then
serve the files in `dist/`with`yarn http-server dist -p 4200`.
Ejecutando`yarn start` (incluso cuando se apunta explícitamente al modo de producción) no configura el
ServiceWorker. Si quieres probar el ServiceWorker localmente, puedes usar`yarn build`y luego
ejecutar los archivos en `dist/`con`yarn http-server dist -p 4200`.
## Guide to authoring
## Guía de autoría
Existen dos tipos de contenido en la documentación:
There are two types of content in the documentation:
* **Documentación de API**: descripciones de los módulos, clases, interfaces, decoradores, etc que son parte de la plataforma Angular.
La documentacion de API está generada directamente desde el código fuente.
El código fuente está contenido en archivos TypeScript , almacenados en la carpeta `angular/packages`.
Cada elemento de la API puede tener un comentario anterior, el cual contiene etiquetas y contenido de estilos JSDoc.
El contenido está escrito en markdown.
* **API docs**: descriptions of the modules, classes, interfaces, decorators, etc that make up the Angular platform.
API docs are generated directly from the source code.
The source code is contained in TypeScript files, located in the `angular/packages` folder.
Each API item may have a preceding comment, which contains JSDoc style tags and content.
The content is written in markdown.
* **Otro contenido**: guias, tutoriales, y otro material de marketing.
Todos los demás contenidos se escriben utilizando markdown en archivos de texto, ubicados en la carpeta `angular/aio/content`.
Más específicamente, hay subcarpetas que contienen tipos particulares de contenido: guías, tutoriales y marketing.
* **Other content**: guides, tutorials, and other marketing material.
All other content is written using markdown in text files, located in the `angular/aio/content` folder.
More specifically, there are sub-folders that contain particular types of content: guides, tutorial and marketing.
* **Ejempos de código**: los ejemplos de código deben ser comprobables para garantizar su precisión.
Además, nuestros ejemplos tienen un aspecto específico y permiten al usuario copiar el código fuente. Para mayor
ejemplos se representan en una interfaz con pestañas (e.g. template, HTML, y TypeScript en pestañas separadas). Adicionalmente, algunos son ejemplos en acción, que proporcionan enlaces donde se puede editar el código, ejecutar, y/o descargar. Para obtener más detalles sobre cómo trabajar con ejemplos de código, lea los [fragmentos de código](https://docs.angular.lat/guide/docs-style-guide#code-snippets), [código fuente de marcado ](https://docs.angular.lat/guide/docs-style-guide#source-code-markup), y [ ejemplos en acción ](https://docs.angular.lat/guide/docs-style-guide#live-examples) paginas de los [ autores de guías de estilo ](https://docs.angular.lat/guide/docs-style-guide).
* **Code examples**: code examples need to be testable to ensure their accuracy.
Also, our examples have a specific look and feel and allow the user to copy the source code. For larger
examples they are rendered in a tabbed interface (e.g. template, HTML, and TypeScript on separate
tabs). Additionally, some are live examples, which provide links where the code can be edited, executed, and/or downloaded. For details on working with code examples, please read the [Code snippets](https://angular.io/guide/docs-style-guide#code-snippets), [Source code markup](https://angular.io/guide/docs-style-guide#source-code-markup), and [Live examples](https://angular.io/guide/docs-style-guide#live-examples) pages of the [Authors Style Guide](https://angular.io/guide/docs-style-guide).
Usamos la herramienta [dgeni](https://github.com/angular/dgeni) para convertir estos archivos en docs que se pueden ver en el doc-viewer.
Las [guías de estilo para Autores](https://docs.angular.lat/guide/docs-style-guide) prescriben pautas para
escribir páginas de guía, explica cómo usar la documentación de clases y componentes, y cómo marcar el código fuente para producir fragmentos de código.
We use the [dgeni](https://github.com/angular/dgeni) tool to convert these files into docs that can be viewed in the doc-viewer.
### Generando documentos completos
The [Authors Style Guide](https://angular.io/guide/docs-style-guide) prescribes guidelines for
writing guide pages, explains how to use the documentation classes and components, and how to markup sample source code to produce code snippets.
La principal tarea para generar los documentos es `yarn docs`. Esto procesará todos los archivos fuente (API y otros), extrayendo la documentación y generando archivos JSON que pueden ser consumidos por el doc-viewer.
### Generating the complete docs
### Generación parcial de doc para editores
The main task for generating the docs is `yarn docs`. This will process all the source files (API and other),
extracting the documentation and generating JSON files that can be consumed by the doc-viewer.
La generación completa de documentos puede llevar hasta un minuto. Eso es demasiado lento para la creación y edición eficiente de documentos.
### Partial doc generation for editors
Puedes ealizar pequeños cambios en un editor inteligente que muestre un markdown con formato:
>En VS Code, _Cmd-K, V_ abre la vista previa de markdown en el panel lateral; _Cmd-B_ alterna la barra izquierda
Full doc generation can take up to one minute. That's too slow for efficient document creation and editing.
Puedes también mirar los cambios que se muestran correctamente en el doc-viewer
con un tiempo de ciclo rápido de edición / visualización.
You can make small changes in a smart editor that displays formatted markdown:
>In VS Code, _Cmd-K, V_ opens markdown preview in side pane; _Cmd-B_ toggles left sidebar
Para este propósito, usa la tarea `yarn docs-watch`, que observa los cambios en los archivos de origen y solo vuelve a procesar los archivos necesarios para generar los documentos relacionados con el archivo que ha cambiado.
Dado que esta tarea tiene accesos directos, es mucho más rápido (a menudo menos de 1 segundo) pero no producirá contenido de fidelidad completa. Por ejemplo, los enlaces a otros documentoss y ejemplos de código pueden no mostrarse correctamente. Esto se nota especialmente en los enlaces a otros documentos y en los ejemplos incrustados, que no siempre se representan correctamente.
You also want to see those changes displayed properly in the doc viewer
with a quick, edit/view cycle time.
La configuración general es la siguiente:
For this purpose, use the `yarn docs-watch` task, which watches for changes to source files and only
re-processes the files necessary to generate the docs that are related to the file that has changed.
Since this task takes shortcuts, it is much faster (often less than 1 second) but it won't produce full
fidelity content. For example, links to other docs and code examples may not render correctly. This is
most particularly noticed in links to other docs and in the embedded examples, which may not always render
correctly.
The general setup is as follows:
* Open a terminal, ensure the dependencies are installed; run an initial doc generation; then start the doc-viewer:
* Abrir una terminal, estar seguro que las dependencias están instaladas; ejecutar una generación inicial del doc; luego iniciar el doc-viewer:
```bash
yarn setup
yarn start
```
*Open a second terminal and start watching the docs
*Abrir una segunda terminal e iniciar el observador de documentos.
```bash
yarn docs-watch
```
>Alternatively, try the consolidated `serve-and-sync` command that builds, watches and serves in the same terminal window
>Alternativamente, prueba el comando fusionado `serve-and-sync` que crea, observa y ejecuta en la misma ventana de la terminal
```bash
yarn serve-and-sync
```
*Open a browser at https://localhost:4200/ and navigate to the document on which you want to work.
You can automatically open the browser by using`yarn start -o`in the first terminal.
*Abre un navegador con la siguiente dirección https://localhost:4200/ y navega hasta el documento en el que quieras trabajar.
Puedes automáticamente abrir el navegador utilizando`yarn start -o`en la primera terminal.
*Make changes to the page's associated doc or example files. Every time a file is saved, the doc will
be regenerated, the app will rebuild and the page will reload.
*Realiza cambios en la página de documentación asociada o en los archivos de ejemplo. Cada vez que un archivo es guardado, la documentación se regenerará, la aplicación se reconstruirá y la página se volverá a cargar.
* If you get a build error complaining about examples or any other odd behavior, be sure to consult
the [Authors Style Guide](https://angular.io/guide/docs-style-guide).
*Si recibes un error de compilación acerca de los ejemplos o cualquier otro error, asegúrate de consultar las
[guías de estilo para Autores](https://angular.io/guide/docs-style-guide) para más información.
<!-- The `class.special` template binding will override any host binding to the `special` class set by `dirWithClassBinding` or `comp-with-host-binding`.-->
<!-- The `class.special` template binding overrides any host binding to the `special` class set by `dirWithClassBinding` or `comp-with-host-binding`.-->
<!-- The `style.color` template binding will override any host binding to the `color` property set by `dirWithStyleBinding` or `comp-with-host-binding`. -->
<!-- The `style.color` template binding overrides any host binding to the `color` property set by `dirWithStyleBinding` or `comp-with-host-binding`. -->
The web is used by a wide variety of people, including those who have visual or motor impairments.
A variety of assistive technologies are available that make it much easier for these groups to
interact with web-based software applications.
In addition, designing an application to be more accessible generally improves the user experience for all users.
Hay una amplia variedad de personas que utilizan la web, algunas de ellas con discapacidad visual o motora.
Existen diferentes tecnologías de apoyo que hacen que sea mucho más fácil para estos grupos
interactuar con aplicaciones de software basadas en la web.
Además, diseñar una aplicación para que sea más accesible, normalmente mejora la experiencia de usuario en general.
For an in-depth introduction to issues and techniques for designing accessible applications, see the [Accessibility](https://developers.google.com/web/fundamentals/accessibility/#what_is_accessibility) section of the Google's [Web Fundamentals](https://developers.google.com/web/fundamentals/).
Para una introducción en profundidad a los problemas y técnicas sobre el diseño de aplicaciones accesibles, puede consultar la sección de [Accesibilidad](https://developers.google.com/web/fundamentals/accessibility/#what_is_accessibility) de Google [Fundamentos Web](https://developers.google.com/web/fundamentals/).
This page discusses best practices for designing Angular applications that
work well for all users, including those who rely on assistive technologies.
Esta página habla de las mejores prácticas para diseñar aplicaciones en Angular que funcionan
bien para todos los usuarios, incluyendo aquéllos que necesitan tecnologías de apoyo.
<divclass="alert is-helpful">
For the sample app that this page describes, see the<live-example></live-example>.
Para ver la aplicación de ejemplo que describe esta página, ir a<live-example></live-example>.
</div>
## Accessibility attributes
## Atributos de accesibilidad
Building accessible web experience often involves setting [ARIA attributes](https://developers.google.com/web/fundamentals/accessibility/semantics-aria)
to provide semantic meaning where it might otherwise be missing.
Use [attribute binding](guide/attribute-binding) template syntax to control the values of accessibility-related attributes.
Crear una web accesible a menudo implica establecer los [atributos ARIA](https://developers.google.com/web/fundamentals/accessibility/semantics-aria)
para proporcionar la semántica que, de otro modo, podría no estar presente.
Usa la plantilla de sintaxis del [enlace de atributos](attribute binding) (guide/attribute-binding) para controlar los valores de los atributos relacionados con la accesibilidad.
When binding to ARIA attributes in Angular, you must use the `attr.` prefix, as the ARIA
specification depends specifically on HTML attributes rather than properties of DOM elements.
Para enlazar los atributos ARIA en Angular, debes usar el prefijo `attr.`, ya que la especificación ARIA
depende de los atributos HTML y no de las propiedades de los elementos del DOM.
```html
<!-- Use attr. when binding to an ARIA attribute -->
Note that this syntaxis only necessary for attribute _bindings_.
Static ARIA attributes require no extra syntax.
Observa que esta sintaxis solo es necesaria para los _enlaces_ de atributos.
Los atributos ARIA estáticos no requieren de ninguna sintaxis adicional.
```html
<!-- Static ARIA attributes require no extra syntax -->
<buttonaria-label="Save document">...</button>
```
NOTE:
NOTA:
<divclass="alert is-helpful">
By convention, HTML attributes use lowercase names (`tabindex`), while properties use camelCase names (`tabIndex`).
Por convenio, los atributos HTML se escriben en minúscula (`tabindex`), mientras que para las propiedades se usa *camelCase* (`tabIndex`).
See the [Binding syntax](guide/binding-syntax#html-attribute-vs-dom-property) guide for more background on the difference between attributes and properties.
Consulta la guía [Sintaxis del enlace](guide/binding-syntax#html-attribute-vs-dom-property) para saber más sobre las diferencias entre atributos y propiedades.
</div>
## Angular UI components
## Componentes del interfaz de usuario de Angular
The [Angular Material](https://material.angular.io/) library, which is maintained by the Angular team, is a suite of reusable UI components that aims to be fully accessible.
The [Component Development Kit (CDK)](https://material.angular.io/cdk/categories) includes the `a11y` package that provides tools to support various areas of accessibility.
For example:
La librería [Angular Material](https://material.angular.io/), que es mantenida por el equipo Angular, es un conjunto de componentes reutilizables para la interfaz de usuario que pretende ser totalmente accesible.
El [Kit de Desarrollo de Componentes (CDK)](https://material.angular.io/cdk/categories) (Component Development Kit) incluye el paquete `a11y` que proporciona herramientas para dar soporte a distintos aspectos de la accesibilidad.
Por ejemplo:
*`LiveAnnouncer`is used to announce messages for screen-reader users using an `aria-live` region. See the W3C documentation for more information on [aria-live regions](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live).
*`LiveAnnouncer`se utiliza para comunicar mensajes a los usuarios de lectores de pantalla que usan la region `aria-live`. Se puede consultar la documentación de la W3C para obtener más información sobre [regiones aria-live](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live).
*The`cdkTrapFocus`directive traps Tab-key focus within an element. Use it to create accessible experience for components like modal dialogs, where focus must be constrained.
*La directiva`cdkTrapFocus`limita el foco de la tecla de tabulación para que se quede dentro de un elemento. Úsala para crear una experiencia accesible en componentes como las ventanas modales, donde el foco debe estar limitado.
For full details of these and other tools, see the [Angular CDK accessibility overview](https://material.angular.io/cdk/a11y/overview).
Para obtener más detalles sobre esta y otras herramientas, consulta el [resumen de accesibilidad del Angular CDK](https://material.angular.io/cdk/a11y/overview).
### Augmenting native elements
### Aumento de elementos nativos
Native HTML elements capture a number of standard interaction patterns that are important to accessibility.
When authoring Angular components, you should re-use these native elements directly when possible, rather than re-implementing well-supported behaviors.
Los elementos HTML nativos capturan una serie de patrones de interacción estándar que son importantes para la accesibilidad.
Al crear componentes de Angular, deberías reutilizar estos elementos nativos directamente cuando sea posible, en lugar de volver a implementar comportamientos bien soportados.
For example, instead of creating a custom element for a new variety of button, you can create a component that uses an attribute selector with a native`<button>` element.
This most commonly applies to`<button>`and`<a>`, but can be used with many other types of element.
Por ejemplo, en lugar de crear un elemento personalizado para un nuevo tipo de botón, puedes crear un componente que use un selector de atributos con un elemento nativo`<button>`.
Esto se aplica sobre todo a`<button>`y`<a>`, pero se puede usar con muchos otros tipos de elementos.
You can see examples of this pattern in Angular Material: [`MatButton`](https://github.com/angular/components/blob/master/src/material/button/button.ts#L66-L68), [`MatTabNav`](https://github.com/angular/components/blob/master/src/material/tabs/tab-nav-bar/tab-nav-bar.ts#L67), [`MatTable`](https://github.com/angular/components/blob/master/src/material/table/table.ts#L17).
### Using containers for native elements
### Uso de contenedores para elementos nativos
Sometimes using the appropriate native element requires a container element.
For example, the native`<input>`element cannot have children, so any custom text entry components need
to wrap an `<input>` with additional elements.
While you might just include the `<input>` in your custom component's template,
this makes it impossible for users of the component to set arbitrary properties and attributes to the input element.
Instead, you can create a container component that uses content projection to include the native control in the
component's API.
A veces, para usar el elemento nativo apropiado hace falta un contenedor.
Por ejemplo, el elemento nativo`<input>`no puede tener hijos, por lo que cualquier componente de entrada de texto personalizado necesita envolver un `<input>` con elementos adicionales.
You can see [`MatFormField`](https://material.angular.io/components/form-field/overview) as an example of this pattern.
Si bien puedes incluir el `<input>` en la plantilla de tu componente personalizado,
esto hace que sea imposible para los usuarios de dicho componente establecer propiedades y atributos arbitrarios para el elemento de entrada.
En su lugar, puedes crear un componente contenedor que utilice la proyección de contenido para incluir el control nativo en el
API del componente.
## Case study: Building a custom progress bar
Puedes consultar [`MatFormField`](https://material.angular.io/components/form-field/overview) para ver un ejemplo de este patrón.
The following example shows how to make a simple progress bar accessible by using host binding to control accessibility-related attributes.
## Caso práctico: creación de una barra de progreso personalizada
* The component defines an accessibility-enabled element with both the standard HTML attribute `role`, and ARIA attributes. The ARIA attribute `aria-valuenow` is bound to the user's input.
El siguiente ejemplo muestra cómo hacer que una barra de progreso simple sea accesible utilizando el *host binding* para controlar los atributos relacionados con la accesibilidad.
* El componente define un elemento habilitado para accesibilidad con el atributo HTML estándar `role` y los atributos ARIA. El atributo ARIA `aria-valuenow` está vinculado a la entrada del usuario.
Tracking and controlling [focus](https://developers.google.com/web/fundamentals/accessibility/focus/) in a UI is an important consideration in designing for accessibility.
When using Angular routing, you should decide where page focus goes upon navigation.
El seguimiento y el control del [foco](https://developers.google.com/web/fundamentals/accessibility/focus/) en una interfaz de usuario son aspectos muy importantes en el diseño si queremos tener en cuenta la accesibilidad.
Al usar el enrutamiento de Angular, debes decidir dónde va el foco de la página al navegar.
To avoid relying solely on visual cues, you need to make sure your routing code updates focus after page navigation.
Use the`NavigationEnd`event from the `Router`service to know when to update
focus.
Para evitar depender únicamente de señales visuales, te debes asegurar de que el código de enrutamiento actualiza el foco después de la navegación de la página.
Usa el evento`NavigationEnd`del servicio`Router`para saber cuándo actualizar el foco.
El siguiente ejemplo muestra cómo encontrar y poner el foco en el contenido principal de la cabecera (el elemento `#main-content-header`) dentro del DOM después de la navegación.
The following example shows how to find and focus the main content header in the DOM after navigation.
@ -341,7 +341,7 @@ The following are some of the key AngularJS built-in directives and their equiva
In Angular, the template no longer specifies its associated controller.
Rather, the component specifies its associated template as part of the component class decorator.
For more information, see [Architecture Overview](guide/architecture#components).
For more information, see [Architecture Overview](guide/architecture#componentes).
</td>
@ -1035,7 +1035,7 @@ The Angular code is shown using TypeScript.
This is a nonissue in Angular because ES 2015 modules
handle the namespacing for you.
For more information on modules, see the [Modules](guide/architecture#modules) section of the
For more information on modules, see the [Modules](guide/architecture#módulos) section of the
[Architecture Overview](guide/architecture).
</td>
@ -1112,7 +1112,7 @@ The Angular code is shown using TypeScript.
This is how you associate a template with logic, which is defined in the component class.
For more information, see the [Components](guide/architecture#components)
For more information, see the [Components](guide/architecture#componentes)
section of the [Architecture Overview](guide/architecture) page.
</td>
@ -1144,7 +1144,7 @@ The Angular code is shown using TypeScript.
In Angular, you create a component class to contain the data model and control methods. Use the TypeScript <code>export</code> keyword to export the class so that the functionality can be imported into NgModules.
For more information, see the [Components](guide/architecture#components)
For more information, see the [Components](guide/architecture#componentes)
section of the [Architecture Overview](guide/architecture) page.
App shell is a way to render a portion of your application via a route at build time.
It can improve the user experience by quickly launching a static rendered page (a skeleton common to all pages) while the browser downloads the full client version and switches to it automatically after the code loads.
App shell es una manera de renderizar una porción de tu aplicación a través de una ruta en tiempo de compilación (build time).
Puede mejorar la experiencia de usuario lanzando rápidamente una página estática renderizada (un esqueleto común a todas las páginas) mientras el navegador descarga la versión completa del cliente y la muestra automáticamente al finalizar su carga.
This gives users a meaningful first paint of your application that appears quickly because the browser can simply render the HTML and CSS without the need to initialize any JavaScript.
Esto da a los usuarios una primera visualización significativa de su aplicación que aparece rápidamente porque el navegador simplemente puede renderizar HTML y CSS sin la necesidad de inicializar JavaScript.
Learn more in [The App Shell Model](https://developers.google.com/web/fundamentals/architecture/app-shell).
Obténga más información en [El modelo de aplicación Shell](https://developers.google.com/web/fundamentals/architecture/app-shell).
## Step 1: Prepare the application
## Paso 1: Prepara la aplicación
You can do this with the following CLI command:
Puedes hacer esto con el siguiente comando CLI:
<code-examplelanguage="bash">
ng new my-app --routing
</code-example>
For an existing application, you have to manually add the`RouterModule`and defining a `<router-outlet>` within your application.
Para una aplicación existente, debes agregar manualmente el`RouterModule`y definir un`<router-outlet>`dentro de tu aplicación.
## Step 2: Create the app shell
## Paso 2: Crea el shell de la aplicación
Use the CLI to automatically create the app shell.
Usa la CLI para crear automáticamente el shell de la aplicación.
<code-examplelanguage="bash">
ng generate app-shell
</code-example>
*`client-project` takes the name of your client application.
*`client-project` toma el nombre de tu aplicación cliente.
After running this command you will notice that the `angular.json` configuration file has been updated to add two new targets, with a few other changes.
Después de ejecutar este comando, notará que el archivo de configuración `angular.json` se ha actualizado para agregar dos nuevos targets, con algunos otros cambios.
<code-examplelanguage="json">
"server": {
@ -53,20 +53,18 @@ After running this command you will notice that the `angular.json` configuration
}
</code-example>
## Step 3: Verify the app is built with the shell content
## Paso 3: Verifica que la aplicación está construida con el contenido del shell
Use the CLI to build the`app-shell` target.
Usa la CLI para construir el`app-shell` target.
<code-examplelanguage="bash">
ng run my-app:app-shell
</code-example>
Or to use the production configuration.
O usa la configuración de producción.
<code-examplelanguage="bash">
ng run my-app:app-shell:production
</code-example>
To verify the build output, open `dist/my-app/index.html`. Look for default text `app-shell works!` to show that the app shell route was rendered as part of the output.
Para verificar el resultado de la compilación, abre `dist/my-app/index.html`. Busca el texto por defecto `app-shell works!` para mostrar que la ruta del shell de la aplicación se ha renderizado como parte de la carpeta de distribución.
Angular apps are modular and Angular has its own modularity system called *NgModules*.
NgModules are containers for a cohesive block of code dedicated to an application domain, a workflow, or a closely related set of capabilities. They can contain components, service providers, and other code files whose scope is defined by the containing NgModule. They can import functionality that is exported from other NgModules, and export selected functionality for use by other NgModules.
Every Angular app has at least one NgModule class, [the *root module*](guide/bootstrapping), which is conventionally named `AppModule` and resides in a file named `app.module.ts`. You launch your app by *bootstrapping* the root NgModule.
While a small application might have only one NgModule, most apps have many more *feature modules*. The *root* NgModule for an app is so named because it can include child NgModules in a hierarchy of any depth.
## NgModule metadata
An NgModule is defined by a class decorated with `@NgModule()`. The `@NgModule()` decorator is a function that takes a single metadata object, whose properties describe the module. The most important properties are as follows.
*`declarations`: The [components](guide/architecture-components), *directives*, and *pipes* that belong to this NgModule.
*`exports`: The subset of declarations that should be visible and usable in the *component templates* of other NgModules.
*`imports`: Other modules whose exported classes are needed by component templates declared in *this* NgModule.
*`providers`: Creators of [services](guide/architecture-services) that this NgModule contributes to the global collection of services; they become accessible in all parts of the app. (You can also specify providers at the component level, which is often preferred.)
*`bootstrap`: The main application view, called the *root component*, which hosts all other app views. Only the *root NgModule* should set the `bootstrap` property.
`AppComponent` is included in the `exports` list here for illustration; it isn't actually necessary in this example. A root NgModule has no reason to *export* anything because other modules don't need to *import* the root NgModule.
</div>
## NgModules and components
NgModules provide a *compilation context* for their components. A root NgModule always has a root component that is created during bootstrap, but any NgModule can include any number of additional components, which can be loaded through the router or created through the template. The components that belong to an NgModule share a compilation context.
A component and its template together define a *view*. A component can contain a *view hierarchy*, which allows you to define arbitrarily complex areas of the screen that can be created, modified, and destroyed as a unit. A view hierarchy can mix views defined in components that belong to different NgModules. This is often the case, especially for UI libraries.
When you create a component, it's associated directly with a single view, called the *host view*. The host view can be the root of a view hierarchy, which can contain *embedded views*, which are in turn the host views of other components. Those components can be in the same NgModule, or can be imported from other NgModules. Views in the tree can be nested to any depth.
<divclass="alert is-helpful">
**Note:** The hierarchical structure of views is a key factor in the way Angular detects and responds to changes in the DOM and app data.
</div>
## NgModules and JavaScript modules
The NgModule system is different from and unrelated to the JavaScript (ES2015) module system for managing collections of JavaScript objects. These are *complementary* module systems that you can use together to write your apps.
In JavaScript each *file* is a module and all objects defined in the file belong to that module.
The module declares some objects to be public by marking them with the `export` key word.
Other JavaScript modules use *import statements* to access public objects from other modules.
Angular loads as a collection of JavaScript modules. You can think of them as library modules. Each Angular library name begins with the `@angular` prefix. Install them with the node package manager `npm` and import parts of them with JavaScript `import` statements.
<brclass="clear">
For example, import Angular's `Component` decorator from the `@angular/core` library like this.
In this way you're using the Angular and JavaScript module systems *together*. Although it's easy to confuse the two systems, which share the common vocabulary of "imports" and "exports", you will become familiar with the different contexts in which they are used.
<divclass="alert is-helpful">
Learn more from the [NgModules](guide/ngmodules) guide.
Angular apps are modular and Angular has its own modularity system called*NgModules*.
NgModules are containers for a cohesive block of code dedicated to an application domain, a workflow, or a closely related set of capabilities. They can contain components, service providers, and other code files whose scope is defined by the containing NgModule. They can import functionality that is exported from other NgModules, and export selected functionality for use by other NgModules.
Las aplicaciones Angular son modulares y Angular tiene su propio sistema de modularidad llamado*NgModules*.
Los NgModules son contenedores para un bloque cohesivo de código dedicado a un dominio de aplicación, un flujo de trabajo o un conjunto de capacidades estrechamente relacionadas. Pueden contener componentes, proveedores de servicios y otros archivos de código cuyo alcance está definido por el NgModule que los contiene. Pueden importar la funcionalidad que se exporta desde otros NgModules y exportar la funcionalidad seleccionada para que la utilicen otros NgModules.
Every Angular app has at least one NgModule class, [the *root module*](guide/bootstrapping), which is conventionally named`AppModule`and resides in a file named `app.module.ts`. You launch your app by *bootstrapping* the root NgModule.
Cada aplicación Angular tiene al menos una clase NgModule, [el *módulo raíz*](guide/bootstrapping), que se llama convencionalmente`AppModule`y reside en un archivo llamado `app.module.ts`. Inicia tu aplicación *cargando* el NgModule raíz.
While a small application might have only one NgModule, most apps have many more *feature modules*. The *root* NgModule for an app is so named because it can include child NgModules in a hierarchy of any depth.
Si bien una aplicación pequeña puede tener sólo un NgModule, la mayoría de las aplicaciones tienen muchos más *módulos de funcionalidad*. El NgModule *raíz* para una aplicación se llama así porque puede incluir NgModules secundarios en una jerarquía de cualquier profundidad.
## NgModule metadata
## Metadatos de NgModule
An NgModule is defined by a class decorated with`@NgModule()`. The`@NgModule()`decorator is a function that takes a single metadata object, whose properties describe the module. The most important properties are as follows.
Un NgModule está definido por una clase decorada con`@NgModule()`. El decorador`@NgModule()`es una función que toma un único objeto de metadatos, cuyas propiedades describen el módulo. Las propiedades más importantes son las siguientes.
*`declarations`: The [components](guide/architecture-components), *directives*, and*pipes*that belong to this NgModule.
*`declarations`: Los [componentes](guide/architecture-components), *directivas*, y*pipes*que pertenecen a este NgModule.
*`exports`: The subset of declarations that should be visible and usable in the *component templates*of other NgModules.
*`exports`: El subconjunto de declaraciones que deberían ser visibles y utilizables en las *plantillas de componentes*de otros NgModules.
*`imports`: Other modules whose exported classes are needed by component templates declared in *this* NgModule.
*`imports`: Otros módulos cuyas clases exportadas son necesarias para las plantillas de componentes declaradas en *este* NgModule.
*`providers`: Creators of [services](guide/architecture-services) that this NgModule contributes to the global collection of services; they become accessible in all parts of the app. (You can also specify providers at the component level.)
*`providers`: Creadores de [servicios](guide/architecture-services) que este NgModule aporta a la colección global de servicios; se vuelven accesibles en todas las partes de la aplicación. (También puedes especificar proveedores a nivel de componente, que a menudo es preferido).
*`bootstrap`: The main application view, called the *root component*, which hosts all other app views. Only the *root NgModule* should set the`bootstrap` property.
*`bootstrap`: La vista principal de la aplicación, llamado el *componente raíz*, que aloja todas las demás vistas de la aplicación. Sólo el *NgModule raíz* debe establecer la propiedad`bootstrap`.
`AppComponent`is included in the `exports`list here for illustration; it isn't actually necessary in this example. A root NgModule has no reason to*export*anything because other modules don't need to*import*the root NgModule.
Aquí se incluye `AppComponent`en la lista de `exports`como ilustración; en realidad no es necesario en este ejemplo. Un NgModule raíz no tiene ninguna razón para*exportar*nada porque otros módulos no necesitan*importar*el NgModule raíz.
</div>
## NgModules and components
## NgModules y componentes
NgModules provide a *compilation context* for their components. A root NgModule always has a root component that is created during bootstrap, but any NgModule can include any number of additional components, which can be loaded through the router or created through the template. The components that belong to an NgModule share a compilation context.
NgModules proporciona un *contexto de compilación* para sus componentes. Un NgModule raíz siempre tiene un componente raíz que se crea durante el arranque, pero cualquier NgModule puede incluir cualquier cantidad de componentes adicionales, que se pueden cargar a través del enrutador o crear a través de la plantilla. Los componentes que pertenecen a un NgModule comparten un contexto de compilación.
@ -41,7 +41,7 @@ NgModules provide a *compilation context* for their components. A root NgModule
<brclass="clear">
A component and its template together definea *view*. A component can contain a *view hierarchy*, which allows you to define arbitrarily complex areas of the screen that can be created, modified, and destroyed as a unit. A view hierarchy can mix views defined in components that belong to different NgModules. This is often the case, especially for UI libraries.
Juntos, un componente y su plantilla definen una *vista*. Un componente puede contener una *jerarquía de vista*, que te permiten definir áreas arbitrariamente complejas de la pantalla que se pueden crear, modificar y destruir como una unidad. Una jerarquía de vistas puede mezclar vistas definidas en componentes que pertenecen a diferentes NgModules. Este suele ser el caso, especialmente para las bibliotecas de interfaz de usuario.
@ -49,56 +49,56 @@ A component and its template together define a *view*. A component can contain a
<brclass="clear">
When you create a component, it's associated directly with a single view, called the *host view*. The host view can be the root of a view hierarchy, which can contain *embedded views*, which are in turn the host views of other components. Those components can be in the same NgModule, or can be imported from other NgModules. Views in the tree can be nested to any depth.
Cuando creas un componente, se asocia directamente con una sola vista, llamada *vista host*. La vista host puede ser la raíz de una jerarquía de vistas, que puede contener *vistas incrustadas*, que a su vez son las vistas de host de otros componentes. Esos componentes pueden estar en el mismo NgModule o pueden importarse desde otros NgModules. Las vistas en el árbol se pueden anidar a cualquier profundidad.
<divclass="alert is-helpful">
**Note:**The hierarchical structure of views is a key factor in the way Angular detects and responds to changes in the DOM and app data.
**Nota:**La estructura jerárquica de las vistas es un factor clave en la forma en que Angular detecta y responde a los cambios en el DOM y los datos de la aplicación.
</div>
## NgModules and JavaScript modules
## NgModules y módulos JavaScript
The NgModule system is different from and unrelated to the JavaScript (ES2015) module system for managing collections of JavaScript objects. These are *complementary* module systems that you can use together to write your apps.
El sistema NgModule es diferente y no está relacionado con el sistema de módulos JavaScript (ES2015) para administrar colecciones de objetos JavaScript. Estos son sistemas de módulos *complementarios* que puedes usar juntos para escribir tus aplicaciones.
In JavaScript each *file*is a module and all objects defined in the file belong to that module.
The module declares some objects to be public by marking them with the `export` key word.
Other JavaScript modules use *import statements* to access public objects from other modules.
En JavaScript, cada *archivo*es un módulo y todos los objetos definidos en el archivo pertenecen a ese módulo.
El módulo declara que algunos objetos son públicos marcándolos con la palabra clave `export`.
Otros módulos de JavaScript usan *declaraciones de importación* para acceder a objetos públicos de otros módulos.
Angular loads as a collection of JavaScript modules. You can think of them as library modules. Each Angular library name begins with the `@angular` prefix. Install them with the node package manager`npm`and import parts of them with JavaScript `import` statements.
Angular se carga como una colección de módulos JavaScript. Puedes pensar en ellos como módulos de biblioteca. Cada nombre de biblioteca de Angular comienza con el prefijo `@angular`. Instálalos con el gestor de paquetes`npm`e importa partes de ellos con declaraciones `import` de JavaScript.
<brclass="clear">
For example, import Angular's`Component` decorator from the`@angular/core`library like this.
Por ejemplo, importa el decorador`Component` de Angular de la biblioteca`@angular/core`como esta.
In this way you're using the Angular and JavaScript module systems *together*. Although it's easy to confuse the two systems, which share the common vocabulary of "imports" and "exports", you will become familiar with the different contexts in which they are used.
De esta manera, estás utilizando los sistemas de módulos Angular y JavaScript *juntos*. Aunque es fácil confundir los dos sistemas, que comparten el vocabulario común de "importaciones" y "exportaciones", te familiarizarás con los diferentes contextos en los que se utilizan.
<divclass="alert is-helpful">
Learn more from the [NgModules](guide/ngmodules) guide.
Obtén más información en la guía [NgModules](guide/ngmodules).
After you understand the basic Angular building blocks, you can learn more
about the features and tools that can help you develop and deliver Angular applications.
* Work through the [Tour of Heroes](tutorial) tutorial to get a feel for how to fit the basic building blocks together to create a well-designed application.
* Check out the [Glossary](guide/glossary) to understand Angular-specific terms and usage.
* Use the documentation to learn about key features in more depth, according to your stage of development and areas of interest.
## Application architecture
* The [Components and templates](guide/displaying-data) guide explains how to connect the application data in your [components](guide/glossary#component) to your page-display [templates](guide/glossary#template), to create a complete interactive application.
* The [NgModules](guide/ngmodules) guide provides in-depth information on the modular structure of an Angular application.
* The [Routing and navigation](guide/router) guide provides in-depth information on how to construct applications that allow a user to navigate to different [views](guide/glossary#view) within your single-page app.
* The [Dependency injection](guide/dependency-injection) guide provides in-depth information on how to construct an application such that each component class can acquire the services and objects it needs to perform its function.
## Responsive programming
The **Components and Templates** guide provides guidance and details of the [template syntax](guide/template-syntax) that you use to display your component data when and where you want it within a view, and to collect input from users that you can respond to.
Additional pages and sections describe some basic programming techniques for Angular apps.
* [Lifecycle hooks](guide/lifecycle-hooks): Tap into key moments in the lifetime of a component, from its creation to its destruction, by implementing the lifecycle hook interfaces.
* [Observables and event processing](guide/observables): How to use observables with components and services to publish and subscribe to messages of any type, such as user-interaction events and asynchronous operation results.
* [Angular elements](guide/elements): How to package components as *custom elements* using Web Components, a web standard for defining new HTML elements in a framework-agnostic way.
* [Forms](guide/forms-overview): Support complex data entry scenarios with HTML-based input validation.
* [Animations](guide/animations): Use Angular's animation library to animate component behavior
without deep knowledge of animation techniques or CSS.
## Client-server interaction
Angular provides a framework for single-page apps, where most of the logic and data resides on the client.
Most apps still need to access a server using the `HttpClient` to access and save data.
For some platforms and applications, you might also want to use the PWA (Progressive Web App) model to improve the user experience.
* [HTTP](guide/http): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
* [Server-side rendering](guide/universal): Angular Universal generates static application pages on the server through server-side rendering (SSR). This allows you to run your Angular app on the server in order to improve performance and show the first page quickly on mobile and low-powered devices, and also facilitate web crawlers.
* [Service workers and PWA](guide/service-worker-intro): Use a service worker to reduce dependency on the network and significantly improve the user experience.
* [Web workers](guide/web-worker): Learn how to run CPU-intensive computations in a background thread.
## Support for the development cycle
The **Development Workflow** section describes the tools and processes you use to compile, test, and deploy Angular applications.
* [CLI Command Reference](cli): The Angular CLI is a command-line tool that you use to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment.
* [Compilation](guide/aot-compiler): Angular provides just-in-time (JIT) compilation for the development environment, and ahead-of-time (AOT) compilation for the production environment.
* [Testing platform](guide/testing): Run unit tests on your application parts as they interact with the Angular framework.
* [Deployment](guide/deployment): Learn techniques for deploying your Angular application to a remote server.
* [Security guidelines](guide/security): Learn about Angular's built-in protections against common web-app vulnerabilities and attacks such as cross-site scripting attacks.
* [Internationalization](guide/i18n): Make your app available in multiple languages with Angular's internationalization (i18n) tools.
* [Accessibility](guide/accessibility): Make your app accessible to all users.
## File structure, configuration, and dependencies
* [Workspace and file structure](guide/file-structure): Understand the structure of Angular workspace and project folders.
* [Building and serving](guide/build): Learn to define different build and proxy server configurations for your project, such as development, staging, and production.
* [npm packages](guide/npm-packages): The Angular Framework, Angular CLI, and components used by Angular applications are packaged as [npm](https://docs.npmjs.com/) packages and distributed via the npm registry. The Angular CLI creates a default `package.json` file, which specifies a starter set of packages that work well together and jointly support many common application scenarios.
* [TypeScript configuration](guide/typescript-configuration): TypeScript is the primary language for Angular application development.
* [Browser support](guide/browser-support): Make your apps compatible across a wide range of browsers.
## Extending Angular
* [Angular libraries](guide/libraries): Learn about using and creating re-usable libraries.
* [Schematics](guide/schematics): Learn about customizing and extending the CLI's generation capabilities.
* [CLI builders](guide/cli-builder): Learn about customizing and extending the CLI's ability to apply tools to perform complex tasks, such as building and testing applications.
After you understand the basic Angular building blocks, you can learn more
about the features and tools that can help you develop and deliver Angular applications.
Una vez que comprendas los conceptos básicos de Angular, puedes aprender más sobre las funcionalidades y herramientas que pueden ayudarte a desarrollar y entregar aplicaciones Angular.
*Work through the [Tour of Heroes](tutorial) tutorial to get a feel for how to fit the basic building blocks together to create a well-designed application.
*Realiza el tutorial [Tour de Héroes](tutorial) para familiarizarte con los conceptos básicos necesarios para crear una aplicación bien diseñada.
* Check out the [Glossary](guide/glossary) to understand Angular-specific terms and usage.
* Consulta el [Glosario](guide/glossary) para comprender los términos específicos de Angular y su correspondiente utilización.
* Use the documentation to learn about key features in more depth, according to your stage of development and areas of interest.
* Utiliza la documentación te permite conocer en detalle las funcionalidades claves, según tu etapa de desarrollo y tus áreas de interés.
## Application architecture
## Arquitectura de la aplicación
*The [Components and templates](guide/displaying-data) guide explains how to connect the application data in your [components](guide/glossary#component) to your page-display [templates](guide/glossary#template), to create a complete interactive application.
*La guía de [Componentes y Plantillas](guide/displaying-data) explica como conectar los datos de la aplicación de sus [componentes](guide/glossary#componente) con las [plantillas](guide/glossary#plantilla) de las pantallas, para crear una aplicación completamente interactiva.
*The [NgModules](guide/ngmodules) guide provides in-depth information on the modular structure of an Angular application.
*La guía de [NgModules](guide/ngmodules) proporciona información detallada sobre la estructura de módulos utilizada en una aplicación Angular.
*The [Routing and navigation](guide/router) guide provides in-depth information on how to construct applications that allow a user to navigate to different [views](guide/glossary#view) within your single-page app.
*La guía de [Enrutamiento y navigación](guide/router) describe como crear aplicaciones que permitan al usuario navegar entre las diferentes [vistas](guide/glossary#vista) dentro de su aplicación de una sola página (SPA).
*The [Dependency injection](guide/dependency-injection) guide provides in-depth information on how to construct an application such that each component class can acquire the services and objects it needs to perform its function.
*La guía de [Injección de dependencias](guide/dependency-injection) brinda información detallada sobre cómo construir una aplicación de modo que cada clase de componente pueda adquirir los servicios y objetos que necesita para realizar su función.
## Responsive programming
## Programación responsive
The **Components and Templates** guide provides guidance and details of the [template syntax](guide/template-syntax) that you use to display your component data when and where you want it within a view, and to collect input from users that you can respond to.
La guía de **Componentes y Plantillas** brinda orientación y detalles de la [sintaxis de plantilla](guide/template-syntax) que se utilizan para mostrar la información de sus componentes, cuando y donde lo desees dentro de una vista y para obtener entradas (inputs) de los usuarios a las que puedas responder.
Additional pages and sections describe some basic programming techniques for Angular apps.
Las páginas y secciones adicionales describen algunas técnicas básicas de programación para aplicaciones Angular.
* [Lifecycle hooks](guide/lifecycle-hooks): Tap into key moments in the lifetime of a component, from its creation to its destruction, by implementing the lifecycle hook interfaces.
* [Lifecycle Hooks](guide/lifecycle-hooks): Aprovecha los momentos claves de la vida de un componente, desde su creación hasta su destrucción, implementando las interfaces de los `lifecycle hooks`.
* [Observables and event processing](guide/observables): How to use observables with components and services to publish and subscribe to messages of any type, such as user-interaction events and asynchronous operation results.
* [Observables y procesamiento de eventos](guide/observables): Cómo utilizar observables con componentes y servicios para publicar y suscribirse a mensajes de cualquier tipo, tales como los eventos de interacción del usuario y los resultados de operaciones asincrónicas.
* [Angular elements](guide/elements): How to package components as *custom elements* using Web Components, a web standard for defining new HTML elements in a framework-agnostic way.
* [Elementos Angular](guide/elements): Cómo empaquetar componentes como *elementos personalizados* utilizando Web Components, un estándar web para definir nuevos elementos HTML de una manera agnóstica a cualquier framework.
* [Forms](guide/forms-overview): Support complex data entry scenarios with HTML-based input validation.
* [Formularios](guide/forms-overview): Soporta escenarios complejos de entrada de datos con validación de entradas (inputs) basadas en HTML.
* [Animations](guide/animations): Use Angular's animation library to animate component behavior
without deep knowledge of animation techniques or CSS.
* [Animaciones](guide/animations): Utiliza la librería de animación de Angular para animar el comportamiento de los componentes sin necesidad de conocer en profundidad las técnicas de animación o CSS.
## Client-server interaction
## Interacción Cliente-Servidor
Angular provides a framework for single-page apps, where most of the logic and data resides on the client.
Most apps still need to access a server using the`HttpClient`to access and save data.
For some platforms and applications, you might also want to use the PWA (Progressive Web App) model to improve the user experience.
Angular ofrece un framework para aplicaciones de una sola página (SPA), donde la mayoría de la lógica y los datos se encuentran en el cliente.
La mayoría de las aplicaciones todavía necesitan acceder a un servidor usando el`HttpClient`para acceder y guardar datos.
Para algunas plataformas y aplicaciones, se puede también querer utilizar el modelo PWA (Aplicaciones Web Progresivas) para mejorar la experiencia de usuario.
* [HTTP](guide/http): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client.
* [HTTP](guide/http): Comunícate con un servidor para obtener datos, guardarlos e invocar acciones del lado del servidor con un cliente HTTP.
* [Server-side rendering](guide/universal): Angular Universal generates static application pages on the server through server-side rendering (SSR). This allows you to run your Angular app on the server in order to improve performance and show the first page quickly on mobile and low-powered devices, and also facilitate web crawlers.
* [Renderizado del lado del servidor](guide/universal): Angular Universal genera páginas de aplicación estáticas en el servidor a través de la renderización del lado del servidor (SSR). Esto te permite ejecutar tu aplicación Angular en el servidor para mejorar el rendimiento y mostrar la primera página rápidamente en dispositivos móviles y de baja potencia, y también facilitar los rastreadores web.
* [Service workers and PWA](guide/service-worker-intro): Use a service worker to reduce dependency on the network and significantly improve the user experience.
* [Service workers y PWA](guide/service-worker-intro): Utiliza un service worker para reducir la dependencia de la red y mejorar significativamente la experiencia del usuario.
* [Web workers](guide/web-worker): Learn how to run CPU-intensive computations in a background thread.
* [Web workers](guide/web-worker): Aprende a ejecutar cálculos con uso intensivo de la CPU en un hilo en segundo plano.
## Support for the development cycle
## Soporte del Ciclo de Desarrollo
The **Development Workflow** section describes the tools and processes you use to compile, test, and deploy Angular applications.
La sección **Workflow de Desarrollo** detalla las herramientas y los procesos utilizados para compilar, probar y desplegar aplicaciones Angular.
* [CLI Command Reference](cli): The Angular CLI is a command-line tool that you use to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment.
* [CLI Referencia de Comando](cli): La CLI de Angular es una interfaz de línea de comandos utilizada para crear proyectos, generar código de aplicaciones y librerías y realizar un conjunto de tareas de desarrollo tales como pruebas, empaquetamiento y despliegue de aplicaciones.
* [Compilation](guide/aot-compiler): Angular provides just-in-time (JIT) compilation for the development environment, and ahead-of-time (AOT) compilation for the production environment.
* [Compilación](guide/aot-compiler): Angular proporciona compilación `just-in-time` (JIT) para el entorno de desarrollo y compilación `ahead-of-time` (AOT) para el entorno de producción.
* [Testing platform](guide/testing): Run unit tests on your application parts as they interact with the Angular framework.
* [Plataforma de pruebas](guide/testing): Ejecuta pruebas unitarias sobre las distintas partes de tu aplicación a medida que interactúan con el framework de Angular.
* [Deployment](guide/deployment): Learn techniques for deploying your Angular application to a remote server.
* [Despliegue](guide/deployment): Aprende técnicas para desplegar tu aplicación Angular en un servidor remoto.
* [Security guidelines](guide/security): Learn about Angular's built-in protections against common web-app vulnerabilities and attacks such as cross-site scripting attacks.
* [Lineamientos de Seguridad](guide/security): Aprende sobre las protecciones integradas por Angular contra las vulnerabilidades y los ataques comunes a las aplicaciones web, como por ejemplo, ataques de cross-site scripting.
* [Internationalization](guide/i18n): Make your app available in multiple languages with Angular's internationalization (i18n) tools.
* [Internacionalización](guide/i18n): Haz que tu aplicación soporte múltiples lenguajes con las herramientas de internacionalización de Angular (i18n).
* [Accessibility](guide/accessibility): Make your app accessible to all users.
* [Accesibilidad](guide/accessibility): Haz que tu aplicación sea accesible a todos los usuarios.
## File structure, configuration, and dependencies
## Estructura de Archivos, Configuración y Dependencias
* [Workspace and file structure](guide/file-structure): Understand the structure of Angular workspace and project folders.
* [Espacio de trabajo y estructura de archivos](guide/file-structure): Comprende la estructura del espacio de trabajo y las carpetas de proyectos en Angular.
* [Building and serving](guide/build): Learn to define different build and proxy server configurations for your project, such as development, staging, and production.
* [Construcción y servicio](guide/build): Aprende a definir diferentes configuraciones de servidores proxy y construcción para tu proyecto, como por ejemplo desarrollo, staging y producción.
* [npm packages](guide/npm-packages): The Angular Framework, Angular CLI, and components used by Angular applications are packaged as [npm](https://docs.npmjs.com/) packages and distributed via the npm registry. The Angular CLI creates a default `package.json` file, which specifies a starter set of packages that work well together and jointly support many common application scenarios.
* [Paquetes npm](guide/npm-packages): El Framework de Angular, la CLI de Angular y los componentes usados por las aplicaciones Angular se empaquetan como paquetes [npm](https://docs.npmjs.com/) y se distribuyen a través del registro de `npm`. La CLI de Angular crea por defecto un archivo `package.json`, que especifica un conjunto inicial de paquetes que funcionan bien en conjunto y dan soporte a muchos escenarios de aplicaciones comunes.
* [TypeScript configuration](guide/typescript-configuration): TypeScript is the primary language for Angular application development.
* [Configuración de Typescript](guide/typescript-configuration): TypeScript es el lenguaje principal utilizado para el desarrollo de aplicaciones Angular.
* [Browser support](guide/browser-support): Make your apps compatible across a wide range of browsers.
* [Soporte de Navegadores](guide/browser-support): Haz que tus aplicaciones sean compatibles en una amplia gama de navegadores.
## Extending Angular
## Extendiendo Angular
* [Angular libraries](guide/libraries): Learn about using and creating re-usable libraries.
* [Librerías Angular](guide/libraries): Aprende a usar y crear librerías reutilizables.
* [Schematics](guide/schematics): Learn about customizing and extending the CLI's generation capabilities.
* [Esquemas](guide/schematics): Aprende como personalizar y extender las capacidades de generación de la CLI.
* [CLI builders](guide/cli-builder): Learn about customizing and extending the CLI's ability to apply tools to perform complex tasks, such as building and testing applications.
* [Constructores de la CLI](guide/cli-builder): Aprende a personalizar y extender la capacidad de la CLI de aplicar herramientas para realizar tareas complejas, como la construcción y pruebas de aplicaciones.
Services can depend on other services. For example, here's a `HeroService` that depends on the `Logger` service, and also uses `BackendService` to get heroes. That service in turn might depend on the `HttpClient` service to fetch heroes asynchronously from a server.
DI is wired into the Angular framework and used everywhere to provide new components with the services or other things they need.
Components consume services; that is, you can *inject* a service into a component, giving the component access to that service class.
To define a class as a service in Angular, use the `@Injectable()` decorator to provide the metadata that allows Angular to inject it into a component as a *dependency*.
Similarly, use the `@Injectable()` decorator to indicate that a component or other class (such as another service, a pipe, or an NgModule) *has* a dependency.
* The *injector* is the main mechanism. Angular creates an application-wide injector for you during the bootstrap process, and additional injectors as needed. You don't have to create injectors.
* An injector creates dependencies, and maintains a *container* of dependency instances that it reuses if possible.
* A *provider* is an object that tells an injector how to obtain or create a dependency.
For any dependency that you need in your app, you must register a provider with the app's injector,
so that the injector can use the provider to create new instances.
For a service, the provider is typically the service class itself.
<divclass="alert is-helpful">
A dependency doesn't have to be a service—it could be a function, for example, or a value.
</div>
When Angular creates a new instance of a component class, it determines which services or other dependencies that component needs by looking at the constructor parameter types. For example, the constructor of `HeroListComponent` needs `HeroService`.
When Angular discovers that a component depends on a service, it first checks if the injector has any existing instances of that service. If a requested service instance doesn't yet exist, the injector makes one using the registered provider, and adds it to the injector before returning the service to Angular.
When all requested services have been resolved and returned, Angular can call the component's constructor with those services as arguments.
The process of `HeroService` injection looks something like this.
You must register at least one *provider* of any service you are going to use.
The provider can be part of the service's own metadata, making that service available everywhere,
or you can register providers with specific modules or components.
You register providers in the metadata of the service (in the `@Injectable()` decorator),
or in the `@NgModule()` or `@Component()` metadata
* By default, the Angular CLI command [`ng generate service`](cli/generate) registers a provider with the root injector for your service by including provider metadata in the `@Injectable()` decorator. The tutorial uses this method to register the provider of HeroService class definition.
```
@Injectable({
providedIn: 'root',
})
```
When you provide the service at the root level, Angular creates a single, shared instance of `HeroService`
and injects it into any class that asks for it.
Registering the provider in the `@Injectable()` metadata also allows Angular to optimize an app
by removing the service from the compiled app if it isn't used.
* When you register a provider with a [specific NgModule](guide/architecture-modules), the same instance of a service is available to all components in that NgModule. To register at this level, use the `providers` property of the `@NgModule()` decorator,
```
@NgModule({
providers: [
BackendService,
Logger
],
...
})
```
* When you register a provider at the component level, you get a new instance of the
service with each new instance of that component.
At the component level, register a service provider in the `providers` property of the `@Component()` metadata.
# Introduction to services and dependency injection
# Introducción a servicios e inyección de dependencias
*Service*is a broad category encompassing any value, function, or feature that an app needs.
A service is typically a class with a narrow, well-defined purpose.
It should do something specific and do it well.
*Servicio*es una categoría amplia que abarca cualquier valor, función o característica que necesite una aplicación.
Un servicio es típicamente una clase con un propósito limitado y bien definido.
Debe hacer algo específico y hacerlo bien.
Angular distinguishes components from services to increase modularity and reusability.
By separating a component's view-related functionality from other kinds of processing,
you can make your component classes lean and efficient.
Angular distingue los componentes de los servicios para aumentar la modularidad y la reutilización.
Al separar la funcionalidad relacionada con la vista de un componente de otros tipos de procesamiento, puedes hacer que tus componentes sean ágiles y eficientes.
Ideally, a component's job is to enable the user experience and nothing more.
A component should present properties and methods for data binding,
in order to mediate between the view (rendered by the template)
and the application logic (which often includes some notion of a*model*).
Idealmente, el trabajo de un componente es permitir la experiencia del usuario y nada más.
Un componente debe presentar propiedades y métodos para el enlace de datos,
para mediar entre la vista (representada por la plantilla)
y la lógica de la aplicación (que a menudo incluye alguna noción de*modelo *).
A component can delegate certain tasks to services, such as fetching data from the server,
validating user input, or logging directly to the console.
By defining such processing tasks in an *injectable service class*, you make those tasks
available to any component.
You can also make your app more adaptable by injecting different providers of the same kind of service,
as appropriate in different circumstances.
Un componente puede delegar ciertas tareas a los servicios, como obtener datos del servidor, validar la entrada del usuario o registrar información directamente en la consola.
Al definir tales tareas de procesamiento en una * clase de servicio inyectable *, hace que esas tareas sean disponibles para cualquier componente.
También puedes hacer que tu aplicación sea más adaptable inyectando diferentes proveedores del mismo tipo de servicio, según corresponda en diferentes circunstancias.
Angular doesn't *enforce* these principles. Angular does help you *follow* these principles
by making it easy to factor your application logic into services and make those services
available to components through *dependency injection*.
Angular no * impone * estos principios. Angular te ayuda a * seguir * estos principios
al facilitar la integración de la lógica de tu aplicación en los servicios y hacer que esos servicios sean disponibles para los componentes a través de * inyección de dependencia *.
## Service examples
## Ejemplos de servicios
Here's an example of a service class that logs to the browser console.
A continuación, se muestra un ejemplo de una clase de servicio que registra información en la consola del navegador.
Services can depend on other services. For example, here's a`HeroService`that depends on the`Logger` service, and also uses`BackendService`to get heroes. That service in turn might depend on the `HttpClient` service to fetch heroes asynchronously from a server.
Los servicios pueden depender de otros servicios. Por ejemplo, hay un`HeroService`que depende del`Logger` service, y también usa`BackendService`para obtener héroes. Ese servicio, a su vez, podría depender del servicio `HttpClient` para buscar héroes de forma asíncrona desde un servidor.
DI is wired into the Angular framework and used everywhere to provide new components with the services or other things they need.
Components consume services; that is, you can*inject*a service into a component, giving the component access to that service class.
Inyección de dependencia está conectado al framework de Angular y se usa en todas partes para proporcionar nuevos componentes con los servicios u otras cosas que necesitan.
Los componentes consumen servicios; es decir, puede*inyectar *un servicio en un componente, dándole acceso al componente a ese servicio.
To define a class as a service in Angular, use the`@Injectable()`decorator to provide the metadata that allows Angular to inject it into a component as a *dependency*.
Similarly, use the`@Injectable()`decorator to indicate that a component or other class (such as another service, a pipe, or an NgModule) *has* a dependency.
Para definir una clase como un servicio en Angular, usa el decorador`@Injectable()`para proporcionar los metadatos que le permitan a Angular inyectarlo en un componente como una *dependencia *.
De manera similar, usa el decorador`@Injectable()`para indicar que un componente u otra clase (como otro servicio, un pipeline o un NgModule) * tiene *una dependencia.
*The*injector*is the main mechanism. Angular creates an application-wide injector for you during the bootstrap process, and additional injectors as needed. You don't have to create injectors.
*El*inyector*es el mecanismo principal. Angular crea un inyector para toda la aplicación durante el proceso de arranque e inyectores adicionales según sea necesario. No es necesario crear inyectores.
*An injector creates dependencies, and maintains a*container* of dependency instances that it reuses if possible.
*Un inyector crea dependencias y mantiene un*contenedor * de instancias de dependencia que reutiliza si es posible.
*A*provider*is an object that tells an injector how to obtain or create a dependency.
*Un*proveedor *es un objeto que le dice a un inyector cómo obtener o crear una dependencia.
For any dependency that you need in your app, you must register a provider with the app's injector,
so that the injector can use the provider to create new instances.
For a service, the provider is typically the service class itself.
Para cualquier dependencia que necesites en tu aplicación, debes registrar un proveedor con el inyector de la aplicación, con el fin de que el inyector pueda utilizar el proveedor para crear nuevas instancias.
Para un servicio, el proveedor suele ser la propia clase de servicio.
<divclass="alert is-helpful">
A dependency doesn't have to be a service—it could be a function, for example, or a value.
Una dependencia no tiene que ser solamente un servicio—podría ser una función, por ejemplo, o un valor.
</div>
When Angular creates a new instance of a component class, it determines which services or other dependencies that component needs by looking at the constructor parameter types. For example, the constructor of`HeroListComponent` needs`HeroService`.
Cuando Angular crea una nueva instancia de una clase de componente, determina qué servicios u otras dependencias necesita ese componente al observar los tipos de parámetros del constructor. Por ejemplo, el constructor de`HeroListComponent` necesita`HeroService`.
When Angular discovers that a component depends on a service, it first checks if the injector has any existing instances of that service. If a requested service instance doesn't yet exist, the injector makes one using the registered provider, and adds it to the injector before returning the service to Angular.
Cuando Angular descubre que un componente depende de un servicio, primero verifica si el inyector tiene instancias existentes de ese servicio. Si una instancia de servicio solicitada aún no existe, el inyector crea una utilizando el proveedor registrado y la agrega al inyector antes de devolver el servicio a Angular.
When all requested services have been resolved and returned, Angular can call the component's constructor with those services as arguments.
Cuando todos los servicios solicitados se han resuelto y devuelto, Angular puede llamar al constructor del componente con esos servicios como argumentos.
The process of `HeroService` injection looks something like this.
El proceso de inyección de "HeroService" se parece a esto.
You must register at least one*provider* of any service you are going to use.
The provider can be part of the service's own metadata, making that service available everywhere,
or you can register providers with specific modules or components.
You register providers in the metadata of the service (in the `@Injectable()` decorator),
or in the `@NgModule()` or `@Component()` metadata
Deberías registrar al menos un*proveedor * de cualquier servicio que vayas a utilizar.
El proveedor puede formar parte de los propios metadatos del servicio, haciendo que ese servicio esté disponible en todas partes, o puede registrar proveedores con módulos o componentes específicos.
Debes registrar proveedores en los metadatos del servicio (en el decorador `@Injectable()`),
o en los metadatos `@NgModule()` o `@Component()`
*By default, the Angular CLI command [`ng generate service`](cli/generate) registers a provider with the root injector for your service by including provider metadata in the `@Injectable()` decorator. The tutorial uses this method to register the provider of HeroService class definition.
*Por defecto, el comando CLI de Angular [`ng generate service`](cli/generate) registra un proveedor con el inyector raíz para tu servicio al incluir metadatos del proveedor en el decorador `@Injectable()`. El tutorial utiliza este método para registrar el proveedor de la definición de clase HeroService.
```
@Injectable({
@ -90,12 +83,10 @@ or in the `@NgModule()` or `@Component()` metadata
})
```
When you provide the service at the root level, Angular creates a single, shared instance of `HeroService`
and injects it into any class that asks for it.
Registering the provider in the `@Injectable()` metadata also allows Angular to optimize an app
by removing the service from the compiled app if it isn't used.
Cuando proporcionas el servicio en el nivel raíz, Angular crea una instancia única compartida de `HeroService` y lo inyecta en cualquier clase que lo solicite.
El registro del proveedor en los metadatos `@Injectable()` también permite a Angular optimizar una aplicación eliminando el servicio de la aplicación compilada si no se utiliza.
* When you register a provider with a [specific NgModule](guide/architecture-modules), the same instance of a service is available to all components in that NgModule. To register at this level, use the `providers` property of the `@NgModule()` decorator.
* Cuando registras un proveedor con un [NgModule específico](guide/architecture-modules), la misma instancia de un servicio está disponible para todos los componentes en ese NgModule. Para registrar en este nivel, usa la propiedad `Provider` del decorador `@NgModule()`.
```
@NgModule({
@ -107,10 +98,10 @@ or in the `@NgModule()` or `@Component()` metadata
})
```
* When you register a provider at the component level, you get a new instance of the
service with each new instance of that component.
At the component level, register a service provider in the `providers` property of the `@Component()` metadata.
* Cuando registras un proveedor a nivel del componente, obtienes una nueva instancia del
servicio con cada nueva instancia de ese componente.
A nivel del componente, registra un proveedor de servicios en la propiedad `Providers` de los metadatos `@Component()`.
Angular is a platform and framework for building single-page client applications using HTML and TypeScript.
Angular is written in TypeScript.
It implements core and optional functionality as a set of TypeScript libraries that you import into your apps.
The architecture of an Angular application relies on certain fundamental concepts.
The basic building blocks are *NgModules*, which provide a compilation context for *components*. NgModules collect related code into functional sets; an Angular app is defined by a set of NgModules. An app always has at least a *root module* that enables bootstrapping, and typically has many more *feature modules*.
* Components define *views*, which are sets of screen elements that Angular can choose among and modify according to your program logic and data.
* Components use *services*, which provide specific functionality not directly related to views. Service providers can be *injected* into components as *dependencies*, making your code modular, reusable, and efficient.
Modules, components and services are classes that use *decorators*. These decorators mark their type and provide metadata that tells Angular how to use them.
* The metadata for a component class associates it with a *template* that defines a view. A template combines ordinary HTML with Angular *directives* and *binding markup* that allow Angular to modify the HTML before rendering it for display.
* The metadata for a service class provides the information Angular needs to make it available to components through *dependency injection (DI)*.
An app's components typically define many views, arranged hierarchically. Angular provides the `Router` service to help you define navigation paths among views. The router provides sophisticated in-browser navigational capabilities.
<divclass="alert is-helpful">
See the [Angular Glossary](guide/glossary) for basic definitions of important Angular terms and usage.
</div>
<divclass="alert is-helpful">
For the sample app that this page describes, see the <live-example></live-example>.
</div>
## Modules
Angular *NgModules* differ from and complement JavaScript (ES2015) modules. An NgModule declares a compilation context for a set of components that is dedicated to an application domain, a workflow, or a closely related set of capabilities. An NgModule can associate its components with related code, such as services, to form functional units.
Every Angular app has a *root module*, conventionally named `AppModule`, which provides the bootstrap mechanism that launches the application. An app typically contains many functional modules.
Like JavaScript modules, NgModules can import functionality from other NgModules, and allow their own functionality to be exported and used by other NgModules. For example, to use the router service in your app, you import the `Router` NgModule.
Organizing your code into distinct functional modules helps in managing development of complex applications, and in designing for reusability. In addition, this technique lets you take advantage of *lazy-loading*—that is, loading modules on demand—to minimize the amount of code that needs to be loaded at startup.
<divclass="alert is-helpful">
For a more detailed discussion, see [Introduction to modules](guide/architecture-modules).
</div>
## Components
Every Angular application has at least one component, the *root component* that connects a component hierarchy with the page document object model (DOM). Each component defines a class that contains application data and logic, and is associated with an HTML *template* that defines a view to be displayed in a target environment.
The `@Component()` decorator identifies the class immediately below it as a component, and provides the template and related component-specific metadata.
<divclass="alert is-helpful">
Decorators are functions that modify JavaScript classes. Angular defines a number of decorators that attach specific kinds of metadata to classes, so that the system knows what those classes mean and how they should work.
<ahref="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0">Learn more about decorators on the web.</a>
</div>
### Templates, directives, and data binding
A template combines HTML with Angular markup that can modify HTML elements before they are displayed.
Template *directives* provide program logic, and *binding markup* connects your application data and the DOM.
There are two types of data binding:
* *Event binding* lets your app respond to user input in the target environment by updating your application data.
* *Property binding* lets you interpolate values that are computed from your application data into the HTML.
Before a view is displayed, Angular evaluates the directives and resolves the binding syntax in the template to modify the HTML elements and the DOM, according to your program data and logic. Angular supports *two-way data binding*, meaning that changes in the DOM, such as user choices, are also reflected in your program data.
Your templates can use *pipes* to improve the user experience by transforming values for display.
For example, use pipes to display dates and currency values that are appropriate for a user's locale.
Angular provides predefined pipes for common transformations, and you can also define your own pipes.
<divclass="alert is-helpful">
For a more detailed discussion of these concepts, see [Introduction to components](guide/architecture-components).
</div>
{@a dependency-injection}
## Services and dependency injection
For data or logic that isn't associated with a specific view, and that you want to share across components, you create a *service* class. A service class definition is immediately preceded by the `@Injectable()` decorator. The decorator provides the metadata that allows other providers to be **injected** as dependencies into your class.
*Dependency injection* (DI) lets you keep your component classes lean and efficient. They don't fetch data from the server, validate user input, or log directly to the console; they delegate such tasks to services.
<divclass="alert is-helpful">
For a more detailed discussion, see [Introduction to services and DI](guide/architecture-services).
</div>
### Routing
The Angular `Router` NgModule provides a service that lets you define a navigation path among the different application states and view hierarchies in your app. It is modeled on the familiar browser navigation conventions:
* Enter a URL in the address bar and the browser navigates to a corresponding page.
* Click links on the page and the browser navigates to a new page.
* Click the browser's back and forward buttons and the browser navigates backward and forward through the history of pages you've seen.
The router maps URL-like paths to views instead of pages. When a user performs an action, such as clicking a link, that would load a new page in the browser, the router intercepts the browser's behavior, and shows or hides view hierarchies.
If the router determines that the current application state requires particular functionality, and the module that defines it hasn't been loaded, the router can *lazy-load* the module on demand.
The router interprets a link URL according to your app's view navigation rules and data state. You can navigate to new views when the user clicks a button or selects from a drop box, or in response to some other stimulus from any source. The router logs activity in the browser's history, so the back and forward buttons work as well.
To define navigation rules, you associate *navigation paths* with your components. A path uses a URL-like syntax that integrates your program data, in much the same way that template syntax integrates your views with your program data. You can then apply program logic to choose which views to show or to hide, in response to user input and your own access rules.
<divclass="alert is-helpful">
For a more detailed discussion, see [Routing and navigation](guide/router).
</div>
<hr/>
## What's next
You've learned the basics about the main building blocks of an Angular application. The following diagram shows how these basic pieces are related.
* [Introduction to services and dependency injection](guide/architecture-services)
When you're familiar with these fundamental building blocks, you can explore them in more detail in the documentation. To learn about more tools and techniques that are available to help you build and deploy Angular applications, see [Next steps: tools and techniques](guide/architecture-next-steps).
Angular is a platform and framework for building single-page client applications using HTML and TypeScript.
Angular is written in TypeScript.
It implements core and optional functionality as a set of TypeScript libraries that you import into your apps.
Angular es una plataforma y un framework para crear aplicaciones de una sola página en el lado del cliente usando HTML y TypeScript.
Angular está escrito en TypeScript.
Implementa la funcionalidad básica y opcional como un conjunto de bibliotecas TypeScript que importas en tus aplicaciones.
The architecture of an Angular application relies oncertain fundamental concepts.
The basic building blocks are *NgModules*, which provide a compilation context for*components*. NgModules collect related code into functional sets; an Angular app is defined by a set of NgModules. An app always has at least a *root module* that enables bootstrapping, and typically has many more *feature modules*.
La arquitectura de una aplicación en Angular se basa en ciertos conceptos fundamentales.
Los bloques de construcción básicos son los *NgModules*, que proporcionan un contexto de compilación para los*componentes*. Los NgModules recopilan código relacionado en conjuntos funcionales; una aplicación de Angular se define por un conjunto de NgModules. Una aplicación siempre tiene al menos un *módulo raíz* que permite el arranque y generalmente tiene muchos más *módulos de funcionalidad*.
*Components define *views*, which are sets of screen elements that Angular can choose among and modify according to your program logic and data.
*Los componentes definen*vistas*, que son conjuntos de elementos de la pantalla que Angular puede elegir y modificar de acuerdo con la lógica y los datos de tu programa.
*Components use*services*, which provide specific functionality not directly related to views. Service providers can be*injected* into components as*dependencies*, making your code modular, reusable, and efficient.
*Los componentes usan*servicios*, los cuales proporcionan una funcionalidad específica que no está directamente relacionada con las vistas. Los proveedores de servicios pueden*inyectarse* en componentes como*dependencias*, haciendo que tu código sea modular, reutilizable y eficiente.
Modules, components and services are classes that use*decorators*. These decorators mark their type and provide metadata that tells Angular how to use them.
Los módulos, componentes y servicios son clases que usan*decoradores*. Estos decoradores indican su tipo y proporcionan metadatos que le indican a Angular cómo usarlos.
*The metadata for a component class associates it with a *template* that defines a view. A template combines ordinary HTML with Angular*directives*and *binding markup* that allow Angular to modify the HTML before rendering it for display.
*Los metadatos para una clase componente son asociados con una *plantilla* que define una vista. Una plantilla combina HTML ordinario con*directivas*de Angular y *enlace markup* que permiten a Angular modificar el HTML antes de mostrarlo para su visualización.
*The metadata for a service class provides the information Angular needs to make it available to components through *dependency injection (DI)*.
*Los metadatos para una clase servicio proporcionan la información que Angular necesita para que esté disponible para los componentes a través de la *Inyección de Dependencia (ID)*.
An app's components typically define many views, arranged hierarchically. Angular provides the `Router` service to help you define navigation paths among views. The router provides sophisticated in-browser navigational capabilities.
Los componentes de una aplicación suelen definir muchas vistas, ordenadas jerárquicamente. Angular proporciona el servicio `Router` para ayudarte a definir rutas de navegación entre vistas. El enrutador proporciona capacidades de navegación sofisticadas en el navegador.
<divclass="alert is-helpful">
See the [Angular Glossary](guide/glossary) for basic definitions of important Angular terms and usage.
Visita el [Glosario de Angular](guide/glossary) para ver las definiciones básicas de términos importantes en Angular y su uso.
</div>
<divclass="alert is-helpful">
For the sample app that this page describes, see the<live-example></live-example>.
Para ver la aplicación de ejemplo que describe esta página, consulta el<live-example>ejemplo</live-example>.
</div>
## Modules
## Módulos
Angular*NgModules* differ from and complement JavaScript (ES2015) modules. An NgModule declares a compilation context for a set of components that is dedicated to an application domain, a workflow, or a closely related set of capabilities. An NgModule can associate its components with related code, such as services, to form functional units.
Los*NgModules* de Angular difieren y complementan los módulos JavaScript (ES2015). Un NgModule declara un contexto de compilación para un conjunto de componentes que está dedicado a un dominio de aplicación, un flujo de trabajo o un conjunto de capacidades estrechamente relacionadas. Un NgModule puede asociar sus componentes con código relacionado, como servicios, para formar unidades funcionales.
Every Angular app has a *root module*, conventionally named`AppModule`, which provides the bootstrap mechanism that launches the application. An app typically contains many functional modules.
Cada aplicación en Angular tiene un *módulo raíz*, convencionalmente nombrado`AppModule`, que proporciona el mecanismo de arranque que inicia la aplicación. Una aplicación generalmente contiene muchos módulos funcionales.
Like JavaScript modules, NgModules can import functionality from other NgModules, and allow their own functionality to be exported and used by other NgModules. For example, to use the router service in your app, you import the `Router` NgModule.
Como en los módulos de JavaScript, los NgModules pueden importar la funcionalidad de otros, y permiten que su propia funcionalidad sea exportada y utilizada por otros NgModules. Por ejemplo, para utilizar el servicio de enrutamiento en su aplicación, importa el NgModule `Router`.
Organizing your code into distinct functional modules helps in managing development of complex applications, and in designing for reusability. In addition, this technique lets you take advantage of *lazy-loading*—that is, loading modules on demand—to minimize the amount of code that needs to be loaded at startup.
Organizar tu código en distintos módulos funcionales ayuda a gestionar el desarrollo de aplicaciones complejas, y en el diseño para su reutilización. Además, esta técnica te permite aprovechar la *carga diferida*—es decir, cargar módulos bajo demanda—para minimizar la cantidad de código que debe cargarse al inicio.
<divclass="alert is-helpful">
For a more detailed discussion, see [Introduction to modules](guide/architecture-modules).
Para más información, visita [Introducción a los módulos](guide/architecture-modules).
</div>
## Components
## Componentes
Every Angular application has at least one component, the *root component* that connects a component hierarchy with the page document object model (DOM). Each component defines a class that contains application data and logic, and is associated with an HTML *template* that defines a view to be displayed in a target environment.
Cada aplicación de Angular tiene al menos un componente, el *componente raíz* que conecta una jerarquía de componentes con el modelo de objetos del documento de la página (DOM). Cada componente define una clase que contiene datos y lógica de la aplicación, y está asociado con una *plantilla* HTML que define una vista que se mostrará en un entorno de destino.
The`@Component()` decorator identifies the class immediately below it as a component, and provides the template and related component-specific metadata.
El decorador`@Component()` identifica la clase inmediatamente debajo de ella como un componente, y proporciona la plantilla y los metadatos específicos del componente relacionado.
<divclass="alert is-helpful">
Decorators are functions that modify JavaScript classes. Angular defines a number of decorators that attach specific kinds of metadata to classes, so that the system knows what those classes mean and how they should work.
Los decoradores son funciones que modifican las clases de JavaScript. Angular define una serie de decoradores que adjuntan tipos específicos de metadatos a las clases, para que el sistema sepa qué significan esas clases y cómo deberían funcionar.
<ahref="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0">Learn more about decorators on the web.</a>
<ahref="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841#.x5c2ndtx0">Obten más información sobre decoradores en la web.</a>
</div>
### Templates, directives, and data binding
### Plantillas, directivas y enlace de datos
A template combines HTML with Angular markup that can modify HTML elements before they are displayed.
Template*directives*provide program logic, and *binding markup* connects your application data and the DOM.
There are two types of data binding:
Una plantilla combina HTML con markup de Angular que puede modificar elementos HTML antes de que se muestren.
Las*directivas*de la plantilla proporcionan la lógica de programa y el *enlace markup* conecta los datos de tu aplicación y el DOM.
Hay dos tipos de enlace de datos:
* *Event binding* lets your app respond to user input in the target environment by updating your application data.
* *Property binding* lets you interpolate values that are computed from your application data into the HTML.
* *Manejador de eventos* permite que tu aplicación responda a la entrada del usuario en el entorno objetivo actualizando los datos de tu aplicación.
* *Vincular propiedades* te permite interpolar valores que se calculan a partir de los datos de tu aplicación en HTML.
Before a view is displayed, Angular evaluates the directives and resolves the binding syntax in the template to modify the HTML elements and the DOM, according to your program data and logic. Angular supports*two-way data binding*, meaning that changes in the DOM, such as user choices, are also reflected in your program data.
Antes de mostrar una vista, Angular evalúa las directivas y resuelve la sintaxis de enlace en la plantilla para modificar los elementos HTML y el DOM, de acuerdo con los datos y la lógica de tu programa. Angular soporta*enlace de datos en dos sentidos*, lo que significa que los cambios en el DOM, como las elecciones del usuario, también se reflejan en los datos de su programa.
Your templates can use*pipes*to improve the user experience by transforming values for display.
For example, use pipes to display dates and currency values that are appropriate for a user's locale.
Angular provides predefined pipes for common transformations, and you can also define your own pipes.
Tus plantillas pueden usar*pipes*para mejorar la experiencia del usuario mediante la transformación de valores para mostrar.
Por ejemplo, usa pipes para mostrar fechas y valores de moneda que sean apropiados para la configuración regional de un usuario.
Angular proporciona pipes predefinidas para transformaciones comunes, y también puedes definir tus propias pipes.
<divclass="alert is-helpful">
For a more detailed discussion of these concepts, see [Introduction to components](guide/architecture-components).
Para más información sobre estos conceptos, visita [Introducción a los componentes](guide/architecture-components).
</div>
{@a dependency-injection}
## Services and dependency injection
## Servicios e inyección de dependencia
For data or logic that isn't associated with a specific view, and that you want to share across components, you create a *service* class. A service class definition is immediately preceded by the`@Injectable()` decorator. The decorator provides the metadata that allows other providers to be**injected**as dependencies into your class.
Para los datos o la lógica que no están asociados con una vista específica y que deseas compartir entre componentes, crea una clase *servicio*. Una definición de clase servicio está inmediatamente precedida por el decorador`@Injectable()`. El decorador proporciona los metadatos que permiten**inyectar**otros proveedores como dependencias en su clase.
*Dependency injection* (DI) lets you keep your component classes lean and efficient. They don't fetch data from the server, validate user input, or log directly to the console; they delegate such tasks to services.
*Inyección de Dependecia* (ID) te permite mantener sus clases componente ligeras y eficientes. No obtienen datos del servidor, validan la entrada del usuario o registra directamente en la consola; tales tareas son delegadas a los servicios.
<divclass="alert is-helpful">
For a more detailed discussion, see [Introduction to services and DI](guide/architecture-services).
Para más información, visita [Introducción a los servicios e inyección de dependencia](guide/architecture-services).
</div>
### Routing
### Enrutamiento
The Angular`Router`NgModule provides a service that lets you define a navigation path among the different application states and view hierarchies in your app. It is modeled on the familiar browser navigation conventions:
El NgModule`Router`de Angular proporciona un servicio que te permite definir una ruta de navegación entre los diferentes estados de la aplicación y ver sus jerarquías. Se basa en las convenciones frecuentes de navegación del navegador:
*Enter a URL in the address bar and the browser navigates to a corresponding page.
*Ingresa una URL en la barra de direcciones para que el navegador vaya a la página correspondiente.
*Click links on the page and the browser navigates to a new page.
*Haz clic en los enlaces de la página para que el navegador vaya a una nueva página.
*Click the browser's back and forward buttons and the browser navigates backward and forward through the history of pages you've seen.
*Haz clic en los botones atrás y adelante del navegador para que el navegador vaya hacia atrás y hacia adelante a través del historial de las páginas que has visto.
The router maps URL-like paths to views instead of pages. When a user performs an action, such as clicking a link, that would load a new page in the browser, the router intercepts the browser's behavior, and shows or hides view hierarchies.
El enrutador mapea rutas similares a URL para las vistas en lugar de páginas. Cuando un usuario realiza una acción, como hacer clic en un enlace, que cargaría una nueva página en el navegador, el enrutador intercepta el comportamiento del navegador y muestra u oculta las jerarquías de vista.
If the router determines that the current application state requires particular functionality, and the module that defines it hasn't been loaded, the router can *lazy-load* the module on demand.
Si el enrutador determina que el estado actual de la aplicación requiere una funcionalidad particular, y el módulo que lo define no se ha cargado, el enrutador puede hacer *cargar diferida* sobre el módulo bajo demanda.
The router interprets a link URL according to your app's view navigation rules and data state. You can navigate to new views when the user clicks a button or selects from a drop box, or in response to some other stimulus from any source. The router logs activity in the browser's history, so the back and forward buttons work as well.
El enrutador interpreta una URL de enlace de acuerdo con las reglas de navegación de visualización de la aplicación y el estado de los datos. Puedes navegar a las nuevas vistas cuando el usuario hace clic en un botón o selecciona desde un cuadro desplegable, o en respuesta a algún otro estímulo de cualquier fuente. El enrutador registra la actividad en el historial del navegador, por lo que los botones de retroceso y avance también funcionan.
To define navigation rules, you associate*navigation paths* with your components. A path uses a URL-like syntax that integrates your program data, in much the same way that template syntax integrates your views with your program data. You can then apply program logic to choose which views to show or to hide, in response to user input and your own access rules.
Para definir reglas de navegación, asocia *rutas de navegación* a tus componentes. Una ruta utiliza una sintaxis similar a una URL que integra los datos de tu programa, de la misma manera que la sintaxis de la plantilla integra tus vistas con los datos de tu programa. Luego puedes aplicar la lógica del programa para elegir qué vistas mostrar u ocultar, en respuesta a la entrada del usuario y a tus propias reglas de acceso.
<divclass="alert is-helpful">
For a more detailed discussion, see [Routing and navigation](guide/router).
Para más información, visita [Enrutamiento y navegación](guide/router).
</div>
<hr/>
## What's next
## ¿Qué sigue?
You've learned the basics about the main building blocks of an Angular application. The following diagram shows how these basic pieces are related.
Has aprendido los conceptos básicos sobre los bloques de construcción de una aplicación en Angular. El siguiente diagrama muestra cómo se relacionan estos conceptos básicos.
* [Introduction to services and dependency injection](guide/architecture-services)
* [Introducción a los Servicios e Inyección de Dependencias.](guide/architecture-services)
When you're familiar with these fundamental building blocks, you can explore them in more detail in the documentation. To learn about more tools and techniques that are available to help you build and deploy Angular applications, see [Next steps: tools and techniques](guide/architecture-next-steps).
Cuando estés familiarizado con estos bloques de construcción fundamentales, podrás explorarlos con más detalle en la documentación. Para saber más acerca de las herramientas y técnicas disponibles para ayudarte a crear y desplegar aplicaciones de Angular, visita [Próximos pasos: herramientas y técnicas](guide/architecture-next-steps).
The template syntax provides specialized one-way bindings for scenarios less well-suited to property binding.
<divclass="alert is-helpful">
See the <live-example></live-example> for a working example containing the code snippets in this guide.
</div>
## Attribute binding
Set the value of an attribute directly with an **attribute binding**. This is the only exception to the rule that a binding sets a target property and the only binding that creates and sets an attribute.
Usually, setting an element property with a [property binding](guide/property-binding)
is preferable to setting the attribute with a string. However, sometimes
there is no element property to bind, so attribute binding is the solution.
Consider the [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) and
[SVG](https://developer.mozilla.org/en-US/docs/Web/SVG). They are purely attributes, don't correspond to element properties, and don't set element properties. In these cases, there are no property targets to bind to.
Attribute binding syntax resembles property binding, but
instead of an element property between brackets, start with the prefix `attr`,
followed by a dot (`.`), and the name of the attribute.
You then set the attribute value, using an expression that resolves to a string,
or remove the attribute when the expression resolves to `null`.
One of the primary use cases for attribute binding
Here's how to set the `class` attribute without a binding in plain HTML:
```html
<!-- standard class attribute setting -->
<divclass="foo bar">Some text</div>
```
You can also add and remove CSS class names from an element's `class` attribute with a **class binding**.
To create a single class binding, start with the prefix `class` followed by a dot (`.`) and the name of the CSS class (for example, `[class.foo]="hasFoo"`).
Angular adds the class when the bound expression is truthy, and it removes the class when the expression is falsy (with the exception of `undefined`, see [styling delegation](#styling-delegation)).
To create a binding to multiple classes, use a generic `[class]` binding without the dot (for example, `[class]="classExpr"`).
The expression can be a space-delimited string of class names, or you can format it as an object with class names as the keys and truthy/falsy expressions as the values.
With object format, Angular will add a class only if its associated value is truthy.
It's important to note that with any object-like expression (`object`, `Array`, `Map`, `Set`, etc), the identity of the object must change for the class list to be updated.
Updating the property without changing object identity will have no effect.
If there are multiple bindings to the same class name, conflicts are resolved using [styling precedence](#styling-precedence).
The [NgClass](guide/built-in-directives/#ngclass) directive can be used as an alternative to direct `[class]` bindings.
However, using the above class binding syntax without `NgClass` is preferred because due to improvements in class binding in Angular, `NgClass` no longer provides significant value, and might eventually be removed in the future.
<hr/>
## Style binding
Here's how to set the `style` attribute without a binding in plain HTML:
```html
<!-- standard style attribute setting -->
<divstyle="color: blue">Some text</div>
```
You can also set styles dynamically with a **style binding**.
To create a single style binding, start with the prefix `style` followed by a dot (`.`) and the name of the CSS style property (for example, `[style.width]="width"`).
The property will be set to the value of the bound expression, which is normally a string.
Optionally, you can add a unit extension like `em` or `%`, which requires a number type.
<divclass="alert is-helpful">
Note that a _style property_ name can be written in either
[dash-case](guide/glossary#dash-case), as shown above, or
[camelCase](guide/glossary#camelcase), such as `fontSize`.
</div>
If there are multiple styles you'd like to toggle, you can bind to the `[style]` property directly without the dot (for example, `[style]="styleExpr"`).
The expression attached to the `[style]` binding is most often a string list of styles like `"width: 100px; height: 100px;"`.
You can also format the expression as an object with style names as the keys and style values as the values, like `{width: '100px', height: '100px'}`.
It's important to note that with any object-like expression (`object`, `Array`, `Map`, `Set`, etc), the identity of the object must change for the class list to be updated.
Updating the property without changing object identity will have no effect.
If there are multiple bindings to the same style property, conflicts are resolved using [styling precedence rules](#styling-precedence).
The [NgStyle](guide/built-in-directives/#ngstyle) directive can be used as an alternative to direct `[style]` bindings.
However, using the above style binding syntax without `NgStyle` is preferred because due to improvements in style binding in Angular, `NgStyle` no longer provides significant value, and might eventually be removed in the future.
<hr/>
{@a styling-precedence}
## Styling Precedence
A single HTML element can have its CSS class list and style values bound to multiple sources (for example, host bindings from multiple directives).
When there are multiple bindings to the same class name or style property, Angular uses a set of precedence rules to resolve conflicts and determine which classes or styles are ultimately applied to the element.
<divclass="alert is-helpful">
<h4>Styling precedence (highest to lowest)</h4>
1. Template bindings
1. Property binding (for example, `<div [class.foo]="hasFoo">` or `<div [style.color]="color">`)
1. Map binding (for example, `<div [class]="classExpr">` or `<div [style]="styleExpr">`)
1. Static value (for example, `<div class="foo">` or `<div style="color: blue">`)
1. Directive host bindings
1. Property binding (for example, `host: {'[class.foo]': 'hasFoo'}` or `host: {'[style.color]': 'color'}`)
1. Map binding (for example, `host: {'[class]': 'classExpr'}` or `host: {'[style]': 'styleExpr'}`)
1. Static value (for example, `host: {'class': 'foo'}` or `host: {'style': 'color: blue'}`)
1. Component host bindings
1. Property binding (for example, `host: {'[class.foo]': 'hasFoo'}` or `host: {'[style.color]': 'color'}`)
1. Map binding (for example, `host: {'[class]': 'classExpr'}` or `host: {'[style]': 'styleExpr'}`)
1. Static value (for example, `host: {'class': 'foo'}` or `host: {'style': 'color: blue'}`)
</div>
The more specific a class or style binding is, the higher its precedence.
A binding to a specific class (for example, `[class.foo]`) will take precedence over a generic `[class]` binding, and a binding to a specific style (for example, `[style.bar]`) will take precedence over a generic `[style]` binding.
Specificity rules also apply when it comes to bindings that originate from different sources.
It's possible for an element to have bindings in the template where it's declared, from host bindings on matched directives, and from host bindings on matched components.
Template bindings are the most specific because they apply to the element directly and exclusively, so they have the highest precedence.
Directive host bindings are considered less specific because directives can be used in multiple locations, so they have a lower precedence than template bindings.
Directives often augment component behavior, so host bindings from components have the lowest precedence.
It is possible for higher precedence styles to "delegate" to lower precedence styles using `undefined` values.
Whereas setting a style property to `null` ensures the style is removed, setting it to `undefined` will cause Angular to fall back to the next-highest precedence binding to that style.
Imagine that the `dirWithHostBinding` directive and the `comp-with-host-binding` component both have a `[style.width]` host binding.
In that case, if `dirWithHostBinding` sets its binding to `undefined`, the `width` property will fall back to the value of the `comp-with-host-binding` host binding.
However, if `dirWithHostBinding` sets its binding to `null`, the `width` property will be removed entirely.
The template syntax provides specialized one-way bindings for scenarios less well-suited to property binding.
La sintaxis de la plantilla proporciona enlaces one-way especializados para escenarios menos adecuados para el enlace de propiedades.
<divclass="alert is-helpful">
See the<live-example></live-example>for a working example containing the code snippets in this guide.
Consulta el<live-example></live-example>para ver un ejemplo práctico que contiene los fragmentos de código de esta guía.
</div>
## Attribute binding
## Enlace de atributo
Set the value of an attribute directly with an **attribute binding**. This is the only exception to the rule that a binding sets a target property and the only binding that creates and sets an attribute.
Establece el valor de un atributo directamente con un **enlace de atributo**. Esta es la única excepción a la regla de que un enlace establece una propiedad de destino y el único enlace que crea y establece un atributo.
Usually, setting an element property with a [property binding](guide/property-binding)
is preferable to setting the attribute with a string. However, sometimes
there is no element property to bind, so attribute binding is the solution.
Por lo general, establecer una propiedad de elemento con un [enlace de propiedad](guide/property-binding) es preferible establecer el atributo con una string. Sin embargo, a veces
no hay ninguna propiedad de elemento para vincular, por lo que la vinculación de atributos es la solución.
Consider the [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) and
[SVG](https://developer.mozilla.org/en-US/docs/Web/SVG). They are purely attributes, don't correspond to element properties, and don't set element properties. In these cases, there are no property targets to bind to.
Considera el [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) y
[SVG](https://developer.mozilla.org/en-US/docs/Web/SVG). Son puramente atributos, no corresponden a las propiedades del elemento y no establecen las propiedades del elemento. En estos casos, no hay objetivos de propiedad a los que vincularse.
Attribute binding syntax resembles property binding, but
instead of an element property between brackets, start with the prefix `attr`,
followed by a dot (`.`), and the name of the attribute.
You then set the attribute value, using an expression that resolves to a string,
or remove the attribute when the expression resolves to `null`.
La sintaxis de enlace de atributo se parece al enlace de propiedad, pero en lugar de una propiedad de elemento entre paréntesis, comienza con el prefijo `attr`, seguido de un punto (`.`) y el nombre del atributo.
Luego establece el valor del atributo, utilizando una expresión que se resuelve en una string, o elimina el atributo cuando la expresión se resuelva en `null`.
One of the primary use cases for attribute binding
is to set ARIA attributes, as in this example:
Uno de los casos de uso principales para el enlace de atributos es establecer atributos ARIA, como en este ejemplo:
Can't bind to 'colspan' since it isn't a known native property
</code-example>
As the message says, the `<td>` element does not have a `colspan` property. This is true
because `colspan`is an attribute—`colSpan`, with a capital `S`, is the
corresponding property. Interpolation and property binding can set only *properties*, not attributes.
Como dice el mensaje, el elemento `<td>` no tiene una propiedad `colspan`. Esto es verdad
porque `colspan`es un atributo—`colSpan`, con una `S` mayúscula, es la propiedad correspondiente. La interpolación y el enlace de propiedades solo pueden establecer *propiedades*, no atributos.
Instead, you'd use property binding and write it like this:
En su lugar, puedes usar el enlace de propiedad y lo escribirías así:
@ -66,28 +60,28 @@ Instead, you'd use property binding and write it like this:
{@a class-binding}
## Class binding
## Enlace de clase
Here's how to set the `class` attribute without a binding in plain HTML:
Aquí se explica cómo configurar el atributo `class` sin un enlace en HTML simple:
```html
<!-- standard class attribute setting -->
<divclass="foo bar">Some text</div>
<divclass="foo bar">Algún texto</div>
```
You can also add and remove CSS class names from an element's `class` attribute with a **class binding**.
También puedes agregar y eliminar nombres de clase CSS del atributo `class` de un elemento con un **enlace de clase**.
To create a single class binding, start with the prefix`class`followed by a dot (`.`) and the name of the CSS class (for example, `[class.foo]="hasFoo"`).
Angular adds the class when the bound expression is truthy, and it removes the class when the expression is falsy (with the exception of `undefined`, see [styling delegation](#styling-delegation)).
Para crear un enlace de clase único, comienza con el prefijo`class`seguido de un punto (`.`) y el nombre de la clase CSS (por ejemplo, `[class.foo]="hasFoo"`).
Angular agrega la clase cuando la expresión enlazada es verdadera y elimina la clase cuando la expresión es falsa (con la excepción de `undefined`, vea [delegación de estilo](#styling-delegation)).
To create a binding to multiple classes, use a generic `[class]`binding without the dot (for example, `[class]="classExpr"`).
The expression can be a space-delimited string of class names, or you can format it as an object with class names as the keys and truthy/falsy expressions as the values.
With object format, Angular will add a class only if its associated value is truthy.
Para crear un enlace a varias clases, usa un enlace genérico`[class]`sin el punto (por ejemplo, `[class]="classExpr"`).
La expresión puede ser una string de nombres de clase delimitada por espacios, o puede formatearla como un objeto con nombres de clase como claves y expresiones de verdad / falsedad como valores.
Con el formato de objeto, Angular agregará una clase solo si su valor asociado es verdadero.
It's important to note that with any object-like expression (`object`,`Array`, `Map`, `Set`, etc), the identity of the object must change for the class list to be updated.
Updating the property without changing object identity will have no effect.
Es importante tener en cuenta que con cualquier expresión similar a un objeto (`object`,`Array`, `Map`, `Set`, etc.), la identidad del objeto debe cambiar para que se actualice la lista de clases.
Actualizar la propiedad sin cambiar la identidad del objeto no tendrá ningún efecto.
If there are multiple bindings to the same class name, conflicts are resolved using [styling precedence](#styling-precedence).
Si hay varios enlaces al mismo nombre de clase, los conflictos se resuelven usando [precedencia de estilo](#styling-precedence).
<style>
td,th{vertical-align:top}
@ -104,26 +98,26 @@ If there are multiple bindings to the same class name, conflicts are resolved us
@ -139,43 +133,43 @@ If there are multiple bindings to the same class name, conflicts are resolved us
</table>
The [NgClass](guide/built-in-directives/#ngclass) directive can be used as an alternative to direct `[class]` bindings.
However, using the above class binding syntax without `NgClass` is preferred because due to improvements in class binding in Angular, `NgClass` no longer provides significant value, and might eventually be removed in the future.
La directiva [NgClass](guide/built-in-directives/#ngclass) se puede utilizar como alternativa a los enlaces directos`[class]`.
Sin embargo, se prefiere usar la sintaxis de enlace de clase anterior sin `NgClass` porque debido a las mejoras en el enlace de clase en Angular, `NgClass` ya no proporciona un valor significativo y podría eliminarse en el futuro.
<hr/>
## Stylebinding
{@a style-binding}
Here's how to set the `style` attribute without a binding in plain HTML:
## Enlace de estilo
Aquí se explica cómo configurar el atributo `style` sin un enlace en HTML simple:
```html
<!-- standard style attribute setting -->
<divstyle="color: blue">Some text</div>
<divstyle="color: blue">Algún texto</div>
```
You can also set styles dynamically with a **style binding**.
También se puede establecer estilos dinámicamente con un **enlace de estilo**.
To create a single style binding, start with the prefix`style`followed by a dot (`.`) and the name of the CSS style property (for example, `[style.width]="width"`).
The property will be set to the value of the bound expression, which is normally a string.
Optionally, you can add a unit extension like`em` or`%`, which requires a number type.
Para crear un enlace de estilo único, comienza con el prefijo`style`seguido de un punto (`.`) y el nombre de la propiedad de estilo CSS (por ejemplo, `[style.width]="width"`).
La propiedad se establecerá en el valor de la expresión enlazada, que normalmente es una string.
Opcionalmente, se puede agregar una extensión de unidad como`em` o `%`, que requiere un tipo de número.
<divclass="alert is-helpful">
Note that a _style property_ name can be written in either
[dash-case](guide/glossary#dash-case), as shown above, or
[camelCase](guide/glossary#camelcase), such as `fontSize`.
Ten en cuenta que se puede escribir una _propiedad de estilo_ en [dash-case](guide/glossary#dash-case), como se muestra arriba, o [camelCase](guide/glossary#camelcase), como `fontSize`.
</div>
If there are multiple styles you'd like to toggle, you can bind to the `[style]` property directly without the dot (for example,`[style]="styleExpr"`).
The expression attached to the `[style]` binding is most often a string list of styles like`"width: 100px; height: 100px;"`.
Si deseas alternar múltiples estilos, puedes vincular la propiedad `[style]` directamente sin el punto (por ejemplo, `[style]="styleExpr"`).
La expresión asociada al enlace `[style]` suele ser una lista de string de estilos como`"width: 100px; height: 100px;"`.
You can also format the expression as an object with style names as the keys and style values as the values, like`{width: '100px', height: '100px'}`.
It's important to note that with any object-like expression (`object`, `Array`, `Map`, `Set`, etc), the identity of the object must change for the class list to be updated.
Updating the property without changing object identity will have no effect.
También se puede formatear la expresión como un objeto con nombres de estilo como claves y valores de estilo como los valores, como`{width: '100px', height: '100px'}`.
Es importante tener en cuenta que con cualquier expresión similar a un objeto (`object`, `Array`, `Map`, `Set`, etc), la identidad del objeto debe cambiar para que se actualice la lista de clases.
Actualizar la propiedad sin cambiar la identidad del objeto no tendrá ningún efecto.
If there are multiple bindings to the same style property, conflicts are resolved using [styling precedence rules](#styling-precedence).
Si hay varios enlaces a la misma propiedad de estilo, los conflictos se resuelven usando [reglas de precedencia de estilo](#styling-precedence).
<style>
td,th{vertical-align:top}
@ -192,33 +186,33 @@ If there are multiple bindings to the same style property, conflicts are resolve
@ -233,71 +227,71 @@ If there are multiple bindings to the same style property, conflicts are resolve
</tr>
</table>
The [NgStyle](guide/built-in-directives/#ngstyle) directive can be used as an alternative to direct `[style]` bindings.
However, using the above style binding syntax without `NgStyle` is preferred because due to improvements in style binding in Angular, `NgStyle` no longer provides significant value, and might eventually be removed in the future.
La directiva [NgStyle](guide/built-in-directives/#ngstyle) se puede utilizar como alternativa a los enlaces directos`[style]`.
Sin embargo, se prefiere usar la sintaxis de enlace de estilos anterior sin `NgStyle` porque debido a las mejoras en el enlace de estilos en Angular, `NgStyle` ya no proporciona un valor significativo y podría eliminarse en el futuro.
<hr/>
{@a styling-precedence}
## Styling Precedence
## Precedencia de estilo
A single HTML element can have its CSS class list and style values bound to multiple sources (for example, host bindings from multiple directives).
Un único elemento HTML puede tener su lista de clases CSS y valores de estilo vinculados a múltiples fuentes (por ejemplo, enlaces de host de múltiples directivas).
When there are multiple bindings to the same class name or style property, Angular uses a set of precedence rules to resolve conflicts and determine which classes or styles are ultimately applied to the element.
Cuando hay varios enlaces al mismo nombre de clase o propiedad de estilo, Angular usa un conjunto de reglas de precedencia para resolver conflictos y determinar qué clases o estilos se aplican finalmente al elemento.
<divclass="alert is-helpful">
<h4>Styling precedence (highest to lowest)</h4>
<h4>Precedencia de estilo (de mayor a menor)</h4>
1.Template bindings
1.Property binding (for example, `<div [class.foo]="hasFoo">` or`<div [style.color]="color">`)
1.Map binding (for example, `<div [class]="classExpr">` or`<div [style]="styleExpr">`)
1.Static value (for example, `<div class="foo">` or`<div style="color: blue">`)
1.Directive host bindings
1.Property binding (for example, `host: {'[class.foo]': 'hasFoo'}` or`host: {'[style.color]': 'color'}`)
1.Map binding (for example, `host: {'[class]': 'classExpr'}` or`host: {'[style]': 'styleExpr'}`)
1.Static value (for example, `host: {'class': 'foo'}` or`host: {'style': 'color: blue'}`)
1.Component host bindings
1.Property binding (for example, `host: {'[class.foo]': 'hasFoo'}` or`host: {'[style.color]': 'color'}`)
1.Map binding (for example, `host: {'[class]': 'classExpr'}` or`host: {'[style]': 'styleExpr'}`)
1.Static value (for example, `host: {'class': 'foo'}` or`host: {'style': 'color: blue'}`)
1.Enlaces de plantillas
1.Enlace de propiedad (por ejemplo, `<div [class.foo]="hasFoo">` o `<div [style.color]="color">`)
1.Enlace de mapa (por ejemplo, `<div [class]="classExpr">` o `<div [style]="styleExpr">`)
1.Valor estático (por ejemplo, `<div class="foo">` o `<div style="color: blue">`)
1.Enlaces de directivas hosts
1.Enlace de propiedad (por ejemplo, `host: {'[class.foo]': 'hasFoo'}` o `host: {'[style.color]': 'color'}`)
1.Enlace de mapa (por ejemplo, `host: {'[class]': 'classExpr'}` o `host: {'[style]': 'styleExpr'}`)
The more specific a class or style binding is, the higher its precedence.
Cuanto más específico sea un enlace de clase o estilo, mayor será su precedencia.
A binding to a specific class (for example, `[class.foo]`) will take precedence over a generic `[class]` binding, and a binding to a specific style (for example, `[style.bar]`) will take precedence over a generic `[style]` binding.
Un enlace a una clase específica (por ejemplo, `[class.foo]`) tendrá prioridad sobre un enlace genérico`[class]`, y un enlace a un estilo específico (por ejemplo, `[style.bar]`) tendrá prioridad sobre un enlace genérico`[style]`.
Specificity rules also apply when it comes to bindings that originate from different sources.
It's possible for an element to have bindings in the template where it's declared, from host bindings on matched directives, and from host bindings on matched components.
Las reglas de especificidad también se aplican cuando se trata de enlaces que se originan de diferentes fuentes.
Es posible que un elemento tenga enlaces en la plantilla donde se declara, desde enlaces de host en directivas coincidentes y desde enlaces de host en componentes coincidentes.
Template bindings are the most specific because they apply to the element directly and exclusively, so they have the highest precedence.
Los enlaces de plantilla son los más específicos porque se aplican al elemento directa y exclusivamente, por lo que tienen la mayor prioridad.
Directive host bindings are considered less specific because directives can be used in multiple locations, so they have a lower precedence than template bindings.
Los enlaces de host de directiva se consideran menos específicos porque las directivas se pueden usar en varias ubicaciones, por lo que tienen una precedencia menor que los enlaces de plantilla.
Directives often augment component behavior, so host bindings from components have the lowest precedence.
Las directivas a menudo aumentan el comportamiento de los componentes, por lo que los enlaces de host de los componentes tienen la prioridad más baja.
It is possible for higher precedence styles to "delegate" to lower precedence styles using`undefined` values.
Whereas setting a style property to `null` ensures the style is removed, setting it to`undefined`will cause Angular to fall back to the next-highest precedence binding to that style.
Es posible que los estilos de precedencia más alta "deleguen" a los estilos de precedencia más bajos utilizando valores`undefined`.
Mientras que establecer una propiedad de estilo en `null` asegura que el estilo se elimine, establecerlo en`undefined`hará que Angular vuelva al siguiente enlace de precedencia más alto para ese estilo.
Imagine that the`dirWithHostBinding`directive and the `comp-with-host-binding`component both have a`[style.width]` host binding.
In that case, if`dirWithHostBinding`sets its binding to `undefined`, the `width` property will fall back to the value of the `comp-with-host-binding` host binding.
However, if`dirWithHostBinding`sets its binding to `null`, the `width` property will be removed entirely.
Imagina que la directiva`dirWithHostBinding` y el componente `comp-with-host-binding` tienen un enlace de host`[style.width]`.
En ese caso, si `dirWithHostBinding`establece su enlace en `undefined`, la propiedad `width` volverá al valor del enlace de host del componente `comp-with-host-binding`.
Sin embargo, si`dirWithHostBinding`establece su enlace en `null`, la propiedad `width` se eliminará por completo.
Now you could use your `ItemDirective` in a component. This example uses `AppModule`, but you'd do it the same way for a feature module. For more about directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives). You'd also use the same technique for [pipes](guide/pipes) and components.
Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean.
{@a imports}
## The `imports` array
The module's `imports` array appears exclusively in the `@NgModule` metadata object.
It tells Angular about other NgModules that this particular module needs to function properly.
This list of modules are those that export components, directives, or pipes
that the component templates in this module reference. In this case, the component is
`AppComponent`, which references components, directives, or pipes in `BrowserModule`,
`FormsModule`, or `HttpClientModule`.
A component template can reference another component, directive,
or pipe when the referenced class is declared in this module or
the class was imported from another module.
{@a bootstrap-array}
## The `providers` array
The providers array is where you list the services the app needs. When
you list services here, they are available app-wide. You can scope
them when using feature modules and lazy loading. For more information, see
[Providers](guide/providers).
## The `bootstrap` array
The application launches by bootstrapping the root `AppModule`, which is
also referred to as an `entryComponent`.
Among other things, the bootstrapping process creates the component(s) listed in the `bootstrap` array
and inserts each one into the browser DOM.
Each bootstrapped component is the base of its own tree of components.
Inserting a bootstrapped component usually triggers a cascade of
component creations that fill out that tree.
While you can put more than one component tree on a host web page,
most applications have only one component tree and bootstrap a single root component.
This one root component is usually called `AppComponent` and is in the
root module's `bootstrap` array.
## More about Angular Modules
For more on NgModules you're likely to see frequently in apps,
see [Frequently Used Modules](guide/frequent-ngmodules).
Now you could use your`ItemDirective`in a component. This example uses`AppModule`, but you'd do it the same way for a feature module. For more about directives, see [Attribute Directives](guide/attribute-directives) and [Structural Directives](guide/structural-directives). You'd also use the same technique for [pipes](guide/pipes) and components.
Ahora puedes usar tu`ItemDirective`en un componente. Este ejemplo usa`AppModule`, pero se haría de la misma manera para un módulo de funciones. Para obtener más información sobre las directivas, consulta [Directivas de atributos](guide/attribute-directives) y [Directivas estructurales](guide/structural-directives). También se usaría la misma técnica para [pipes](guide/pipes) y componentes.
Recuerda, los componentes, directivas y pipes pertenecen a un solo módulo. Solo se necesita declararlos una vez en tu aplicación porque se comparten importando los módulos necesarios. Esto ahorra tiempo y ayuda a mantener la aplicación optimizada.
Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean.
{@a imports}
## The `imports` array
The module's `imports` array appears exclusively in the `@NgModule` metadata object.
It tells Angular about other NgModules that this particular module needs to function properly.
<code-example
path="bootstrapping/src/app/app.module.ts"
region="imports"
header="src/app/app.module.ts (excerpt)">
</code-example>
This list of modules are those that export components, directives, or pipes
that component templates in this module reference. In this case, the component is
`AppComponent`, which references components, directives, or pipes in `BrowserModule`,
`FormsModule`, or `HttpClientModule`.
A component template can reference another component, directive,
or pipe when the referenced class is declared in this module or
the class was imported from another module.
## El array de `imports`
El array de `imports` del módulo aparece exclusivamente en el objeto de metadatos del `@NgModule`.
Le dice a Angular sobre otros NgModules que este módulo en particular necesita para funcionar correctamente.
Esta lista de módulos son los que exportan componentes, directivas o pipes
que las plantillas de componentes en este módulo hacen referencia. En este caso, el componente es
`AppComponent`, que hace referencia a componentes, directivas o pipes en `BrowserModule`,
`FormsModule`, o `HttpClientModule`.
Una plantilla de componente puede hacer referencia a otro componente, directiva,
o pipe cuando la clase referenciada se declara en este módulo o
la clase se importó de otro módulo.
{@a bootstrap-array}
## The `providers` array
## El array `providers`
The providers array is where you list the services the app needs. When
you list services here, they are available app-wide. You can scope
them when using feature modules and lazy loading. For more information, see
[Providers](guide/providers).
El array `providers` es donde se enumeran los servicios que necesita la aplicación. Cuando
enumera los servicios, están disponibles en toda la aplicación. Puedes reducir el scope
al usar módulos de funciones y carga diferida. Para más información, ver
[Proveedores](guide/providers).
## The `bootstrap` array
## El array `bootstrap`
The application launches by bootstrapping the root`AppModule`, which is
also referred to as an`entryComponent`.
Among other things, the bootstrapping process creates the component(s) listed in the `bootstrap` array
and inserts each one into the browser DOM.
La aplicación se inicia haciendo bootstraping desde la raíz`AppModule`, que es
también conocido como`entryComponent`.
Entre otras cosas, el proceso de carga crea los componentes enumerados en el array de `bootstrap`
e inserta cada uno en el DOM del navegador.
Each bootstrapped component is the base of its own tree of components.
Inserting a bootstrapped component usually triggers a cascade of
component creations that fill out that tree.
Cada componente bootstrap es la base de su propio árbol de componentes.
La inserción de un componente bootstrapped generalmente desencadena una cascada de
creaciones de componentes que completan ese árbol.
While you can put more than one component tree on a host web page,
most applications have only one component tree and bootstrap a single root component.
Si bien puedes colocar más de un árbol de componentes en una página web de host,
la mayoría de las aplicaciones tienen solo un árbol de componentes y arrancan un solo componente raíz.
This one root component is usually called `AppComponent` and is in the
root module's`bootstrap`array.
Este componente raíz se suele llamar `AppComponent` y se encuentra en el
array`bootstrap`del módulo raíz.
## Más sobre módulos Angular
## More about Angular Modules
For more on NgModules you're likely to see frequently in apps,
see [Frequently Used Modules](guide/frequent-ngmodules).
Para obtener más información sobre NgModules que probablemente veas con frecuencia en las aplicaciones,
consulta [Módulos de uso frecuente](guide/frequent-ngmodules).
<td><p>List of dependency injection providers visible both to the contents of this module and to importers of this module.</p>
<td><p>Lista de proveedores de inyección de dependencias visibles tanto para los contenidos de este módulo como para los importadores de este módulo.</p>
<td><p>Binds style property<code>width</code>to the result of expression <code>mySize</code>in pixels. Units are optional.</p>
<td><p>Vincula la propiedad de estilo<code>width</code>al resultado de la expresión <code>mySize</code>en píxeles. La unidad de medida es opcional.</p>
<td><p>Calls method <code>readRainbow</code>when a click event is triggered on this button element (or its children) and passes in the event object.</p>
<td><p>Llama al método<code>readRainbow</code>cuando se lanza un evento click en este elemento botón (o sus hijos) y pasa por argumento el objeto evento.</p>
<td><p>Creates a local variable <code>movieplayer</code>that provides access to the<code>video</code> element instance in data-binding and event-binding expressions in the current template.</p>
<td><p>Crea una variable local <code>movieplayer</code>que provee acceso a la instancia del elemento<code>video</code> en las expresiones de data-binding y event-binding de la actual plantilla.</p>
<td><p>The safe navigation operator (<code>?</code>) means that the<code>employer</code>field is optional and if<code>undefined</code>, the rest of the expression should be ignored.</p>
<td><p>El operador de navegación seguro (<code>?</code>) significa que el campo<code>employer</code>es opcional y que si es<code>undefined</code>, el resto de la expresión debería ser ignorado.</p>
<td><p>An SVG snippet template needs an <code>svg:</code> prefix on its root element to disambiguate the SVG element from an HTML component.</p>
<td><p>Una plantilla de fragmento SVG necesita un prefijo <code>svg:</code> en su elemento raíz para distinguir el elemento SVG de un componente HTML.</p>
<td><p>Conditionally swaps the contents of the div by selecting one of the embedded templates based on the current value of<code>conditionExpression</code>.</p>
<td><p>Intercambia condicionalmente el contenido del div seleccionando una de las plantillas incrustadas en función del valor actual de<code>conditionExpression</code>.</p>
<td><p>Binds the presence of CSS classes on the element to the truthiness of the associated map values. The right-hand expression should return {class-name: true/false} map.</p>
<td><p>Vincula la presencia de clases CSS en el elemento a la veracidad de los valores de mapa asociados. La expresión de la derecha debería devolver el mapa {class-name: true/false}.</p>
<td><p>Allows you to assign styles to an HTML element using CSS. You can use CSS directly, as in the first example, or you can call a method from the component.</p>
<p>Te permite asignar estilos a un elemento HTML usando CSS. Puedes usar CSS directamente, como en el primer ejemplo, o puedes llamar a un método desde el componente.</p>
</td>
</tr>
</tbody></table>
<tableclass="is-full-width is-fixed-layout">
<tbody><tr>
<th>Forms</th>
<th>Formularios</th>
<th><p><code>import { FormsModule } from '@angular/forms';</code>
<td><p>Declares that a class can be provided and injected by other classes. Without this decorator, the compiler won't generate enough metadata to allow the class to be created properly when it's injected somewhere.</p>
<td><p>Declara que una clase puede ser proporcionada e inyectada por otras clases. Sin este decorador, el compilador no generará suficientes metadatos para permitir que la clase se cree correctamente cuando se inyecta en alguna parte.</p>
<td><code><b>@Output()</b> myEvent = new EventEmitter();</code></td>
<td><p>Declares an output property that fires events that you can subscribe to with an event binding (example: <code><my-cmp (myEvent)="doSomething()"></code>).</p>
<td><p>Declara una propiedad de salida (output) que dispara eventos a los que puedes suscribirse con un enlace de evento (event binding) (ejemplo: <code><my-cmp (myEvent)="doSomething()"></code>).</p>
<td><p>Binds a host element property (here, the CSS class<code>valid</code>) to a directive/component property (<code>isValid</code>).</p>
<td><p>Vincula una propiedad del elemento anfitrión (aquí, la clase CSS<code>valid</code>) a una propiedad de directiva/componente (<code>isValid</code>).</p>
<td><p>Subscribes to a host element event (<code>click</code>) with a directive/component method (<code>onClick</code>), optionally passing an argument (<code>$event</code>).</p>
<td><p>Se suscribe a un evento del elemento anfitrión (<code>click</code>) con un método de directiva/componente (<code>onClick</code>), opcionalmente, pasando un argumento (<code>$event</code>).</p>
<td><p>Binds the first result of the component content query (<code>myPredicate</code>) to a property (<code>myChildComponent</code>) of the class.</p>
<td><p>Vincula el primer resultado de la consulta de contenido del componente (<code>myPredicate</code>) a una propiedad (<code>myChildComponent</code>) de la clase.</p>
<td><p>Binds the results of the component content query (<code>myPredicate</code>) to a property (<code>myChildComponents</code>) of the class.</p>
<td><p>Vincula los resultados de la consulta de contenido del componente (<code>myPredicate</code>) a una propiedad (<code>myChildComponents</code>) de la clase.</p>
<td><p>Binds the first result of the component view query (<code>myPredicate</code>) to a property (<code>myChildComponent</code>) of the class. Not available for directives.</p>
<td><p>Vincula el primer resultado de la consulta de vista del componente (<code>myPredicate</code>) a una propiedad (<code>myChildComponent</code>) de la clase. No disponible para directivas.</p>
<td><p>Binds the results of the component view query (<code>myPredicate</code>) to a property (<code>myChildComponents</code>) of the class. Not available for directives.</p>
<td><p>Vincula los resultados de la consulta de vista del componente (<code>myPredicate</code>) a una propiedad (<code>myChildComponents</code>) de la clase. No disponible para directivas.</p>
</td>
</tr>
</tbody></table>
<tableclass="is-full-width is-fixed-layout">
<tbody><tr>
<th>Directive and component change detection and lifecycle hooks</th>
<th><p>(implemented as class methods)
<th>Detección de cambios (change detection) y ciclos de vida (lifecycle hooks) en directivas y componentes</th>
<td><p>Called after every change to input properties and before processing content or child views.</p>
<td><p>Se llama después de cada cambio en las propiedades de entrada (input) y antes de procesar contenido o vistas de hijos.</p>
</td>
</tr><tr>
<td><code><b>ngOnInit()</b> { ... }</code></td>
<td><p>Called after the constructor, initializing input properties, and the first call to<code>ngOnChanges</code>.</p>
<td><p>Se llama después del constructor, inicializando propiedades de entrada (input), y la primera llamada a<code>ngOnChanges</code>.</p>
</td>
</tr><tr>
<td><code><b>ngDoCheck()</b> { ... }</code></td>
<td><p>Called every time that the input properties of a component or a directive are checked. Use it to extend change detection by performing a custom check.</p>
<td><p>Se llama cada vez que se verifican las propiedades de entrada (input) de un componente o una directiva. Úselo para extender la detección de cambios (change detection) realizando una verificación personalizada.</p>
<td><p>Called after<code>ngAfterContentInit</code>when the component's views and child views / the view that a directive is in has been initialized.</p>
<td><p>Se llama después de<code>ngAfterContentInit</code>cuando las vistas del componente y las vistas hijas / la vista en la que se encuentra una directiva ha sido inicializado.</p>
<td><p>Configures routes for the application. Supports static, parameterized, redirect, and wildcard routes. Also supports custom route data and resolve.</p>
<td><p>Configura rutas para la aplicación. Soporta rutas estáticas, parametrizadas, de redireccionamiento y comodines. También soporta datos de ruta personalizados y los resuelve.</p>
<td><p>Creates a link to a different view based on a route instruction consisting of a route path, required and optional parameters, query parameters, and a fragment. To navigate to a root route, use the<code>/</code> prefix; for a child route, use the<code>./</code>prefix; for a sibling or parent, use the<code>../</code> prefix.</p>
<td><p>Crea un enlace a una vista diferente basada en una instrucción de ruta que consta de un camino de de ruta, parámetros obligatorios y opcionales, parámetros de consulta y un fragmento. Para navegar a un camino de ruta, usa el prefijo<code>/</code>; para una ruta hija, usa el prefijo<code>./</code>; para un padre o hermano, usa el prefijo<code>../</code>.</p>
<td><p>An interface for defining a class that the router should call first to determine if it should activate this component. Should return a boolean|UrlTree or an Observable/Promise that resolves to a boolean|UrlTree.</p>
<td><p>Una interfaz para definir una clase que el enrutador debe llamar primero para determinar si debe activar este componente. Debe devolver un boolean|UrlTree o un Observable/Promise que se resuelba en un boolean|UrlTree.</p>
<td><p>An interface for defining a class that the router should call first to determine if it should deactivate this component after a navigation. Should return a boolean|UrlTree or an Observable/Promise that resolves to a boolean|UrlTree.</p>
<td><p>Una interfaz para definir una clase que el enrutador debería llamar primero para determinar si debería desactivar este componente después de una navegación. Debe devolver un boolean|UrlTree o un Observable/Promise que se resuelva a boolean|UrlTree.</p>
<td><p>An interface for defining a class that the router should call first to determine if it should activate the child route. Should return a boolean|UrlTree or an Observable/Promise that resolves to a boolean|UrlTree.</p>
<td><p>Una interfaz para definir una clase que el enrutador debe llamar primero para determinar si debe activar la ruta hija. Debe devolver un boolean|UrlTree o un Observable/Promise que se resuelva en un boolean|UrlTree.</p>
<td><p>An interface for defining a class that the router should call first to resolve route data beforerendering the route. Should return a value or an Observable/Promise that resolves to a value.</p>
<td><p>Una interfaz para definir una clase que el enrutador debe llamar primero para resolver los datos de la ruta antes de representar la ruta. Debe devolver un valor o un Observable/Promise que se resuelva en un valor.</p>
<td><p>An interface for defining a class that the router should call first to check if the lazy loaded module should be loaded. Should return a boolean|UrlTree or an Observable/Promise that resolves to a boolean|UrlTree.</p>
<td><p>Una interfaz para definir una clase a la que el enrutador debe llamar primero para verificar si el módulo perezoso cargado (lazy loaded module) debe cargarse. Debe devolver un boolean|UrlTree o un Observable/Promise que se resuelva en un boolean|UrlTree.</p>
You can often use observables instead of promises to deliver values asynchronously. Similarly, observables can take the place of event handlers. Finally, because observables deliver multiple values, you can use them where you might otherwise build and operate on arrays.
Observables behave somewhat differently from the alternative techniques in each of these situations, but offer some significant advantages. Here are detailed comparisons of the differences.
## Observables compared to promises
Observables are often compared to promises. Here are some key differences:
* Observables are declarative; computation does not start until subscription. Promises execute immediately on creation. This makes observables useful for defining recipes that can be run whenever you need the result.
* Observables provide many values. Promises provide one. This makes observables useful for getting multiple values over time.
* Observables differentiate between chaining and subscription. Promises only have `.then()` clauses. This makes observables useful for creating complex transformation recipes to be used by other part of the system, without causing the work to be executed.
* Observables `subscribe()` is responsible for handling errors. Promises push errors to the child promises. This makes observables useful for centralized and predictable error handling.
### Creation and subscription
* Observables are not executed until a consumer subscribes. The `subscribe()` executes the defined behavior once, and it can be called again. Each subscription has its own computation. Resubscription causes recomputation of values.
<code-example
path="comparing-observables/src/observables.ts"
header="src/observables.ts (observable)"
region="observable">
</code-example>
* Promises execute immediately, and just once. The computation of the result is initiated when the promise is created. There is no way to restart work. All `then` clauses (subscriptions) share the same computation.
<code-example
path="comparing-observables/src/promises.ts"
header="src/promises.ts (promise)"
region="promise">
</code-example>
### Chaining
* Observables differentiate between transformation function such as a map and subscription. Only subscription activates the subscriber function to start computing the values.
<code-example
path="comparing-observables/src/observables.ts"
header="src/observables.ts (chain)"
region="chain">
</code-example>
* Promises do not differentiate between the last `.then` clauses (equivalent to subscription) and intermediate `.then` clauses (equivalent to map).
<code-example
path="comparing-observables/src/promises.ts"
header="src/promises.ts (chain)"
region="chain">
</code-example>
### Cancellation
* Observable subscriptions are cancellable. Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work.
<code-example
path="comparing-observables/src/observables.ts"
header="src/observables.ts (unsubcribe)"
region="unsubscribe">
</code-example>
* Promises are not cancellable.
### Error handling
* Observable execution errors are delivered to the subscriber's error handler, and the subscriber automatically unsubscribes from the observable.
<code-example
path="comparing-observables/src/observables.ts"
header="src/observables.ts (error)"
region="error">
</code-example>
* Promises push errors to the child promises.
<code-example
path="comparing-observables/src/promises.ts"
header="src/promises.ts (error)"
region="error">
</code-example>
### Cheat sheet
The following code snippets illustrate how the same kind of operation is defined using observables and promises.
<table>
<thead>
<tr>
<th>Operation</th>
<th>Observable</th>
<th>Promise</th>
</tr>
</thead>
<tbody>
<tr>
<td>Creation</td>
<td>
<pre>
new Observable((observer) => {
observer.next(123);
});</pre>
</td>
<td>
<pre>
new Promise((resolve, reject) => {
resolve(123);
});</pre>
</td>
</tr>
<tr>
<td>Transform</td>
<td><pre>obs.pipe(map((value) => value * 2));</pre></td>
<td><pre>promise.then((value) => value * 2);</pre></td>
</tr>
<tr>
<td>Subscribe</td>
<td>
<pre>
sub = obs.subscribe((value) => {
console.log(value)
});</pre>
</td>
<td>
<pre>
promise.then((value) => {
console.log(value);
});</pre>
</td>
</tr>
<tr>
<td>Unsubscribe</td>
<td><pre>sub.unsubscribe();</pre></td>
<td>Implied by promise resolution.</td>
</tr>
</tbody>
</table>
## Observables compared to events API
Observables are very similar to event handlers that use the events API. Both techniques define notification handlers, and use them to process multiple values delivered over time. Subscribing to an observable is equivalent to adding an event listener. One significant difference is that you can configure an observable to transform an event before passing the event to the handler.
Using observables to handle events and asynchronous operations can have the advantage of greater consistency in contexts such as HTTP requests.
Here are some code samples that illustrate how the same kind of operation is defined using observables and the events API.
An observable produces values over time. An array is created as a static set of values. In a sense, observables are asynchronous where arrays are synchronous. In the following examples, ➞ implies asynchronous value delivery.
You can often use observables instead of promises to deliver values asynchronously. Similarly, observables can take the place of event handlers. Finally, because observables deliver multiple values, you can use them where you might otherwise build and operate on arrays.
A menudo puedes usar observables en lugar de promesas para entregar valores de forma asíncrona. Del mismo modo, los observables pueden reemplazar a los controladores de eventos. Finalmente, porque los observables entregan múltiples valores, puedes usarlos donde de otro modo podrías construir y operar con arrays.
Observables behave somewhat differently from the alternative techniques in each of these situations, but offer some significant advantages. Here are detailed comparisons of the differences.
Los observables se comportan de manera algo diferente a las técnicas alternativas en cada una de estas situaciones, pero ofrecen algunas ventajas significativas. Aquí hay comparaciones detalladas de las diferencias.
## Observables compared to promises
## Observables en comparación con promesas
Observables are often compared to promises. Here are some key differences:
Los observables a menudo se comparan con las promesas. Aquí hay algunas diferencias clave:
*Observables are declarative; computation does not start until subscription. Promises execute immediately on creation. This makes observables useful for defining recipes that can be run whenever you need the result.
*Los observables son declarativos; La ejecución no comienza hasta la suscripción. Las promesas se ejecutan inmediatamente después de la creación. Esto hace que los observables sean útiles para definir recetas que se pueden ejecutar cuando necesites el resultado.
*Observables provide many values. Promises provide one. This makes observables useful for getting multiple values over time.
*Los observables proporcionan muchos valores. Las promesas proporcionan un valor. Esto hace que los observables sean útiles para obtener múltiples valores a lo largo del tiempo.
*Observables differentiate between chaining and subscription. Promises only have`.then()` clauses. This makes observables useful for creating complex transformation recipes to be used by other part of the system, without causing the work to be executed.
*Los observables diferencian entre encadenamiento y suscripción. Las promesas solo tienen cláusulas`.then()`. Esto hace que los observables sean útiles para crear recetas de transformación complejas para ser utilizadas por otra parte del sistema, sin que el trabajo se ejecute.
* Observables `subscribe()`is responsible for handling errors. Promises push errors to the child promises. This makes observables useful for centralized and predictable error handling.
* Observables `subscribe()`es responsable de manejar los errores. Las promesas empujan los errores a promesas hijas. Esto hace que los observables sean útiles para el manejo centralizado y predecible de errores.
### Creación y suscripción
### Creation and subscription
* Observables are not executed until a consumer subscribes. The `subscribe()` executes the defined behavior once, and it can be called again. Each subscription has its own computation. Resubscription causes recomputation of values.
* Los observables no se ejecutan hasta que un consumidor se suscribe. El `subscribe()` ejecuta el comportamiento definido una vez, y se puede volver a llamar. Cada suscripción tiene su propia computación. La resuscripción provoca la recomputación de los valores.
<code-example
path="comparing-observables/src/observables.ts"
@ -27,7 +26,7 @@ Observables are often compared to promises. Here are some key differences:
region="observable">
</code-example>
*Promises execute immediately, and just once. The computation of the result is initiated when the promise is created. There is no way to restart work. All`then` clauses (subscriptions) share the same computation.
*Las promesas se ejecutan de inmediato, y solo una vez. La computación del resultado se inicia cuando se crea la promesa. No hay forma de reiniciar el trabajo. Todas las cláusulas`then` (suscripciones) comparten la misma computación.
<code-example
path="comparing-observables/src/promises.ts"
@ -35,9 +34,9 @@ Observables are often compared to promises. Here are some key differences:
region="promise">
</code-example>
### Chaining
### Encadenamiento
*Observables differentiate between transformation function such as a map and subscription. Only subscription activates the subscriber function to start computing the values.
*Los observables diferencian entre la función de transformación, como `map` y `subscription`. Solo la suscripción activa la función de suscriptor para comenzar a calcular los valores.
<code-example
path="comparing-observables/src/observables.ts"
@ -45,7 +44,7 @@ Observables are often compared to promises. Here are some key differences:
region="chain">
</code-example>
*Promises do not differentiate between the last`.then` clauses (equivalent to subscription) and intermediate`.then` clauses (equivalent to map).
*Las promesas no diferencian entre las últimas cláusulas`.then` (equivalentes al subscription) y las cláusulas intermedias`.then` (equivalentes al map).
<code-example
path="comparing-observables/src/promises.ts"
@ -53,9 +52,9 @@ Observables are often compared to promises. Here are some key differences:
region="chain">
</code-example>
### Cancellation
### Cancelación
*Observable subscriptions are cancellable. Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work.
*Las suscripciones de los observables son cancelables. La cancelación de la suscripción evita que el oyente reciba más valores y notifica a la función del suscriptor que cancele el trabajo.
<code-example
path="comparing-observables/src/observables.ts"
@ -63,11 +62,11 @@ Observables are often compared to promises. Here are some key differences:
region="unsubscribe">
</code-example>
*Promises are not cancellable.
*Las promesas no son cancelables.
### Error handling
### Manejo de errores
*Observable execution errors are delivered to the subscriber's error handler, and the subscriber automatically unsubscribes from the observable.
*Los errores de ejecución en observables se entregan al controlador de errores del suscriptor, y el suscriptor cancela automáticamente la suscripción del observable.
<code-example
path="comparing-observables/src/observables.ts"
@ -75,7 +74,7 @@ Observables are often compared to promises. Here are some key differences:
region="error">
</code-example>
*Promises push errors to the child promises.
*Las promesas empujan los errores a las promesas hijas.
<code-example
path="comparing-observables/src/promises.ts"
@ -83,9 +82,9 @@ Observables are often compared to promises. Here are some key differences:
region="error">
</code-example>
### Cheat sheet
### Hoja de trucos
The following code snippets illustrate how the same kind of operation is defined using observables and promises.
Los siguientes fragmentos de código ilustran cómo se define el mismo tipo de operación utilizando observables y promesas.
<table>
<thead>
@ -139,13 +138,13 @@ promise.then((value) => {
</tbody>
</table>
## Observables compared to events API
## Observables en comparación con eventos API
Observables are very similar to event handlers that use the events API. Both techniques define notification handlers, and use them to process multiple values delivered over time. Subscribing to an observable is equivalent to adding an event listener. One significant difference is that you can configure an observable to transforman event before passing the event to the handler.
Los observables son muy similares a los controladores de eventos que usan la API de eventos. Ambas técnicas definen manejadores de notificaciones y las utilizan para procesar múltiples valores entregados a lo largo del tiempo. Suscribirse a un observable es equivalente a agregar un detector de eventos. Una diferencia significativa es que puedes configurar un observable para transformar un evento antes de pasar el evento al controlador.
Using observables to handle events and asynchronous operations can have the advantage of greater consistency in contexts such as HTTP requests.
El uso de observables para manejar eventos y operaciones asíncronas puede tener la ventaja de una mayor coherencia en contextos como las solicitudes HTTP.
Here are some code samples that illustrate how the same kind of operation is defined using observables and the events API.
Aquí hay algunos ejemplos de código que ilustran cómo se define el mismo tipo de operación usando observables y la API de eventos.
An observable produces values over time. An array is created as a static set of values. In a sense, observables are asynchronous where arrays are synchronous. In the following examples, ➞ implies asynchronous value delivery.
Un observable produce valores a lo largo del tiempo. Se crea un array como un conjunto estático de valores. En cierto sentido, los observables son asíncronos mientras que los arrays son síncronos. En los siguientes ejemplos, ➞ implica entrega de valor asíncrono.
* [Introduction to Angular animations](guide/animations)
* [Transition and triggers](guide/transition-and-triggers)
<hr>
So far, we've learned simple animations of single HTML elements. Angular also lets you animate coordinated sequences, such as an entire grid or list of elements as they enter and leave a page. You can choose to run multiple animations in parallel, or run discrete animations sequentially, one following another.
Functions that control complex animation sequences are as follows:
*`query()` finds one or more inner HTML elements.
*`stagger()` applies a cascading delay to animations for multiple elements.
* [`group()`](api/animations/group) runs multiple animation steps in parallel.
*`sequence()` runs animation steps one after another.
{@a complex-sequence}
## Animate multiple elements using query() and stagger() functions
The `query()` function allows you to find inner elements within the element that is being animated. This function targets specific HTML elements within a parent component and applies animations to each element individually. Angular intelligently handles setup, teardown, and cleanup as it coordinates the elements across the page.
The `stagger()` function allows you to define a timing gap between each queried item that is animated and thus animates elements with a delay between them.
The Filter/Stagger tab in the live example shows a list of heroes with an introductory sequence. The entire list of heroes cascades in, with a slight delay from top to bottom.
The following example demonstrates how to use `query()` and `stagger()` functions on the entry of an animated element.
* Use `query()` to look for an element entering the page that meets certain criteria.
* For each of these elements, use `style()` to set the same initial style for the element. Make it invisible and use `transform` to move it out of position so that it can slide into place.
* Use `stagger()` to delay each animation by 30 milliseconds.
* Animate each element on screen for 0.5 seconds using a custom-defined easing curve, simultaneously fading it in and un-transforming it.
You've seen how to add a delay between each successive animation. But you may also want to configure animations that happen in parallel. For example, you may want to animate two CSS properties of the same element but use a different `easing` function for each one. For this, you can use the animation [`group()`](api/animations/group) function.
<divclass="alert is-helpful">
**Note:** The [`group()`](api/animations/group) function is used to group animation *steps*, rather than animated elements.
</div>
In the following example, using groups on both `:enter` and `:leave` allow for two different timing configurations. They're applied to the same element in parallel, but run independently.
Complex animations can have many things happening at once. But what if you want to create an animation involving several animations happening one after the other? Earlier we used [`group()`](api/animations/group) to run multiple animations all at the same time, in parallel.
A second function called `sequence()` lets you run those same animations one after the other. Within `sequence()`, the animation steps consist of either `style()` or `animate()` function calls.
* Use `style()` to apply the provided styling data immediately.
* Use `animate()` to apply styling data over a given time interval.
## Filter animation example
Let's take a look at another animation on the live example page. Under the Filter/Stagger tab, enter some text into the **Search Heroes** text box, such as `Magnet` or `tornado`.
The filter works in real time as you type. Elements leave the page as you type each new letter and the filter gets progressively stricter. The heroes list gradually re-enters the page as you delete each letter in the filter box.
The HTML template contains a trigger called `filterAnimation`.
* Ignores any animations that are performed when the user first opens or navigates to this page. The filter narrows what is already there, so it assumes that any HTML elements to be animated already exist in the DOM.
* Performs a filter match for matches.
For each match:
* Hides the element by making it completely transparent and infinitely narrow, by setting its opacity and width to 0.
* Animates in the element over 300 milliseconds. During the animation, the element assumes its default width and opacity.
* If there are multiple matching elements, staggers in each element starting at the top of the page, with a 50-millisecond delay between each element.
## Animation sequence summary
Angular functions for animating multiple elements start with `query()` to find inner elements, for example gathering all images within a `<div>`. The remaining functions, `stagger()`, [`group()`](api/animations/group), and `sequence()`, apply cascades or allow you to control how multiple animation steps are applied.
## More on Angular animations
You may also be interested in the following:
* [Introduction to Angular animations](guide/animations)
* [Transition and triggers](guide/transition-and-triggers)
Una comprensión básica de los siguientes conceptos:
* [Introduction to Angular animations](guide/animations)
* [Transition and triggers](guide/transition-and-triggers)
- [Introducción a animaciones Angular](guide/animations)
- [Transición y triggers](guide/transition-and-triggers)
<hr>
So far, we've learned simple animations of single HTML elements. Angular also lets you animate coordinated sequences, such as an entire grid or list of elements as they enter and leave a page. You can choose to run multiple animations in parallel, or run discrete animations sequentially, one following another.
Hasta ahora, hemos aprendido animaciones simples de elementos HTML individuales. Angular también te permite animar secuencias coordinadas, como un grid completo o una lista de elementos cuando entran y salen de una página. Puedes elegir ejecutar varias animaciones en paralelo, o ejecutar animaciones discretas secuencialmente, una tras otra.
Functions that control complex animation sequences are as follows:
Las funciones que controlan secuencias de animación complejas son las siguientes:
*`query()`finds one or more inner HTML elements.
*`stagger()` applies a cascading delay to animations for multiple elements.
* [`group()`](api/animations/group) runs multiple animation steps in parallel.
*`sequence()`runs animation steps one after another.
-`query()`encuentra uno o más elementos HTML internos.
-`stagger()` aplica un retraso en cascada a las animaciones para varios elementos.
- [`group()`](api/animations/group) ejecuta varios pasos de animación en paralelo.
-`sequence()`ejecuta pasos de animación uno tras otro.
{@a complex-sequence}
##Animate multiple elements using query() and stagger() functions
##Animar varios elementos usando las funciones query() y stagger()
The`query()`function allows you to find inner elements within the element that is being animated. This function targets specific HTML elements within a parent component and applies animations to each element individually. Angular intelligently handles setup, teardown, and cleanup as it coordinates the elements across the page.
La función`query()`permite encontrar elementos internos dentro del elemento que estás animando. Esta función se dirige a elementos HTML específicos dentro de un componente principal y aplica animaciones a cada elemento individualmente. Angular maneja de manera inteligente la configuración, el desmontaje y la limpieza a medida que coordina los elementos en la página.
The`stagger()`function allows you to define a timing gap between each queried item that is animated and thus animates elements with a delay between them.
La función`stagger()`permite definir un intervalo de tiempo entre cada elemento consultado que está animado y, por lo tanto, anima elementos con un retraso entre ellos.
The Filter/Stagger tab in the live example shows a list of heroes with an introductory sequence. The entire list of heroes cascades in, with a slight delay from top to bottom.
La pestaña Filter/Stagger en el ejemplo en vivo muestra una lista de héroes con una secuencia introductoria. La lista completa de héroes entra en cascada, con un ligero retraso de arriba a abajo.
The following example demonstrates how to use`query()`and`stagger()`functions on the entry of an animated element.
El siguiente ejemplo demuestra cómo utilizar las funciones`query()`y`stagger()`en la entrada de un elemento animado.
* Use`query()`to look for an element entering the page that meets certain criteria.
- Usa`query()`para buscar un elemento que ingrese a la página que cumpla con ciertos criterios.
*For each of these elements, use`style()`to set the same initial style for the element. Make it invisible and use`transform`to move it out of position so that it can slide into place.
-Para cada uno de estos elementos, usa`style()`para establecer el mismo estilo inicial para el elemento. Hazlo invisible y usa`transform`para moverlo fuera de su posición para que pueda deslizarse a su lugar.
* Use`stagger()`to delay each animation by 30 milliseconds.
- Usa`stagger()`para retrasar cada animación en 30 milisegundos.
* Animate each element on screen for 0.5 seconds using a custom-defined easing curve, simultaneously fading it in and un-transforming it.
- Anima cada elemento en la pantalla durante 0,5 segundos utilizando una curva de easing (suavizado) definida a medida, desvaneciéndolo y deshaciéndolo simultáneamente.
You've seen how to add a delay between each successive animation. But you may also want to configure animations that happen in parallel. For example, you may want to animate two CSS properties of the same element but use a different `easing` function for each one. For this, you can use the animation [`group()`](api/animations/group) function.
Has visto cómo agregar un retraso entre cada animación sucesiva. Pero es posible que también quieras configurar animaciones que suceden en paralelo. Por ejemplo, es posible que quieras animar dos propiedades CSS del mismo elemento pero utilizar una función de `easing` diferente para cada una. Para ello, puedes utilizar la función de animación [`group()`](api/animations/group).
<divclass="alert is-helpful">
**Note:**The [`group()`](api/animations/group) function is used to group animation *steps*, rather than animated elements.
**Nota:**La función [`group()`](api/animations/group) se usa para agrupar _pasos_ de animación, en lugar de elementos animados.
</div>
In the following example, using groups on both`:enter`and`:leave`allow for two different timing configurations. They're applied to the same element in parallel, but run independently.
En el siguiente ejemplo, el uso de grupos tanto en`:enter`como en`:leave`permite dos configuraciones de tiempo diferentes. Se aplican al mismo elemento en paralelo, pero se ejecutan de forma independiente.
Complex animations can have many things happening at once. But what if you want to create an animation involving several animations happening one after the other? Earlier we used [`group()`](api/animations/group) to run multiple animations all at the same time, in parallel.
Las animaciones complejas pueden tener muchas cosas sucediendo a la vez. Pero, ¿qué sucede si quieres crear una animación que involucre varias animaciones sucediendo una tras otra? Anteriormente usamos [`group()`](api/animations/group) para ejecutar múltiples animaciones al mismo tiempo, en paralelo.
A second function called`sequence()`lets you run those same animations one after the other. Within `sequence()`, the animation steps consist of either`style()` or`animate()` function calls.
Una segunda función llamada`sequence()`permite ejecutar esas mismas animaciones una tras otra. Dentro de `sequence()`, los pasos de la animación consisten en llamadas de función`style()` o `animate()`
* Use`style()`to apply the provided styling data immediately.
* Use`animate()`to apply styling data over a given time interval.
- Usa`style()`para aplicar los datos de estilo proporcionados inmediatamente.
- Usa`animate()`para aplicar datos de estilo en un intervalo de tiempo determinado.
## Filter animation example
## Ejemplo de animación de filtro
Let's take a look at another animation on the live example page. Under the Filter/Stagger tab, enter some text into the**Search Heroes** text box, such as`Magnet` or`tornado`.
Echemos un vistazo a otra animación en la página de ejemplo. En la pestaña Filter/Stagger, ingresa un texto en el cuadro de texto**Search Heroes**, como`Magnet` o `tornado`.
The filter works in real time as you type. Elements leave the page as you type each new letter and the filter gets progressively stricter. The heroes list gradually re-enters the page as you delete each letter in the filter box.
El filtro funciona en tiempo real a medida que escribe. Los elementos abandonan la página a medida que escribe cada nueva letra y el filtro se vuelve progresivamente más estricto. La lista de héroes vuelve a entrar gradualmente en la página a medida que eliminas cada letra en la caja de filtro.
The HTML template contains a trigger called`filterAnimation`.
La plantilla HTML contiene un trigger llamado`filterAnimation`.
* Ignores any animations that are performed when the user first opens or navigates to this page. The filter narrows what is already there, so it assumes that any HTML elements to be animated already exist in the DOM.
- Ignora las animaciones que se realizan cuando el usuario abre o navega por primera vez a esta página. El filtro reduce lo que ya está allí, por lo que asume que los elementos HTML que se van a animar ya existen en el DOM.
*Performs a filter match for matches.
-Realiza un filtro de coincidencia.
For each match:
Para cada coincidencia:
*Hides the element by making it completely transparent and infinitely narrow, by setting its opacity and width to 0.
-Oculta el elemento haciéndolo completamente transparente e infinitamente estrecho, estableciendo su opacidad y ancho en 0.
* Animates in the element over 300 milliseconds. During the animation, the element assumes its default width and opacity.
- Anima el elemento más de 300 milisegundos. Durante la animación, el elemento asume su ancho y opacidad predeterminados.
*If there are multiple matching elements, staggers in each element starting at the top of the page, with a 50-millisecond delay between each element.
-Si hay varios elementos coincidentes, se escalona en cada elemento comenzando en la parte superior de la página, con un retraso de 50milisegundos entre cada elemento.
## Animation sequence summary
## Resumen de la secuencia de animación
Angular functions for animating multiple elements start with `query()` to find inner elements, for example gathering all images within a `<div>`. The remaining functions, `stagger()`, [`group()`](api/animations/group), and`sequence()`, apply cascades or allow you to control how multiple animation steps are applied.
Las funciones Angular para animar múltiples elementos comienzan con `query()` para encontrar elementos internos, por ejemplo, reuniendo todas las imágenes dentro de un `<div>`. Las funciones restantes, `stagger()`, [`group()`](api/animations/group) y`sequence()`, aplican cascadas o te permiten controlar cómo se aplican múltiples pasos de animación.
## More on Angular animations
## Más sobre animaciones en Angular
You may also be interested in the following:
También puedes estar interesado en lo siguiente:
* [Introduction to Angular animations](guide/animations)
* [Transition and triggers](guide/transition-and-triggers)
Every component requires a CSS _selector_. A selector instructs Angular to instantiate this component wherever it finds the corresponding tag in template HTML. For example, consider a component, `hello-world.component.ts` that defines its selector as `app-hello-world`. This selector instructs angular to instantiate this component any time the tag, `<app-hellow-world>` in a template.
To specify a component's selector, add a `selector` statement to the `@Component` decorator.
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-examplelanguage="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.
<divclass="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'.
Puedes crear, probar y comprobar con los comandos de CLI:
<code-examplelanguage="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-examplelanguage="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).
<divclass="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-examplelanguage="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.
| browser support | [`IE 9 and 10, IE mobile`](#ie-9-10-and-mobile) | <!--v10--> v11 |
For information about Angular CDK and Angular Material deprecations, see the [changelog](https://github.com/angular/components/blob/master/CHANGELOG.md).
@ -89,11 +84,9 @@ Tip: In the [API reference section](api) of this doc site, deprecated APIs are i
| API | Replacement | Deprecation announced | Notes |
| [`ViewEncapsulation.Native`](api/core/ViewEncapsulation#Native) | [`ViewEncapsulation.ShadowDom`](api/core/ViewEncapsulation#ShadowDom) | v6 | Use the native encapsulation mechanism of the renderer. See [view.ts](https://github.com/angular/angular/blob/3e992e18ebf51d6036818f26c3d77b52d3ec48eb/packages/core/src/metadata/view.ts#L32).
| [`defineInjectable`](api/core/defineInjectable) | `ɵɵdefineInjectable` | v8 | Used only in generated code. No source code should depend on this API. |
| [`entryComponents`](api/core/NgModule#entryComponents) | none | v9 | See [`entryComponents`](#entryComponents) |
| [`ANALYZE_FOR_ENTRY_COMPONENTS`](api/core/ANALYZE_FOR_ENTRY_COMPONENTS) | none | v9 | See [`ANALYZE_FOR_ENTRY_COMPONENTS`](#entryComponents) |
@ -119,26 +112,6 @@ Tip: In the [API reference section](api) of this doc site, deprecated APIs are i
@ -394,28 +367,6 @@ These two properties have subtle differences, so switching to `textContent` unde
All of the `wtf*` APIs are deprecated and will be removed in a future version.
{@a webworker-apps}
### Running Angular applications in platform-webworker
The `@angular/platform-*` packages enable Angular to be run in different contexts. For examples,
`@angular/platform-server` enables Angular to be run on the server, and `@angular/platform-browser`
enables Angular to be run in a web browser.
`@angular/platform-webworker` was introduced in Angular version 2 as an experiment in leveraging
Angular's rendering architecture to run an entire web application in a
[web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). We've learned a lot
from this experiment and have come to the conclusion that running the entire application in a web
worker is not the best strategy for most applications.
Going forward, we will focus our efforts related to web workers around their primary use case of
offloading CPU-intensive, non-critical work needed for initial rendering (such as in-memory search
and image processing). Learn more in the
[guide to Using Web Workers with the Angular CLI](guide/web-worker).
As of Angular version 8, all `platform-webworker` APIs are deprecated.
This includes both packages: `@angular/platform-webworker` and
`@angular/platform-webworker-dynamic`.
{@a entryComponents}
### `entryComponents` and `ANALYZE_FOR_ENTRY_COMPONENTS` no longer required
Previously, the `entryComponents` array in the `NgModule` definition was used to tell the compiler which components would be created and inserted dynamically. With Ivy, this isn't a requirement anymore and the `entryComponents` array can be removed from existing module declarations. The same applies to the `ANALYZE_FOR_ENTRY_COMPONENTS` injection token.
@ -464,20 +415,6 @@ export class MyModule {
}
```
{@a ie-9-10-and-mobile}
### IE 9, 10, and IE mobile support
Support for IE 9 and 10 has been deprecated, as well as support for IE Mobile. These will be dropped in a future version.
Supporting outdated browsers like these increases bundle size, code complexity, and test load, and also requires time and effort that could be spent on improvements to the framework.
For example, fixing issues can be more difficult, as a straightforward fix for modern browsers could break old ones that have quirks due to not receiving updates from vendors.
The final decision was made on three key points:
* __Vendor support__: Microsoft dropped support of IE 9 and 10 on 1/12/16, meaning they no longer provide security updates or technical support. Additionally, Microsoft dropped support for Windows 10 Mobile in December 2019.
* __Usage statistics__: We looked at usage trends for IE 9 and 10 (as well as IE Mobile) from various sources and all indicated that usage percentages were extremely small (fractions of 1%).
* __Feedback from partners__: We also reached out to some of our Angular customers and none expressed concern about dropping IE 9, 10, nor IE Mobile support.
{@a wrapped-value}
### `WrappedValue`
@ -544,15 +481,13 @@ This section contains a complete list all of the currently deprecated CLI flags.
{@a removed}
## Removed APIs
The following APIs have been removed starting with version 10.0.0*:
The following APIs have been removed starting with version 11.0.0*:
| `@angular/core` | Undecorated base classes that use Angular features | Add Angular decorator | See [migration guide](guide/migration-undecorated-classes) for more info |
| `@angular/core` | `ModuleWithProviders` without a generic | `ModuleWithProviders` with a generic | See [migration guide](guide/migration-module-with-providers) for more info |
| `@angular/core` | Style Sanitization | no action needed | See [style sanitization API removal](#style-sanitization) for more info
Angular [components](guide/glossary#component) form the data structure of your application.
The HTML [template](guide/glossary#template) associated with a component provides the means to display that data in the context of a web page.
Together, a component's class and template form a [view](guide/glossary#view) of your application data.
The process of combining data values with their representation on the page is called [data binding](guide/glossary#data-binding).
You display your data to a user (and collect data from the user) by *binding* controls in the HTML template to the data properties of the component class.
In addition, you can add logic to the template by including [directives](guide/glossary#directive), which tell Angular how to modify the page as it is rendered.
Angular defines a *template language* that expands HTML notation with syntax that allows you to define various kinds of data binding and logical directives.
When the page is rendered, Angular interprets the template syntax to update the HTML according to your logic and current data state.
Before you read the complete [template syntax guide](guide/template-syntax), the exercises on this page give you a quick demonstration of how template syntax works.
In this demo, you'll create a component with a list of heroes.
You'll display the list of hero names and conditionally show a message below the list.
When you bootstrap with the `AppComponent` class (in <code>main.ts</code>), Angular looks for a `<app-root>`
in the `index.html`, finds it, instantiates an instance of `AppComponent`, and renders it
inside the `<app-root>` tag.
Now run the app. It should display the title and hero name:
<divclass="lightbox">
<imgsrc="generated/images/guide/displaying-data/title-and-hero.png"alt="Title and Hero">
</div>
The next few sections review some of the coding choices in the app.
## Choosing the template source
The `@Component` metadata tells Angular where to find the component's template.
You can store your component's template in one of two places.
* You can define the template *inline* using the `template` property of the `@Component` decorator. An inline template is useful for a small demo or test.
* Alternatively, you can define the template in a separate HTML file and link to that file in the `templateUrl` property of the `@Component` decorator. This configuration is typical for anything more complex than a small test or demo, and is the default when you generate a new component.
In either style, the template data bindings have the same access to the component's properties.
Here the app uses inline HTML because the template is small and the demo is simpler without the additional HTML file.
<divclass="alert is-helpful">
By default, the Angular CLI command [`ng generate component`](cli/generate) generates components with a template file.
You can override that by adding the "-t" (short for `inlineTemplate=true`) option:
You could instead declare and initialize the properties using a constructor.
This app uses more terse "variable assignment" style simply for brevity.
{@a ngFor}
## Add logic to loop through data
The `*ngFor` directive (predefined by Angular) lets you loop through data. The following example uses the directive to show all of the values in an array property.
To display a list of heroes, begin by adding an array of hero names to the component and redefine `myHero` to be the first name in the array.
Don't forget the leading asterisk (\*) in `*ngIf`. It is an essential part of the syntax.
Read more about `ngIf` and `*` in the [ngIf section](guide/built-in-directives#ngIf) of the [Built-in directives](guide/built-in-directives) page.
</div>
The template expression inside the double quotes,
`*ngIf="heroes.length > 3"`, looks and behaves much like TypeScript.
When the component's list of heroes has more than three items, Angular adds the paragraph
to the DOM and the message appears.
If there are three or fewer items, Angular omits the paragraph, so no message appears.
For more information, see [template expression operators](guide/interpolation#template-expressions).
<divclass="alert is-helpful">
Angular isn't showing and hiding the message. It is adding and removing the paragraph element from the DOM. That improves performance, especially in larger projects when conditionally including or excluding
big chunks of HTML with many data bindings.
</div>
Try it out. Because the array has four items, the message should appear.
Go back into <code>app.component.ts</code> and delete or comment out one of the elements from the heroes array.
The browser should refresh automatically and the message should disappear.
## Summary
Now you know how to use:
* **Interpolation** with double curly braces to display a component property.
* **ngFor** to display an array of items.
* A TypeScript class to shape the **model data** for your component and display properties of that model.
* **ngIf** to conditionally display a chunk of HTML based on a boolean expression.
@ -4,7 +4,7 @@ An entry component is any component that Angular loads imperatively, (which mean
<divclass="alert is-helpful">
To contrast the two types of components, there are components which are included in the template, which are declarative. Additionally, there are components which you load imperatively; that is, entry components.
To contrast the two types of components, there are components which are included in the template, which are declarative. Additionally, there are components which you load imperatively; that is, entry components.
</div>
@ -75,11 +75,10 @@ All router components must be entry components. Because this would require you t
## The `entryComponents` array
<divclass="alert is-helpful">
Since 9.0.0 with Ivy, the `entryComponents` property is no longer necessary. See [deprecations guide](guide/deprecations#entryComponents).
Since 9.0.0 with Ivy, the `entryComponents` property is no longer necessary. See [deprecations guide](guide/deprecations#entryComponents).
</div>
Though the `@NgModule` decorator has an `entryComponents` array, most of the time
Though [template expressions](guide/interpolation#template-expressions) shouldn't have [side effects](guide/property-binding#avoid-side-effects), template
Though [template expressions](guide/interpolation#template-expressions) shouldn't have [side effects](guide/property-binding-best-practices#avoid-side-effects), template
statements usually do. The `deleteItem()` method does have
| `app/app.component.ts` | Defines the logic for the app's root component, named `AppComponent`. The view associated with this root component becomes the root of the [view hierarchy](guide/glossary#view-hierarchy) as you add components and services to your application. |
| `app/app.component.ts` | Defines the logic for the app's root component, named `AppComponent`. The view associated with this root component becomes the root of the [view hierarchy](guide/glossary#view-tree) as you add components and services to your application. |
| `app/app.component.html` | Defines the HTML template associated with the root `AppComponent`. |
| `app/app.component.css` | Defines the base CSS stylesheet for the root `AppComponent`. |
| `app/app.component.spec.ts` | Defines a unit test for the root `AppComponent`. |
| `app/app.module.ts` | Defines the root module, named `AppModule`, that tells Angular how to assemble the application. Initially declares only the `AppComponent`. As you add more components to the app, they must be declared here. |
| `app/package.json` | This file is generated only in applications created using `--strict` mode. This file is not used by package managers. It is used to tell the tools and bundlers whether the code under this directory is free of non-local [side-effects](guide/strict-mode#side-effect). |
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
