From 17af5b39f4d023850fd02d118502cddacd334f3c Mon Sep 17 00:00:00 2001 From: Suguru Inatomi Date: Thu, 1 Nov 2018 21:21:49 +0900 Subject: [PATCH 01/21] update origin --- origin | 2 +- update-origin.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/origin b/origin index 3b4d9dc576..8634d0bcd8 160000 --- a/origin +++ b/origin @@ -1 +1 @@ -Subproject commit 3b4d9dc576ba9e999ee03e231b70ff06dceeef75 +Subproject commit 8634d0bcd8dd78718e9448b9319f54fd6eaed080 diff --git a/update-origin.sh b/update-origin.sh index c0a97fbd1e..f440702641 100755 --- a/update-origin.sh +++ b/update-origin.sh @@ -2,7 +2,7 @@ echo "Checking aio changes in origin..." -ngVersion="6.1.x" +ngVersion="7.0.x" git -C origin fetch origin ${ngVersion} git -C origin reset FETCH_HEAD --hard From 57a6b04e8bd3ec7cb67e148046522c2e4e09c16c Mon Sep 17 00:00:00 2001 From: Suguru Inatomi Date: Thu, 1 Nov 2018 21:32:43 +0900 Subject: [PATCH 02/21] no diff files --- aio-ja/content/guide/ajs-quick-reference.md | 4 +- aio-ja/content/guide/aot-compiler.md | 30 +- aio-ja/content/guide/browser-support.md | 6 +- aio-ja/content/guide/build.md | 492 +++++++ .../guide/complex-animation-sequences.md | 8 +- .../guide/dependency-injection-in-action.md | 68 +- .../guide/dependency-injection-navtree.md | 34 +- .../guide/dependency-injection-providers.md | 36 +- aio-ja/content/guide/deployment.md | 400 +++--- aio-ja/content/guide/docs-style-guide.md | 50 +- aio-ja/content/guide/file-structure.md | 126 ++ aio-ja/content/guide/forms-overview.md | 165 +-- aio-ja/content/guide/glossary.md | 11 +- .../hierarchical-dependency-injection.md | 20 +- aio-ja/content/guide/i18n.md | 76 +- aio-ja/content/guide/reusable-animations.md | 4 +- aio-ja/content/guide/route-animations.md | 14 +- aio-ja/content/guide/router.md | 300 ++--- aio-ja/content/guide/set-document-title.md | 8 +- aio-ja/content/guide/structural-directives.md | 60 +- aio-ja/content/guide/template-syntax.md | 192 +-- .../content/guide/transition-and-triggers.md | 40 +- aio-ja/content/guide/upgrade-performance.md | 8 +- aio-ja/content/guide/upgrade.md | 176 +-- aio-ja/content/guide/visual-studio-2015.md | 48 +- aio-ja/content/guide/workspace-config.md | 135 ++ aio-ja/content/marketing/contribute.html | 13 +- aio-ja/content/marketing/contributors.json | 1168 +++++++++-------- aio-ja/content/marketing/events.en.html | 54 +- aio-ja/content/marketing/resources.json | 17 +- aio-ja/content/marketing/test.html | 22 +- 31 files changed, 2289 insertions(+), 1496 deletions(-) create mode 100644 aio-ja/content/guide/build.md create mode 100644 aio-ja/content/guide/file-structure.md create mode 100644 aio-ja/content/guide/workspace-config.md diff --git a/aio-ja/content/guide/ajs-quick-reference.md b/aio-ja/content/guide/ajs-quick-reference.md index b900fd0a78..2bc8f4531b 100644 --- a/aio-ja/content/guide/ajs-quick-reference.md +++ b/aio-ja/content/guide/ajs-quick-reference.md @@ -202,10 +202,10 @@ The following are some of the key AngularJS built-in directives and their equiva ### Bootstrapping - +
- + Angular doesn't have a bootstrap directive. diff --git a/aio-ja/content/guide/aot-compiler.md b/aio-ja/content/guide/aot-compiler.md index 24ca09cf6f..dd0bed2019 100644 --- a/aio-ja/content/guide/aot-compiler.md +++ b/aio-ja/content/guide/aot-compiler.md @@ -8,7 +8,7 @@ This guide explains how to specify metadata and apply available compiler options
Watch compiler author Tobias Bosch explain the Angular Compiler at AngularConnect 2016. + Watch compiler author Tobias Bosch explain the Angular compiler at AngularConnect 2016.
@@ -21,7 +21,7 @@ Angular offers two ways to compile your application: 1. **_Just-in-Time_ (JIT)**, which compiles your app in the browser at runtime. 1. **_Ahead-of-Time_ (AOT)**, which compiles your app at build time. -JIT compilation is the default when you run the _build-only_ or the _build-and-serve-locally_ CLI commands: +JIT compilation is the default when you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands: ng build @@ -30,7 +30,7 @@ JIT compilation is the default when you run the _build-only_ or the _build-and-s {@a compile} -For AOT compilation, append the `--aot` flags to the _build-only_ or the _build-and-serve-locally_ CLI commands: +For AOT compilation, include the `--aot` option with the `ng build` or `ng serve` command: ng build --aot @@ -41,7 +41,7 @@ For AOT compilation, append the `--aot` flags to the _build-only_ or the _build- The `ng build` command with the `--prod` meta-flag (`ng build --prod`) compiles with AOT by default. -See the [CLI documentation](https://github.com/angular/angular-cli/wiki) for details, especially the [`build` topic](https://github.com/angular/angular-cli/wiki/build). +See the [CLI command reference](cli) and [Building and serving Angular apps](guide/build) for more information. @@ -1308,6 +1308,28 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there]( } ``` +{@a tsconfig-extends} +## Configuration inheritance with extends +Similar to TypeScript Compiler, Angular Compiler also supports `extends` in the `tsconfig.json` on `angularCompilerOptions`. A tsconfig file can inherit configurations from another file using the `extends` property. + The `extends` is a top level property parallel to `compilerOptions` and `angularCompilerOptions`. + The configuration from the base file are loaded first, then overridden by those in the inheriting config file. + Example: +```json +{ + "extends": "../tsconfig.base.json", + "compilerOptions": { + "experimentalDecorators": true, + ... + }, + "angularCompilerOptions": { + "fullTemplateTypeCheck": true, + "preserveWhitespaces": true, + ... + } +} +``` + More information about tsconfig extends can be found in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html). + {@a compiler-options} ## Angular template compiler options diff --git a/aio-ja/content/guide/browser-support.md b/aio-ja/content/guide/browser-support.md index fea8cd245a..df9e9a5c22 100644 --- a/aio-ja/content/guide/browser-support.md +++ b/aio-ja/content/guide/browser-support.md @@ -122,7 +122,7 @@ Note that polyfills cannot magically transform an old, slow browser into a moder ## Enabling polyfills -[Angular CLI](https://github.com/angular/angular-cli/wiki) users enable polyfills through the `src/polyfills.ts` file that +[Angular CLI](cli) users enable polyfills through the `src/polyfills.ts` file that the CLI created with your project. This file incorporates the mandatory and many of the optional polyfills as JavaScript `import` statements. @@ -140,7 +140,7 @@ For example, [if you need the web animations polyfill](http://caniuse.com/#feat= Then open the `polyfills.ts` file and un-comment the corresponding `import` statement as in the following example: - + /** * Required to support Web Animations `@angular/platform-browser/animations`. * Needed for: All but Chrome, Firefox and Opera. http://caniuse.com/#feat=web-animation @@ -553,7 +553,7 @@ computed with the closure com If you are not using the CLI, you should add your polyfill scripts directly to the host web page (`index.html`), perhaps like this. - + <!-- pre-zone polyfills --> <script src="node_modules/core-js/client/shim.min.js"></script> <script src="node_modules/web-animations-js/web-animations.min.js"></script> diff --git a/aio-ja/content/guide/build.md b/aio-ja/content/guide/build.md new file mode 100644 index 0000000000..7fad196614 --- /dev/null +++ b/aio-ja/content/guide/build.md @@ -0,0 +1,492 @@ +# Building and serving Angular apps + +This page discusses build-specific configuration options for Angular projects. + +{@a app-environments} + +## Configuring application environments + +You can define different named build configurations for your project, such as *stage* and *production*, with different defaults. + +Each named build configuration can have defaults for any of the options that apply to the various build targets, such as `build`, `serve`, and `test`. The [Angular CLI](cli) `build`, `serve`, and `test` commands can then replace files with appropriate versions for your intended target environment. + +The following figure shows how a project has multiple build targets, which can be executed using the named configurations that you define. + +
+ build configurations and targets +
+ +### Configure environment-specific defaults + +A project's `src/environments/` folder contains the base configuration file, `environment.ts`, which provides a default environment. +You can add override defaults for additional environments, such as production and staging, in target-specific configuration files. + +For example: + +``` +└──myProject/src/environments/ + └──environment.ts + └──environment.prod.ts + └──environment.stage.ts +``` + +The base file `environment.ts`, contains the default environment settings. For example: + + +export const environment = { + production: false +}; + + +The `build` command uses this as the build target when no environment is specified. +You can add further variables, either as additional properties on the environment object, or as separate objects. +For example, the following adds a default for a variable to the default environment: + +``` +export const environment = { + production: false, + apiUrl: 'http://my-api-url' +}; +``` + +You can add target-specific configuration files, such as `environment.prod.ts`. +The following sets content sets default values for the production build target: + +``` +export const environment = { + production: true + apiUrl: 'http://my-prod-url' +}; +``` + +### Using environment-specific variables in your app + +The following application structure configures build targets for production and staging environments: + +``` +└── src + └── app + ├── app.component.html + └── app.component.ts + └── environments + ├── environment.prod.ts + ├── environment.staging.ts + └── environment.ts +``` + +To use the environment configurations you have defined, your components must import the original environments file: + +``` +import { environment } from './../environments/environment'; +``` + +This ensures that the build and serve commands can find the configurations for specific build targets. + +The following code in the component file (`app.component.ts`) uses an environment variable defined in the configuration files. + +``` +import { Component } from '@angular/core'; +import { environment } from './../environments/environment'; + +@Component({ + selector: 'app-root', + templateUrl: './app.component.html', + styleUrls: ['./app.component.css'] +}) +export class AppComponent { + constructor() { + console.log(environment.production); // Logs false for default environment + } + title = 'app works!'; +} +``` +{@a file-replacement} + +## Configure target-specific file replacements + +The main CLI configuration file, `angular.json`, contains a `fileReplacements` section in the configuration for each build target, which allows you to replace any file with a target-specific version of that file. +This is useful for including target-specific code or variables in a build that targets a specific environment, such as production or staging. + +By default no files are replaced. +You can add file replacements for specific build targets. +For example: + +``` +"configurations": { + "production": { + "fileReplacements": [ + { + "replace": "src/environments/environment.ts", + "with": "src/environments/environment.prod.ts" + } + ], + ... +``` + +This means that when you build your production configuration (using `ng build --prod` or `ng build --configuration=production`), the `src/environments/environment.ts` file is replaced with the target-specific version of the file, `src/environments/environment.prod.ts`. + +You can add additional configurations as required. To add a staging environment, create a copy of `src/environments/environment.ts` called `src/environments/environment.staging.ts`, then add a `staging` configuration to `angular.json`: + +``` +"configurations": { + "production": { ... }, + "staging": { + "fileReplacements": [ + { + "replace": "src/environments/environment.ts", + "with": "src/environments/environment.staging.ts" + } + ] + } +} +``` + +You can add more configuration options to this target environment as well. +Any option that your build supports can be overridden in a build target configuration. + +To build using the staging configuration, run `ng build --configuration=staging`. + +You can also configure the `serve` command to use the targeted build configuration if you add it to the "serve:configurations" section of `angular.json`: + +``` +"serve": { + "builder": "@angular-devkit/build-angular:dev-server", + "options": { + "browserTarget": "your-project-name:build" + }, + "configurations": { + "production": { + "browserTarget": "your-project-name:build:production" + }, + "staging": { + "browserTarget": "your-project-name:build:staging" + } + } +}, +``` + +{@a size-budgets} + +## Configure size budgets + +As applications grow in functionality, they also grow in size. +The CLI allows you to set size thresholds in your configuration to ensure that parts of your application stay within size boundaries that you define. + +Define your size boundaries in the CLI configuration file, `angular.json`, in a `budgets` section for each [configured environment](#app-environments). + +``` +{ + ... + "configurations": { + "production": { + ... + budgets: [] + } + } +} +``` + +You can specify size budgets for the entire app, and for particular parts. +Each budget entry configures a budget of a given type. +Specify size values in the following formats: + +* 123 or 123b: Size in bytes + +* 123kb: Size in kilobytes + +* 123mb: Size in megabytes + +* 12%: Percentage of size relative to baseline. (Not valid for baseline values.) + +When you configure a budget, the build system warns or reports and error when a given part of the app reaches or exceeds a boundary size that you set. + +Each budget entry is a JSON object with the following properties: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyValue
typeThe type of budget. One of: + + * bundle - The size of a specific bundle. + * initial - The initial size of the app. + * allScript - The size of all scripts. + * all - The size of the entire app. + * anyScript - The size of any one script. + * any - The size of any file. + +
name + + The name of the bundle (for `type=bundle`). + +
baselineAn absolute baseline size for percentage values.
maximumWarningWarns when a size exceeds this threshold percentage of the baseline.
maximumErrorReports an error when the size exceeds this threshold percentage of the baseline.
minimumWarningWarns when the size reaches this threshold percentage of the baseline.
minimumErrorReports an error when the size reaches this threshold percentage of the baseline.
warningWarns when the size ??reaches or exceeds?? this threshold percentage of the baseline.
errorReports an error when the size ??reaches or exceeds?? this threshold percentage of the baseline.
+ + +{@a browser-compat} + +## Configuring browser compatibility + +The CLI uses [Autoprefixer](https://github.com/postcss/autoprefixer) to ensure compatibility with different browser and browser versions. +You may find it necessary to target specific browsers or exclude certain browser versions from your build. + +Internally, Autoprefixer relies on a library called [Browserslist](https://github.com/browserslist/browserslist) to figure out which browsers to support with prefixing. +Browserlist looks for configuration options in a `browserlist` property of the package configuration file, or in a configuration file named `.browserslistrc`. +Autoprefixer looks for the Browserlist configuration when it prefixes your CSS. + +* You can tell Autoprefixer what browsers to target by adding a browserslist property to the package configuration file, `package.json`: +``` + "browserslist": [ + "> 1%", + "last 2 versions" + ] +``` + +* Alternatively, you can add a new file, `.browserslistrc`, to the project directory, that specifies browsers you want to support: +``` + ### Supported Browsers + > 1% + last 2 versions +``` + +See the [browserslist repo](https://github.com/browserslist/browserslist) for more examples of how to target specific browsers and versions. + +
+Backward compatibility + +If you want to produce a progressive web app and are using [Lighthouse](https://developers.google.com/web/tools/lighthouse/) to grade the project, add the following browserslist entry to your `package.json` file, in order to eliminate the [old flexbox](https://developers.google.com/web/tools/lighthouse/audits/old-flexbox) prefixes: + +``` +"browserslist": [ + "last 2 versions", + "not ie <= 10", + "not ie_mob <= 10" +] +``` + +
+ +{@a proxy} + +## Proxying to a backend server + +You can use the [proxying support](https://webpack.js.org/configuration/dev-server/#devserver-proxy) in the `webpack` dev server to divert certain URLs to a backend server, by passing a file to the `--proxy-config` build option. +For example, to divert all calls for `http://localhost:4200/api` to a server running on `http://localhost:3000/api`, take the following steps. + +1. Create a file `proxy.conf.json` in the projects `src/` folder, next to `package.json`. + +1. Add the following content to the new proxy file: + ``` + { + "/api": { + "target": "http://localhost:3000", + "secure": false + } + } + ``` + +1. In the CLI configuration file, `angular.json`, add the `proxyConfig` option to the `serve` target: + ``` + ... + "architect": { + "serve": { + "builder": "@angular-devkit/build-angular:dev-server", + "options": { + "browserTarget": "your-application-name:build", + "proxyConfig": "src/proxy.conf.json" + }, + ... + ``` + +1. To run the dev server with this proxy configuration, call `ng serve`. + +You can edit the proxy configuration file to add configuration options; some examples are given below. +For a description of all options, see [webpack DevServer documentation](https://webpack.js.org/configuration/dev-server/#devserver-proxy). + +Note that if you edit the proxy configuration file, you must relaunch the `ng serve` process to make your changes effective. + +### Rewrite the URL path + +The `pathRewrite` proxy configuration option lets you rewrite the URL path at run time. +For example, you can specify the following `pathRewrite` value to the proxy configuration to remove "api" from the end of a path. + +``` +{ + "/api": { + "target": "http://localhost:3000", + "secure": false, + "pathRewrite": { + "^/api": "" + } + } +} +``` + +If you need to access a backend that is not on `localhost`, set the `changeOrigin` option as well. For example: + +``` +{ + "/api": { + "target": "http://npmjs.org", + "secure": false, + "pathRewrite": { + "^/api": "" + }, + "changeOrigin": true + } +} +``` + +To help determine whether your proxy is working as intended, set the `logLevel` option. For example: + +``` +{ + "/api": { + "target": "http://localhost:3000", + "secure": false, + "pathRewrite": { + "^/api": "" + }, + "logLevel": "debug" + } +} +``` + +Proxy log levels are `info` (the default), `debug`, `warn`, `error`, and `silent`. + +### Proxy multiple entries + +You can proxy multiple entries to the same target by defining the configuration in JavaScript. + +Set the proxy configuration file to `proxy.conf.js` (instead of `proxy.conf.json`), and specify configuration files as in the following example. + +``` +const PROXY_CONFIG = [ + { + context: [ + "/my", + "/many", + "/endpoints", + "/i", + "/need", + "/to", + "/proxy" + ], + target: "http://localhost:3000", + secure: false + } +] + +module.exports = PROXY_CONFIG; +``` + +In the CLI configuration file, `angular.json`, point to the JavaScript proxy configuration file: + +``` +... +"architect": { + "serve": { + "builder": "@angular-devkit/build-angular:dev-server", + "options": { + "browserTarget": "your-application-name:build", + "proxyConfig": "src/proxy.conf.js" + }, +... +``` + +### Bypass the proxy + +If you need to optionally bypass the proxy, or dynamically change the request before it's sent, add the bypass option, as shown in this JavaScript example. + +``` +const PROXY_CONFIG = { + "/api/proxy": { + "target": "http://localhost:3000", + "secure": false, + "bypass": function (req, res, proxyOptions) { + if (req.headers.accept.indexOf("html") !== -1) { + console.log("Skipping proxy for browser request."); + return "/index.html"; + } + req.headers["X-Custom-Header"] = "yes"; + } + } +} + +module.exports = PROXY_CONFIG; +``` + +### Using corporate proxy + +If you work behind a corporate proxy, the cannot directly proxy calls to any URL outside your local network. +In this case, you can configure the backend proxy to redirect calls through your corporate proxy using an agent: + + +npm install --save-dev https-proxy-agent + + +When you define an environment variable `http_proxy` or `HTTP_PROXY`, an agent is automatically added to pass calls through your corporate proxy when running `npm start`. + +Use the following content in the JavaScript configuration file. + +``` +var HttpsProxyAgent = require('https-proxy-agent'); +var proxyConfig = [{ + context: '/api', + target: 'http://your-remote-server.com:3000', + secure: false +}]; + +function setupForCorporateProxy(proxyConfig) { + var proxyServer = process.env.http_proxy || process.env.HTTP_PROXY; + if (proxyServer) { + var agent = new HttpsProxyAgent(proxyServer); + console.log('Using corporate proxy server: ' + proxyServer); + proxyConfig.forEach(function(entry) { + entry.agent = agent; + }); + } + return proxyConfig; +} + +module.exports = setupForCorporateProxy(proxyConfig); +``` + diff --git a/aio-ja/content/guide/complex-animation-sequences.md b/aio-ja/content/guide/complex-animation-sequences.md index 929030d432..54eaee3fd9 100644 --- a/aio-ja/content/guide/complex-animation-sequences.md +++ b/aio-ja/content/guide/complex-animation-sequences.md @@ -38,7 +38,7 @@ The following example demonstrates how to use `query()` and `stagger()` function * Animate each element on screen for 0.5 seconds using a custom-defined easing curve, simultaneously fading it in and un-transforming it. - + ## Parallel animation using group() function @@ -51,7 +51,7 @@ You've seen how to add a delay between each successive animation. But you may al 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. - + ## Sequential vs. parallel animations @@ -70,11 +70,11 @@ The filter works in real time as you type. Elements leave the page as you type e The HTML template contains a trigger called `filterAnimation`. - + The component file contains three transitions. - + The animation does the following: diff --git a/aio-ja/content/guide/dependency-injection-in-action.md b/aio-ja/content/guide/dependency-injection-in-action.md index c1b69372ab..d622fde4d1 100644 --- a/aio-ja/content/guide/dependency-injection-in-action.md +++ b/aio-ja/content/guide/dependency-injection-in-action.md @@ -21,7 +21,7 @@ constructor, and lets the framework provide them. The following example shows that `AppComponent` declares its dependence on `LoggerService` and `UserContext`. - + @@ -30,7 +30,7 @@ The following example shows that `AppComponent` declares its dependence on `Logg `UserService`, another service that gathers information about a particular user. - + @@ -68,7 +68,7 @@ by providing that service *at the sub-root component for that branch*. This example shows how to make a different instance of `HeroService` available to `HeroesBaseComponent` by adding it to the `providers` array of the `@Component()` decorator of the sub-component. - + @@ -103,7 +103,7 @@ This is called *sandboxing* because each service and component instance has its In this example, `HeroBiosComponent` presents three instances of `HeroBioComponent`. - + @@ -111,7 +111,7 @@ In this example, `HeroBiosComponent` presents three instances of `HeroBioCompone Each `HeroBioComponent` can edit a single hero's biography. `HeroBioComponent` relies on `HeroCacheService` to fetch, cache, and perform other persistence operations on that hero. - + @@ -122,7 +122,7 @@ as they'd be competing with each other to determine which hero to cache. Instead, each `HeroBioComponent` gets its *own* `HeroCacheService` instance by listing `HeroCacheService` in its metadata `providers` array. - + @@ -179,13 +179,13 @@ that parent component becomes the host. The following example covers this second These decorators can be used individually or together, as shown in the example. This `HeroBiosAndContactsComponent` is a revision of `HeroBiosComponent` which you looked at [above](guide/dependency-injection-in-action#hero-bios-component). - + Focus on the template: - + @@ -193,7 +193,7 @@ Now there's a new `` element between the `` tags. Angular *projects*, or *transcludes*, the corresponding `HeroContactComponent` into the `HeroBioComponent` view, placing it in the `` slot of the `HeroBioComponent` template. - + @@ -206,13 +206,13 @@ The result is shown below, with the hero's telephone number from `HeroContactCom Here's `HeroContactComponent`, which demonstrates the qualifying decorators. - + Focus on the constructor parameters. - + @@ -256,7 +256,7 @@ the app throws an exception when it cannot find the required logger at the host Using a custom provider allows you to provide a concrete implementation for implicit dependencies, such as built-in browser APIs. The following example uses an `InjectionToken` to provide the [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) browser API as a dependency in the `BrowserStorageService`. - + @@ -266,7 +266,7 @@ The `factory` function returns the `localStorage` property that is attached to t Providers can also be scoped by injector through constructor parameter decorators. The following example overrides the `BROWSER_STORAGE` token in the `Component` class `providers` with the `sessionStorage` browser API. The same `BrowserStorageService` is injected twice in the constructor, decorated with `@Self` and `@SkipSelf` to define which injector handles the provider dependency. - + @@ -283,7 +283,7 @@ As a result, you might need to access a component's DOM element. To illustrate, here's a simplified version of `HighlightDirective` from the [Attribute Directives](guide/attribute-directives) page. - + @@ -297,7 +297,7 @@ whose `nativeElement` property exposes the DOM element for the directive to mani The sample code applies the directive's `myHighlight` attribute to two `
` tags, first without a value (yielding the default color) and then with an assigned color value. - + @@ -323,7 +323,7 @@ Angular passes this token to the injector and assigns the result to the paramete The following is a typical example. - + @@ -366,7 +366,7 @@ It's visually simple: a few properties and the logs produced by a logger. The code behind it customizes how and where the DI framework provides dependencies. The use cases illustrate different ways to use the [*provide* object literal](guide/dependency-injection-providers#provide) to associate a definition object with a DI token. - + @@ -384,7 +384,7 @@ You can also use a value provider in a unit test to provide mock data in place o The `HeroOfTheMonthComponent` example has two value providers. - + @@ -405,7 +405,7 @@ The title string literal is immediately available. The `someHero` variable in this example was set earlier in the file as shown below. You can't use a variable whose value will be defined later. - + @@ -425,7 +425,7 @@ extend the default class, or emulate the behavior of the real class in a test ca The following code shows two examples in `HeroOfTheMonthComponent`. - + @@ -446,7 +446,7 @@ Components outside the tree continue to receive the original `LoggerService` ins `DateLoggerService` inherits from `LoggerService`; it appends the current date/time to each message: - + @@ -458,7 +458,7 @@ The `useExisting` provider key lets you map one token to another. In effect, the first token is an *alias* for the service associated with the second token, creating two ways to access the same service object. - + @@ -470,13 +470,13 @@ You might want to shrink that API surface to just the members you actually need. In this example, the `MinimalLogger` [class-interface](#class-interface) reduces the API to two members: - + The following example puts `MinimalLogger` to use in a simplified version of `HeroOfTheMonthComponent`. - + @@ -507,7 +507,7 @@ This is illustrated in the following image, which displays the logging date. The `useFactory` provider key lets you create a dependency object by calling a factory function, as in the following example. - + @@ -530,7 +530,7 @@ The `runnersUpFactory()` returns the *provider factory function*, which can use the passed-in state value and the injected services `Hero` and `HeroService`. - + @@ -570,13 +570,13 @@ That's the subject of the next section. The previous *Hero of the Month* example used the `MinimalLogger` class as the token for a provider of `LoggerService`. - + `MinimalLogger` is an abstract class. - + @@ -604,7 +604,7 @@ Using a class as an interface gives you the characteristics of an interface in a To minimize memory cost, however, the class should have *no implementation*. The `MinimalLogger` transpiles to this unoptimized, pre-minified JavaScript for a constructor function. - + @@ -633,13 +633,13 @@ another token that happens to have the same name. You encountered them twice in the *Hero of the Month* example, in the *title* value provider and in the *runnersUp* factory provider. - + You created the `TITLE` token like this: - + @@ -667,7 +667,7 @@ The `HeroesBaseComponent` can stand on its own. It demands its own instance of `HeroService` to get heroes and displays them in the order they arrive from the database. - + @@ -693,7 +693,7 @@ You must provide the `HeroService` again for *this* component, then pass it down to the base class inside the constructor. - + @@ -731,7 +731,7 @@ appear *above* the class definition. Break the circularity with `forwardRef`. - + diff --git a/aio-ja/content/guide/dependency-injection-navtree.md b/aio-ja/content/guide/dependency-injection-navtree.md index 266dbd3132..c0ee455dbf 100644 --- a/aio-ja/content/guide/dependency-injection-navtree.md +++ b/aio-ja/content/guide/dependency-injection-navtree.md @@ -40,7 +40,7 @@ In the following example, the parent `AlexComponent` has several children includ {@a alex} - + @@ -49,7 +49,7 @@ In the following example, the parent `AlexComponent` has several children includ *Cathy* reports whether or not she has access to *Alex* after injecting an `AlexComponent` into her constructor: - + @@ -98,7 +98,7 @@ inject its parent via the parent's base class*. The sample's `CraigComponent` explores this question. [Looking back](#alex), you see that the `Alex` component *extends* (*inherits*) from a class named `Base`. - + @@ -106,7 +106,7 @@ you see that the `Alex` component *extends* (*inherits*) from a class named `Bas The `CraigComponent` tries to inject `Base` into its `alex` constructor parameter and reports if it succeeded. - + @@ -138,7 +138,7 @@ and add that provider to the `providers` array of the `@Component()` metadata fo {@a alex-providers} - + @@ -149,7 +149,7 @@ The [*forwardRef*](guide/dependency-injection-in-action#forwardref) breaks the c *Carol*, the third of *Alex*'s child components, injects the parent into its `parent` parameter, the same way you've done it before. - + @@ -177,7 +177,7 @@ That means he must both *inject* the `Parent` class interface to get *Alice* and Here's *Barry*. - + @@ -190,11 +190,11 @@ For now, focus on *Barry*'s constructor. - + - + @@ -229,7 +229,7 @@ You [learned earlier](guide/dependency-injection-in-action#class-interface) that The example defines a `Parent` class interface. - + @@ -241,7 +241,7 @@ Such a narrow interface helps decouple the child component class from its parent A component that could serve as a parent *should* implement the class interface as the `AliceComponent` does. - + @@ -251,7 +251,7 @@ Doing so adds clarity to the code. But it's not technically necessary. Although `AlexComponent` has a `name` property, as required by its `Base` class, its class signature doesn't mention `Parent`. - + @@ -277,19 +277,19 @@ It doesn't in this example *only* to demonstrate that the code will compile and Writing variations of the same parent *alias provider* gets old quickly, especially this awful mouthful with a [*forwardRef*](guide/dependency-injection-in-action#forwardref). - + You can extract that logic into a helper function like the following. - + Now you can add a simpler, more meaningful parent provider to your components. - + @@ -299,14 +299,14 @@ The application might have a variety of parent types, each with its own class in Here's a revised version that defaults to `parent` but also accepts an optional second parameter for a different parent class interface. - + And here's how you could use it with a different parent type. - + diff --git a/aio-ja/content/guide/dependency-injection-providers.md b/aio-ja/content/guide/dependency-injection-providers.md index b654d26e20..302ed985c5 100644 --- a/aio-ja/content/guide/dependency-injection-providers.md +++ b/aio-ja/content/guide/dependency-injection-providers.md @@ -130,7 +130,7 @@ like the title of the application or the address of a web API endpoint. These configuration objects aren't always instances of a class. They can be object literals, as shown in the following example. - + {@a interface-not-valid-token} @@ -147,7 +147,7 @@ In TypeScript, an interface is a design-time artifact, and doesn't have a runtim -
+
This might seem strange if you're used to dependency injection in strongly typed languages where an interface is the preferred dependency lookup key. However, JavaScript, doesn't have interfaces, so when TypeScript is transpiled to JavaScript, the interface disappears. @@ -157,13 +157,13 @@ There is no interface type information left for Angular to find at runtime. One alternative is to provide and inject the configuration object in an NgModule like `AppModule`. - + Another solution to choosing a provider token for non-class dependencies is to define and use an `InjectionToken` object. The following example shows how to define such a token. - + The type parameter, while optional, conveys the dependency's type to developers and tooling. @@ -177,10 +177,10 @@ Register the dependency provider using the `InjectionToken` object: Now you can inject the configuration object into any constructor that needs it, with the help of an `@Inject()` parameter decorator. - + -
+
Although the `AppConfig` interface plays no role in dependency injection, it supports typing of the configuration object within the class. @@ -215,21 +215,21 @@ who is authorized and who isn't. To resolve this, we give the `HeroService` constructor a boolean flag to control display of secret heroes. - + You can inject `Logger`, but you can't inject the `isAuthorized` flag. Instead, you can use a factory provider to create a new logger instance for `HeroService`. A factory provider needs a factory function. - + Although `HeroService` has no access to `UserService`, the factory function does. You inject both `Logger` and `UserService` into the factory provider and let the injector pass them along to the factory function. - + * The `useFactory` field tells Angular that the provider is a factory function whose implementation is `heroServiceFactory`. @@ -248,10 +248,10 @@ The following shows the new and the old implementations side-by-side. - + - + @@ -293,7 +293,7 @@ When you provide multiple sets of routes using [RouterModule.forRoot](api/router and [RouterModule.forChild](api/router/RouterModule#forchild) in a single module, the [ROUTES](api/router/ROUTES) token combines all the different provided sets of routes into a single value. -
Search for [Constants in API documentation](api?type=const) to find more built-in tokens. @@ -309,7 +309,7 @@ When providers are tree-shakable, the Angular compiler removes the associated services from the final output when it determines that they are not used in your application. This significantly reduces the size of your bundles. -
+
Ideally, if an application isn't injecting a service, it shouldn't be included in the final output. However, Angular has to be able to identify at build time whether the service will be required or not. @@ -322,13 +322,13 @@ Thus, services provided at the NgModule or component level are not tree-shakable The following example of non-tree-shakable providers in Angular configures a service provider for the injector of an NgModule. - + This module can then be imported into your application module to make the service available for injection in your app, as shown in the following example. - + When `ngc` runs, it compiles `AppModule` into a module factory, which contains definitions for all the providers declared in all the modules it includes. At runtime, this factory becomes an injector that instantiates these services. @@ -340,13 +340,13 @@ You can make a provider tree-shakable by specifying it in the `@Injectable()` de The following example shows the tree-shakable equivalent to the `ServiceModule` example above. - + The service can be instantiated by configuring a factory function, as in the following example. - + -
+
To override a tree-shakable provider, configure the injector of a specific NgModule or component with another provider, using the `providers: []` array syntax of the `@NgModule()` or `@Component()` decorator. diff --git a/aio-ja/content/guide/deployment.md b/aio-ja/content/guide/deployment.md index 95e3799a2f..b30bb2ddda 100644 --- a/aio-ja/content/guide/deployment.md +++ b/aio-ja/content/guide/deployment.md @@ -1,60 +1,192 @@ # Deployment -This page describes techniques for deploying your Angular application to a remote server. +When you are ready to deploy your Angular application to a remote server, you have various options for +deployment. {@a dev-deploy} {@a copy-files} ## Simplest deployment possible -For the simplest deployment, build for development and copy the output directory to a web server. +For the simplest deployment, create a production build and copy the output directory to a web server. -1. Start with the development build +1. Start with the production build: - ng build + ng build --prod 2. Copy _everything_ within the output folder (`dist/` by default) to a folder on the server. +3. Configure the server to redirect requests for missing files to `index.html`. +Learn more about server-side redirects [below](#fallback). -3. If you copy the files into a server _sub-folder_, append the build flag, `--base-href` and set the `` appropriately.

+This is the simplest production-ready deployment of your application. - For example, if the `index.html` is on the server at `/my/app/index.html`, set the _base href_ to - `` like this. +{@a deploy-to-github} - - ng build --base-href=/my/app/ +## Deploy to GitHub pages + +Another simple way to deploy your Angular app is to use [GitHub Pages](https://help.github.com/articles/what-is-github-pages/). + +1. You need to [create a GitHub account](https://github.com/join) if you don't have one, and then [create a repository](https://help.github.com/articles/create-a-repo/) for your project. +Make a note of the user name and project name in GitHub. + +1. Build your project using Github project name, with the Angular CLI command [`ng build`](cli/build) and the options shown here: + + ng build --prod --output-path docs --base-href + + +1. When the build is complete, make a copy of `docs/index.html` and name it `docs/404.html`. + +1. Commit your changes and push. + +1. On the GitHub project page, configure it to [publish from the docs folder](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch). + +You can see your deployed page at `https://.github.io//`. + +
+ RewriteEngine On + # If an existing asset or directory is requested go to it as it is + RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR] + RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d + RewriteRule ^ - [L] + + # If the requested resource doesn't exist, use index.html + RewriteRule ^ /index.html - You'll see that the `` is set properly in the generated `dist/index.html`.

- If you copy to the server's root directory, omit this step and leave the `` alone.

- Learn more about the role of `` [below](guide/deployment#base-tag). +* [Nginx](http://nginx.org/): use `try_files`, as described in +[Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps), +modified to serve `index.html`: -4. Configure the server to redirect requests for missing files to `index.html`. -Learn more about server-side redirects [below](guide/deployment#fallback). + + try_files $uri $uri/ /index.html; + -This is _not_ a production deployment. It's not optimized and it won't be fast for users. -It might be good enough for sharing your progress and ideas internally with managers, teammates, and other stakeholders. +* [IIS](https://www.iis.net/): add a rewrite rule to `web.config`, similar to the one shown +[here](http://stackoverflow.com/a/26152011/2116927): -{@a optimize} + + <system.webServer> + <rewrite> + <rules> + <rule name="Angular Routes" stopProcessing="true"> + <match url=".*" /> + <conditions logicalGrouping="MatchAll"> + <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> + <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> + </conditions> + <action type="Rewrite" url="/index.html" /> + </rule> + </rules> + </rewrite> + </system.webServer> -## Optimize for production + -Although deploying directly from the development environment works, -you can generate an optimized build with additional CLI command line flags, -starting with `--prod`. -### Build with _--prod_ +* [GitHub Pages](https://pages.github.com/): you can't +[directly configure](https://github.com/isaacs/github/issues/408) +the GitHub Pages server, but you can add a 404 page. +Copy `index.html` into `404.html`. +It will still be served as the 404 response, but the browser will process that page and load the app properly. +It's also a good idea to +[serve from `docs/` on master](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch) +and to +[create a `.nojekyll` file](https://www.bennadel.com/blog/3181-including-node-modules-and-vendors-folders-in-your-github-pages-site.htm) - - ng build --prod - -The `--prod` _meta-flag_ engages the following optimization features. +* [Firebase hosting](https://firebase.google.com/docs/hosting/): add a +[rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites). + + + "rewrites": [ { + "source": "**", + "destination": "/index.html" + } ] + + + +{@a cors} + +### Requesting services from a different server (CORS) + +Angular developers may encounter a + +cross-origin resource sharing error when making a service request (typically a data service request) +to a server other than the application's own host server. +Browsers forbid such requests unless the server permits them explicitly. + +There isn't anything the client application can do about these errors. +The server must be configured to accept the application's requests. +Read about how to enable CORS for specific servers at +enable-cors.org. + +
+ +{@a optimize} + +## Production optimizations + +The `--prod` _meta-flag_ engages the following build optimization features. * [Ahead-of-Time (AOT) Compilation](guide/aot-compiler): pre-compiles Angular component templates. * [Production mode](#enable-prod-mode): deploys the production environment which enables _production mode_. @@ -63,32 +195,22 @@ The `--prod` _meta-flag_ engages the following optimization features. * Uglification: rewrites code to use short, cryptic variable and function names. * Dead code elimination: removes unreferenced modules and much unused code. -The remaining [copy deployment steps](#copy-files) are the same as before. - -You may further reduce bundle sizes by adding the `build-optimizer` flag. +See [`ng build`](cli/build) for more about CLI build options and what they do. - - ng build --prod --build-optimizer - - -See the [CLI Documentation](https://github.com/angular/angular-cli/wiki/build) -for details about available build options and what they do. {@a enable-prod-mode} -### Enable production mode +### Enable runtime production mode -Angular apps run in development mode by default, as you can see by the following message on the browser -console: +In addition to build optimizations, Angular also has a runtime production mode. Angular apps run in development mode by default, as you can see by the following message on the browser console: Angular is running in the development mode. Call enableProdMode() to enable the production mode. -Switching to _production mode_ can make it run faster by disabling development specific checks such as the dual change detection cycles. +Switching to _production mode_ makes it run faster by disabling development specific checks such as the dual change detection cycles. -Building for production (or appending the `--environment=prod` flag) enables _production mode_ -Look at the CLI-generated `main.ts` to see how this works. +When you enable production builds via `--prod` command line flag, the runtime production mode is enabled as well. {@a lazy-loading} @@ -102,22 +224,24 @@ Configure the Angular Router to defer loading of all other modules (and their as or by [_lazy loading_](guide/router#asynchronous-routing "Lazy loading") them on demand. -#### Don't eagerly import something from a lazy loaded module +
` to the se When the `base` tag is mis-configured, the app fails to load and the browser console displays `404 - Not Found` errors for the missing files. Look at where it _tried_ to find those files and adjust the base tag appropriately. -## _build_ vs. _serve_ - -You'll probably prefer `ng build` for deployments. +## Building and serving for deployment -The **ng build** command is intended for building the app and deploying the build artifacts elsewhere. -The **ng serve** command is intended for fast, local, iterative development. +When you are designing and developing applications, you typically use `ng serve` to build your app for fast, local, iterative development. +When you are ready to deploy, however, you must use the `ng build` command to build the app and deploy the build artifacts elsewhere. -Both `ng build` and `ng serve` **clear the output folder** before they build the project. -The `ng build` command writes generated build artifacts to the output folder. -The `ng serve` command does not. -It serves build artifacts from memory instead for a faster development experience. +Both `ng build` and `ng serve` clear the output folder before they build the project, but only the `ng build` command writes the generated build artifacts to the output folder.
@@ -222,160 +341,13 @@ To output to a different folder, change the `outputPath` in `angular.json`.
-The `ng serve` command builds, watches, and serves the application from a local CLI development server. - -The `ng build` command generates output files just once and does not serve them. -The `ng build --watch` command will regenerate output files when source files change. -This `--watch` flag is useful if you're building during development and -are automatically re-deploying changes to another server. - - -See the [CLI `build` topic](https://github.com/angular/angular-cli/wiki/build) for more details and options. - -
- -{@a server-configuration} - -## Server configuration - -This section covers changes you may have make to the server or to files deployed to the server. - -{@a fallback} - -### Routed apps must fallback to `index.html` - -Angular apps are perfect candidates for serving with a simple static HTML server. -You don't need a server-side engine to dynamically compose application pages because -Angular does that on the client-side. - -If the app uses the Angular router, you must configure the server -to return the application's host page (`index.html`) when asked for a file that it does not have. - -{@a deep-link} - - -A routed application should support "deep links". -A _deep link_ is a URL that specifies a path to a component inside the app. -For example, `http://www.mysite.com/heroes/42` is a _deep link_ to the hero detail page -that displays the hero with `id: 42`. - -There is no issue when the user navigates to that URL from within a running client. -The Angular router interprets the URL and routes to that page and hero. - -But clicking a link in an email, entering it in the browser address bar, -or merely refreshing the browser while on the hero detail page — -all of these actions are handled by the browser itself, _outside_ the running application. -The browser makes a direct request to the server for that URL, bypassing the router. - -A static server routinely returns `index.html` when it receives a request for `http://www.mysite.com/`. -But it rejects `http://www.mysite.com/heroes/42` and returns a `404 - Not Found` error *unless* it is -configured to return `index.html` instead. - -#### Fallback configuration examples - -There is no single configuration that works for every server. -The following sections describe configurations for some of the most popular servers. -The list is by no means exhaustive, but should provide you with a good starting point. - -#### Development servers - -* [Lite-Server](https://github.com/johnpapa/lite-server): the default dev server installed with the -[Quickstart repo](https://github.com/angular/quickstart) is pre-configured to fallback to `index.html`. - - -* [Webpack-Dev-Server](https://github.com/webpack/webpack-dev-server): setup the -`historyApiFallback` entry in the dev server options as follows: - - - historyApiFallback: { - disableDotRule: true, - htmlAcceptHeaders: ['text/html', 'application/xhtml+xml'] - } - - - -#### Production servers - -* [Apache](https://httpd.apache.org/): add a -[rewrite rule](http://httpd.apache.org/docs/current/mod/mod_rewrite.html) to the `.htaccess` file as shown - (https://ngmilk.rocks/2015/03/09/angularjs-html5-mode-or-pretty-urls-on-apache-using-htaccess/): - - - RewriteEngine On - # If an existing asset or directory is requested go to it as it is - RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR] - RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d - RewriteRule ^ - [L] - - # If the requested resource doesn't exist, use index.html - RewriteRule ^ /index.html - - - -* [NGinx](http://nginx.org/): use `try_files`, as described in -[Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps), -modified to serve `index.html`: - - - try_files $uri $uri/ /index.html; - - - -* [IIS](https://www.iis.net/): add a rewrite rule to `web.config`, similar to the one shown -[here](http://stackoverflow.com/a/26152011/2116927): - - - <system.webServer> - <rewrite> - <rules> - <rule name="Angular Routes" stopProcessing="true"> - <match url=".*" /> - <conditions logicalGrouping="MatchAll"> - <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> - <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> - </conditions> - <action type="Rewrite" url="/index.html" /> - </rule> - </rules> - </rewrite> - </system.webServer> - - - +The `ng serve` command builds, watches, and serves the application from local memory, using a local development server. +When you have deployed your app to another server, however, you might still want to serve the app so that you can continue to see changes that you make in it. +You can do this by adding the `--watch` option to the `ng build` command. -* [GitHub Pages](https://pages.github.com/): you can't -[directly configure](https://github.com/isaacs/github/issues/408) -the GitHub Pages server, but you can add a 404 page. -Copy `index.html` into `404.html`. -It will still be served as the 404 response, but the browser will process that page and load the app properly. -It's also a good idea to -[serve from `docs/` on master](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch) -and to -[create a `.nojekyll` file](https://www.bennadel.com/blog/3181-including-node-modules-and-vendors-folders-in-your-github-pages-site.htm) +``` +ng build --watch +``` +Like the `ng serve` command, this regenerates output files when source files change. - -* [Firebase hosting](https://firebase.google.com/docs/hosting/): add a -[rewrite rule](https://firebase.google.com/docs/hosting/url-redirects-rewrites#section-rewrites). - - - "rewrites": [ { - "source": "**", - "destination": "/index.html" - } ] - - - -{@a cors} - -### Requesting services from a different server (CORS) - -Angular developers may encounter a - -cross-origin resource sharing error when making a service request (typically a data service request) -to a server other than the application's own host server. -Browsers forbid such requests unless the server permits them explicitly. - -There isn't anything the client application can do about these errors. -The server must be configured to accept the application's requests. -Read about how to enable CORS for specific servers at -enable-cors.org. +For complete details of the CLI commands, see the [CLI command reference](cli). diff --git a/aio-ja/content/guide/docs-style-guide.md b/aio-ja/content/guide/docs-style-guide.md index 48d875d8f0..65cb4efb19 100644 --- a/aio-ja/content/guide/docs-style-guide.md +++ b/aio-ja/content/guide/docs-style-guide.md @@ -310,22 +310,22 @@ _This_ "Authors Doc Style Guide" has its own sample application, located in the The following _code-example_ displays the sample's `app.module.ts`. - + Here's the brief markup that produced that lengthy snippet: ```html + header="src/app/app.module.ts"> ``` You identified the snippet's source file by setting the `path` attribute to sample folder's location _within_ `content/examples`. In this example, that path is `docs-style-guide/src/app/app.module.ts`. -You added a header to tell the reader where to find the file by setting the `title` attribute. -Following convention, you set the `title` attribute to the file's location within the sample's root folder. +You added a header to tell the reader where to find the file by setting the `header` attribute. +Following convention, you set the `header` attribute to the file's location within the sample's root folder.
@@ -343,7 +343,7 @@ If you want to include an ignored code file in your project and display it in a The preferred way to un-ignore a file is to update the `content/examples/.gitignore` like this: - + # my-guide !my-guide/src/something.js !my-guide/more-javascript*.js @@ -357,7 +357,7 @@ You control the _code-example_ output by setting one or more of its attributes: * `path`- the path to the file in the `content/examples` folder. -* `title`- the header of the code listing. +* `header`- the header of the code listing. * `region`- displays the source file fragment with that region name; regions are identified by _docregion_ markup in the source file, as explained [below](#region "Displaying a code fragment"). @@ -395,7 +395,7 @@ A couple of observations: 1. The `region` value, `"class"`, is the name of the `#docregion` in the source file. Confirm that by looking at `content/examples/docs-style-guide/src/app/app.module.ts` -1. Omitting the `title` is fine when the source of the fragment is obvious. We just said that this is a fragment of the `app.module.ts` file which was displayed immediately above, in full, with a header. +1. Omitting the `header` is fine when the source of the fragment is obvious. We just said that this is a fragment of the `app.module.ts` file which was displayed immediately above, in full, with a header. There's no need to repeat the header. 1. The line numbers disappeared. By default, the doc viewer omits line numbers when there are fewer than 10 lines of code; it adds line numbers after that. You can turn line numbers on or off explicitly by setting the `linenums` attribute. @@ -415,11 +415,11 @@ Here's the markup for an "avoid" example in the + header="app/heroes/hero-button/hero-button.component.ts"> ``` - + {@a code-tabs} @@ -434,29 +434,29 @@ Code tabs display code much like _code examples_ do. The added advantage is tha #### Code-pane attributes * `path` - a file in the content/examples folder -* `title` - seen in the header of a tab +* `header` - seen in the header of a tab * `linenums` - overrides the `linenums` property at the `code-tabs` level for this particular pane. The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when the number of lines of code are greater than 10. -The next example displays multiple code tabs, each with its own title. +The next example displays multiple code tabs, each with its own header. It demonstrates control over display of line numbers at both the `` and `` levels. @@ -469,21 +469,21 @@ The `linenums` attribute in the second pane restores line numbering for _itself ```html @@ -548,7 +548,7 @@ The `src/main.ts` is a simple example of a file with a single _#docregion_ at th + header="src/main.ts">
@@ -622,12 +622,12 @@ Here's are the two corresponding code snippets displayed side-by-side. @@ -660,12 +660,12 @@ Here's an example that excerpts certain scripts from `package.json` into a parti + header="package.json (selected scripts)"> ```html + header="package.json (selected scripts)"> ``` #### Partial file naming @@ -689,7 +689,7 @@ Remember to exclude these files from stackblitz by listing them in the `stackbli + header="stackblitz.json"> {@a live-examples} ## Live examples diff --git a/aio-ja/content/guide/file-structure.md b/aio-ja/content/guide/file-structure.md new file mode 100644 index 0000000000..ad6d53f3eb --- /dev/null +++ b/aio-ja/content/guide/file-structure.md @@ -0,0 +1,126 @@ +# Workspace and project file structure + +You develop apps in the context of an Angular [workspace](guide/glossary#workspace). A workspace contains the files for one or more [projects](guide/glossary#project). A project is the set of files that comprise a standalone app, a library, or a set of end-to-end (e2e) tests. + +The Angular CLI command `ng new ` gets you started. +When you run this command, the CLI installs the necessary Angular npm packages and other dependencies in a new workspace, with a root folder named *project_name*. +It also creates the following workspace and starter project files: + +* An initial skeleton app project, also called *project_name* (in the `src/` subfolder). +* An end-to-end test project (in the `e2e/` subfolder). +* Related configuration files. + +The initial app project contains a simple Welcome app, ready to run. + +## Workspace files + +The top level of the workspace contains a number of workspace-wide configuration files. + +| WORKSPACE CONFIG FILES | PURPOSE | +| :--------------------- | :------------------------------------------| +| `.editorconfig` | Configuration for code editors. See [EditorConfig](https://editorconfig.org/). | +| `.gitignore` | Specifies intentionally untracked files that [Git](https://git-scm.com/) should ignore. | +| `angular.json` | CLI configuration for all projects in the workspace, including configuration options for build, serve, and test tools that the CLI uses, such as [Karma](https://karma-runner.github.io/) and [Protractor](http://www.protractortest.org/). | +| `node_modules` | Provides [npm packages](guide/npm-packages) to the entire workspace. | +| `package.json` | Lists package dependencies. See [npm documentation](https://docs.npmjs.com/files/package.json) for the specific format and contents of this file.| +| `tsconfig.app.json` | Default [TypeScript](https://www.typescriptlang.org/) configuration for apps in the workspace. | +| `tsconfig.spec.json` | Default TypeScript configuration for e2e test apps in the workspace. | +| `tslint.json` | Default [TSLint](https://palantir.github.io/tslint/) configuration for apps in the workspace. | +| `README.md` | Introductory documentation. | +| `package-lock.json` | Provides version information for all packages installed into `node_modules` by the npm client. See [npm documentation](https://docs.npmjs.com/files/package-lock.json) for details. If you use the yarn client, this file will be [yarn.lock](https://yarnpkg.com/lang/en/docs/yarn-lock/) instead. | + +All projects within a workspace share this configuration context. +Project-specific [TypeScript](https://www.typescriptlang.org/) configuration files inherit from the workspace-wide `tsconfig.*.json`, and app-specific [TSLint](https://palantir.github.io/tslint/) configuration files inherit from the workspace-wide `tslint.json`. + +### Default app project files + +The CLI command `ng new my-app` creates a workspace folder named "my-app" and generates a new app skeleton. +This initial app is the *default app* for CLI commands (unless you change the default after creating additional apps). + +A newly generated app contains the source files for a root module, with a root component and template. +When the workspace file structure is in place, you can use the `ng generate` command on the command line to add functionality and data to the initial app. + +