Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

refactor: convert docs-code blocks to inline TypeScript documentation

Browse source 
This PR converts the custom <docs-code> blocks to standard Markdown code blocks with TypeScript syntax highlighting.
This commit is contained in:
Angelo Parziale 2025-11-17 23:33:00 +01:00 committed by GitHub
parent cbd77b9db8
commit 7a2d5116f2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 85 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

162
adev/src/content/guide/components/queries.md
View file

@ -15,7 +15,7 @@ There are two categories of query: **view queries** and **content queries.**
View queries retrieve results from the elements in the component's _view_ — the elements defined in the component's own template. You can query for a single result with the `viewChild` function.
<docs-code language="angular-ts" highlight="[14, 15]">
```typescript {highlight: [14, 15]}
@Component({
selector: 'custom-card-header',
/*...*/
@ -25,14 +25,14 @@ export class CustomCardHeader {
}
@Component({
selector: 'custom-card',
template: '<custom-card-header>Visit sunny California!</custom-card-header>',
selector: 'custom-card',
template: '<custom-card-header>Visit sunny California!</custom-card-header>',
})
export class CustomCard {
header = viewChild(CustomCardHeader);
headerText = computed(() => this.header()?.text);
header = viewChild(CustomCardHeader);
headerText = computed(() => this.header()?.text);
}
</docs-code>
```
In this example, the `CustomCard` component queries for a child `CustomCardHeader` and uses the result in a `computed`.
@ -40,7 +40,7 @@ If the query does not find a result, its value is `undefined`. This may occur if
You can also query for multiple results with the `viewChildren` function.
<docs-code language="angular-ts" highlight="[17, 19, 20, 21, 22, 23]">
```typescript {highlight: [17]}
@Component({
selector: 'custom-card-action',
/*...*/
@ -50,16 +50,16 @@ export class CustomCardAction {
}
@Component({
selector: 'custom-card',
template: ` <custom-card-action>Save</custom-card-action>
selector: 'custom-card',
template: `<custom-card-action>Save</custom-card-action>
<custom-card-action>Cancel</custom-card-action>
`,
})
export class CustomCard {
actions = viewChildren(CustomCardAction);
actionsTexts = computed(() => this.actions().map(action => action.text);
actions = viewChildren(CustomCardAction);
actionsTexts = computed(() => this.actions().map(action => action.text);
}
</docs-code>
```
`viewChildren` creates a signal with an `Array` of the query results.
@ -69,7 +69,7 @@ actionsTexts = computed(() => this.actions().map(action => action.text);
Content queries retrieve results from the elements in the component's _content_— the elements nested inside the component in the template where it's used. You can query for a single result with the `contentChild` function.
<docs-code language="angular-ts" highlight="[14, 15]">
```typescript {highlight: [14, 15]}
@Component({
selector: 'custom-toggle',
/*...*/
@ -79,26 +79,26 @@ export class CustomToggle {
}
@Component({
selector: 'custom-expando',
/_..._/
selector: 'custom-expando',
/* ... */
})
export class CustomExpando {
toggle = contentChild(CustomToggle);
toggleText = computed(() => this.toggle()?.text);
toggle = contentChild(CustomToggle);
toggleText = computed(() => this.toggle()?.text);
}
@Component({
/_ ... _/
// CustomToggle is used inside CustomExpando as content.
template: ` <custom-expando>
/* ... */
// CustomToggle is used inside CustomExpando as content.
template: `
<custom-expando>
<custom-toggle>Show</custom-toggle>
</custom-expando>
`
})
export class UserProfile { }
</docs-code>
In this example, the `CustomExpando` component queries for a child `CustomToggle` and accesses the result in a `computed`.
export class UserProfile { }
```
If the query does not find a result, its value is `undefined`. This may occur if the target element is absent or hidden by `@if`. Angular keeps the result of `contentChild` up to date as your application state changes.
@ -106,7 +106,7 @@ By default, content queries find only _direct_ children of the component and do
You can also query for multiple results with the `contentChildren` function.
<docs-code language="angular-ts" highlight="[14, 16, 17, 18, 19, 20]">
```typescript {highlight: [14, 16, 17, 18, 19, 20]}
@Component({
selector: 'custom-menu-item',
/*...*/
@ -116,24 +116,26 @@ export class CustomMenuItem {
}
@Component({
selector: 'custom-menu',
/_..._/
selector: 'custom-menu',
/*...*/
})
export class CustomMenu {
items = contentChildren(CustomMenuItem);
itemTexts = computed(() => this.items().map(item => item.text));
items = contentChildren(CustomMenuItem);
itemTexts = computed(() => this.items().map(item => item.text));
}
@Component({
selector: 'user-profile',
template: ` <custom-menu>
selector: 'user-profile',
template: `
<custom-menu>
<custom-menu-item>Cheese</custom-menu-item>
<custom-menu-item>Tomato</custom-menu-item>
</custom-menu>
`
})
export class UserProfile { }
</docs-code>
```
`contentChildren` creates a signal with an `Array` of the query results.
@ -213,6 +215,7 @@ All query functions accept an options object as a second parameter. These option
By default, the query locator indicates both the element you're searching for and the value retrieved. You can alternatively specify the `read` option to retrieve a different value from the element matched by the locator.
```ts
@Component({/*...*/})
export class CustomExpando {
toggle = contentChild(ExpandoContent, {read: TemplateRef});
@ -229,7 +232,7 @@ Developers most commonly use `read` to retrieve `ElementRef` and `TemplateRef`.
By default, `contentChildren` queries find only _direct_ children of the component and do not traverse into descendants.
`contentChild` queries do traverse into descendants by default.
<docs-code language="angular-ts" highlight="[13, 14, 15, 16]">
```typescript {highlight: [13, 14, 15, 16]}
@Component({
selector: 'custom-expando',
/*...*/
@ -240,8 +243,8 @@ export class CustomExpando {
}
@Component({
selector: 'user-profile',
template: ` <custom-expando>
selector: 'user-profile',
template: ` <custom-expando>
<some-other-component>
<custom-toggle>Show</custom-toggle>
</some-other-component>
@ -249,7 +252,7 @@ template: ` <custom-expando>
`
})
export class UserProfile { }
</docs-code>
```
In the example above, `CustomExpando` cannot find `<custom-toggle>` with `contentChildren` because it is not a direct child of `<custom-expando>`. By setting `descendants: true`, you configure the query to traverse all descendants in the same template. Queries, however, _never_ pierce into components to traverse elements in other templates.
@ -266,7 +269,7 @@ You can alternatively declare queries by adding the corresponding decorator to a
You can query for a single result with the `@ViewChild` decorator.
<docs-code language="angular-ts" highlight="[14, 16, 17, 18]">
```typescript {highlight: [14, 16, 17, 18]}
@Component({
selector: 'custom-card-header',
/*...*/
@ -276,17 +279,17 @@ export class CustomCardHeader {
}
@Component({
selector: 'custom-card',
template: '<custom-card-header>Visit sunny California!</custom-card-header>',
selector: 'custom-card',
template: '<custom-card-header>Visit sunny California!</custom-card-header>',
})
export class CustomCard {
@ViewChild(CustomCardHeader) header: CustomCardHeader;
@ViewChild(CustomCardHeader) header: CustomCardHeader;
ngAfterViewInit() {
console.log(this.header.text);
ngAfterViewInit() {
console.log(this.header.text);
}
}
}
</docs-code>
```
In this example, the `CustomCard` component queries for a child `CustomCardHeader` and accesses the result in `ngAfterViewInit`.
@ -296,7 +299,7 @@ Angular keeps the result of `@ViewChild` up to date as your application state ch
You can also query for multiple results with the `@ViewChildren` decorator.
<docs-code language="angular-ts" highlight="[17, 19, 20, 21, 22, 23]">
```typescript {highlight: [17, 19, 20, 21, 22, 23]}
@Component({
selector: 'custom-card-action',
/*...*/
@ -306,21 +309,22 @@ export class CustomCardAction {
}
@Component({
selector: 'custom-card',
template: ` <custom-card-action>Save</custom-card-action>
selector: 'custom-card',
template: `
<custom-card-action>Save</custom-card-action>
<custom-card-action>Cancel</custom-card-action>
`,
})
export class CustomCard {
@ViewChildren(CustomCardAction) actions: QueryList<CustomCardAction>;
@ViewChildren(CustomCardAction) actions: QueryList<CustomCardAction>;
ngAfterViewInit() {
this.actions.forEach(action => {
console.log(action.text);
});
ngAfterViewInit() {
this.actions.forEach(action => {
console.log(action.text);
});
}
}
}
</docs-code>
```
`@ViewChildren` creates a `QueryList` object that contains the query results. You can subscribe to changes to the query results over time via the `changes` property.
@ -328,7 +332,7 @@ console.log(action.text);
You can query for a single result with the `@ContentChild` decorator.
<docs-code language="angular-ts" highlight="[14, 16, 17, 18, 25]">
```typescript {highlight: [14, 16, 17, 18, 25]}
@Component({
selector: 'custom-toggle',
/*...*/
@ -338,26 +342,28 @@ export class CustomToggle {
}
@Component({
selector: 'custom-expando',
/_..._/
selector: 'custom-expando',
/*...*/
})
export class CustomExpando {
@ContentChild(CustomToggle) toggle: CustomToggle;
ngAfterContentInit() {
console.log(this.toggle.text);
}
export class CustomExpando {
@ContentChild(CustomToggle) toggle: CustomToggle;
ngAfterContentInit() {
console.log(this.toggle.text);
}
}
@Component({
selector: 'user-profile',
template: ` <custom-expando>
selector: 'user-profile',
template: `
<custom-expando>
<custom-toggle>Show</custom-toggle>
</custom-expando>
`
})
export class UserProfile { }
</docs-code>
```
In this example, the `CustomExpando` component queries for a child `CustomToggle` and accesses the result in `ngAfterContentInit`.
@ -367,7 +373,7 @@ Angular keeps the result of `@ContentChild` up to date as your application state
You can also query for multiple results with the `@ContentChildren` decorator.
<docs-code language="angular-ts" highlight="[14, 16, 17, 18, 19, 20]">
```typescript {highlight: [15, 17, 18, 19, 20, 21]}
@Component({
selector: 'custom-menu-item',
/*...*/
@ -377,29 +383,31 @@ export class CustomMenuItem {
}
@Component({
selector: 'custom-menu',
/_..._/
selector: 'custom-menu',
/*...*/
})
export class CustomMenu {
@ContentChildren(CustomMenuItem) items: QueryList<CustomMenuItem>;
ngAfterContentInit() {
this.items.forEach(item => {
console.log(item.text);
});
}
export class CustomMenu {
@ContentChildren(CustomMenuItem) items: QueryList<CustomMenuItem>;
ngAfterContentInit() {
this.items.forEach(item => {
console.log(item.text);
});
}
}
@Component({
selector: 'user-profile',
template: ` <custom-menu>
selector: 'user-profile',
template: `
<custom-menu>
<custom-menu-item>Cheese</custom-menu-item>
<custom-menu-item>Tomato</custom-menu-item>
</custom-menu>
`
})
export class UserProfile { }
</docs-code>
```
`@ContentChildren` creates a `QueryList` object that contains the query results. You can subscribe to changes to the query results over time via the `changes` property.