介绍
# Raycast Extensions Skill
使用 React、TypeScript 和 Raycast API 构建强大的扩展。
## 快速开始（代理工作流）
在负责实现或修复 Raycast 功能时，请遵循以下步骤：
1. **确定核心组件**：判断 UI 需要 `List`、`Grid`、`Detail` 还是 `Form`。 2. **查阅参考**：打开并阅读 `references/api/` 中对应的文件（例如 `references/api/list.md`）。 3. **使用默认设置**： - **反馈**：使用 `showToast` 处理加载/成功/失败状态。仅在快速后台完成时使用 `showHUD`。 - **数据**：对于频繁/临时数据使用 `Cache`，对于持久化用户数据使用 `LocalStorage`。 - **访问权限**：在使用前始终检查 `environment.canAccess(AI)` 或 `environment.canAccess(BrowserExtension)`。 4. **实现**：使用 `@raycast/api` 组件提供简洁的实现。 5. **引用**：链接回你使用的具体 `references/api/*.md` 文件。
## 常用模式
### 1. 列表和网格（可搜索 UI） 使用 `List` 处理文本繁多的数据，使用 `Grid` 处理图像繁多的数据。 - [List Reference](references/api/list.md) | [Grid Reference](references/api/grid.md)
```tsx <List isLoading={isLoading} searchBarPlaceholder="Search items..." throttle> <List.Item title="Item Title" subtitle="Subtitle" accessories={[{ text: "Tag" }]} actions={ <ActionPanel> <Action.Push title="View Details" target={<Detail markdown="# Details" />} /> <Action.CopyToClipboard title="Copy" content="value" /> </ActionPanel> } /> </List> ```
### 2. 详情（富 Markdown） 用于显示长篇内容或项目详细信息。 - [Detail Reference](references/api/detail.md)
```tsx <Detail isLoading={isLoading} markdown="# Heading\nContent here." metadata={ <Detail.Metadata> <Detail.Metadata.Label title="Status" text="Active" icon={Icon.Checkmark} /> </Detail.Metadata> } /> ```
### 3. 表单（用户输入） 始终包含 `SubmitForm` 操作。 - [Form Reference](references/api/form.md)
```tsx <Form actions={ <ActionPanel> <Action.SubmitForm onSubmit={(values) => console.log(values)} /> </ActionPanel> } > <Form.TextField id="title" title="Title" placeholder="Enter title" /> <Form.TextArea id="description" title="Description" /> </Form> ```
### 4. 反馈与交互 大多数情况下优先使用 `showToast` 进行反馈。 - [Toast Reference](references/api/toast.md) | [HUD Reference](references/api/hud.md)
```typescript // Success/Failure await showToast({ style: Toast.Style.Success, title: "Success!" });
// HUD (Overlay) await showHUD("Done!"); ```
### 5. 数据持久化 使用 `Cache` 提高性能，使用 `LocalStorage` 保持持久化。 - [Cache Reference](references/api/caching.md) | [Storage Reference](references/api/storage.md)
```typescript // Cache (Sync/Transient) const cache = new Cache(); cache.set("key", "value");
// LocalStorage (Async/Persistent) await LocalStorage.setItem("key", "value"); ```
### 6. AI 与浏览器扩展（受限 API） 始终使用 `environment.canAccess` 检查进行包裹。 - [AI Reference](references/api/ai.md) | [Browser Reference](references/api/browser-extension.md)
```typescript if (environment.canAccess(AI)) { const result = await AI.ask("Prompt"); }
if (environment.canAccess(BrowserExtension)) { const tabs = await BrowserExtension.getTabs(); } ```
## 其他资源
### API 参考树
- **UI 组件** - [Action Panel](references/api/action-panel.md) - [Detail](references/api/detail.md) - [Form](references/api/form.md) - [Grid](references/api/grid.md) - [List](references/api/list.md) - [User Interface](references/api/user-interface.md) - **交互** - [Actions](references/api/actions.md) - [Alert](references/api/alert.md) - [Keyboard](references/api/keyboard.md) - [Navigation](references/api/navigation.md) - [Raycast Window Search Bar](references/api/raycast-window-search-bar.md) - **工具与服务** - [AI](references/api/ai.md) - [Browser Extension](references/api/browser-extension.md) - [Clipboard](references/api/clipboard.md) - [Environment](references/api/environment.md) - [Feedback & HUD](references/api/feedback.md) - [HUD](references/api/hud.md) - [Toast](references/api/toast.md) - [OAuth](references/api/oauth.md) - [System Utilities](references/api/system-utilities.md) - **数据与配置** - [Caching](references/api/caching.md) - [Colors](references/api/colors.md) - [Icons & Images](references/api/icons-images.md) - [Preferences](references/api/preferences.md) - [Storage](references/api/storage.md) - **高级** - [Command Related Utilities](references/api/command-related-utilities.md) - [Menu Bar Commands](references/api/menu-bar-commands.md) - [Tool](references/api/tool.md) - [Window Management](references/api/window-management.md)
## 示例
有关结合多个组件和 API 的端到端示例，请参阅 [examples.md](examples.md)。