raycast-extensions

Raycast 扩展开发

使用 React、TypeScript 和 Node.js 构建 Raycast 扩展。

快速开始

1. 创建扩展：在 Raycast 中运行“Create Extension”命令
2. 安装并开发：npm install && npm run dev
3. 编辑：修改 src/index.tsx，更改会自动热重载
4. 测试：扩展会显示在 Raycast 根搜索结果的顶部

选择 UI 原语

需求	组件
可搜索的项目列表	List
图片图库／网格	Grid
收集用户输入	Form
显示丰富内容	Detail
状态栏常驻显示	MenuBarExtra

决策树

1. 要显示用户可以搜索／筛选的项目吗？

   • 以文本为主 → List
   • 以图片为主 → Grid

2. 要收集用户输入吗？ → Form

3. 要显示详细内容吗？ → Detail（支持 Markdown 和元数据）

4. 要在状态栏中始终显示吗？ → MenuBarExtra

核心模式

带有 ActionPanel 的列表

import { ActionPanel, Action, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Item"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard content="Copied!" />
            <Action.OpenInBrowser url="https://raycast.com" />
          </ActionPanel>
        }
      />
    </List>
  );
}

数据获取

import { List } from "@raycast/api";
import { useFetch } from "@raycast/utils";

export default function Command() {
  const { data, isLoading } = useFetch<Item[]>("https://api.example.com/items");
  
  return (
    <List isLoading={isLoading}>
      {data?.map((item) => <List.Item key={item.id} title={item.name} />)}
    </List>
  );
}

AI 集成

import { AI, Clipboard } from "@raycast/api";

export default async function Command() {
  const answer = await AI.ask("Summarize this text");
  await Clipboard.copy(answer);
}

说明

AI 需要 Raycast Pro。使用 environment.canAccess(AI) 检查访问权限。

参考资料

如需详细文档，请参阅：

• UI 组件：references/ui-components.md - List、Detail、Form、Grid、ActionPanel、MenuBarExtra
• Hooks 和实用工具：references/hooks-utilities.md - useFetch、LocalStorage、Clipboard、OAuth、runAppleScript
• AI API：references/ai-api.md - AI.ask、useAI、模型选择、流式传输
• 包结构：references/package-structure.md - manifest、命令、偏好设置

示例

examples/ 中提供了可运行的示例：

文件	模式
list-with-actions.tsx	List 和 ActionPanel 基础用法
list-with-detail.tsx	带详情面板的 List
form-with-validation.tsx	Form 和 useForm 验证
detail-with-metadata.tsx	Detail Markdown 和元数据
grid-with-images.tsx	Grid 布局
data-fetching.tsx	useFetch 模式
ai-integration.tsx	使用流式传输的 AI.ask
menubar-extra.tsx	MenuBarExtra 交互