Form

我们的 Form 组件提供了出色的用户体验，可以从用户那里收集一些数据并提交以满足扩展需求。

两种类型：受控与不受控

React 中的项可以是以下两种类型之一：受控或不受控。

不受控的项是两者中较简单的一个。它最接近纯 HTML 输入。 React 将其放在页面上，Raycast 跟踪其余部分。不受控的输入需要更少的代码，但会使执行某些操作变得更加困难。

对于受控，您可以明确控制该项显示的 value 。您必须编写代码来通过定义 onChange 回调来响应更改，将当前值存储在某处，并将该值传递回要显示的项。这是你的代码中的一种回馈循环。想连接起来这些需要更多的工作，不过它们提供了够多的可控性。

您可以在每个支持的项下查看下面这两种样式。

校验

在提交数据之前，确保以正确的格式填写所有必需的表单控件非常重要。

在 Raycast 中，可以通过 API 完全控制验证。为了保持与本机相同的行为，正确的使用方法是验证 onBlur 回调中的值，更新条目的错误并使用 onChange 回调跟踪更新从而删除错误的值。

请记住，表单有任何错误，都不会触发 Action.SubmitForm onSubmit 回调。

例子

import { Form } from "@raycast/api";
import { useState } from "react";

export default function Command() {
  const [nameError, setNameError] = useState<string | undefined>();
  const [passwordError, setPasswordError] = useState<string | undefined>();

  function dropNameErrorIfNeeded() {
    if (nameError && nameError.length > 0) {
      setNameError(undefined);
    }
  }

  function dropPasswordErrorIfNeeded() {
    if (passwordError && passwordError.length > 0) {
      setPasswordError(undefined);
    }
  }

  return (
    <Form>
      <Form.TextField
        id="nameField"
        title="Full Name"
        placeholder="Enter your name"
        error={nameError}
        onChange={dropNameErrorIfNeeded}
        onBlur={(event) => {
          if (event.target.value?.length == 0) {
            setNameError("The field should't be empty!");
          } else {
            dropNameErrorIfNeeded();
          }
        }}
      />
      <Form.PasswordField
        id="password"
        title="New Password"
        error={passwordError}
        onChange={dropPasswordErrorIfNeeded}
        onBlur={(event) => {
          const value = event.target.value;
          if (value && value.length > 0) {
            if (!validatePassword(value)) {
              setPasswordError("Password should be at least 8 characters!");
            } else {
              dropPasswordErrorIfNeeded();
            }
          } else {
            setPasswordError("The field should't be empty!");
          }
        }}
      />
      <Form.TextArea id="bioTextArea" title="Add Bio" placeholder="Describe who you are" />
      <Form.DatePicker id="birthDate" title="Date of Birth" />
    </Form>
  );
}

function validatePassword(value: string): boolean {
  return value.length >= 8;
}

草稿

草稿是一种在最终用户退出命令时保留已填写的输入（但尚未提交）的机制。要启用此机制，请在表单上设置 enableDrafts 属性，并使用顶级属性 draftValues 填充表单的初始值。

尚不支持嵌套在导航中的表单草稿。在这种情况下，您将看到一条警告。
草稿不会保留 Form.Password 的值。
一旦 Action.SubmitForm 被触发，草稿就会被丢弃。
如果您调用 popToRoot()，草稿将不会被保留或更新。

例子

import { Form, ActionPanel, Action, popToRoot, LaunchProps } from "@raycast/api";

interface TodoValues {
  title: string;
  description?: string;
  dueDate?: Date;
}

export default function Command(props: LaunchProps<{ draftValues: TodoValues }>) {
  const { draftValues } = props;

  return (
    <Form
      enableDrafts
      actions={
        <ActionPanel>
          <Action.SubmitForm
            onSubmit={(values: TodoValues) => {
              console.log("onSubmit", values);
              popToRoot();
            }}
          />
        </ActionPanel>
      }
    >
      <Form.TextField id="title" title="Title" defaultValue={draftValues?.title} />
      <Form.TextArea id="description" title="Description" defaultValue={draftValues?.description} />
      <Form.DatePicker id="dueDate" title="Due Date" defaultValue={draftValues?.dueDate} />
    </Form>
  );
}

import { Form, ActionPanel, Action, popToRoot, LaunchProps } from "@raycast/api";
import { useState } from "react";

interface TodoValues {
  title: string;
  description?: string;
  dueDate?: Date;
}

export default function Command(props: LaunchProps<{ draftValues: TodoValues }>) {
  const { draftValues } = props;

  const [title, setTitle] = useState<string>(draftValues?.title || "");
  const [description, setDescription] = useState<string>(draftValues?.description || "");
  const [dueDate, setDueDate] = useState<Date | null>(draftValues?.dueDate || null);

  return (
    <Form
      enableDrafts
      actions={
        <ActionPanel>
          <Action.SubmitForm
            onSubmit={(values: TodoValues) => {
              console.log("onSubmit", values);
              popToRoot();
            }}
          />
        </ActionPanel>
      }
    >
      <Form.TextField id="title" title="Title" value={title} onChange={setTitle} />
      <Form.TextArea id="description" title="Description" value={description} onChange={setDescription} />
      <Form.DatePicker id="dueDate" title="Due Date" value={dueDate} onChange={setDueDate} />
    </Form>
  );
}

API 参数

Form

显示表单项的列表，例如 Form.TextField, Form.Checkbox 或 Form.Dropdown.

参数

名称

描述

类型

默认

actions

对 ActionPanel 的引用。

React.ReactNode

children

表单的 Form.Item 元素。

React.ReactNode

enableDrafts

当用户退出屏幕时是否保留 Form.Items 值。

boolean

false

isLoading

是否应在搜索栏下方显示或隐藏 loading 栏

boolean

false

navigationTitle

Raycast 中显示的该视图的主标题

string

Command title

Form.TextField

带有用于输入的文本字段的表单项。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" defaultValue="Steve" />
    </Form>
  );
}

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

export default function Command() {
  const [name, setName] = useState<string>("");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="name" value={name} onChange={setName} />
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

defaultValue

项的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

string

error

显示表单项验证问题的可选错误消息。如果存在 error ，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在条目的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

placeholder

文本字段中显示的占位符文本。

string

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

value

当前项的值

string

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<string>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: string) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<string>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.PasswordField

具有用于输入密码的安全文本字段的表单项，其中输入的字符必须保密。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Password" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.PasswordField id="password" title="Enter Password" />
    </Form>
  );
}

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

export default function Command() {
  const [password, setPassword] = useState<string>("");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Password" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.PasswordField id="password" value={password} onChange={setPassword} />
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

string

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

placeholder

密码字段中显示的占位符文本。

string

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

value

当前项的值

string

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<string>) => void

onChange

当项的值发生变化时会触发的回调。

(newValue: string) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<string>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦该项。

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.TextArea

带有用于输入的文本区域的表单项。该项支持多行文本输入。

例子

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

const DESCRIPTION =
  "We spend too much time staring at loading indicators. The Raycast team is dedicated to make everybody interact faster with their computers.";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Description" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextArea id="description" defaultValue={DESCRIPTION} />
    </Form>
  );
}

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

export default function Command() {
  const [description, setDescription] = useState<string>("");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Description" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextArea id="description" value={description} onChange={setDescription} />
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

string

enableMarkdown

Markdown 是否会在 TextArea 中突出显示。启用后，Markdown 快捷方式开始对 TextArea 起作用（按 ⌘ + B 将在所选文本周围添加粗体，⌘ + I 将使所选文本变为斜体等）

boolean

false

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

placeholder

文本区域中显示的占位符文本。

string

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

value

当前项的值

string

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<string>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: string) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<string>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.Checkbox

带有复选框的表单项。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Answer" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Checkbox id="answer" label="Are you happy?" defaultValue={true} />
    </Form>
  );
}

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

export default function Command() {
  const [checked, setChecked] = useState(true);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Answer" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Checkbox id="answer" label="Do you like orange juice?" value={checked} onChange={setChecked} />
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

label*

显示在复选框右侧的标签。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

boolean

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

value

当前项的值

boolean

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<boolean>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: boolean) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<boolean>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.DatePicker

带有日期选择器的表单项。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="dateOfBirth" title="Date of Birth" defaultValue={new Date(1955, 1, 24)} />
    </Form>
  );
}

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

export default function Command() {
  const [date, setDate] = useState<Date | null>(null);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.DatePicker id="launchDate" title="Launch Date" value={date} onChange={setDate} />
    </Form>
  );
}

Props

Prop

Description

Type

Default

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

Date

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

max

允许选择的最长日期（含）。

Date

min

允许选择的最短日期（含）。

Date

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

type

可以选择哪些类型的日期组件

Form.DatePicker.Type

value

当前项的值

Date

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<Date | null>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: Date | null) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<Date | null>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

带有下拉菜单的表单项。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="emoji" title="Favorite Emoji" defaultValue="lol">
        <Form.Dropdown.Item value="poop" title="Pile of poop" icon="💩" />
        <Form.Dropdown.Item value="rocket" title="Rocket" icon="🚀" />
        <Form.Dropdown.Item value="lol" title="Rolling on the floor laughing face" icon="🤣" />
      </Form.Dropdown>
    </Form>
  );
}

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

export default function Command() {
  const [programmingLanguage, setProgrammingLanguage] = useState<string>("typescript");

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown
        id="dropdown"
        title="Favorite Language"
        value={programmingLanguage}
        onChange={setProgrammingLanguage}
      >
        <Form.Dropdown.Item value="cpp" title="C++" />
        <Form.Dropdown.Item value="javascript" title="JavaScript" />
        <Form.Dropdown.Item value="ruby" title="Ruby" />
        <Form.Dropdown.Item value="python" title="Python" />
        <Form.Dropdown.Item value="swift" title="Swift" />
        <Form.Dropdown.Item value="typescript" title="TypeScript" />
      </Form.Dropdown>
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

children

内容为 Sections 或是item。如果指定了 Form.Dropdown.Item 元素，则会自动创建默认部分。

React.ReactNode

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

string

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

filtering

切换 Raycast filtering。如果为 true，Raycast 将使用搜索栏中的查询来过滤项目。当为 false 时，扩展程序需要负责过滤。

boolean 或 { keepSectionOrder: boolean }

当指定 onSearchTextChange 时为 false，否则为 true。

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

isLoading

是否应在搜索栏旁边显示或隐藏 loading 指示器

boolean

false

placeholder

显示在下拉搜索字段中的占位符文本。

string

"Search…"

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

throttle

onSearchTextChange 处理程序是在每次按下键盘时触发还是延迟以限制事件。当将自定义过滤逻辑与异步操作（例如网络请求）结合使用时，建议设置为 true。

boolean

false

title

显示在项的左侧标题。

string

value

当前项的值

string

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<string>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: string) => void

onFocus

当项获得焦点时调用将触发的回调。

(event: FormEvent<string>) => void

onSearchTextChange

当项获得焦点时，应该调用将触发的回调。

(text: string) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.Dropdown 的项

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Icon" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="icon" title="Icon">
        <Form.Dropdown.Item value="circle" title="Cirlce" icon={Icon.Circle} />
      </Form.Dropdown>
    </Form>
  );
}

参数

Prop

Description

Type

Default

title*

显示的标题。

string

value*

下拉项的值。确保为每个项目分配每个唯一值。

string

icon

该项显示的可选图标。

Image.ImageLike

keywords

一个可选属性，用于提供额外的可索引字符串以供搜索。在 Raycast 中过滤项目时，除了标题之外还会搜索关键字。

string[]

The title of its section if any

视觉上分离的下拉项组。

使用 sections 将相关的菜单项分组在一起。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Dropdown id="food" title="Favorite Food">
        <Form.Dropdown.Section title="Fruits">
          <Form.Dropdown.Item value="apple" title="Apple" icon="🍎" />
          <Form.Dropdown.Item value="banana" title="Banana" icon="🍌" />
        </Form.Dropdown.Section>
        <Form.Dropdown.Section title="Vegetables">
          <Form.Dropdown.Item value="broccoli" title="Broccoli" icon="🥦" />
          <Form.Dropdown.Item value="carrot" title="Carrot" icon="🥕" />
        </Form.Dropdown.Section>
      </Form.Dropdown>
    </Form>
  );
}

参数

名称

描述

类型

默认

children

子项

React.ReactNode

title

显示在该部分上方的标题

string

Form.TagPicker

带有标签选择器的表单项，允许用户选择多个项目。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Favorite" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="sports" title="Favorite Sports" defaultValue={["football"]}>
        <Form.TagPicker.Item value="basketball" title="Basketball" icon="🏀" />
        <Form.TagPicker.Item value="football" title="Football" icon="⚽️" />
        <Form.TagPicker.Item value="tennis" title="Tennis" icon="🎾" />
      </Form.TagPicker>
    </Form>
  );
}

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

export default function Command() {
  const [countries, setCountries] = useState<string[]>(["ger", "ned", "pol"]);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Countries" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="countries" title="Visited Countries" value={countries} onChange={setCountries}>
        <Form.TagPicker.Item value="ger" title="Germany" icon="🇩🇪" />
        <Form.TagPicker.Item value="ind" title="India" icon="🇮🇳" />
        <Form.TagPicker.Item value="ned" title="Netherlands" icon="🇳🇱" />
        <Form.TagPicker.Item value="nor" title="Norway" icon="🇳🇴" />
        <Form.TagPicker.Item value="pol" title="Poland" icon="🇵🇱" />
        <Form.TagPicker.Item value="rus" title="Russia" icon="🇷🇺" />
        <Form.TagPicker.Item value="sco" title="Scotland" icon="🏴󠁧󠁢󠁳󠁣󠁴󠁿" />
      </Form.TagPicker>
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

children

tag 的子项.

React.ReactNode

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

string[]

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

placeholder

token 字段中显示的占位符文本。

string

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

value

当前项的值

string[]

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<string[]>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: string[]) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<string[]>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.TagPicker.Item

Form.TagPicker 的子项

例子

import { ActionPanel, Color, Form, Icon, Action } from "@raycast/api";

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Color" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TagPicker id="color" title="Color">
        <Form.TagPicker.Item value="red" title="Red" icon={{ source: Icon.Circle, tintColor: Color.Red }} />
        <Form.TagPicker.Item value="green" title="Green" icon={{ source: Icon.Circle, tintColor: Color.Green }} />
        <Form.TagPicker.Item value="blue" title="Blue" icon={{ source: Icon.Circle, tintColor: Color.Blue }} />
      </Form.TagPicker>
    </Form>
  );
}

参数

名称

描述

类型

默认

title*

标签的名称.

string

value*

标签的值。确保为每个项分配唯一的值。

string

icon

标签中显示的图标。

Image.ImageLike

Form.Separator

显示分隔线的表单项。用于对表单项进行分组并在视觉上分隔表单项。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Form" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.TextField id="textfield" />
      <Form.Separator />
      <Form.TextArea id="textarea" />
    </Form>
  );
}

Form.FilePicker

带有按钮的表单项，用于打开对话框以选择某些文件和/或某些目录（取决于其属性）。

当用户选择了一些已存在的项目时，当调用 onSubmit 回调时，它们可能会被删除或更改。因此，在对其进行操作之前，您应该始终确保这些项目存在！

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { files: string[] }) => {
              const files = values.files.filter((file: any) => fs.existsSync(file) && fs.lstatSync(file).isFile());
              console.log(files);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" />
    </Form>
  );
}

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { files: string[] }) => {
              const file = values.files[0];
              if (!fs.existsSync(file) || !fs.lstatSync(file).isFile()) {
                return false;
              }
              console.log(file);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" allowMultipleSelection={false} />
    </Form>
  );
}

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm
            title="Submit Name"
            onSubmit={(values: { folders: string[] }) => {
              const folder = values.folders[0];
              if (!fs.existsSync(folder) || fs.lstatSync(folder).isDirectory()) {
                return false;
              }
              console.log(folder);
            }}
          />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="folders" allowMultipleSelection={false} canChooseDirectories canChooseFiles={false} />
    </Form>
  );
}

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

export default function Command() {
  const [files, setFiles] = useState<string[]>([]);

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit Name" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.FilePicker id="files" value={files} onChange={setFiles} />
    </Form>
  );
}

参数

名称

描述

类型

默认

id*

表单项的 ID。确保为每个表单项分配一个唯一的 ID。

string

allowMultipleSelection

指示用户是否可以选择多个项或仅选择一项。

boolean

true

autoFocus

表单渲染后项是否应自动获得焦点。

boolean

canChooseDirectories

是否可以选择目录。

boolean

false

canChooseFiles

是否可以选择文件。

boolean

true

defaultValue

条目的默认值。请记住，defaultValue 将在每个组件生命周期配置一次。这意味着如果用户更改该值，则重新渲染时不会配置 defaultValue。

string[]

error

显示表单项验证问题的可选错误消息。如果存在错误，表单项将以红色边框突出显示，并在右侧显示错误消息。

string

info

用于描述表单项的可选信息消息。它显示在项的右侧，并带有一个信息图标。当图标悬停时，将显示信息消息。

string

showHiddenFiles

文件选择器是否显示通常对用户隐藏的文件。

boolean

false

storeValue

提交后是否应保留项的值，并在下次渲染表单时恢复。

boolean

title

显示在项的左侧标题。

string

value

当前项的值

string[]

onBlur

当项失去焦点时将触发的回调。

(event: FormEvent<string[]>) => void

onChange

当项的 value 发生变化时会触发的回调。

(newValue: string[]) => void

onFocus

当项获得焦点时，应该调用将触发的回调。

(event: FormEvent<string[]>) => void

方法（命令式 API）

名称

签名

描述

focus

() => void

聚焦某项

reset

() => void

将表单项重置为其初始值，或 defaultValue（如果指定）。

Form.Description

带有简单文本标签的表单项。

不要使用此组件来显示其他表单字段的验证消息。

例子

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

export default function Command() {
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={(values) => console.log(values)} />
        </ActionPanel>
      }
    >
      <Form.Description
        title="Import / Export"
        text="Exporting will back-up your preferences, quicklinks, snippets, floating notes, script-command folder paths, aliases, hotkeys, favorites and other data."
      />
    </Form>
  );
}

参数

名称

描述

类型

默认

text*

显示在中间的文本。

string

title

描述项左侧的显示标题。

string

类型

Form.Event

某些 Form.Item 回调（例如 onFocus 和 onBlur）可以返回可以以不同方式使用的 Form.Event 对象。

属性

描述

类型

target*

包含与事件相关的目标数据的接口

{ id: string; value: any }

type*

事件类型

Form.Event.Type

例子

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

export default function Main() {
  return (
    <Form>
      <Form.TextField id="textField" title="Text Field" onBlur={logEvent} onFocus={logEvent} />
      <Form.TextArea id="textArea" title="Text Area" onBlur={logEvent} onFocus={logEvent} />
      <Form.Dropdown id="dropdown" title="Dropdown" onBlur={logEvent} onFocus={logEvent}>
        {[1, 2, 3, 4, 5, 6, 7].map((num) => (
          <Form.Dropdown.Item value={String(num)} title={String(num)} key={num} />
        ))}
      </Form.Dropdown>
      <Form.TagPicker id="tagPicker" title="Tag Picker" onBlur={logEvent} onFocus={logEvent}>
        {[1, 2, 3, 4, 5, 6, 7].map((num) => (
          <Form.TagPicker.Item value={String(num)} title={String(num)} key={num} />
        ))}
      </Form.TagPicker>
    </Form>
  );
}

function logEvent(event: Form.Event<string[] | string>) {
  console.log(`Event '${event.type}' has happened for '${event.target.id}'. Current 'value': '${event.target.value}'`);
}

Form.Event.Type

不同类型的 Form.Event。可以是 "focus" 或 "blur"。

Form.Values

表单项的值。

对于类型安全的表单值，您可以定义自己的接口。使用表单项的 ID 作为属性名称。

例子

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

interface Values {
  todo: string;
  due?: Date;
}

export default function Command() {
  function handleSubmit(values: Values) {
    console.log(values);
  }

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={handleSubmit} />
        </ActionPanel>
      }
    >
      <Form.TextField id="todo" title="Todo" />
      <Form.DatePicker id="due" title="Due Date" />
    </Form>
  );
}

属性

名称

类型

必填

描述

[itemId: string]

any

Yes

给定项的表单值。

Form.DatePicker.Type

用户可以使用 Form.DatePicker 选择日期组件的类型。

枚举成员

名称

描述

DateTime

除了年、月、日之外，还可以选择时、秒

Date

只能选择年、月、日

命令式API

您可以使用 React 的 useRef 钩子来创建可以访问本机表单项公开的命令式 API（例如 .focus() 或 .reset()）的变量。

命令式 API 需要 1.33.0 或更高版本的 @raycast/api 包。

import { useRef } from "react";
import { ActionPanel, Form, Action } from "@raycast/api";

interface FormValues {
  nameField: string;
  bioTextArea: string;
  datePicker: string;
}

export default function Command() {
  const textFieldRef = useRef<Form.TextField>(null);
  const textAreaRef = useRef<Form.TextArea>(null);
  const datePickerRef = useRef<Form.DatePicker>(null);
  const passwordFieldRef = useRef<Form.PasswordField>(null);
  const dropdownRef = useRef<Form.Dropdown>(null);
  const tagPickerRef = useRef<Form.TagPicker>(null);
  const firstCheckboxRef = useRef<Form.Checkbox>(null);
  const secondCheckboxRef = useRef<Form.Checkbox>(null);

  async function handleSubmit(values: FormValues) {
    console.log(values);
    datePickerRef.current?.focus();
    dropdownRef.current?.reset();
  }

  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm title="Submit" onSubmit={handleSubmit} />
          <ActionPanel.Section title="Focus">
            <Action title="Focus TextField" onAction={() => textFieldRef.current?.focus()} />
            <Action title="Focus TextArea" onAction={() => textAreaRef.current?.focus()} />
            <Action title="Focus DatePicker" onAction={() => datePickerRef.current?.focus()} />
            <Action title="Focus PasswordField" onAction={() => passwordFieldRef.current?.focus()} />
            <Action title="Focus Dropdown" onAction={() => dropdownRef.current?.focus()} />
            <Action title="Focus TagPicker" onAction={() => tagPickerRef.current?.focus()} />
            <Action title="Focus First Checkbox" onAction={() => firstCheckboxRef.current?.focus()} />
            <Action title="Focus Second Checkbox" onAction={() => secondCheckboxRef.current?.focus()} />
          </ActionPanel.Section>
          <ActionPanel.Section title="Reset">
            <Action title="Reset TextField" onAction={() => textFieldRef.current?.reset()} />
            <Action title="Reset TextArea" onAction={() => textAreaRef.current?.reset()} />
            <Action title="Reset DatePicker" onAction={() => datePickerRef.current?.reset()} />
            <Action title="Reset PasswordField" onAction={() => passwordFieldRef.current?.reset()} />
            <Action title="Reset Dropdown" onAction={() => dropdownRef.current?.reset()} />
            <Action title="Reset TagPicker" onAction={() => tagPickerRef.current?.reset()} />
            <Action title="Reset First Checkbox" onAction={() => firstCheckboxRef.current?.reset()} />
            <Action title="Reset Second Checkbox" onAction={() => secondCheckboxRef.current?.reset()} />
          </ActionPanel.Section>
        </ActionPanel>
      }
    >
      <Form.TextField id="textField" title="TextField" ref={textFieldRef} />
      <Form.TextArea id="textArea" title="TextArea" ref={textAreaRef} />
      <Form.DatePicker id="datePicker" title="DatePicker" ref={datePickerRef} />
      <Form.PasswordField id="passwordField" title="PasswordField" ref={passwordFieldRef} />
      <Form.Separator />
      <Form.Dropdown
        id="dropdown"
        title="Dropdown"
        defaultValue="first"
        onChange={(newValue) => {
          console.log(newValue);
        }}
        ref={dropdownRef}
      >
        <Form.Dropdown.Item value="first" title="First" />
        <Form.Dropdown.Item value="second" title="Second" />
      </Form.Dropdown>
      <Form.Separator />
      <Form.TagPicker
        id="tagPicker"
        title="TagPicker"
        ref={tagPickerRef}
        onChange={(t) => {
          console.log(t);
        }}
      >
        {["one", "two", "three"].map((tag) => (
          <Form.TagPicker.Item key={tag} value={tag} title={tag} />
        ))}
      </Form.TagPicker>
      <Form.Separator />
      <Form.Checkbox
        id="firstCheckbox"
        title="First Checkbox"
        label="First Checkbox"
        ref={firstCheckboxRef}
        onChange={(checked) => {
          console.log("first checkbox onChange ", checked);
        }}
      />
      <Form.Checkbox
        id="secondCheckbox"
        title="Second Checkbox"
        label="Second Checkbox"
        ref={secondCheckboxRef}
        onChange={(checked) => {
          console.log("second checkbox onChange ", checked);
        }}
      />
      <Form.Separator />
    </Form>
  );
}

最后更新于2年前