使用不同加载状态的插槽渲染异步分配。 result 状态优先于后续加载状态和失败状态。

注意：内部块接收异步分配的结果作为 :let。let 只能访问内部块，不能访问其他插槽。

示例

<.async_result :let={org} assign={@org}>
  <:loading>Loading organization...</:loading>
  <:failed :let={_failure}>there was an error loading the organization</:failed>
  <%= if org do %>
    <%= org.name %>
  <% else %>
    You don't have an organization yet.
  <% end %>
</.async_result>

要在后续 assign_async 调用中再次显示加载和失败状态，请将分配重置为无结果的 %AsyncResult{}。

{:noreply,
  socket
  |> assign_async(:page, :data, &reload_data/0)
  |> assign(:page, AsyncResult.loading())}

属性

• assign (Phoenix.LiveView.AsyncResult) (必需)

插槽

• loading - 在分配首次加载时渲染。
• failed - 在捕获错误或退出或 assign_async 首次返回 {:error, reason} 时渲染。接收错误作为 :let。
• inner_block - 当分配通过 AsyncResult.ok/2 成功加载时渲染。接收结果作为 :let。

生成动态命名的 HTML 标签。

如果发现标签名称是不安全的 HTML，则会引发 ArgumentError。

属性

• name (:string) (必需) - 标签名称，例如 div。
• 接受全局属性。要添加到标签中的其他 HTML 属性，确保正确转义。

插槽

• inner_block

示例

<.dynamic_tag name="input" type="text"/>

<input type="text"/>

<.dynamic_tag name="p">content</.dynamic_tag>

<p>content</p>

围绕容器包装选项卡焦点，以实现可访问性。

这是模态框、对话框和菜单等界面必不可少的辅助功能。

属性

• id (:string) (必需) - 容器标签的 DOM 标识符。
• 接受全局属性。要添加到容器标签中的其他 HTML 属性。

插槽

• inner_block (必需) - 渲染在容器标签内的内容。

示例

只需在此组件内渲染您的内部内容，当用户在容器内容中切换选项卡时，焦点将围绕容器进行包装。

<.focus_wrap id="my-modal" class="bg-white">
  <div id="modal-content">
    Are you sure?
    <button phx-click="cancel">Cancel</button>
    <button phx-click="confirm">OK</button>
  </div>
</.focus_wrap>

渲染表单。

此函数接收一个 Phoenix.HTML.Form 结构，通常使用 to_form/2 创建，并生成相关的表单标签。它可以在 LiveView 内或外部使用。

要查看表单在实践中的工作方式，您可以在 Phoenix 应用程序中运行 mix phx.gen.live Blog Post posts title body:text，这将设置必要的数据库表和 LiveView 来管理您的数据。

示例：在 LiveView 内

在 LiveView 内，此函数组件通常使用 for={@form} 调用，其中 @form 是 to_form/1 函数的结果。 to_form/1 预期数据源为映射或 Ecto.Changeset，并将其规范化为 Phoenix.HTML.Form 结构。

例如，您可以使用在 Phoenix.LiveView.handle_event/3 回调中接收的参数来创建 Ecto changeset，然后使用 to_form/1 将其转换为表单。然后，在您的模板中，将 @form 作为参数传递给 :for。

<.form
  for={@form}
  phx-change="change_name"
>
  <.input field={@form[:email]} />
</.form>

.input 组件通常定义为您的应用程序的一部分，并添加所有必要的样式。

def input(assigns) do
  ~H"""
  <input type="text" name={@field.name} id={@field.id} value={@field.value} class="..." />
  """
end

表单接受多个选项。例如，如果您正在进行文件上传，并且您想捕获提交，您可以改写为

<.form
  for={@form}
  multipart
  phx-change="change_user"
  phx-submit="save_user"
>
  ...
  <input type="submit" value="Save" />
</.form>

请注意，两个示例都使用 phx-change。LiveView 必须实现 phx-change 事件，并在输入值到达时存储它们。这很重要，因为如果页面上发生了无关的更改，LiveView 应该使用更新的值重新渲染输入。如果没有 phx-change，输入将被清除。或者，您可以在表单上使用 phx-update="ignore" 来丢弃任何更新。

使用 for 属性

for 属性也可以是映射或 Ecto.Changeset。在这种情况下，将动态创建表单，您可以使用 :let 捕获它。

<.form
  :let={form}
  for={@changeset}
  phx-change="change_user"
>

但是，这种方法在 LiveView 中不建议使用，原因有两个

• 如果您使用 @form[:field] 而不是通过 let 变量 form 来访问表单字段，LiveView 可以更好地优化您的代码。

• Ecto changeset 旨在一次性使用。通过从未将 changeset 存储在分配中，您将不太可能在操作之间使用它。

关于 :errors 的说明

即使 changeset.errors 不为空，如果 changeset 的 :action 为 nil 或 :ignore，则不会在表单中显示错误。

这对表单字段的验证提示很有用，例如新表单的空 changeset。该 changeset 无效，但我们不想在执行实际用户操作之前显示错误。

例如，如果用户提交并调用 Repo.insert/1，并且在 changeset 验证时失败，则操作将设置为 :insert 以表明尝试插入，并且该操作的存在将导致显示错误。对于 Repo.update/delete 也是如此。

如果您想手动显示错误，您也可以自己设置操作，直接在 Ecto.Changeset 结构字段上设置，或者使用 Ecto.Changeset.apply_action/2 设置。由于操作可以是任意的，您可以将其设置为 :validate 或任何其他内容，以避免给人的印象是实际上已经尝试过数据库操作。

示例：在 LiveView 外部（常规 HTTP 请求）

form 组件仍然可以用来在 LiveView 之外提交表单。在这种情况下，必须给出 action 属性。如果没有该属性，则会丢弃 form 方法和 csrf 令牌。

<.form :let={f} for={@changeset} action={~p"/comments/#{@comment}"}>
  <.input field={f[:body]} />
</.form>

在上面的示例中，我们将 changeset 传递给 for，并使用 :let={f} 捕获了该值。这种方法在 LiveView 外部是可以的，因为没有更改跟踪优化需要考虑。

CSRF 防护

CSRF 防护是一种机制，用于确保渲染表单的用户是实际提交表单的用户。默认情况下，此模块会生成一个 CSRF 令牌。您的应用程序应该在服务器上检查此令牌，以防止攻击者代表其他用户在您的服务器上发出请求。Phoenix 默认情况下会检查此令牌。

在将表单发布到其地址中包含主机的主机时，例如 "//host.com/path" 而不是只使用 "/path"，Phoenix 会将主机签名包含在令牌中，并且仅在访问的主机与令牌中的主机相同的情况下验证令牌。这是为了防止令牌泄露到第三方应用程序。如果此行为有问题，您可以使用 Plug.CSRFProtection.get_csrf_token/0 生成一个非主机特定的令牌，并通过 :csrf_token 选项将其传递给表单生成器。

属性

• for (:any) (必填) - 现有表单或表单源数据。

• action (:string) - 提交表单时要执行的操作。如果您打算将表单提交到没有 LiveView 的 URL，则必须提供此属性。

• as (:atom) - 表单生成的名称和 ID 中要使用的前缀。例如，设置 as: :user_params 表示参数将在您的 handle_event 中嵌套 "user_params"，或者对于常规 HTTP 请求，将嵌套在 conn.params["user_params"] 中。如果您设置了此选项，则必须使用 :let 捕获表单。

• csrf_token (:any) - 用于验证请求有效性的令牌。当提供操作且方法不是 get 时，会自动生成一个。设置为 false 时，不会生成任何令牌。

• errors (:list) - 使用此选项可手动将错误的关键字列表传递给表单。当将常规映射作为表单源提供时，此选项很有用，它将使错误在 f.errors 下可用。如果您设置了此选项，则必须使用 :let 捕获表单。

• method (:string) - HTTP 方法。仅在提供 :action 时使用。如果方法不是 get 也不 post，则会在表单标记旁边生成一个带有名称 _method 的输入标记。如果提供 :action 但没有方法，则方法将默认为 post。

• multipart (:boolean) - 将 enctype 设置为 multipart/form-data。上传文件时需要此选项。

  默认为 false。

• 接受全局属性。要添加到表单标记的其他 HTML 属性。支持所有全局属性以及：["autocomplete", "name", "rel", "enctype", "novalidate", "target"]。

插槽

• inner_block (必填) - 在表单标记内渲染的内容。

为关联或嵌入渲染嵌套的表单输入。

属性

• field (Phoenix.HTML.FormField) (必填) - 一个 %Phoenix.HTML.Form{}/field 名称元组，例如：{@form[:email]}。

• id (:string) - 要在表单中使用的 ID，默认为给定字段与父表单 ID 的连接。

• as (:atom) - 要在表单中使用的名称，默认为给定字段与父表单名称的连接。

• default (:any) - 如果没有可用值，则要使用的值。

• prepend (:list) - 渲染时要预先添加的值。这仅适用于字段值为列表且没有通过表单发送参数的情况。

• append (:list) - 渲染时要追加的值。这仅适用于字段值为列表且没有通过表单发送参数的情况。

• skip_hidden (:boolean) - 跳过自动渲染隐藏字段，以便更严格地控制生成的标记。

  默认为 false。

• options (:list) - Phoenix.HTML.FormData 协议实现的任何其他选项。

  默认为 []。

插槽

• inner_block (必填) - 为每个嵌套表单渲染的内容。

示例

<.form
  :let={f}
  phx-change="change_name"
>
  <.inputs_for :let={f_nested} field={f[:nested]}>
    <.input type="text" field={f_nested[:name]} />
  </.inputs_for>
</.form>

动态添加和删除输入

动态添加和删除输入可以通过为插入和删除渲染命名按钮来支持。与输入一样，具有名称/值对的按钮在更改和提交事件时会使用表单数据进行序列化。然后，诸如 Ecto 之类的库或自定义参数过滤可以检查参数并处理添加或删除的字段。这可以与 Ecto.Changeset.cast/3 的 :sort_param 和 :drop_param 选项结合使用。例如，假设一个父级具有 :emails has_many 或 embeds_many 关联。要将来自嵌套表单的用户输入强制转换为类型，只需要配置选项即可

schema "mailing_lists" do
  field :title, :string

  embeds_many :emails, EmailNotification, on_replace: :delete do
    field :email, :string
    field :name, :string
  end
end

def changeset(list, attrs) do
  list
  |> cast(attrs, [:title])
  |> cast_embed(:emails,
    with: &email_changeset/2,
    sort_param: :emails_sort,
    drop_param: :emails_drop
  )
end

这里我们可以看到 :sort_param 和 :drop_param 选项的作用。

注意：当使用这些选项时，需要在 has_many 和 embeds_many 上使用 on_replace: :delete。

当 Ecto 从表单中看到指定的排序或删除参数时，它将根据子项在表单中出现的顺序对子项进行排序，添加它没有见过的新的子项，或者如果参数指示这样做，则删除子项。

此类架构和关联的标记将如下所示

<.inputs_for :let={ef} field={@form[:emails]}>
  <input type="hidden" name="mailing_list[emails_sort][]" value={ef.index} />
  <.input type="text" field={ef[:email]} placeholder="email" />
  <.input type="text" field={ef[:name]} placeholder="name" />
  <button
    type="button"
    name="mailing_list[emails_drop][]"
    value={ef.index}
    phx-click={JS.dispatch("change")}
  >
    <.icon name="hero-x-mark" class="w-6 h-6 relative top-2" />
  </button>
</.inputs_for>

<input type="hidden" name="mailing_list[emails_drop][]" />

<button type="button" name="mailing_list[emails_sort][]" value="new" phx-click={JS.dispatch("change")}>
  add more
</button>

我们使用 inputs_for 来渲染 :emails 关联的输入，该关联包含每个子项的电子邮件地址和名称输入。在嵌套输入中，我们渲染一个隐藏的 mailing_list[emails_sort][] 输入，该输入设置为给定子项的索引。这告诉 Ecto 的强制转换操作如何对现有子项进行排序，或者在哪里插入新的子项。接下来，我们像往常一样渲染电子邮件和名称输入。然后，我们渲染一个包含 "delete" 文本的按钮，按钮名称为 mailing_list[emails_drop][]，其中包含子项索引作为其值。

与之前一样，这告诉 Ecto 在单击按钮时删除此索引处的子项。我们在按钮上使用 phx-click={JS.dispatch("change")} 告诉 LiveView 将此按钮单击视为更改事件，而不是表单上的提交事件，这会调用我们表单的 phx-change 绑定。

在 inputs_for 之外，我们渲染一个空的 mailing_list[emails_drop][] 输入，以确保在保存用户删除所有条目的表单时删除所有子项。当删除关联时，需要此隐藏输入。

最后，我们还渲染另一个带有排序参数名称 mailing_list[emails_sort][] 和 value="new" 名称的按钮，以及伴随的 "add more" 文本。请注意，此按钮必须具有 type="button"，以防止它提交表单。Ecto 将将未知排序参数视为新的子项并构建一个新的子项。此按钮是可选的，仅在您需要动态添加条目时才需要。您可以在 <.inputs_for> 之前选择性地添加一个类似的按钮，以防您需要在前面添加条目。

在可枚举类型之间插入分隔符插槽。

当您需要在项目之间添加分隔符时很有用，例如在渲染导航的面包屑时。将每个项目提供给内部块。

示例

<.intersperse :let={item} enum={["home", "profile", "settings"]}>
  <:separator>
    <span class="sep">|</span>
  </:separator>
  <%= item %>
</.intersperse>

渲染以下标记

home <span class="sep">|</span> profile <span class="sep">|</span> settings

属性

• enum (:any) (必填) - 要用分隔符进行插入的可枚举对象。

插槽

• inner_block (必填) - 为每个项目渲染的内部块。
• separator (必填) - 分隔符的插槽。

生成指向给定路由的链接。

要使用传统的浏览器导航在页面之间导航，请使用 href 属性。要修补当前 LiveView 或在 LiveView 之间导航，请分别使用 patch 和 navigate。

属性

• navigate (:string) - 从 LiveView 导航到新的 LiveView。浏览器页面保持不变，但会挂载一个新的 LiveView 进程，并且页面上的其内容会重新加载。只能在同一个路由器 Phoenix.LiveView.Router.live_session/3 下声明的 LiveView 之间导航。否则，将使用完整的浏览器重定向。

• patch (:string) - 修补当前 LiveView。将调用当前 LiveView 的 handle_params 回调，并且会发送最少的内容，就像任何其他 LiveView 差异一样。

• href (:any) - 使用传统的浏览器导航到新位置。这意味着浏览器上的整个页面都将重新加载。

• replace (:boolean) - 当使用 :patch 或 :navigate 时，是否应该使用 pushState 替换浏览器的历史记录？

  默认为 false。

• method (:string) - 要与链接一起使用的 HTTP 方法。这是为了在 LiveView 之外使用而设计的，因此仅适用于 href={...} 属性。它对 patch 和 navigate 指令没有影响。

  如果方法不是 get，则链接将在设置正确信息的表单中生成。为了提交表单，浏览器中必须启用 JavaScript。

  默认为 "get"。

• csrf_token (:any) - 用于 HTTP 方法不为 get 的链接的布尔值或自定义令牌。默认为 true。

• 接受全局属性。添加到 a 标记的其他 HTML 属性。支持所有全局属性以及：["download", "hreflang", "referrerpolicy", "rel", "target", "type"]。

插槽

• inner_block (必填) - 在 a 标记内渲染的内容。

示例

<.link href="/">Regular anchor link</.link>

<.link navigate={~p"/"} class="underline">home</.link>

<.link navigate={~p"/?sort=asc"} replace={false}>
  Sort By Price
</.link>

<.link patch={~p"/details"}>view details</.link>

<.link href={URI.parse("https://elixir.erlang.ac.cn")}>hello</.link>

<.link href="/the_world" method="delete" data-confirm="Really?">delete</.link>

JavaScript 依赖项

为了支持 :method 不为 "get" 的链接或使用上述数据属性，Phoenix.HTML 依赖于 JavaScript。您可以将 priv/static/phoenix_html.js 加载到构建工具中。

数据属性

数据属性作为传递给 data 键的关键字列表添加。支持以下数据属性

• data-confirm - 当 :method 不为 "get" 时，在生成并提交表单之前显示确认提示。

覆盖默认确认行为

phoenix_html.js 在发生点击时确实会在被点击的 DOM 元素上触发自定义事件 phoenix.link.click。这使您可以拦截事件在向 window 冒泡的路上，并执行您自己的自定义逻辑来增强或替换 data-confirm 属性的处理方式。例如，您可以用自定义 JavaScript 实现替换浏览器的 confirm() 行为。

// Compared to a javascript window.confirm, the custom dialog does not block
// javascript execution. Therefore to make this work as expected we store
// the successful confirmation as an attribute and re-trigger the click event.
// On the second click, the `data-confirm-resolved` attribute is set and we proceed.
const RESOLVED_ATTRIBUTE = "data-confirm-resolved";
// listen on document.body, so it's executed before the default of
// phoenix_html, which is listening on the window object
document.body.addEventListener('phoenix.link.click', function (e) {
  // Prevent default implementation
  e.stopPropagation();
  // Introduce alternative implementation
  var message = e.target.getAttribute("data-confirm");
  if(!message){ return; }

  // Confirm is resolved execute the click event
  if (e.target?.hasAttribute(RESOLVED_ATTRIBUTE)) {
    e.target.removeAttribute(RESOLVED_ATTRIBUTE);
    return;
  }

  // Confirm is needed, preventDefault and show your modal
  e.preventDefault();
  e.target?.setAttribute(RESOLVED_ATTRIBUTE, "");

  vex.dialog.confirm({
    message: message,
    callback: function (value) {
      if (value == true) {
        // Customer confirmed, re-trigger the click event.
        e.target?.click();
      } else {
        // Customer canceled
        e.target?.removeAttribute(RESOLVED_ATTRIBUTE);
      }
    }
  })
}, false);

或者，您可以附加自己的自定义行为。

window.addEventListener('phoenix.link.click', function (e) {
  // Introduce custom behaviour
  var message = e.target.getAttribute("data-prompt");
  var answer = e.target.getAttribute("data-prompt-answer");
  if(message && answer && (answer != window.prompt(message))) {
    e.preventDefault();
  }
}, false);

后者也可以绑定到任何 click 事件，但这可以确保您的自定义代码仅在运行 phoenix_html.js 的代码时才会执行。

CSRF 防护

默认情况下，CSRF 令牌是通过 Plug.CSRFProtection 生成的。

一个函数组件，用于在父 LiveView 中渲染 Phoenix.LiveComponent。

虽然 LiveView 可以嵌套，但每个 LiveView 都启动了自己的进程。LiveComponent 提供与 LiveView 相似的功能，只是它们在与 LiveView 相同的进程中运行，并拥有自己的封装状态。这就是为什么它们被称为有状态组件。

属性

• id (:string) (required) - LiveComponent 的唯一标识符。请注意，id 不一定会用作 DOM id。这取决于组件自行决定。

• module (:atom) (required) - 要渲染的 LiveComponent 模块。

提供的任何其他属性都将作为分配映射传递给 LiveComponent。有关更多信息，请参阅 Phoenix.LiveComponent。

示例

<.live_component module={MyApp.WeatherComponent} id="thermostat" city="Kraków" />

为 LiveView 上传构建文件输入标签。

属性

• upload (Phoenix.LiveView.UploadConfig) (required) - Phoenix.LiveView.UploadConfig 结构体。
• accept (:string) - accept 属性的可选覆盖。默认为 allow_upload 指定的 :accept。
• 接受全局属性。支持所有全局属性以及：["webkitdirectory", "required", "disabled", "capture", "form"]。

拖放

通过使用指向 UploadConfig ref 的 phx-drop-target 属性注释可拖放容器来支持拖放，因此以下标记是支持拖放所需的所有内容。

<div class="container" phx-drop-target={@uploads.avatar.ref}>
  <!-- ... -->
  <.live_file_input upload={@uploads.avatar} />
</div>

示例

渲染文件输入

<.live_file_input upload={@uploads.avatar} />

渲染带有标签的文件输入

<label for={@uploads.avatar.ref}>Avatar</label>
<.live_file_input upload={@uploads.avatar} />

为选定的文件在客户端生成图像预览。

属性

• entry (Phoenix.LiveView.UploadEntry) (required) - Phoenix.LiveView.UploadEntry 结构体。
• id (:string) - img 标签的 id。默认情况下，从条目引用派生，但如果需要在同一页面上多次渲染同一条目的预览，则可以根据需要覆盖。默认为 nil。
• 接受全局属性。

示例

<%= for entry <- @uploads.avatar.entries do %>
  <.live_img_preview entry={entry} width="75" />
<% end %>

当您需要多次使用它时，请确保它们具有不同的 id。

<%= for entry <- @uploads.avatar.entries do %>
  <.live_img_preview entry={entry} width="75" />
<% end %>

<%= for entry <- @uploads.avatar.entries do %>
  <.live_img_preview id={"modal-#{entry.ref}"} entry={entry} width="500" />
<% end %>

在 @page_title 更新时渲染标题，并自动添加前缀/后缀。

属性

• prefix (:string) - 在 inner_block 的内容之前添加的前缀。默认为 nil。
• suffix (:string) - 在 inner_block 的内容之后添加的后缀。默认为 nil。

插槽

• inner_block (required) - 在 title 标签内渲染的内容。

示例

<.live_title prefix="MyApp – ">
  <%= assigns[:page_title] || "Welcome" %>
</.live_title>

<.live_title suffix="- MyApp">
  <%= assigns[:page_title] || "Welcome" %>
</.live_title>