為不同的載入狀態呈現一個非同步作業，並帶有插槽。結果狀態優先於後續載入和失敗狀態。

備註：內部區塊接收非同步指定為 :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>

將 tab 焦點包覆在一個無障礙的容器中。

這對於模式對話框和選單等介面而言，是一項基本的無障礙功能。

屬性

• 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 變更組，然後使用 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 變更集旨在讓您一次性使用。透過不再將變更集儲存在 assign 中，您較不容易在各種操作中使用它

關於 :errors 的說明

即使 changeset.errors 不是空的，如果 變更集 :action 是 nil 或 :ignore，表單中仍不會顯示錯誤

這是件有用的事，例如表單欄位的驗證提示，例如某個新表單使用的空變更集。該變更集並非有效，但是我們不希望在實際使用者動作執行之前顯示錯誤

例如，如果使用者提交某樣東西，且呼叫了 Repo.insert/1，變更集驗證卻失敗了，則動作將設定為 :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>

在上述範例中，我們將變更集傳遞給 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 的情況下將表單送出至網址，則必須提供此屬性。

• as (:atom) - 由表單產生之名稱和識別碼中要使用的字首。例如，設定 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的轉換作業如何排序現有子項或要插入新子項的位置。接著，我們照常渲染電子郵件和名稱輸入。然後，我們渲染一個包含「刪除」文字、名稱為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"名稱，並附帶「新增更多」文字。請注意，此按鈕必須具有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 或在 LiveViews 之間導航，請分別使用 patch 和 navigate。

屬性

• navigate (:string) - 從一個 LiveView 導航到新的 LiveView。瀏覽器頁面會保留，但會掛載新的 LiveView 處理序並重新載入頁面上的內容。只能在同一個路由器下宣告的 LiveViews 之間導航 Phoenix.LiveView.Router.live_session/3。否則，會使用完整的瀏覽器重新導向。

• patch (:string) - 修補目前的 LiveView。會呼叫目前的 LiveView 的 handle_params callback，並且會透過連接線傳送最少內容，與其他 LiveView diff 一樣。

• href (:any) - 使用傳統的瀏覽器導航到新位置。表示瀏覽器會重新載入整個頁面。

• replace (:boolean) - 使用 :patch 或 :navigate 時，是否應以 pushState 取代瀏覽器的歷程?

  預設值為 false。

• method (:string) - 使用連結的 HTTP 方法。這用於 Phoenix 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.dev.org.tw")}>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)（必填） - LiveComponent 的唯一識別碼。請注意，id 不一定會用作 DOM 的 id。這要由元件自己決定。

• module (:atom)（必填） - 要渲染的 LiveComponent 模組。

提供的任何其他屬性都會以屬性檔案形式傳遞給 LiveComponent。有關更多資訊，請參閱 Phoenix.LiveComponent。

範例

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

建立一個檔案輸入標籤用於 LiveView 上傳。

屬性

• upload (Phoenix.LiveView.UploadConfig)（必填） - Phoenix.LiveView.UploadConfig 結構。
• accept (:string) - 覆寫 accept 屬性的選項。預設為 allow_upload 所指定的 :accept。
• 接受全域屬性。支援所有全域以及：["webkitdirectory", "required", "disabled", "capture", "form"]。

拖曳和放置

透過為可放置的容器加上 phx-drop-target 屬性，並指向 UploadConfig ref，即可支援拖曳和放置，因此，下列程式碼標記是拖曳和放置支援所需的所有內容

<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) (必需) - Phoenix.LiveView.UploadEntry 結構。
• id (:string) - img 標籤的 id。預設來自 entry ref，但必要時可以覆寫，如果您需要在同一頁面多次呈現同一條目的預覽。預設為 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 (必需) - 在 title 標籤內呈現的內容。

範例

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

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