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

docs: ident the library shematics guide properly (#41755) 

PR Close #41755
This commit is contained in:
Aristeidis Bampakos 2021-04-21 23:49:55 +03:00 committed by Jessica Janiuk
parent 122c8ba0e3
commit dfdd4a2d74
1 changed files with 61 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
aio/content/guide/schematics-for-libraries.md
View File

@ -21,8 +21,8 @@ The following steps show you how to add initial support without modifying any pr
1. Edit the `collection.json` file to define the initial schema for your collection. 1. Edit the `collection.json` file to define the initial schema for your collection.
<code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.1.json"> <code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.1.json">
</code-example> </code-example>
* The `$schema` path is relative to the Angular Devkit collection schema. * The `$schema` path is relative to the Angular Devkit collection schema.
* The `schematics` object describes the named schematics that are part of this collection. * The `schematics` object describes the named schematics that are part of this collection.
@ -31,8 +31,8 @@ The following steps show you how to add initial support without modifying any pr
1. In your library project's `package.json` file, add a "schematics" entry with the path to your schema file. 1. In your library project's `package.json` file, add a "schematics" entry with the path to your schema file.
The Angular CLI uses this entry to find named schematics in your collection when it runs commands. The Angular CLI uses this entry to find named schematics in your collection when it runs commands.
<code-example header="projects/my-lib/package.json (Schematics Collection Reference)" path="schematics-for-libraries/projects/my-lib/package.json" region="collection"> <code-example header="projects/my-lib/package.json (Schematics Collection Reference)" path="schematics-for-libraries/projects/my-lib/package.json" region="collection">
</code-example> </code-example>
The initial schema that you have created tells the CLI where to find the schematic that supports the `ng add` command. The initial schema that you have created tells the CLI where to find the schematic that supports the `ng add` command.
Now you are ready to create that schematic. Now you are ready to create that schematic.
@ -48,8 +48,8 @@ The following steps will define this type of schematic.
1. Open `index.ts` and add the source code for your schematic factory function. 1. Open `index.ts` and add the source code for your schematic factory function.
<code-example header="projects/my-lib/schematics/ng-add/index.ts (ng-add Rule Factory)" path="schematics-for-libraries/projects/my-lib/schematics/ng-add/index.ts"> <code-example header="projects/my-lib/schematics/ng-add/index.ts (ng-add Rule Factory)" path="schematics-for-libraries/projects/my-lib/schematics/ng-add/index.ts">
</code-example> </code-example>
The only step needed to provide initial `ng add` support is to trigger an installation task using the `SchematicContext`. The only step needed to provide initial `ng add` support is to trigger an installation task using the `SchematicContext`.
The task uses the user's preferred package manager to add the library to the project's `package.json` configuration file, and install it in the project’s `node_modules` directory. The task uses the user's preferred package manager to add the library to the project's `package.json` configuration file, and install it in the project’s `node_modules` directory.
@ -85,8 +85,8 @@ To tell the library how to build the schematics, add a `tsconfig.schematics.json
1. Edit the `tsconfig.schematics.json` file to add the following content. 1. Edit the `tsconfig.schematics.json` file to add the following content.
<code-example header="projects/my-lib/tsconfig.schematics.json (TypeScript Config)" path="schematics-for-libraries/projects/my-lib/tsconfig.schematics.json"> <code-example header="projects/my-lib/tsconfig.schematics.json (TypeScript Config)" path="schematics-for-libraries/projects/my-lib/tsconfig.schematics.json">
</code-example> </code-example>
* The `rootDir` specifies that your `schematics/` folder contains the input files to be compiled. * The `rootDir` specifies that your `schematics/` folder contains the input files to be compiled.
@ -94,8 +94,8 @@ To tell the library how to build the schematics, add a `tsconfig.schematics.json
1. To make sure your schematics source files get compiled into the library bundle, add the following scripts to the `package.json` file in your library project's root folder (`projects/my-lib`). 1. To make sure your schematics source files get compiled into the library bundle, add the following scripts to the `package.json` file in your library project's root folder (`projects/my-lib`).
<code-example header="projects/my-lib/package.json (Build Scripts)" path="schematics-for-libraries/projects/my-lib/package.json"> <code-example header="projects/my-lib/package.json (Build Scripts)" path="schematics-for-libraries/projects/my-lib/package.json">
</code-example> </code-example>
* The `build` script compiles your schematic using the custom `tsconfig.schematics.json` file. * The `build` script compiles your schematic using the custom `tsconfig.schematics.json` file.
* The `copy:*` statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure. * The `copy:*` statements copy compiled schematic files into the proper locations in the library output folder in order to preserve the file structure.
@ -119,15 +119,15 @@ When you add a schematic to the collection, you have to point to it in the colle
1. Edit the `schematics/collection.json` file to point to the new schematic subfolder, and include a pointer to a schema file that will specify inputs for the new schematic. 1. Edit the `schematics/collection.json` file to point to the new schematic subfolder, and include a pointer to a schema file that will specify inputs for the new schematic.
<code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.json"> <code-example header="projects/my-lib/schematics/collection.json (Schematics Collection)" path="schematics-for-libraries/projects/my-lib/schematics/collection.json">
</code-example> </code-example>
1. Go to the `<lib-root>/schematics/my-service/` folder. 1. Go to the `<lib-root>/schematics/my-service/` folder.
1. Create a `schema.json` file and define the available options for the schematic. 1. Create a `schema.json` file and define the available options for the schematic.
<code-example header="projects/my-lib/schematics/my-service/schema.json (Schematic JSON Schema)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.json"> <code-example header="projects/my-lib/schematics/my-service/schema.json (Schematic JSON Schema)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.json">
</code-example> </code-example>
* *id*: A unique id for the schema in the collection. * *id*: A unique id for the schema in the collection.
* *title*: A human-readable description of the schema. * *title*: A human-readable description of the schema.
@ -141,8 +141,8 @@ When you add a schematic to the collection, you have to point to it in the colle
1. Create a `schema.ts` file and define an interface that stores the values of the options defined in the `schema.json` file. 1. Create a `schema.ts` file and define an interface that stores the values of the options defined in the `schema.json` file.
<code-example header="projects/my-lib/schematics/my-service/schema.ts (Schematic Interface)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.ts"> <code-example header="projects/my-lib/schematics/my-service/schema.ts (Schematic Interface)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/schema.ts">
</code-example> </code-example>
* *name*: The name you want to provide for the created service. * *name*: The name you want to provide for the created service.
* *path*: Overrides the path provided to the schematic. The default path value is based on the current working directory. * *path*: Overrides the path provided to the schematic. The default path value is based on the current working directory.
@ -189,18 +189,18 @@ For details of these data structures and syntax, see the [Schematics README](htt
1. First, import the schematics definitions you will need. The Schematics framework offers many utility functions to create and use rules when running a schematic. 1. First, import the schematics definitions you will need. The Schematics framework offers many utility functions to create and use rules when running a schematic.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Imports)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schematics-imports"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Imports)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schematics-imports">
</code-example> </code-example>
1. Import the defined schema interface that provides the type information for your schematic's options. 1. Import the defined schema interface that provides the type information for your schematic's options.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schema-imports"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="schema-imports">
</code-example> </code-example>
1. To build up the generation schematic, start with an empty rule factory. 1. To build up the generation schematic, start with an empty rule factory.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Initial Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.1.ts" region="factory"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Initial Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.1.ts" region="factory">
</code-example> </code-example>
This rule factory returns the tree without modification. This rule factory returns the tree without modification.
The options are the option values passed through from the `ng generate` command. The options are the option values passed through from the `ng generate` command.
@ -222,31 +222,31 @@ The `Tree` methods give you access to the complete file tree in your workspace,
To use `workspaces.readWorkspace` you need to create a `workspaces.WorkspaceHost` from the `Tree`. To use `workspaces.readWorkspace` you need to create a `workspaces.WorkspaceHost` from the `Tree`.
Add the following code to your factory function. Add the following code to your factory function.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="workspace"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Schema Import)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="workspace">
</code-example> </code-example>
* Be sure to check that the context exists and throw the appropriate error. Be sure to check that the context exists and throw the appropriate error.
1. The `WorkspaceDefinition`, `extensions` property includes a `defaultProject` value for determining which project to use if not provided. 1. The `workspace.extensions` property includes a `defaultProject` value for determining which project to use if not provided.
We will use that value as a fallback, if no project is explicitly specified in the `ng generate` command. We will use that value as a fallback, if no project is explicitly specified in the `ng generate` command.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Default Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-fallback"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Default Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-fallback">
</code-example> </code-example>
1. Now that you have the project name, use it to retrieve the project-specific configuration information. 1. Now that you have the project name, use it to retrieve the project-specific configuration information.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-info"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Project)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="project-info">
</code-example> </code-example>
The `workspace projects` object contains all the project-specific configuration information. The `workspace.projects` object contains all the project-specific configuration information.
1. The `options.path` determines where the schematic template files are moved to once the schematic is applied. 1. The `options.path` determines where the schematic template files are moved to once the schematic is applied.
The `path` option in the schematic's schema is substituted by default with the current working directory. The `path` option in the schematic's schema is substituted by default with the current working directory.
If the `path` is not defined, use the `sourceRoot` from the project configuration along with the `projectType`. If the `path` is not defined, use the `sourceRoot` from the project configuration along with the `projectType`.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Project Info)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="path"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Project Info)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="path">
</code-example> </code-example>
### Define the rule ### Define the rule
@ -254,8 +254,8 @@ A `Rule` can use external template files, transform them, and return another `Ru
1. Add the following code to your factory function. 1. Add the following code to your factory function.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Template transform)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="template"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Template transform)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="template">
</code-example> </code-example>
* The `apply()` method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules. * The `apply()` method applies multiple rules to a source and returns the transformed source. It takes 2 arguments, a source and an array of rules.
* The `url()` method reads source files from your filesystem, relative to the schematic. * The `url()` method reads source files from your filesystem, relative to the schematic.
@ -266,13 +266,13 @@ A `Rule` can use external template files, transform them, and return another `Ru
1. Finally, the rule factory must return a rule. 1. Finally, the rule factory must return a rule.
<code-example header="projects/my-lib/schematics/my-service/index.ts (Chain Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="chain"> <code-example header="projects/my-lib/schematics/my-service/index.ts (Chain Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts" region="chain">
</code-example> </code-example>
The `chain()` method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic. The `chain()` method allows you to combine multiple rules into a single rule, so that you can perform multiple operations in a single schematic.
Here you are only merging the template rules with any code executed by the schematic. Here you are only merging the template rules with any code executed by the schematic.
See a complete exampled of the schematic rule function. See a complete example of the schematic rule function below.
<code-example header="projects/my-lib/schematics/my-service/index.ts" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts"> <code-example header="projects/my-lib/schematics/my-service/index.ts" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.ts">
</code-example> </code-example>