List

我们的 List 组件提供了开箱即用的用户体验：

• 使用内置过滤以获得最佳性能。

• 将相关项分组到带有标题和子标题的 section 中。

• 给长久操作项显示 loading 指示器。

• 在限制范围内，使用搜索查询代替单个输入查询。

搜索栏

搜索栏允许用户与列表项快速交互。默认情况下，如果用户的输入可以与项目的 title 或 keyword（模糊）匹配，则显示 List.Items 。

自定义过滤

有时，您可能不想依赖 Raycast 的过滤，而是 使用/实现 您自己的过滤。如果是这种情况，您可以将列表的过滤属性设置为 false，这时显示的项目将独立于搜索栏的文本。请注意，如果指定了 onSearchTextChange 侦听器，过滤也会隐式设置为 false。如果您想指定更改侦听器并仍然利用 Raycast 的内置过滤功能，则需要显式将过滤设置为 true。

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

const items = ["Augustiner Helles", "Camden Hells", "Leffe Blonde", "Sierra Nevada IPA"];

export default function Command() {
  const [searchText, setSearchText] = useState("");
  const [filteredList, filterList] = useState(items);

  useEffect(() => {
    filterList(items.filter((item) => item.includes(searchText)));
  }, [searchText]);

  return (
    <List
      filtering={false}
      onSearchTextChange={setSearchText}
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite beer"
    >
      {filteredList.map((item) => (
        <List.Item
          key={item}
          title={item}
          actions={
            <ActionPanel>
              <Action title="Select" onAction={() => console.log(`${item} selected`)} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}

用编程的方式更新搜索栏

在其他时候，您可能希望扩展程序更新搜索栏的内容，例如，您可以存储用户之前的搜索列表，并在下次访问时允许他们从上次中断的地方“继续”。

为此，您可以使用 searchText 属性。

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

const items = ["Augustiner Helles", "Camden Hells", "Leffe Blonde", "Sierra Nevada IPA"];

export default function Command() {
  const [searchText, setSearchText] = useState("");

  return (
    <List
      searchText={searchText}
      onSearchTextChange={setSearchText}
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite beer"
    >
      {items.map((item) => (
        <List.Item
          key={item}
          title={item}
          actions={
            <ActionPanel>
              <Action title="Select" onAction={() => setSearchText(item)} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}

下拉菜单

某些扩展可能会为用户提供第二个过滤维度，比如待办事项扩展可能允许用户使用不同的组，阅读报纸扩展可能希望允许快速切换类别等。

这就是 searchBarAccessory 属性有用的地方。向其传递一个 List.Dropdown 组件，它将显示在搜索栏的右侧。通过使用全局快捷键 ⌘ P 或单击它来调用它。

例子

List.tsx

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

export default function Command() {
  return (
    <List>
      <List.Item title="Item 1" />
      <List.Item title="Item 2" subtitle="Optional subtitle" />
    </List>
  );
}

ListWithSections.tsx

ListWithActions.tsx

ListWithDetail.tsx

ListWithEmptyView.tsx

API 参考

List

参考 List.Section 或 List.Item.

该列表通过对列表项的标题和附加关键字建立索引来使用内置过滤。

例子

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

export default function Command() {
  return (
    <List navigationTitle="Search Beers" searchBarPlaceholder="Search your favorite beer">
      <List.Item title="Augustiner Helles" />
      <List.Item title="Camden Hells" />
      <List.Item title="Leffe Blonde" />
      <List.Item title="Sierra Nevada IPA" />
    </List>
  );
}

参数

名称	描述	类型	默认
actions	对 ActionPanel 的引用。仅当没有任何子项时才会显示。	React.ReactNode	-
children	列出 section 或 item。如果指定了 List.Item 元素，则会自动创建默认部分。	React.ReactNode	-
filtering	切换 Raycast 过滤。如果为 true，Raycast 将使用搜索栏中的查询来过滤项目。当为 false 时，扩展程序需要负责过滤。	boolean or { keepSectionOrder: boolean }	当指定 onSearchTextChange 时为 false，否则为 true。
isLoading	是否在搜索栏下方显示或隐藏 loading	boolean	false
isShowingDetail	列表是否应在项目右侧有一个区域以显示有关所选项的其他详细信息。	boolean	-
navigationTitle	Raycast 中显示的该视图的主标题	string	Command title
searchBarAccessory	List.Dropdown 将显示在搜索栏的右侧。	ReactElement<List.Dropdown.Props, string>	-
searchBarPlaceholder	显示在搜索栏中的占位符文本。	string	"Search…"
searchText	显示在搜索栏中的文本。	string	-
selectedItemId	选择具有指定 id 的项。	string	-
throttle	onSearchTextChange 处理程序是在每次按下键盘时触发还是延迟以限制事件。当自定义过滤逻辑与异步操作（例如网络请求）结合使用时，建议设置为 true。	boolean	false
onSearchTextChange	当搜索栏文本发生变化时触发回调。	(text: string) => void	-
onSelectionChange	当列表中的项选择发生变化时触发回调。	(id: string) => void	-

List.Dropdown

显示在搜索栏右侧的下拉菜单。

例子

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

type DrinkType = { id: string; name: string };

function DrinkDropdown(props: { drinkTypes: DrinkType[]; onDrinkTypeChange: (newValue: string) => void }) {
  const { drinkTypes, onDrinkTypeChange } = props;
  return (
    <List.Dropdown
      tooltip="Select Drink Type"
      storeValue={true}
      onChange={(newValue) => {
        onDrinkTypeChange(newValue);
      }}
    >
      <List.Dropdown.Section title="Alcoholic Beverages">
        {drinkTypes.map((drinkType) => (
          <List.Dropdown.Item key={drinkType.id} title={drinkType.name} value={drinkType.id} />
        ))}
      </List.Dropdown.Section>
    </List.Dropdown>
  );
}

export default function Command() {
  const drinkTypes: DrinkType[] = [
    { id: "1", name: "Beer" },
    { id: "2", name: "Wine" },
  ];
  const onDrinkTypeChange = (newValue: string) => {
    console.log(newValue);
  };
  return (
    <List
      navigationTitle="Search Beers"
      searchBarPlaceholder="Search your favorite drink"
      searchBarAccessory={<DrinkDropdown drinkTypes={drinkTypes} onDrinkTypeChange={onDrinkTypeChange} />}
    >
      <List.Item title="Augustiner Helles" />
      <List.Item title="Camden Hells" />
      <List.Item title="Leffe Blonde" />
      <List.Item title="Sierra Nevada IPA" />
    </List>
  );
}

参数

名称	描述	类型	默认
tooltip*	鼠标悬停在下拉菜单上时显示提示。	string	-
children	下拉部分或 item。如果指定了 Dropdown.Item 元素，则会自动创建默认部分。	React.ReactNode	-
defaultValue	下拉列表的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。	string	-
filtering	切换 Raycast 过滤。如果为 true，Raycast 将使用搜索栏中的查询来过滤项目。当为 false 时，扩展程序需要负责过滤。	boolean or { keepSectionOrder: boolean }	当指定 onSearchTextChange 时为 false，否则为 true。
id	下拉列表的 ID。	string	-
isLoading	是否应在搜索栏旁边显示或隐藏 loading 指示器	boolean	false
placeholder	显示在下拉搜索字段中的占位符文本。	string	"Search…"
storeValue	下拉列表的值是否应在选择后保留，并在下次渲染下拉列表时恢复。	boolean	-
throttle	定义 onSearchTextChange 处理程序是在每次按下键盘时触发还是延迟以限制事件。当将自定义过滤逻辑与异步操作（例如网络请求）结合使用时，建议设置为 true。	boolean	false
value	下拉菜单的当前值。	string	-
onChange	当下拉选择发生变化时触发回调。	(newValue: string) => void	-
onSearchTextChange	当搜索栏文本发生变化时触发回调。	(text: string) => void	-

List.Dropdown.Item

List.Dropdown 中的下拉项

例子

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

export default function Command() {
  return (
    <List
      searchBarAccessory={
        <List.Dropdown tooltip="Dropdown With Items">
          <List.Dropdown.Item title="One" value="one" />
          <List.Dropdown.Item title="Two" value="two" />
          <List.Dropdown.Item title="Three" value="three" />
        </List.Dropdown>
      }
    >
      <List.Item title="Item in the Main List" />
    </List>
  );
}

参数

名称	描述	类型	默认
title*	显示的标题。	string	-
value*	下拉项的值。确保为每个项目分配每个唯一值。	string	-
icon	该项的可选图标。	Image.ImageLike	-
keywords	一个可选属性，用于提供额外的可索引字符串以供搜索。在 Raycast 中过滤项目时，除了标题之外还会搜索关键字。	string[]	The title of its section if any

List.Dropdown.Section

分离的下拉项组。

使用 section 将相关菜单项分到一个组。

例子

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

export default function Command() {
  return (
    <List
      searchBarAccessory={
        <List.Dropdown tooltip="Dropdown With Sections">
          <List.Dropdown.Section title="First Section">
            <List.Dropdown.Item title="One" value="one" />
          </List.Dropdown.Section>
          <List.Dropdown.Section title="Second Section">
            <List.Dropdown.Item title="Two" value="two" />
          </List.Dropdown.Section>
        </List.Dropdown>
      }
    >
      <List.Item title="Item in the Main List" />
    </List>
  );
}

参数

名称	描述	类型	默认
children	section 项	React.ReactNode	-
title	该 section 上方的标题	string	-

List.EmptyView

当没有任何可用项目时显示的视图。

Raycast 提供了一个默认的 EmptyView，如果 List 组件没有子组件，或者有子组件，但没有一个与搜索栏中的查询匹配，则将显示该 EmptyView。也可以通过与其他 List.Item 一起传递空视图来覆盖。

请注意，如果 List 的 isLoading 属性为 true 并且搜索栏为空，则永远不会显示 EmptyView。

列表为空的插图

例子

import { useEffect, useState } from "react";
import { List } from "@raycast/api";

export default function CommandWithCustomEmptyView() {
  const [state, setState] = useState({ searchText: "", items: [] });

  useEffect(() => {
    // perform an API call that eventually populates `items`.
  }, [state.searchText]);

  return (
    <List onSearchTextChange={(newValue) => setState((previous) => ({ ...previous, searchText: newValue }))}>
      {state.searchText === "" && state.items.length === 0 ? (
        <List.EmptyView icon={{ source: "https://placekitten.com/500/500" }} title="Type something to get started" />
      ) : (
        state.items.map((item) => <List.Item key={item} title={item} />)
      )}
    </List>
  );
}

参数

名称	描述	类型	默认
actions	对 ActionPanel 的引用。	React.ReactNode	-
description	空视图的可选描述。	string	-
icon	在 EmptyView 中心的图标。	Image.ImageLike	-
title	空视图的主标题。	string	-

List.Item

List 中的一项

这是 Raycast 的基本 UI 组件之一。列表项代表单个实体。它可以是 GitHub PR、文件或其他任何内容。您很可能想要对此项目执行操作，因此请让用户清楚该列表项的含义。

例子

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

export default function Command() {
  return (
    <List>
      <List.Item icon={Icon.Star} title="Augustiner Helles" subtitle="0,5 Liter" accessories={[{ text: "Germany" }]} />
    </List>
  );
}

参数

名称	描述	类型	默认
title*	显示的主标题，可以选择带有提示。	string 或 { tooltip: string; value: string }	-
accessories	显示在 List.Item 右侧的可选 List.Item.Accessory 项数组。	List.Item.Accessory[]	-
actions	将为所选列表项更新的 ActionPanel。	React.ReactNode	-
detail	当父列表显示详细信息并且选择该项目时，List.Item.Detail 将在右侧区域呈现。	React.ReactNode	-
icon	列表项的可选图标。	Image.ImageLike 或 { tooltip: string; value: Image.ImageLike }	-
id	当选择该项时，此字符串将传递到列表的 onSelectionChange 处理。确保为每个项目分配一个唯一的 ID，否则将自动生成 UUID。	string	-
keywords	一个可选属性，用于提供额外的可索引字符串以供搜索。当通过搜索栏过滤 Raycast 中的列表时，除了标题之外还会搜索关键字。	string[]	-
quickLook	使用 “Quick Look” 预览文件的可选信息。使用 Action.ToggleQuickLook 切换预览。	{ name: string; path: string }	-
subtitle	主标题旁边的可选子标题，可以选择带有提示。	string 或 { tooltip: string; value: string }	-

List.Item.Detail

在列表右侧的详细信息视图。 显示时，建议不要在 List.Item 上显示任何附件，最好将这些附加信息显示在 List.Item.Detail 视图中。

列表详细说明

例子

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

export default function Command() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Pikachu"
        subtitle="Electric"
        detail={
          <List.Item.Detail markdown="![Illustration](https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/25.png)" />
        }
      />
    </List>
  );
}

参数

名称	描述	类型	默认
isLoading	是否应在详细信息上方显示或隐藏 loading 栏	boolean	false
markdown	当父列表显示详细信息并且选择该项时，要在右侧区域呈现的 CommonMark 字符串。	string	-
metadata	要在 List.Item.Detail 底部呈现的 List.Item.Detail.Metadata	React.ReactNode	-

List.Item.Detail.Metadata

在 List.Item.Detail 底部的元数据视图。 使用它来显示有关 List.Item 内容的附加结构化数据。

例子

Metadata + Markdown

列表详细信息-元数据说明

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

export default function Metadata() {
  const markdown = `
![Illustration](https://assets.pokemon.com/assets/cms2/img/pokedex/full/001.png)
There is a plant seed on its back right from the day this Pokémon is born. The seed slowly grows larger.
`;
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            markdown={markdown}
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Types" />
                <List.Item.Detail.Metadata.Label title="Grass" icon="pokemon_types/grass.svg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Poison" icon="pokemon_types/poison.svg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Chracteristics" />
                <List.Item.Detail.Metadata.Label title="Height" text="70cm" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Weight" text="6.9 kg" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Abilities" />
                <List.Item.Detail.Metadata.Label title="Chlorophyll" text="Main Series" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Overgrow" text="Main Series" />
                <List.Item.Detail.Metadata.Separator />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}

单独的 Metadata

参数

名称	描述	类型	默认
children*	元数据视图的元素。	React.ReactNode	-

List.Item.Detail.Metadata.Label

标题的右侧可以选择带有图标 和/或 文本。

List Detail-metadata-label illustration

例子

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

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/grass.svg" text="Grass" />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}

参数

名称	描述	类型	默认
title*	该项的标题。	string	-
icon	该项的图标。	Image.ImageLike	-
text	该项的文本。指定颜色将以提供的颜色显示文本。默认为 Color.SecondaryText。	string 或 { color: Color; value: string }	-

List.Item.Detail.Metadata.Link

显示链接的项。

列表详细信息-元数据-链接说明

例子

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

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Link
                  title="Evolution"
                  target="https://www.pokemon.com/us/pokedex/pikachu"
                  text="Raichu"
                />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}

参数

名称	描述	类型	默认
target*	链接的目标。	string	-
text*	项目的文本。	string	-
title*	在项目上方的标题。	string	-

List.Item.Detail.Metadata.TagList

单行显示的 Tags 列表。

列表详细信息-元数据-标签-列表插图

例子

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

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.TagList title="Type">
                  <List.Item.Detail.Metadata.TagList.Item text="Electric" color={"#eed535"} />
                </List.Item.Detail.Metadata.TagList>
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}

参数

名称	描述	类型	默认
children*	TagList 中包含的 tag。	React.ReactNode	-
title*	在项目上方的标题。	string	-

List.Item.Detail.Metadata.TagList.Item

List.Item.Detail.Metadata.TagList 中的 tag。

参数

名称	描述	类型	默认
text*	tag 的文本。	string	-
color	将文本颜色更改为提供的颜色，并设置相同颜色的透明背景。	Color.ColorLike	-
icon	标签文本前面的可选图标。	Image.ImageLike	-
onAction	单击该项时触发的回调。	() => void	-

List.Item.Detail.Metadata.Separator

显示分隔线的元数据项。使用它来分组和直观地分隔元数据项。

列表详细信息-元数据-分隔符说明

例子

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

export default function Metadata() {
  return (
    <List isShowingDetail>
      <List.Item
        title="Bulbasaur"
        detail={
          <List.Item.Detail
            metadata={
              <List.Item.Detail.Metadata>
                <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/grass.svg" text="Grass" />
                <List.Item.Detail.Metadata.Separator />
                <List.Item.Detail.Metadata.Label title="Type" icon="pokemon_types/poison.svg" text="Poison" />
              </List.Item.Detail.Metadata>
            }
          />
        }
      />
    </List>
  );
}

List.Section

一组 List.Item.

section 是构建列表的好方法。例如，将具有相同状态的 GitHub 问题分组并按优先级排序。这样，用户可以快速访问最相关的内容。

例子

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

export default function Command() {
  return (
    <List>
      <List.Section title="Lager">
        <List.Item title="Camden Hells" />
      </List.Section>
      <List.Section title="IPA">
        <List.Item title="Sierra Nevada IPA" />
      </List.Section>
    </List>
  );
}

参数

名称	描述	类型	默认
children	section 的 List.Item	React.ReactNode	-
subtitle	在该 section 标题旁边的可选子标题。	string	-
title	该 section 上方的标题。	string	-

类型

List.Item.Accessory

描述 List.Item 中的附件视图的接口。

List.Item 装饰图

属性

名称	描述	类型
tag*	label 的字符串或日期，可以选择颜色。日期的格式相对于当前时间（例如 new Date() 将显示为“now”，昨天的日期将显示为“1d”等）。颜色会把文本更改为提供的颜色，并设置相同颜色的透明背景。默认为 Color.SecondaryText。	string 或 Date 或 undefined 或 null 或 { color: Color.ColorLike; value: string 或 Date 或 undefined 或 null }
text	label 的可选文本，可以选择颜色。颜色将文本颜色更改为提供的颜色。默认为 Color.SecondaryText.	string 或 null 或 { color: Color; value: string 或 undefined 或 null }
date	将用作 label 的可选日期，可以设置颜色。日期的格式相对于当前时间（例如 new Date() 将显示为“now”，昨天的日期将显示为“1d”等）。颜色会把文本更改为提供的颜色。 默认为 Color.SecondaryText.	Date 或 null 或 color: Color; value: Date 或 undefined 或 null }
icon	图标的可选 Image.ImageLike。	Image.ImageLike 或 null
tooltip	当附件悬停时显示的提示。	string 或 null

例子

import { Color, Icon, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="An Item with Accessories"
        accessories={[
          { text: `An Accessory Text`, icon: Icon.Hammer },
          { text: { value: `A Colored Accessory Text`, color: Color.Orange }, icon: Icon.Hammer },
          { icon: Icon.Person, tooltip: "A person" },
          { text: "Just Do It!" },
          { date: new Date() },
          { tag: new Date() },
          { tag: { value: new Date(), color: Color.Magenta } },
          { tag: { value: "User", color: Color.Magenta }, tooltip: "Tag with tooltip" },
        ]}
      />
    </List>
  );
}