分享 sRFC 29 —— 改进 Blinks 和 Actions 的输入类型

Fifi · 2024年07月30日 · 69 次阅读

原文:https://forum.solana.com/t/srfc-29-input-types-of-blinks-and-actions/1804

作者:https://x.com/nickfrosty

概要

在 blink 客户端中添加新的输入类型,以改善用户体验,并为 Action 开发者解锁新用例。

原由

当前的 Solana Actions 和 blinks 规范仅支持单一的、通用的非结构化文本框输入类型。虽然这种基本输入很有用,但拥有更明确和声明性的输入类型将允许 Action 开发者和 blink 客户端解锁新的用例,并改善在互联网上使用 blinks 的用户体验。

当前的规范

根据当前的规范,Action API 将使用初始 GET 请求的结构化响应(ActionGetResponse)来声明它需要的用户输入字段,特别是通过links.actions中包含parameters字段的任何子项。

当前的规范是这样的:

/**
 * Response body payload returned from the Action GET Request
 */
export interface ActionGetResponse {
  /** image url that represents the source of the action request */
  icon: string;
  /** describes the source of the action request */
  title: string;
  /** brief summary of the action to be performed */
  description: string;
  /** button text rendered to the user */
  label: string;
  /** UI state for the button being rendered to the user */
  disabled?: boolean;
  /**  */
  links?: {
    /** list of related Actions a user could perform */
    actions: LinkedAction[];
  };
  /** non-fatal error message to be displayed to the user */
  error?: ActionError;
}

/**
 * Related action on a single endpoint
 */
export interface LinkedAction {
  /** URL endpoint for an action */
  href: string;
  /** button text rendered to the user */
  label: string;
  /** parameters used to accept user input within an action */
  parameters?: ActionParameter[];
}

任何 ActionParameter 声明都将被渲染成纯文本输入呈现给用户(带有可选的占位符文本),以便接受他们的输入,最终通过 POST 请求发送 Action API 端点。

此外,用户输入数据仅通过在特定 linked action 的href字段中声明的查询参数和模板字面量(例如:{name} )发送到 Action API。在接受更长的用户输入值或更复杂的输入类型时,这会带来限制和复杂性。

/**
 * Parameter to accept user input within an action
 */
export interface ActionParameter {
  /** parameter name in url */
  name: string;
  /** placeholder text for the user input field */
  label?: string;
  /** declare if this field is required (defaults to `false`) */
  required?: boolean;
}

提案

1. 为支持将更长的和更复杂的用户输入(通过 POST 请求)发送到 Action API,用户输入应可选地通过 POST 请求正文(body)发送,而不仅仅是通过模板化的查询参数(例如已被发送的用户的account地址)。对于每个LinkedAction,所有用户输入都应以如下的方式被发送到 Action API:

  • href值的查询参数中通过模板字面量指定的任何parameters输入都应该通过其命名的查询参数发送各自的用户输入值(这是规范当前的运作方式);
  • 剩下的所有parameters输入(也就是那些没有在href中声明模板字面量的输入)应该在 POST 请求的正文中发送(与用户的account一起发送,但永远不能修改account值);
  • 注意:如果任何parameters的模板字面量被找到,它就不应该通过正文发送。这将减少通过网络发送的总数据,不发送重复数据从来也都是最佳的做法。

最终,这会允许开发人员通过查询参数(不破坏现有的应用程序)或通过 POST 请求正文接受用户输入。并可以像典型的 HTML 表单一样,有效地设置隐式默认使用 POST 正文来接收用户输入。

2. 更新ActionParameter以支持声明不同类型的用户输入,并允许为更复杂的输入提供正则表达式匹配模式。

更新后的ActionParameter应如下所示:

/**
 * Parameter to accept user input within an action
 */
export interface ActionParameter {
  /** input field type */
  type?: ActionParameterType;
  /** regular expression pattern to validate user input client side */
  pattern?: string;
  /** human readable description of the `pattern` */
  patternDescription?: string;
  /** parameter name in url */
  name: string;
  /** placeholder text for the user input field */
  label?: string;
  /** declare if this field is required (defaults to `false`) */
  required?: boolean;
}

匹配模式(pattern)等同于有效的正则表达式字符串。blink 客户端应在发出 POST 请求前使用该正则表达式匹配模式来验证用户输入。如果匹配模式不是有效的正则表达式,客户端就会忽略它。

匹配模式描述(patternDescription)是描述正则表达式匹配模式的人类可读信息。如果提供了匹配模式,则必须提供匹配模式描述

如果用户输入值根据匹配模式被认为无效,用户在客户端就会收到一条错误信息,提示输入字段无效,并显示匹配模式描述字符串。

在大多情况下,类型(type)类似于标准的 HTML 输入元素

新的类型属性应有如下的类型声明:

/**
 * Input type to present to the user 
 * @default `text`
 */
export type ActionParameterType =
  | "text"
  | "email"
  | "url"
  | "number"
  | "date"
  | "datetime-local"
  | "checkbox"
  | "radio"
  | "textarea"
  | "select";

每一个提出的类型值通常应该生成一个用户输入字段,类似于相应的类型的标准 HTML输入元素(即 <输入类型 = "email" />) ,以提供更好的客户端验证和用户体验:

  • text - 等同于 HTML “text” input元素
  • email - 等同于 HTML “email” input 元素
  • url - 等同于 HTML “url” input元素
  • number - 等同于 HTML “number” input元素
  • date - 等同于 HTML “date” input元素
  • datetime-local - 等同于 HTML “datetime-local” input元素
  • checkbox - 等同于一组标准的 HTML “checkbox” input元素。Action API 应返回如下所示的选项(options)。用户应能于所提供的 checkbox 选项中进行多选。
  • radio - 等同于一组标准的 HTML “radio” input元素。Action API 应返回如下所示的选项。用户只能于所提供的 radio 选项中选择一项。
  • 目前不支持上述未说明的其它 HTML 输入类型(hidden, button, submit, file, 等等)。

除了上述类似 HTML 输入类型的元素外,还支持以下用户输入元素:

  • textarea - 等同于 HTML textarea element元素。用户可进行多行输入。
  • select - 等同于 HTML select element元素。用户会体验一个“下拉”样式的字段。Action API 应返回如下所示的选项

类型设置为选择(select)复选框(checkbox)单选框(radio)时,Action API 应包含一个选项数组,每个选项至少提供一个标签(label)值(value)。每个选项还可以有一个选中(selected)值,以告知 blink 客户端用户在默认情况下应选择哪个选项(参见复选框和单选框的区别)。

interface ActionParameterSelectable extends ActionParameter {
  options: Array<{
    /** displayed UI label of this selectable option */
    label: string;
    /** value of this selectable option */
    value: string;
    /** whether or not this option should be selected by default */
    selected?: boolean
  }>;
}

如果没有设置类型或设置了未知/不支持的值,blink 客户端应默认为文本(text),并呈现一个简单的文本输入(正如他们目前的做法)。

Action API 仍负责验证和清理用户输入参数中的所有数据,并在必要时强制执行任何“必需的”用户输入。

对于其它基于 HTML/web 的平台(如本地移动平台),应使用等效的本地用户输入组件,以获得与上述 HTML/web 输入类型相同的体验和客户端验证。

注意:与当前规范一样,如果LinkedAction没有声明parameters属性,那么 Action API 就不会请求用户输入,blink 客户端应继续渲染一个向href端点执行 POST 请求的单个按钮。本提案不会改变这一点。

结语

随着对更多输入类型的支持,开发人员将能够构建更复杂的 blinks,并接受更多的用户输入。户输入字段“过多”可能会降低用户体验,也会降低用户实际输入所有要求输入内容的可能性。

为了避免用户界面(UI)臃肿和降低用户体验,blink 客户端可能会对其显示的输入字段数量进行“软限制”。虽然本 Actions/blink 规范避免对 blinks 的用户界面层采取见仁见智的做法,但以下是一个合理的指导原则(目前 Dialect 的 blinks SDK 也在使用):

  • 10 个按钮 + 3 个输入(如果是独立的 Actions)
  • 10 个输入(如果是一个表单,且当响应中有表单时不渲染其它操作)

因此,Action API 开发人员应限制所请求的输入parameters数量,因为 blink 客户端可能会限制向用户显示的输入字段数量。开发人员还应记住,如果用户看不到所有的输入字段(因为 blink 客户端软限制了这些字段,如上所述),那么用户将无法输入值。因此,如果所有这些字段都是 Action API 所要求的,用户将无法实际执行你的 Action 并达成交易。

暂无回复。
需要 登录 后方可回复, 如果你还没有账号请 注册新账号