mdbook-angular

mdbook 的渲染器，可以将 Angular 代码示例转换为可运行的 Angular 应用程序。

用法

将 mdbook-angular 二进制文件安装到您的 PATH 中，并在您的 book.toml 中通过添加一个 output.angular 部分来启用渲染器。

在您的书中包含实时代码示例有两种方式。第一种是通过将 angular 添加到 TypeScript 或 JavaScript 代码块中，例如。

```ts,angular
// live angular sample here
```

第二种方式是在您的页面中添加一个特殊的 {{#angular}} 标签，该标签指向一个组件

{{#angular ./path/to/file.ts#NameOfExportedComponentClass}}

<!-- or -->

{{#angular ./path/to/file.ts}}

内联代码块

当使用带有 ```ts,angular 的代码块时，该代码块必须包含一个有效的独立组件的单一导出类。如果组件没有定义选择器，则会添加一个。

代码块将被写入插件工作目录内的 TypeScript（或 JavaScript）文件中，因此代码块中的任何相对导入都将无法正确工作。

可以在语言标签中添加标志到代码块中，例如 ```ts,angular,hide,playground。

{{#angular}} 标签

{{#angular}} 标签有两种格式：您要么指向一个文件，要么指向文件中的特定导出。

标签的格式是

{{#angular <file>[#<exportName>][ flag]*}}

一些示例

{{#angular ./example.ts}}
{{#angular ./example.ts hide playground}}
{{#angular ./example.ts#ExampleOneComponent no-playground}}

如果在标签中存在导出名称，则文件应导出一个具有该名称的独立组件。此组件必须具有选择器，并且期望该选择器在页面上是唯一的。

如果标签中没有导出名称，则文件应导出一个单独的独立组件。如果该组件没有选择器，则会添加一个。

如果未设置 hide 标志，则将在 {{#angular}} 标签的位置添加代码块。代码块中显示的内容取决于是否传递了导出组件的名称。如果传递了导出名称，则仅显示该类以及任何装饰器或周围的注释。如果没有传递导出名称，则显示整个文件。

实时示例

在 angular 代码块中使用的所有组件或通过 {{#angular}} 标签导入的组件将在页面上实时显示。每个组件都将通过 bootstrapApplication 作为 单独的 angular 应用程序启动。

如果没有 no-insert 标志，实时应用程序将添加到代码块下方和游乐场上方。如果设置了 insert 标志，则应用程序将不会添加到页面上。相反，您需要负责将应用程序的元素放置在页面上的某个位置。注意，angular 限制了组件的实例数，因此多次在页面上放置元素将不会工作。

游乐场

作为实时示例运行的组件可以定义输入和动作。如果组件至少有一个输入或动作，则除非通过标志或配置禁用，否则将在实时示例下方添加一个游乐场。

输入

输入是通过 Angular 的 @Input() 装饰器定义的。以下限制适用：

• 不支持输入重命名
• 输入类型必须限于以下类型：
  • 文本（字符串）
  • 数字
  • 布尔值
  • 具有字符串值的枚举

如果输入有默认值，则尽可能推断类型。

您可以通过在 @Input() 属性上方添加一个显式的 @input 来配置输入的类型和默认值。在 @input 之后必须是一个有效的 JSON 对象，具有键 "type" 和可选键 "default"。

以下两个属性都将检测为具有默认值 "Bram" 的 "string" 输入。

// explicit:

/**
 * Author of this document
 * @input {"type": "string", "default": "Bram"}
 */
@Input()
author;

// or inferred

/**
 * Author of this document
 */
@Input()
author = "Bram";

您可以将两种方法结合起来，例如，在以下属性中，类型将被设置为枚举 "morning" 或 "evening"，默认值将为 "evening"。

/**
 * The current time of day
 *
 * @input {"type": {"enum": ["morning", "evening"]}}
 */
@Input()
timeOfDay = "evening";

在 @input JSON 对象中传递的 "type" 属性支持以下值：

• "string"
• "number"
• "boolean"
• 一个具有指向字符串数组单键 "enum" 的对象。

动作

操作是组件类上的方法，这些方法在方法上方注释块中通过@action进行注解。

/**
 * Reset the counter
 * @action
 */
reset() {
	this.counter.set(0);
}

标志

以下标志可以传递给每个Angular代码块

• hide：不显示代码，但包括运行中的Angular应用程序和可能的游乐场
• playground / no-playground：无论配置是否允许游乐场，都显示或隐藏当前应用程序的游乐场。如果组件不值得游乐场，则playground标志不会显示游乐场。
• collapsed / uncollapsed：隐藏或显示可点击打开的折叠元素中的源代码（即代码块本身）
• no-insert：不要自动在页面上插入实时应用程序。这允许您在页面上选择的位置一次（且仅一次）写入与Angular组件链接的元素。

配置

您可以配置以下设置

[output.angular]

# Option defined by mdbook itself:

# Executable to run, e.g. if mdbook-angular is not on your PATH
command = "/path/to/mdbook-angular"

# Options changing mdbook-angular behaviour:

# Path to a directory used by mdbook-angular as temporary folder,
# relative to the book.toml file
workdir = "mdbook_angular"

# Which builder to use
#
# There are three to choose from:
# - "experimental" (default) requires at least `@angular-devkit/build-angular`
#   version 16.2.0. This builder builds the code for all chapters in a single go.
# - "slow" works on angular ≥ 14.0.0, but it is a lot slower as it builds every
#   chapter as a separate angular application
# - "background" (not available on Windows) runs the "experimental" builder in a
#   background process, which allows it to watch and rebuild instead of running
#   an entire new build every time a change is made.
builder = "experimental"

# Whether code blocks should be collapsed by default
#
# This can be overridden per code block by adding either the collapsed or
# uncollapsed flag.
# Note this only takes effect on code blocks tagged with "angular", it doesn't
# affect other code blocks.
collapsed = false

# Whether to allow playgrounds, i.e. to add inputs and actions to the page
# allowing your readers to interact with the running code blocks.
#
# This can be overridden per code block by adding either the playground or
# no-playground flag
playgrounds = true

# Options related to the angular build:

# Path to a tsconfig file to use for the build, relative to the book.toml file.
tsconfig = # empty by default

# Language to use for inline styles
inline-style-language = "css"

# Whether to create an optimized angular build or not
optimize = false

# Which polyfills to load, if zone.js is not in the list then it will be loaded
# as first polyfill
# This is a list of strings, all of which must be bare identifiers. Relative
# imports won't work.
polyfills = []

以下设置都不是必需的，默认值在上面的代码中显示。

开发

此项目需要安装mdbook和Angular

yarn install
cargo install mdbook

构建项目

cargo build

然后在test-book文件夹内运行以下命令

yarn exec mdbook serve

# if you've got @angular/cli installed globally, you can also run
mdbook serve
# directly

并将您的浏览器指向https://127.0.0.1:3000

许可证

此项目根据欧盟公共许可证v. 1.2或更高版本许可。完整的许可文本可以在LICENSE.md中找到，在SPDX网站上，或在任何欧盟成员国语言中在欧盟委员会网站上。