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 的表达式

¥JSX-like Expressions

你可以在 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 vs reactive

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.

See below for more examples of differences between Astro and JSX.

变量

Section titled 变量

¥Variables

可以使用大括号语法将局部变量添加到 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 动态属性

¥Dynamic Attributes

局部变量可以用在大括号中来将属性值传递给 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 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>

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

¥Dynamic 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 动态标签

¥Dynamic Tags

你还可以通过将 HTML 标签名称分配给变量或使用组件导入重新分配来使用动态标签：

¥You can also use dynamic tags by assigning an HTML tag name to a variable or with a component import reassignment:

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 需要知道要打包哪些组件进行生产，而动态标签模式阻止了这一点。

• 不支持 define:vars 指令。如果你无法用额外的元素（例如 <div>）封装子元素，那么你可以手动将 style={`--myVar:${value}`} 添加到你的元素中。

片段

Section titled 片段

¥Fragments

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 之间的差异

¥Differences between Astro and 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 属性

¥Attributes

在 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 多种元素

¥Multiple Elements

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 评论

¥Comments

在 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-style comments will be included in browser DOM, while JS ones will be skipped. To leave TODO messages or other development-only explanations, you may wish to use JavaScript-style comments instead.