# Ivy compatibility examples
# Ivy 的兼容性例子
This appendix is intended to provide more background on Ivy changes. Many of these examples list error messages you may see, so searching by error message might be a good idea if you are debugging.
本附录旨在为 Ivy 的变更提供更多背景信息。其中很多例子列出了你可能会看到的错误信息，所以如果你正在调试，按错误信息搜索可能是个好主意。
NOTE: Most of these issues affect a small percentage of applications encountering unusual or rare edge cases.
{@a content-children-descendants}
## @ContentChildren queries only match direct children by default
## @ContentChildren 查询默认只匹配直接子组件
### Basic example of change
### 变更的基本例子
Let's say a component (`Comp`) has a `@ContentChildren` query for `'foo'`:
假设某个组件（ `Comp` ）对 `'foo'` 有 `@ContentChildren` 查询：
```html
```
In the previous runtime, the `
` with `#foo` would match.
With Ivy, that `
` does not match because it is not a direct child of ``.
在之前的运行时中，带 `#foo` 的 `
` 会匹配到。而在 Ivy 中， `
` 不能匹配，因为它不是 `` 的直接子节点。
### Background
### 背景
By default, `@ContentChildren` queries have the `descendants` flag set to `false`.
默认情况下， `@ContentChildren` 查询的 `descendants` 标志设置为 `false` 。
In the previous rendering engine, "descendants" referred to "descendant directives".
An element could be a match as long as there were no other directives between the element and the requesting directive.
This made sense for directives with nesting like tabs, where nested tab directives might not be desirable to match.
However, this caused surprising behavior for users because adding an unrelated directive like `ngClass` to a wrapper element could invalidate query results.
在前面的渲染引擎中，“descendants” 指的是“后代指令”。只要元素和请求指令之间没有其它指令，元素就可以匹配。这对于类似于 tabs （页标签组）的嵌套的指令是有意义的，其中嵌套的 tab 指令可能不适合匹配。但是，这会给用户带来令人惊讶的行为，因为只要在包装器元素中添加一个不相关的指令（如 `ngClass`） 就可能会让查询结果无效。
For example, with the content query and template below, the last two `Tab` directives would not be matches:
例如，如果使用下面的内容查询和模板，最后两个 `Tab` 指令不匹配：
```
@ContentChildren(Tab, {descendants: false}) tabs: QueryList
```
```
One
A
Two
```
In addition, the differences between type and string predicates were subtle and sometimes unclear.
For example, if you replace the type predicate above with a `'foo'` string predicate, the matches change:
另外，使用类型谓词和使用字符串谓词之间的差异很微妙，有时甚至都分不清。例如，如果用 `'foo'` 字符串谓词替换上面的类型谓词，匹配就会改变：
```
@ContentChildren('foo', {descendants: false}) foos: QueryList
```
```
One
A
Two
```
Because the previous behavior was inconsistent and surprising to users, we did not want to reproduce it in Ivy.
Instead, we simplified the mental model so that "descendants" refers to DOM nesting only.
Any DOM element between the requesting component and a potential match will invalidate that match.
Type predicates and string predicates also have identical matching behavior.
由于之前的行为对用户来说是不一致和令人惊讶的，所以我们不打算在 Ivy 中重现它。相反，我们简化了其心智模型，以便 “descendants” 只标识 DOM 嵌套。位于发出请求的组件和潜在匹配项之间的任何 DOM 元素都会使该匹配失效。类型谓词和字符串谓词也有了相同的匹配行为。
Ivy behavior for directive/string predicates:
指令/字符串谓词的 Ivy 行为：
```
One
A
Two
```
### Example of error
### 错误信息的例子
The error message that you see will depend on how the particular content query is used in the application code.
Frequently, an error is thrown when a property is referenced on the content query result (which is now `undefined`).
你看到的错误信息取决于应用代码中特定的内容查询的使用方式。当在内容查询结果中引用一个属性（这里是 `undefined`）时，就会抛出一个错误。
For example, if the component sets the content query results to a property, `foos`, `foos.first.bar` would throw the error:
例如，如果组件把内容查询结果设置为属性，那么 `foos`、`foos.first.bar` 会抛出错误：
```
Uncaught TypeError: Cannot read property 'bar' of undefined
```
If you see an error like this, and the `undefined` property refers to the result of a `@ContentChildren` query, it may well be caused by this change.
如果你看到这样的错误，并且 `undefined` 属性引用了 `@ContentChildren` 查询的结果，那么很可能就是由于这个变化造成的。
### Recommended fix
### 推荐的修复方式
You can either add the `descendants: true` flag to ignore wrapper elements or remove the wrapper elements themselves.
你可以添加 `descendants: true` 标志来忽略包装元素，也可以自己删除包装元素。
Option 1:
方案 1：
```
@ContentChildren('foo', {descendants: true}) foos: QueryList;
```
Option 2:
方案 2：
```
```
{@a undecorated-classes}
## All classes that use Angular DI must have an Angular class-level decorator
## 所有使用 Angular DI 的类都必须有一个 Angular 类级装饰器
### Basic example of change:
### 变更的基本例子：
In the previous rendering engine, the following would work:
在以前的渲染引擎中，下列代码可以正常工作：
```
export class DataService {
constructor(@Inject('CONFIG') public config: DataConfig) {}
}
@Injectable()
export class AppService extends DataService {...}
```
In Ivy, it will throw an error because `DataService` is using Angular dependency injection, but is missing an `@Injectable` decorator.
在 Ivy 中，它会抛出一个错误，因为 `DataService` 正在使用 Angular 依赖注入，但它却缺少一个 `@Injectable` 装饰器。
The following would also work in the previous rendering engine, but in Ivy would require a `@Directive` decorator because it uses DI:
下列渲染引擎也能正常工作，但是 Ivy 需要一个 `@Directive` 装饰器，因为它使用了 DI：
```
export class BaseMenu {
constructor(private vcr: ViewContainerRef) {}
}
@Directive({selector: '[settingsMenu]'})
export class SettingsMenu extends BaseMenu {}
```
The same is true if your directive class extends a decorated directive, but does not have a decorator of its own.
如果指令类扩展了装饰指令，但却没有自己的装饰器，那也是如此。
If you're using the CLI, there are two automated migrations that should transition your code for you ([this one](guide/migration-injectable) and [this one](guide/migration-undecorated-classes)).
However, as you're adding new code in version 9, you may run into this difference.
如果你正在使用 CLI，那么有两个自动迁移应该为你转移你的代码（ [本章](guide/migration-injectable)和[本章](guide/migration-undecorated-classes) ）。但是，当你在版本 9 中添加新代码时，可能会遇到这种不同。
### Background
### 背景
When a class has an Angular decorator like `@Injectable` or `@Directive`, the Angular compiler generates extra code to support injecting dependencies into the constructor of your class.
When using inheritance, Ivy needs both the parent class and the child class to apply a decorator to generate the correct code.
Otherwise, when the decorator is missing from the parent class, the subclass will inherit a constructor from a class for which the compiler did not generate special constructor info, and Angular won't have the dependency info it needs to create it properly.
当一个类有一个像 `@Injectable` 或 `@Directive` 这样的 Angular 装饰器时，Angular 编译器会生成额外的代码，以支持把依赖注入到类的构造函数中。当使用继承时，Ivy 既需要父类，也要让子类应用装饰器来生成正确的代码。否则，当父类中缺少装饰器时，该子类将继承一个构造函数，而这个构造函数并没有为编译器生成特殊的构造函数信息，而 Angular 也没有正确创建它所需的依赖信息。
In the previous rendering engine, the compiler had global knowledge, so in some cases (such as AOT mode or the presence of certain injection flags), it could look up the missing data.
However, the Ivy compiler only processes each class in isolation.
This means that compilation has the potential to be faster (and opens the framework up for optimizations and features going forward), but the compiler can't automatically infer the same information as before.
在之前的渲染引擎中，编译器具有全局知识，所以在某些情况下（比如 AOT 模式或某些注入标志的存在），它可以查找丢失的数据。然而，Ivy 编译器只是孤立地处理每个类。这意味着编译有可能更快（并为今后的优化和特性打开框架），但编译器不能自动推断出和以前一样的信息。
Adding the proper decorator explicitly provides this information.
添加合适的装饰器会明确提供这些信息。
### Example of error
### 错误信息的例子
In JIT mode, the framework will throw the following error:
在 JIT 模式下，该框架会抛出以下错误：
```
ERROR: This constructor is not compatible with Angular Dependency Injection because its dependency at index X of the parameter list is invalid.
This can happen if the dependency type is a primitive like a string or if an ancestor of this class is missing an Angular decorator.
Please check that 1) the type for the parameter at index X is correct and 2) the correct Angular decorators are defined for this class and its ancestors.
```
In AOT mode, you'll see something like:
在 AOT 模式下，你会看到如下内容：
```
X inherits its constructor from Y, but the latter does not have an Angular decorator of its own.
Dependency injection will not be able to resolve the parameters of Y's constructor. Either add a
@Directive decorator to Y, or add an explicit constructor to X.
```
In some cases, the framework may not be able to detect the missing decorator.
In these cases, you'll generally see a runtime error thrown when there is a property access attempted on the missing dependency.
If dependency was `foo`, you'd see an error when accessing something like `foo.bar`:
在某些情况下，框架可能无法检测到丢失的装饰器。在这种情况下，你会发现试图对所缺的依赖项进行属性访问时，就会抛出一个运行时错误。如果依赖是 `foo` ，你在访问 `foo.bar` 这样的东西时会看到一个错误：
```
Uncaught TypeError: Cannot read property 'bar' of undefined
```
If you see an error like this, and the `undefined` value refers to something that should have been injected, it may be this change.
如果你看到这样的错误，并且 `undefined` 值引用了应该注入的内容，那么可能就是这种变化。
### Recommended fix
### 推荐的修复方式
- Add an `@Injectable` decorator to anything you plan to provide or inject.
把 `@Injectable` 装饰器添加到你打算提供或注入的东西中。
```
@Injectable()
export class DataService {
constructor(@Inject('CONFIG') public config: DataConfig) {}
}
@Injectable()
export class AppService extends DataService {...}
```
- Add a [selectorless `@Directive` decorator](guide/migration-undecorated-classes#what-does-it-mean-to-have-a-directive-decorator-with-no-metadata-inside-of-it) to any class that extends a directive or any class from which a directive inherits.
把 [无选择器的 `@Directive` 装饰器](guide/migration-undecorated-classes#what-does-it-mean-to-have-a-directive-decorator-with-no-metadata-inside-of-it)添加到扩展指令的类或被指令继承的任何类中。
```
@Directive() // selectorless, so it's not usable directly
export class BaseMenu {
constructor(private vcr: ViewContainerRef) {}
}
@Directive({selector: '[settingsMenu]'})
export class SettingsMenu extends BaseMenu {}
```
{@a select-value-binding}
## Cannot Bind to `value` property of `