Astro 语法

如果你了解 HTML，那么你就已经足够编写你的第一个 Astro 组件了。

英If you know HTML, you already know enough to write your first Astro component.

Astro 组件语法是 HTML 的超集。 语法为 旨在让任何有编写 HTML 或 JSX 经验的人感到熟悉，并添加了对包含组件和 JavaScript 表达式的支持。

英Astro component syntax is a superset of HTML. The syntax was designed to feel familiar to anyone with experience writing HTML or JSX, and adds support for including components and JavaScript expressions.

类似 JSX 的表达式

Section titled 类似 JSX 的表达式

你可以在 Astro 组件的两个代码围栏 (---) 之间的 frontmatter 组件脚本内部定义本地 JavaScript 变量。 然后，你可以使用类似 JSX 的表达式将这些变量注入到组件的 HTML 模板中！

英You can define local JavaScript variables inside of the frontmatter component script between the two code fences (---) of an Astro component. You can then inject these variables into the component’s HTML template using JSX-like expressions!

Dynamic 与反应性

使用这种方法，你可以包含在 frontmatter 中计算的 dynamic 值。 但一旦包含在内，这些值就不是 reactive 并且永远不会改变。 Astro 组件是在渲染步骤中仅运行一次的模板。

英Using this approach, you can include dynamic values that are calculated in the frontmatter. But once included, these values are not reactive and will never change. Astro components are templates that only run once, during the rendering step.

有关 Astro 和 JSX 之间的区别 的更多示例，请参见下文。

变量

Section titled 变量

可以使用大括号语法将局部变量添加到 HTML 中：

英Local variables can be added into the HTML using the curly braces syntax:

src/components/Variables.astro

---
const name = "Astro";
---
<div>
  <h1>Hello {name}!</h1>  <!-- Outputs <h1>Hello Astro!</h1> -->
</div>

动态属性

Section titled 动态属性

局部变量可以用在大括号中来将属性值传递给 HTML 元素和组件：

英Local variables can be used in curly braces to pass attribute values to both HTML elements and components:

src/components/DynamicAttributes.astro

---
const name = "Astro";
---
<h1 class={name}>Attribute expressions are supported</h1>

<MyComponent templateLiteralNameAttribute={`MyNameIs${name}`} />

:::caution 提醒 HTML 属性将转换为字符串，因此无法将函数和对象传递给 HTML 元素。 例如，你不能将事件处理程序分配给 Astro 组件中的 HTML 元素：

英HTML attributes will be converted to strings, so it is not possible to pass functions and objects to HTML elements. For example, you can’t assign an event handler to an HTML element in an Astro component:

dont-do-this.astro

---
function handleClick () {
    console.log("button clicked!");
}
---
<!-- ❌ This doesn't work! ❌ -->
<button onClick={handleClick}>Nothing will happen when you click me!</button>

相反，使用客户端脚本添加事件处理程序，就像在普通 JavaScript 中一样：

英Instead, use a client-side script to add the event handler, like you would in vanilla JavaScript:

do-this-instead.astro

---
---
<button id="button">Click Me</button>
<script>
  function handleClick () {
    console.log("button clicked!");
  }
  document.getElementById("button").addEventListener("click", handleClick);
</script>

:::

动态 HTML

Section titled 动态 HTML

局部变量可以在类似 JSX 的函数中使用来生成动态生成的 HTML 元素：

英Local variables can be used in JSX-like functions to produce dynamically-generated HTML elements:

src/components/DynamicHtml.astro

---
const items = ["Dog", "Cat", "Platypus"];
---
<ul>
  {items.map((item) => (
    <li>{item}</li>
  ))}
</ul>

Astro 可以使用 JSX 逻辑运算符和三元表达式有条件地显示 HTML。

英Astro can conditionally display HTML using JSX logical operators and ternary expressions.

src/components/ConditionalHtml.astro

---
const visible = true;
---
{visible && <p>Show me!</p>}

{visible ? <p>Show me!</p> : <p>Else show me!</p>}

动态标签

Section titled 动态标签

你还可以通过将变量设置为 HTML 标签名称或组件导入来使用动态标签：

英You can also use dynamic tags by setting a variable to an HTML tag name or a component import:

src/components/DynamicTags.astro

---
import MyComponent from "./MyComponent.astro";
const Element = 'div'
const Component = MyComponent;
---
<Element>Hello!</Element> <!-- renders as <div>Hello!</div> -->
<Component /> <!-- renders as <MyComponent /> -->

使用动态标签时：

英When using dynamic tags:

• 变量名必须大写。 例如，使用 Element，而不是 element。 否则，Astro 将尝试将你的变量名称渲染为文本 HTML 标记。

• 不支持水合指令。 使用 client:* 补水指令 时，Astro 需要知道要打包哪些组件进行生产，而动态标签模式阻止了这一点。

片段

Section titled 片段

Astro 支持使用 <Fragment> </Fragment> 或简写 <> </>。

英Astro supports using either <Fragment> </Fragment> or the shorthand <> </>.

添加 set:* 指令 时，片段可用于避免封装元素，如下例所示：

英Fragments can be useful to avoid wrapper elements when adding set:* directives, as in the following example:

src/components/SetHtml.astro

---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

Astro 和 JSX 之间的差异

Section titled Astro 和 JSX 之间的差异

Astro 组件语法是 HTML 的超集。 它的设计初衷是让任何具有 HTML 或 JSX 经验的人都感到熟悉，但 .astro 文件和 JSX 之间存在一些关键区别。

英Astro component syntax is a superset of HTML. It was designed to feel familiar to anyone with HTML or JSX experience, but there are a couple of key differences between .astro files and JSX.

属性

Section titled 属性

在 Astro 中，你对所有 HTML 属性使用标准 kebab-case 格式，而不是 JSX 中使用的 camelCase。 这甚至适用于 React 不支持的 class。

英In Astro, you use the standard kebab-case format for all HTML attributes instead of the camelCase used in JSX. This even works for class, which is not supported by React.

example.astro

<div className="box" dataValue="3" />
<div class="box" data-value="3" />

多种元素

Section titled 多种元素

Astro 组件模板可以渲染多个元素，无需将所有内容封装在单个 <div> 或 <> 中，这与 JavaScript 或 JSX 不同。

英An Astro component template can render multiple elements with no need to wrap everything in a single <div> or <>, unlike JavaScript or JSX.

src/components/RootElements.astro

---
// Template with multiple elements
---
<p>
No need to wrap elements in a single containing element.
</p>
<p>
Astro supports multiple root elements in a template.
</p>

评论

Section titled 评论

在 Astro 中，你可以使用标准 HTML 注释或 JavaScript 样式注释。

英In Astro, you can use standard HTML comments or JavaScript-style comments.

example.astro

---
---
<!-- HTML comment syntax is valid in .astro files -->
{/* JS comment syntax is also valid */}

:::caution 提醒 HTML 风格的注释将包含在浏览器 DOM 中，而 JS 风格的注释将被跳过。 要留下 TODO 消息或其他仅用于开发的说明，你可能希望使用 JavaScript 风格的注释。 :::