create-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Astro Component

创建 Astro 组件

Use this skill when scaffolding a new Astro component, page, layout, or route from a feature request, design, or static markup.

astro-best-practices

is available, apply it alongside this skill for project-wide conventions and review criteria.

当需要根据功能请求、设计稿或静态标记搭建新的 Astro 组件、页面、布局或路由时，使用此 skill。

如果可以使用

astro-best-practices

，请将其与此 skill 配合使用，以遵循项目级规范和审查标准。

Workflow

工作流

1. Pick the right file type

1. 选择正确的文件类型

Choose the simplest primitive that fits the requirement:

component: reusable UI in
```
src/components/
```
page: route entry in
```
src/pages/
```
layout: shared shell in
```
src/layouts/
```
framework island: React, Vue, or similar only when interactivity is required

Start with

.astro

unless there is a real need for client-side framework state.

选择最符合需求的基础类型：

组件：
```
src/components/
```
中可复用的 UI
页面：
```
src/pages/
```
中的路由入口
布局：
```
src/layouts/
```
中共享的页面框架
框架岛：仅在需要交互时使用 React、Vue 或类似框架

除非确实需要客户端框架状态，否则请从

.astro

开始。

2. Clarify the contract

2. 明确组件约定

Before scaffolding, determine:

what props the file accepts
whether it renders children or named slots
whether it fetches data
whether any interactivity is required
which styling approach the project already uses

Keep the public surface small. If a prop does not change rendering in a meaningful way, it probably should not exist.

在搭建之前，确定：

文件接受哪些 props
是否渲染 children 或命名插槽
是否获取数据
是否需要任何交互功能
项目已采用哪种样式方案

保持公开接口精简。如果某个 prop 不会对渲染产生实质影响，那么它通常就不应该存在。

3. Scaffold with strong defaults

3. 使用合理的默认设置进行搭建

Use typed props and semantic structure:

astro

---
interface Props {
  title: string
  variant?: 'primary' | 'secondary'
}

const { title, variant = 'primary' } = Astro.props
---

<section class:list={['card', variant]}>
  <h2>{title}</h2>
  <slot />
</section>

<style>
  .card {
    padding: 1rem;
  }
</style>

Good defaults:

semantic elements over generic
```
div
```
s
logical heading structure
sensible prop defaults
scoped styles unless the project uses another pattern intentionally
```
class:list
```
for conditional classes when it keeps markup clear

使用类型化 props 和语义化结构：

astro

---
interface Props {
  title: string
  variant?: 'primary' | 'secondary'
}

const { title, variant = 'primary' } = Astro.props
---

<section class:list={['card', variant]}>
  <h2>{title}</h2>
  <slot />
</section>

<style>
  .card {
    padding: 1rem;
  }
</style>

合理的默认设置：

优先使用语义化元素，而不是通用的
```
div
```
使用逻辑清晰的标题层级结构
为 props 设置合理的默认值
除非项目有意采用其他模式，否则使用作用域样式
当使用
```
class:list
```
能让标记更清晰时，用它处理条件类名

4. Add interactivity only when needed

4. 仅在必要时添加交互功能

If the component needs client-side behavior:

keep the interactive part as small as possible
isolate it in a framework component if that is the project pattern
choose the lightest hydration directive that works

Example:

astro

---
import SearchBox from './SearchBox.tsx'
---

<SearchBox client:visible />

Avoid turning large sections of a page into islands when a small interactive leaf component is enough.

如果组件需要客户端行为：

尽量缩小交互部分的范围
如果这是项目的既定模式，请将其隔离在框架组件中
选择能够满足需求的最轻量 hydration 指令

示例：

astro

---
import SearchBox from './SearchBox.tsx'
---

<SearchBox client:visible />

如果一个小型交互叶子组件已经足够，不要将页面中的大块内容都转换为岛组件。

5. Review accessibility and resilience

5. 审查无障碍能力和稳健性

Before calling the component done, check:

semantic HTML is appropriate
interactive elements are keyboard reachable
visible labels and accessible names exist
images have correct
```
alt
```
behavior
heading levels make sense in context
focus states remain visible

在认定组件完成之前，检查：

是否正确使用了语义化 HTML
交互元素是否可以通过键盘访问
是否存在可见标签和 accessible name
图片的
```
alt
```
行为是否正确
标题层级是否符合当前上下文
焦点状态是否保持可见

6. Fit the component into the project

6. 将组件融入项目

Align with the existing codebase:

follow naming conventions
preserve the established layout and styling approach
keep imports relative and readable
do not introduce a framework dependency just to mimic static HTML

与现有代码库保持一致：

遵循命名约定
保持既定的布局和样式方案
使用相对导入路径，并确保清晰易读
不要仅为模拟静态 HTML 而引入框架依赖

Use This Skill For

适用场景

converting static HTML into Astro components
scaffolding new routes or layouts
breaking large Astro files into smaller pieces
turning a design into accessible Astro markup

将静态 HTML 转换为 Astro 组件
搭建新的路由或布局
将大型 Astro 文件拆分为更小的模块
将设计稿转换为无障碍的 Astro 标记