填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

原理圖(Schematic)

Generating code using schematics

原理圖是一個基於範本的支援複雜邏輯的程式碼產生器。它是一組透過產生程式碼或修改程式碼來轉換軟體專案的指令。原理圖會打包成集合(collection)並用 npm 安裝。

A schematic is a template-based code generator that supports complex logic. It is a set of instructions for transforming a software project by generating or modifying code. Schematics are packaged into collections and installed with npm.

原理圖的集合可以作為一個強大的工具,以建立、修改和維護任何軟體專案,特別是當要自訂 Angular 專案以滿足你自己組織的特定需求時。例如,你可以藉助原理圖來用預定義的範本或佈局產生常用的 UI 模式或特定的元件。你也可以使用原理圖來強制執行架構規則和約定,讓你的專案保持一致性和互操作性。

The schematic collection can be a powerful tool for creating, modifying, and maintaining any software project, but is particularly useful for customizing Angular projects to suit the particular needs of your own organization. You might use schematics, for example, to generate commonly-used UI patterns or specific components, using predefined templates or layouts. You can use schematics to enforce architectural rules and conventions, making your projects consistent and inter-operative.

Angular CLI 中的原理圖

Schematics for the Angular CLI

原理圖是 Angular 生態系統的一部分。Angular CLI 使用原理圖對 Web 應用專案進行轉換。 你可以修改這些原理圖,並定義新的原理圖,比如更新程式碼以修復依賴中的重大變更,或者把新的配置項或框架新增到現有的專案中。

Schematics are part of the Angular ecosystem. The Angular CLI uses schematics to apply transforms to a web-app project. You can modify these schematics, and define new ones to do things like update your code to fix breaking changes in a dependency, for example, or to add a new configuration option or framework to an existing project.

@schematics/angular 集合中的原理圖是 ng generateng add 命令的預設原理圖。此包裡包含一些有名字的原理圖,可用於配置 ng generate 子命令的選項,比如 ng generate componentng generate serviceng generate 的子命令是相應原理圖的簡寫。你可以用長格式來指定要產生的原理圖(或原理圖集合):

Schematics that are included in the @schematics/angular collection are run by default by the commands ng generate and ng add. The package contains named schematics that configure the options that are available to the CLI for ng generate sub-commands, such as ng generate component and ng generate service. The subcommands for ng generate are shorthand for the corresponding schematic. You can specify a particular schematic (or collection of schematics) to generate, using the long form:

      
      ng generate my-schematic-collection:my-schematic-name
    

或者

or

      
      ng generate my-schematic-name --collection collection-name
    

配置 CLI 的原理圖

Configuring CLI schematics

與原理圖相關聯的 JSON 模式會告訴 Angular CLI 命令和子命令都有哪些選項以及預設值。這些預設值可以透過在命令列中為該選項提供不同的值來進行覆蓋。要了解如何更改程式碼產生選項的預設值,請參閱“ 工作區配置 ”。

A JSON schema associated with a schematic tells the Angular CLI what options are available to commands and subcommands, and determines the defaults. These defaults can be overridden by providing a different value for an option on the command line. See Workspace Configuration for information about how you can change the generation option defaults for your workspace.

CLI 中那些用來產生專案及其部件的預設原理圖,其 JSON 模式收集在 @schematics/angular套件中。該模式描述了 CLI 中每個可用的 ng generate 子命令選項,如 --help 輸出中所示。

The JSON schemas for the default schematics used by the CLI to generate projects and parts of projects are collected in the package @schematics/angular. The schema describes the options available to the CLI for each of the ng generate sub-commands, as shown in the --help output.

編寫函式庫的原理圖

Developing schematics for libraries

作為一名函式庫開發人員,你可以建立自己的自訂原理圖集合,以便把你的函式庫與 Angular CLI 整合在一起。

As a library developer, you can create your own collections of custom schematics to integrate your library with the Angular CLI.

  • 新增(Add)原理圖允許開發人員使用 ng add 在 Angular 工作區中安裝你的函式庫。

    An add schematic allows developers to install your library in an Angular workspace using ng add.

  • 產生(Generation)原理圖可以告訴 ng generate 子命令如何修改專案、新增配置和指令碼,以及為函式庫中定義的工件提供腳手架。

    Generation schematics can tell the ng generate subcommands how to modify projects, add configurations and scripts, and scaffold artifacts that are defined in your library.

  • 更新(Update)原理圖可以告訴 ng update 命令,如何更新函式庫的依賴,並在發佈新版本時調整其中的重大變更。

    An update schematic can tell the ng update command how to update your library's dependencies and adjust for breaking changes when you release a new version.

要了解它們的更多細節以及如何建立它們,請參閱:

For more details of what these look like and how to create them, see:

新增(Add)原理圖

Add schematics

函式庫中通常都會提供一個新增原理圖,以便透過 ng add 把這個函式庫新增到現有專案中。add 命令會執行套件管理器來下載新的依賴,並呼叫一個原理圖形式的安裝指令碼。

An add schematic is typically supplied with a library, so that the library can be added to an existing project with ng add. The add command uses your package manager to download new dependencies, and invokes an installation script that is implemented as a schematic.

例如,@angular/material原理圖會要求 add 命令安裝並設定 Angular Material 及其主題,並註冊可透過 ng generate 建立的新啟動器元件。你可以把它作為自己的 "新增原理圖" 的範例。

For example, the @angular/materialschematic tells the add command to install and set up Angular Material and theming, and register new starter components that can be created with ng generate. You can look at this one as an example and model for your own add schematic.

合作伙伴和第三方函式庫也可以透過新增原理圖來支援 Angular CLI。例如,@ng-bootstrap/schematics 會把 ng-bootstrap 新增到應用中,@clr/angular 會安裝並設定 VMWare 的 Clarity

Partner and third party libraries also support the Angular CLI with add schematics. For example, @ng-bootstrap/schematics adds ng-bootstrap to an app, and @clr/angular installs and sets up Clarity from VMWare.

"新增原理圖" 還可以透過更改配置、新增額外依賴(比如Polyfill指令碼),或者新增程式包特有的初始化程式碼來修改專案。例如,@angular/pwa 原理圖會透過新增一個應用清單(manifest)和 Service Worker,來把你的應用變成一個 PWA,@angular/elements 原理圖添加了 document-register-element.js Polyfill指令碼和 Angular Elelments 的依賴項。

An add schematic can also update a project with configuration changes, add additional dependencies (such as polyfills), or scaffold package-specific initialization code. For example, the @angular/pwa schematic turns your application into a PWA by adding an application manifest and service worker, and the @angular/elements  schematic adds the document-register-element.js polyfill and dependencies for Angular Elements.

產生(Generation)原理圖

Generation schematics

產生器原理圖是 ng generate 的操作指令。 那些已經有文件的子命令會使用預設的 Angular 產生器原理圖,但你可以在子命令中指定另一個原理圖來產生你的函式庫中定義的那些工件。

Generation schematics are instructions for the ng generate command. The documented sub-commands use the default Angular generation schematics, but you can specify a different schematic (in place of a sub-command) to generate an artifact defined in your library.

例如,Angular Material 為它定義的一些 UI 元件提供了產生器原理圖。下面的命令會使用其中一個原理圖來渲染一個 Angular Material 的 <mat-table> 元件,它預先配置了一個用於排序和分頁的資料來源。

Angular Material, for example, supplies generation schematics for the UI components that it defines. The following command uses one of these schematics to render an Angular Material <mat-table> that is pre-configured with a datasource for sorting and pagination.

      
      ng generate @angular/material:table 

    

更新原理圖

Update schematics

ng update 命令可以用來更新工作區的函式庫依賴。如果你沒有提供任何選項或使用了 help 選項,該命令會檢查你的工作區並建議要更新哪些函式庫。

The ng update command can be used to update your workspace's library dependencies. If you supply no options or use the help option, the command examines your workspace and suggests libraries to update.

      
      ng update
    We analyzed your package.json, there are some packages to update:

      Name                               Version                  Command to update
     --------------------------------------------------------------------------------
      @angular/cdk                       7.2.2 -> 7.3.1           ng update @angular/cdk
      @angular/cli                       7.2.3 -> 7.3.0           ng update @angular/cli
      @angular/core                      7.2.2 -> 7.2.3           ng update @angular/core
      @angular/material                  7.2.2 -> 7.3.1           ng update @angular/material
      rxjs                               6.3.3 -> 6.4.0           ng update rxjs

There might be additional packages that are outdated.
    Run "ng update --all" to try to update all at the same time.
    

如果你給這個命令指定一組要更新的函式庫(或 --all 標誌),它就會更新這些函式庫、這些函式庫的對等依賴,以及對等依賴的對等依賴。

If you pass the command a set of libraries to update (or the --all flag), it updates those libraries, their peer dependencies, and the peer dependencies that depend on them.

如果存在不一致(例如,如果在某個簡單的 semver 範圍內無法匹配對等依賴),那麼該命令會產生一個錯誤,並且不會更改工作區中的任何內容。

If there are inconsistencies (for example, if peer dependencies cannot be matched by a simple semver range), the command generates an error and does not change anything in the workspace.

我們建議你不要強制更新所有的依賴項,而應該首先嚐試更新特定的依賴項。

We recommend that you do not force an update of all dependencies by default. Try updating specific dependencies first.

關於 ng update 命令工作原理的更多資訊,請參閱“更新命令”

For more about how the ng update command works, see Update Command.

如果你建立的新版本的函式庫引入了潛在的重大更改,你可以提供一個更新原理圖,讓 ng update 命令能夠自動解決所更新專案中的任何重大修改。

If you create a new version of your library that introduces potential breaking changes, you can provide an update schematic to enable the ng update command to automatically resolve any such changes in the project being updated.

例如,假設你要更新 Angular Material 函式庫。

For example, suppose you want to update the Angular Material library.

      
      ng update @angular/material
    

該命令會在你的工作區的 package.json 中更新 @angular/material 及其依賴項 @angular/cdk。如果任何一個套件中包含了涵蓋從現有版本到新版本的遷移規則的更新原理圖,那麼該命令就會在你的工作區中執行這個原理圖。

This command updates both @angular/material and its dependency @angular/cdk in your workspace's package.json. If either package contains an update schematic that covers migration from the existing version to a new version, the command runs that schematic on your workspace.