Component parameter value guidance updates (#28696)
Luke Latham
GitHub
parent
da3c48a6fc
commit
f321a3c27a
|
|
@ -270,17 +270,17 @@ The following rendered HTML markup from the `ParameterParent` component shows `P
|
|||
</div>
|
||||
```
|
||||
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value using [Razor's reserved `@` symbol](xref:mvc/views/razor#razor-syntax). The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value. The value of the attribute can typically be any C# expression that matches the type of the parameter. The value of the attribute can optionally lead with a [Razor reserved `@` symbol](xref:mvc/views/razor#razor-syntax), but it isn't required.
|
||||
|
||||
If the component parameter is of type string, then the attribute value is instead treated as a C# string literal by default. If you want to specify a C# expression instead, then use the `@` prefix.
|
||||
|
||||
The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
|
||||
* The value of the `title` field.
|
||||
* The result of the `GetTitle` C# method.
|
||||
* The current local date in long format with <xref:System.DateTime.ToLongDateString%2A>, which uses an [implicit C# expression](xref:mvc/views/razor#implicit-razor-expressions).
|
||||
* The `panelData` object's `Title` property.
|
||||
|
||||
The `@` prefix is required for string parameters. Otherwise, the framework assumes that a string literal is set.
|
||||
|
||||
Outside of string parameters, we recommend the use of the `@` prefix for nonliterals, even when they aren't strictly required.
|
||||
|
||||
We don't recommend the use of the `@` prefix for literals (for example, boolean values), keywords (for example, `this`), or `null`, but you can choose to use them if you wish. For example, `IsFixed="@true"` is uncommon but supported.
|
||||
|
||||
Quotes around parameter attribute values are optional in most cases per the HTML5 specification. For example, `Value=this` is supported, instead of `Value="this"`. However, we recommend using quotes because it's easier to remember and widely adopted across web-based technologies.
|
||||
|
|
@ -288,26 +288,34 @@ Quotes around parameter attribute values are optional in most cases per the HTML
|
|||
Throughout the documentation, code examples:
|
||||
|
||||
* Always use quotes. Example: `Value="this"`.
|
||||
* Nonliterals always use the `@` prefix, even when it's optional. Examples: `Title="@title"`, where `title` is a string-typed variable. `Count="@ct"`, where `ct` is a number-typed variable.
|
||||
* Literals, outside of Razor expressions, always avoid `@`. Example: `IsFixed="true"`.
|
||||
* Use the `@` prefix with nonliterals, ***even when it's optional***. Example: `Count="@ct"`, where `ct` is a number-typed variable. `Count="ct"` is a valid stylistic approach, but the documentation and examples don't adopt the convention.
|
||||
* Always avoid `@` for literals, outside of Razor expressions. Example: `IsFixed="true"`.
|
||||
|
||||
`Pages/ParameterParent2.razor`:
|
||||
|
||||
:::code language="razor" source="~/../blazor-samples/7.0/BlazorSample_WebAssembly/Pages/index/ParameterParent2.razor":::
|
||||
|
||||
> [!NOTE]
|
||||
> When assigning a C# member to a component parameter, prefix the member with the `@` symbol and never prefix the parameter's HTML attribute.
|
||||
> When assigning a C# member to a component parameter, don't prefix the parameter's HTML attribute with `@`.
|
||||
>
|
||||
> Correct:
|
||||
> Correct (`Title` is a string parameter, `Count` is a number-typed parameter):
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" />
|
||||
> <ParameterChild Title="@title" Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" Count="ct" />
|
||||
> ```
|
||||
>
|
||||
> Incorrect:
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="title" />
|
||||
> <ParameterChild @Title="@title" @Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="@title" @Count="ct" />
|
||||
> ```
|
||||
|
||||
Unlike in Razor pages (`.cshtml`), Blazor can't perform asynchronous work in a Razor expression while rendering a component. This is because Blazor is designed for rendering interactive UIs. In an interactive UI, the screen must always display something, so it doesn't make sense to block the rendering flow. Instead, asynchronous work is performed during one of the [asynchronous lifecycle events](xref:blazor/components/lifecycle). After each asynchronous lifecycle event, the component may render again. The following Razor syntax is **not** supported:
|
||||
|
|
@ -1792,17 +1800,17 @@ The following rendered HTML markup from the `ParameterParent` component shows `P
|
|||
</div>
|
||||
```
|
||||
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value using [Razor's reserved `@` symbol](xref:mvc/views/razor#razor-syntax). The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value. The value of the attribute can typically be any C# expression that matches the type of the parameter. The value of the attribute can optionally lead with a [Razor reserved `@` symbol](xref:mvc/views/razor#razor-syntax), but it isn't required.
|
||||
|
||||
If the component parameter is of type string, then the attribute value is instead treated as a C# string literal by default. If you want to specify a C# expression instead, then use the `@` prefix.
|
||||
|
||||
The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
|
||||
* The value of the `title` field.
|
||||
* The result of the `GetTitle` C# method.
|
||||
* The current local date in long format with <xref:System.DateTime.ToLongDateString%2A>, which uses an [implicit C# expression](xref:mvc/views/razor#implicit-razor-expressions).
|
||||
* The `panelData` object's `Title` property.
|
||||
|
||||
The `@` prefix is required for string parameters. Otherwise, the framework assumes that a string literal is set.
|
||||
|
||||
Outside of string parameters, we recommend the use of the `@` prefix for nonliterals, even when they aren't strictly required.
|
||||
|
||||
We don't recommend the use of the `@` prefix for literals (for example, boolean values), keywords (for example, `this`), or `null`, but you can choose to use them if you wish. For example, `IsFixed="@true"` is uncommon but supported.
|
||||
|
||||
Quotes around parameter attribute values are optional in most cases per the HTML5 specification. For example, `Value=this` is supported, instead of `Value="this"`. However, we recommend using quotes because it's easier to remember and widely adopted across web-based technologies.
|
||||
|
|
@ -1810,26 +1818,34 @@ Quotes around parameter attribute values are optional in most cases per the HTML
|
|||
Throughout the documentation, code examples:
|
||||
|
||||
* Always use quotes. Example: `Value="this"`.
|
||||
* Nonliterals always use the `@` prefix, even when it's optional. Examples: `Title="@title"`, where `title` is a string-typed variable. `Count="@ct"`, where `ct` is a number-typed variable.
|
||||
* Literals, outside of Razor expressions, always avoid `@`. Example: `IsFixed="true"`.
|
||||
* Use the `@` prefix with nonliterals, ***even when it's optional***. Example: `Count="@ct"`, where `ct` is a number-typed variable. `Count="ct"` is a valid stylistic approach, but the documentation and examples don't adopt the convention.
|
||||
* Always avoid `@` for literals, outside of Razor expressions. Example: `IsFixed="true"`.
|
||||
|
||||
`Pages/ParameterParent2.razor`:
|
||||
|
||||
:::code language="razor" source="~/../blazor-samples/6.0/BlazorSample_WebAssembly/Pages/index/ParameterParent2.razor":::
|
||||
|
||||
> [!NOTE]
|
||||
> When assigning a C# member to a component parameter, prefix the member with the `@` symbol and never prefix the parameter's HTML attribute.
|
||||
> When assigning a C# member to a component parameter, don't prefix the parameter's HTML attribute with `@`.
|
||||
>
|
||||
> Correct:
|
||||
> Correct (`Title` is a string parameter, `Count` is a number-typed parameter):
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" />
|
||||
> <ParameterChild Title="@title" Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" Count="ct" />
|
||||
> ```
|
||||
>
|
||||
> Incorrect:
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="title" />
|
||||
> <ParameterChild @Title="@title" @Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="@title" @Count="ct" />
|
||||
> ```
|
||||
|
||||
Unlike in Razor pages (`.cshtml`), Blazor can't perform asynchronous work in a Razor expression while rendering a component. This is because Blazor is designed for rendering interactive UIs. In an interactive UI, the screen must always display something, so it doesn't make sense to block the rendering flow. Instead, asynchronous work is performed during one of the [asynchronous lifecycle events](xref:blazor/components/lifecycle). After each asynchronous lifecycle event, the component may render again. The following Razor syntax is **not** supported:
|
||||
|
|
@ -3255,17 +3271,17 @@ The following rendered HTML markup from the `ParameterParent` component shows `P
|
|||
</div>
|
||||
```
|
||||
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value using [Razor's reserved `@` symbol](xref:mvc/views/razor#razor-syntax). The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value. The value of the attribute can typically be any C# expression that matches the type of the parameter. The value of the attribute can optionally lead with a [Razor reserved `@` symbol](xref:mvc/views/razor#razor-syntax), but it isn't required.
|
||||
|
||||
If the component parameter is of type string, then the attribute value is instead treated as a C# string literal by default. If you want to specify a C# expression instead, then use the `@` prefix.
|
||||
|
||||
The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
|
||||
* The value of the `title` field.
|
||||
* The result of the `GetTitle` C# method.
|
||||
* The current local date in long format with <xref:System.DateTime.ToLongDateString%2A>, which uses an [implicit C# expression](xref:mvc/views/razor#implicit-razor-expressions).
|
||||
* The `panelData` object's `Title` property.
|
||||
|
||||
The `@` prefix is required for string parameters. Otherwise, the framework assumes that a string literal is set.
|
||||
|
||||
Outside of string parameters, we recommend the use of the `@` prefix for nonliterals, even when they aren't strictly required.
|
||||
|
||||
We don't recommend the use of the `@` prefix for literals (for example, boolean values), keywords (for example, `this`), or `null`, but you can choose to use them if you wish. For example, `IsFixed="@true"` is uncommon but supported.
|
||||
|
||||
Quotes around parameter attribute values are optional in most cases per the HTML5 specification. For example, `Value=this` is supported, instead of `Value="this"`. However, we recommend using quotes because it's easier to remember and widely adopted across web-based technologies.
|
||||
|
|
@ -3273,26 +3289,34 @@ Quotes around parameter attribute values are optional in most cases per the HTML
|
|||
Throughout the documentation, code examples:
|
||||
|
||||
* Always use quotes. Example: `Value="this"`.
|
||||
* Nonliterals always use the `@` prefix, even when it's optional. Examples: `Title="@title"`, where `title` is a string-typed variable. `Count="@ct"`, where `ct` is a number-typed variable.
|
||||
* Literals, outside of Razor expressions, always avoid `@`. Example: `IsFixed="true"`.
|
||||
* Use the `@` prefix with nonliterals, ***even when it's optional***. Example: `Count="@ct"`, where `ct` is a number-typed variable. `Count="ct"` is a valid stylistic approach, but the documentation and examples don't adopt the convention.
|
||||
* Always avoid `@` for literals, outside of Razor expressions. Example: `IsFixed="true"`.
|
||||
|
||||
`Pages/ParameterParent2.razor`:
|
||||
|
||||
:::code language="razor" source="~/../blazor-samples/5.0/BlazorSample_WebAssembly/Pages/index/ParameterParent2.razor":::
|
||||
|
||||
> [!NOTE]
|
||||
> When assigning a C# member to a component parameter, prefix the member with the `@` symbol and never prefix the parameter's HTML attribute.
|
||||
> When assigning a C# member to a component parameter, don't prefix the parameter's HTML attribute with `@`.
|
||||
>
|
||||
> Correct:
|
||||
> Correct (`Title` is a string parameter, `Count` is a number-typed parameter):
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" />
|
||||
> <ParameterChild Title="@title" Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" Count="ct" />
|
||||
> ```
|
||||
>
|
||||
> Incorrect:
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="title" />
|
||||
> <ParameterChild @Title="@title" @Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="@title" @Count="ct" />
|
||||
> ```
|
||||
|
||||
Unlike in Razor pages (`.cshtml`), Blazor can't perform asynchronous work in a Razor expression while rendering a component. This is because Blazor is designed for rendering interactive UIs. In an interactive UI, the screen must always display something, so it doesn't make sense to block the rendering flow. Instead, asynchronous work is performed during one of the [asynchronous lifecycle events](xref:blazor/components/lifecycle). After each asynchronous lifecycle event, the component may render again. The following Razor syntax is **not** supported:
|
||||
|
|
@ -4268,17 +4292,17 @@ The following rendered HTML markup from the `ParameterParent` component shows `P
|
|||
</div>
|
||||
```
|
||||
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value using [Razor's reserved `@` symbol](xref:mvc/views/razor#razor-syntax). The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
Assign a C# field, property, or result of a method to a component parameter as an HTML attribute value. The value of the attribute can typically be any C# expression that matches the type of the parameter. The value of the attribute can optionally lead with a [Razor reserved `@` symbol](xref:mvc/views/razor#razor-syntax), but it isn't required.
|
||||
|
||||
If the component parameter is of type string, then the attribute value is instead treated as a C# string literal by default. If you want to specify a C# expression instead, then use the `@` prefix.
|
||||
|
||||
The following `ParameterParent2` component displays four instances of the preceding `ParameterChild` component and sets their `Title` parameter values to:
|
||||
|
||||
* The value of the `title` field.
|
||||
* The result of the `GetTitle` C# method.
|
||||
* The current local date in long format with <xref:System.DateTime.ToLongDateString%2A>, which uses an [implicit C# expression](xref:mvc/views/razor#implicit-razor-expressions).
|
||||
* The `panelData` object's `Title` property.
|
||||
|
||||
The `@` prefix is required for string parameters. Otherwise, the framework assumes that a string literal is set.
|
||||
|
||||
Outside of string parameters, we recommend the use of the `@` prefix for nonliterals, even when they aren't strictly required.
|
||||
|
||||
We don't recommend the use of the `@` prefix for literals (for example, boolean values), keywords (for example, `this`), or `null`, but you can choose to use them if you wish. For example, `IsFixed="@true"` is uncommon but supported.
|
||||
|
||||
Quotes around parameter attribute values are optional in most cases per the HTML5 specification. For example, `Value=this` is supported, instead of `Value="this"`. However, we recommend using quotes because it's easier to remember and widely adopted across web-based technologies.
|
||||
|
|
@ -4286,26 +4310,34 @@ Quotes around parameter attribute values are optional in most cases per the HTML
|
|||
Throughout the documentation, code examples:
|
||||
|
||||
* Always use quotes. Example: `Value="this"`.
|
||||
* Nonliterals always use the `@` prefix, even when it's optional. Examples: `Title="@title"`, where `title` is a string-typed variable. `Count="@ct"`, where `ct` is a number-typed variable.
|
||||
* Literals, outside of Razor expressions, always avoid `@`. Example: `IsFixed="true"`.
|
||||
* Use the `@` prefix with nonliterals, ***even when it's optional***. Example: `Count="@ct"`, where `ct` is a number-typed variable. `Count="ct"` is a valid stylistic approach, but the documentation and examples don't adopt the convention.
|
||||
* Always avoid `@` for literals, outside of Razor expressions. Example: `IsFixed="true"`.
|
||||
|
||||
`Pages/ParameterParent2.razor`:
|
||||
|
||||
:::code language="razor" source="~/../blazor-samples/3.1/BlazorSample_WebAssembly/Pages/index/ParameterParent2.razor":::
|
||||
|
||||
> [!NOTE]
|
||||
> When assigning a C# member to a component parameter, prefix the member with the `@` symbol and never prefix the parameter's HTML attribute.
|
||||
> When assigning a C# member to a component parameter, don't prefix the parameter's HTML attribute with `@`.
|
||||
>
|
||||
> Correct:
|
||||
> Correct (`Title` is a string parameter, `Count` is a number-typed parameter):
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" />
|
||||
> <ParameterChild Title="@title" Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild Title="@title" Count="ct" />
|
||||
> ```
|
||||
>
|
||||
> Incorrect:
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="title" />
|
||||
> <ParameterChild @Title="@title" @Count="@ct" />
|
||||
> ```
|
||||
>
|
||||
> ```razor
|
||||
> <ParameterChild @Title="@title" @Count="ct" />
|
||||
> ```
|
||||
|
||||
Unlike in Razor pages (`.cshtml`), Blazor can't perform asynchronous work in a Razor expression while rendering a component. This is because Blazor is designed for rendering interactive UIs. In an interactive UI, the screen must always display something, so it doesn't make sense to block the rendering flow. Instead, asynchronous work is performed during one of the [asynchronous lifecycle events](xref:blazor/components/lifecycle). After each asynchronous lifecycle event, the component may render again. The following Razor syntax is **not** supported:
|
||||
|
|
|
|||
Loading…
Reference in New Issue