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

docs: edit and organize language service doc (#33202) 

PR Close #33202
This commit is contained in:
Judy Bogart 2019-10-16 12:40:55 -07:00 committed by Matias Niemelä
parent f289411fa9
commit 8d44b5edac
1 changed files with 75 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
aio/content/guide/language-service.md
View File

@ -1,43 +1,50 @@
# Angular Language Service # Angular Language Service
The Angular Language Service is a way to get completions, errors, The Angular Language Service provides code editors with a way to get completions, errors,
hints, and navigation inside your Angular templates whether they hints, and navigation inside Angular templates.
are external in an HTML file or embedded in annotations/decorators It works with external templates in separate HTML files, and also with in-line templates.
in a string. The Angular Language Service autodetects that you are
opening an Angular file, reads your `tsconfig.json` file, finds all the ## Features
templates you have in your application, and then provides language
services for any templates that you open. Your editor autodetects that you are opening an Angular file.
It then uses the Angular Language Service to read your `tsconfig.json` file, find all the
templates you have in your application, and then provide language services for any templates that you open.
Language services include:
* Completions lists
* AOT Diagnostic messages
* Quick info
* Go to definition
## Autocompletion ### Autocompletion
Autocompletion can speed up your development time by providing you with Autocompletion can speed up your development time by providing you with
contextual possibilities and hints as you type. This example shows contextual possibilities and hints as you type.
autocomplete in an interpolation. As you type it out, This example shows autocomplete in an interpolation. As you type it out,
you can hit tab to complete. you can hit tab to complete.
<figure> <figure>
<img src="generated/images/guide/language-service/language-completion.gif" alt="autocompletion"> <img src="generated/images/guide/language-service/language-completion.gif" alt="autocompletion">
</figure> </figure>
There are also completions within There are also completions within elements. Any elements you have as a component selector will
elements. Any elements you have as a component selector will
show up in the completion list. show up in the completion list.
## Error checking ### Error checking
The Angular Language Service can also forewarn you of mistakes in your code. The Angular Language Service can forewarn you of mistakes in your code.
In this example, Angular doesn't know what `orders` is or where it comes from. In this example, Angular doesn't know what `orders` is or where it comes from.
<figure> <figure>
<img src="generated/images/guide/language-service/language-error.gif" alt="error checking"> <img src="generated/images/guide/language-service/language-error.gif" alt="error checking">
</figure> </figure>
## Navigation ### Quick info and navigation
Navigation allows you to hover to The quick-info feature allows you to hover to see where components, directives, modules, and so on come from.
see where a component, directive, module, etc. is from and then You can then click "Go to definition" or press F12 to go directly to the definition.
click and press F12 to go directly to its definition.
<figure> <figure>
<img src="generated/images/guide/language-service/language-navigation.gif" alt="navigation"> <img src="generated/images/guide/language-service/language-navigation.gif" alt="navigation">
@ -46,41 +53,28 @@ click and press F12 to go directly to its definition.
## Angular Language Service in your editor ## Angular Language Service in your editor
Angular Language Service is currently available for [Visual Studio Code](https://code.visualstudio.com/) and Angular Language Service is currently available as an extension for [Visual Studio Code](https://code.visualstudio.com/),
[WebStorm](https://www.jetbrains.com/webstorm). [WebStorm](https://www.jetbrains.com/webstorm), and [Sublime Text](https://www.sublimetext.com/).
### Visual Studio Code ### Visual Studio Code
In Visual Studio Code, install Angular Language Service from the store, In [Visual Studio Code](https://code.visualstudio.com/), install the extension from the [Extensions: Marketplace](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template). You can open the marketplace from the editor using the Extensions icon on the left menu pane, or use VS Quick Open (⌘+P on Mac, CTRL+P on Windows) and type "? ext".
which is accessible from the bottom icon on the left menu pane.
You can also use the VS Quick Open (⌘+P on Mac, CTRL+P on Windows) to search for the extension. When you've opened it,
enter the following command:
```sh
ext install Angular.ng-template
```
Then click the install button to install the Angular Language Service.
In the marketplace, search for Angular Language Service extension, and click the **Install** button.
### WebStorm ### WebStorm
In webstorm, you have to install the language service as a dev dependency. In [WebStorm](https://www.jetbrains.com/webstorm/), you must install the language service package as a project dependency.
When Angular sees this dev dependency, it provides the
language service inside of WebStorm. Webstorm then gives you
colorization inside the template and autocomplete in addition to the Angular Language Service.
Here's the dev dependency 1. Add the following to your `devDependencies` in your project's `package.json`
you need to have in `package.json`:
```json <code-example language="json" header="package.json">
devDependencies { devDependencies {
"@angular/language-service": "^6.0.0" "@angular/language-service": "^6.0.0"
} }
``` </code-example>
Then in the terminal window at the root of your project, 2. In the terminal window at the root of your project, install the `devDependencies` with `npm` or `yarn`:
install the `devDependencies` with `npm` or `yarn`:
```sh ```sh
npm install npm install
@ -97,79 +91,72 @@ yarn
yarn install yarn install
``` ```
When Angular sees this dev dependency, it provides the language service in the WebStorm environment.
WebStorm then gives you colorization inside the template and autocomplete in addition to the Angular Language Service.
### Sublime Text ### Sublime Text
In [Sublime Text](https://www.sublimetext.com/), you first need an extension to allow Typescript. In [Sublime Text](https://www.sublimetext.com/), the Language Service supports only in-line templates when installed as a plug-in.
Install the latest version of typescript in a local `node_modules` directory: You need a custom Sublime plug-in (or modifications to the current plug-in) for completions in HTML files.
To use the Language Service for in-line templates, you must first add an extension to allow TypeScript, then install the Angular Language Service plug-in. Starting with TypeScript 2.3, TypeScript has a plug-in model that the language service can use.
1. Install the latest version of TypeScript in a local `node_modules` directory:
```sh ```sh
npm install --save-dev typescript npm install --save-dev typescript
``` ```
Then install the Angular Language Service in the same location: 2. Install the Angular Language Service package in the same location:
```sh
npm install --save-dev @angular/language-service
```
Starting with TypeScript 2.3, TypeScript has a language service plugin model that the language service can use.
Next, in your user preferences (`Cmd+,` or `Ctrl+,`), add:
```json
"typescript-tsdk": "<path to your folder>/node_modules/typescript/lib"
```
## Installing in your project
You can also install Angular Language Service in your project with the
following `npm` command:
```sh ```sh
npm install --save-dev @angular/language-service npm install --save-dev @angular/language-service
``` ```
Additionally, add the following to the `"compilerOptions"` section of
your project's `tsconfig.json`.
```json 3. Once the package is installed, add the following to the `"compilerOptions"` section of your project's `tsconfig.json`.
<code-example language="json" header="tsconfig.json">
"plugins": [ "plugins": [
{"name": "@angular/language-service"} {"name": "@angular/language-service"}
] ]
``` </code-example>
Note that this only provides diagnostics and completions in `.ts`
files. You need a custom sublime plugin (or modifications to the current plugin) 4. In your editor's user preferences (`Cmd+,` or `Ctrl+,`), add the following:
for completions in HTML files.
<code-example language="json" header="Sublime Text user preferences">
"typescript-tsdk": "<path to your folder>/node_modules/typescript/lib"
</code-example>
This allows the Angular Language Service to provide diagnostics and completions in `.ts` files.
## How the Language Service works ## How the Language Service works
When you use an editor with a language service, there's an When you use an editor with a language service, the editor starts a separate language-service process
editor process which starts a separate language process/service and communicates with it through an [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call), using the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
to which it speaks through an [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call). When you type into the editor, the editor sends information to the language-service process to
Any time you type inside of the editor, it sends information to the other process to track the state of your project.
track the state of your project. When you trigger a completion list within a template, the editor process first parses the template into an HTML AST, or [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree). Then the Angular compiler interprets
what module the template is part of, the scope you're in, and the component selector. Then it figures out where in the template AST your cursor is. When it determines the
context, it can then determine what the children can be.
It's a little more involved if you are in an interpolation. If you have an interpolation of `{{data.---}}` inside a `div` and need the completion list after `data.---`, the compiler can't use the HTML AST to find the answer. The HTML AST can only tell the compiler that there is some text with the characters "`{{data.---}}`". That's when the template parser produces an expression AST, which resides within the template AST. The Angular Language Services then looks at `data.---` within its context and asks the TypeScript Language Service what the members of data are. TypeScript then returns the list of possibilities.
For more in-depth information, see the
[Angular Language Service API](https://github.com/angular/angular/blob/master/packages/language-service/src/types.ts)
When you trigger a completion list within a template, the editor first parses the template into an
HTML [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree).
The Angular compiler interprets that tree to determine the context: which module the template is part of, the current scope, the component selector, and where your cursor is in the template AST. It can then determine the symbols that could potentially be at that position..
It's a little more involved if you are in an interpolation.
If you have an interpolation of `{{data.---}}` inside a `div` and need the completion list after `data.---`, the compiler can't use the HTML AST to find the answer.
The HTML AST can only tell the compiler that there is some text with the characters "`{{data.---}}`".
That's when the template parser produces an expression AST, which resides within the template AST.
The Angular Language Services then looks at `data.---` within its context, asks the TypeScript Language Service what the members of `data` are, and returns the list of possibilities.
<hr> <hr>
## More on Information ## More information
For more information, see [Chuck Jazdzewski's presentation](https://www.youtube.com/watch?v=ez3R0Gi4z5A&t=368s) on the Angular Language * For more in-depth information on the implementation, see the
Service from [ng-conf](https://www.ng-conf.org/) 2017. [Angular Language Service API](https://github.com/angular/angular/blob/master/packages/language-service/src/types.ts).
* For more on the design considerations and intentions, see [design documentation here](https://github.com/angular/vscode-ng-language-service/wiki/Design).
* See also [Chuck Jazdzewski's presentation](https://www.youtube.com/watch?v=ez3R0Gi4z5A&t=368s) on the Angular Language Service from [ng-conf](https://www.ng-conf.org/) 2017.