raycast-extensions

Raycast 扩展技能

使用 React、TypeScript 和 Raycast API 构建强大的扩展。

仓库约定

• 更新 Raycast 扩展仓库的 CHANGELOG.md 时，始终使用 {PR_MERGE_DATE} 作为日期占位符。
• 切勿在 CHANGELOG.md 中填写具体日历日期。

快速入门（Agent 工作流）

实现或修复 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)。
   • 更新日志：更新 Raycast 扩展仓库的 CHANGELOG.md 时，始终使用 {PR_MERGE_DATE} 作为日期占位符。切勿填写具体日历日期。
4. 实现：使用 @raycast/api 组件提供简洁的实现。
5. 注明出处：链接到你使用的具体 references/api/*.md 文件。

实用模式

1. List 和 Grid（可搜索的 UI）

文本较多的数据使用 List，图片较多的数据使用 Grid。

• List 参考文档 | Grid 参考文档

<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. Detail（富文本 Markdown）

用于展示长篇内容或项目详情。

• Detail 参考文档

<Detail
  isLoading={isLoading}
  markdown="# Heading\nContent here."
  metadata={
    <Detail.Metadata>
      <Detail.Metadata.Label title="Status" text="Active" icon={Icon.Checkmark} />
    </Detail.Metadata>
  }
/>

3. Form（用户输入）

始终包含 SubmitForm 操作。

• Form 参考文档

<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 参考文档 | HUD 参考文档

// Success/Failure
await showToast({ style: Toast.Style.Success, title: "Success!" });

// HUD (Overlay)
await showHUD("Done!");

5. 数据持久化

使用 Cache 提升性能，使用 LocalStorage 实现持久化。

• Cache 参考文档 | Storage 参考文档

// 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 参考文档 | Browser 参考文档

if (environment.canAccess(AI)) {
  const result = await AI.ask("Prompt");
}

if (environment.canAccess(BrowserExtension)) {
  const tabs = await BrowserExtension.getTabs();
}

更多资源

API 参考目录

• UI 组件
  • 操作面板
  • Detail
  • Form
  • Grid
  • List
  • 用户界面
• 交互
  • 操作
  • 警告
  • 键盘
  • 导航
  • Raycast 窗口搜索栏
• 实用工具与服务
  • AI
  • 浏览器扩展
  • 剪贴板
  • 环境
  • 反馈与 HUD
    • HUD
    • Toast
  • OAuth
  • 系统实用工具
• 数据与配置
  • 缓存
  • 颜色
  • 图标与图像
  • 偏好设置
  • 存储
• 高级
  • 命令相关实用工具
  • 菜单栏命令
  • 工具
  • 窗口管理

示例

如需查看结合多个组件和 API 的端到端示例，请参阅 examples.md。