定義 LiveView 的後設資料。

必須從 __live__ 回呼傳回此回傳值。

它接受

• :container - 一個選用的位元組，用於 LiveView 容器的 HTML 標籤和 DOM 屬性。例如： {:li, style: "color: blue;"}。

• :layout - 設定 LiveView 將呈現的配置。這個配置可以在 mount/3 或在 Phoenix.LiveView.Router.live_session/2 的 :layout 選項中覆蓋

• :log - 設定 LiveView 的記錄等級，為 false 或一個記錄等級

• :on_mount - 一個清單，列出要作為 on_mount 鉤子來呼叫的模組名稱和參數的位元組

在當前模組中使用 LiveView 做為 LiveView 標記。

use Phoenix.LiveView,
  container: {:tr, class: "colorized"},
  layout: {MyAppWeb.Layouts, :app},
  log: :info

選項

• :container - 一個 HTML 標籤和 DOM 屬性所需的選用元組，用於 LiveView 容器。例如：{:li, style: "color: blue;"}。有關更多資訊和範例，請參閱 Phoenix.Component.live_render/3。

• :global_prefixes - 用於元件的整體前綴。請參閱 Phoenix.Component 中的 全域屬性 以取得更多資訊。

• :layout - 設定 LiveView 將呈現的配置。這個配置可以在 mount/3 或在 Phoenix.LiveView.Router.live_session/2 的 :layout 選項中覆蓋

• :log - 設定 LiveView 的記錄等級，為 false 或一個記錄等級

允許上傳提供的名稱。

選項

• :accept - 必填。一個不重複的檔案副檔名清單（例如：「.jpeg」）或 MIME 類型（例如：「image/jpeg」或「image/*」）。您也可以使用原子 :any 來取代清單，以允許使用任何類型的檔案。例如，[".jpeg"]、:any，等等。

• :max_entries - 每個檔案輸入允許選取的檔案數上限。預設為 1。

• :max_file_size - 上傳檔案的大小上限（以位元組為單位）。預設為 8MB。例如，12_000_000。

• :chunk_size - 上傳時要傳送的區塊大小（以位元組為單位）。預設為 64_000。

• :chunk_timeout - 在未收到新區塊之前，關閉上傳通道前要等待的毫秒數。預設為 10_000。

• :external - 一個二元函數，用於為外部用戶端上傳器產生元資料。此函數必須回傳 {:ok, meta, socket} 或 {:error, meta, socket}，其中 meta 為一個映射。請參閱上傳區段的範例使用方式。

• :progress - 一個接收進度事件的選用三元函數。

• :auto_upload - 指示用戶端在上傳檔案時自動上傳，而不是等待表單送出。預設為 false。

• :writer - 一個實作 Phoenix.LiveView.UploadWriter 行為的模組，用於寫入上傳的區塊。預設為寫入暫存檔以供使用。請參閱 Phoenix.LiveView.UploadWriter 文件以取得自訂用法的資訊。

在同一名稱下的先前允許上傳仍然有效時會引發。

範例

allow_upload(socket, :avatar, accept: ~w(.jpg .jpeg), max_entries: 2)
allow_upload(socket, :avatar, accept: :any)

若要自動使用上傳檔案，你可以將 auto_upload: true 與自訂進度函數配對，以在完成時使用條目。例如

allow_upload(socket, :avatar, accept: :any, progress: &handle_progress/3, auto_upload: true)

defp handle_progress(:avatar, entry, socket) do
  if entry.done? do
    uploaded_file =
      consume_uploaded_entry(socket, entry, fn %{} = meta ->
        {:ok, ...}
      end)

    {:noreply, put_flash(socket, :info, "file #{uploaded_file.name} uploaded")}
  else
    {:noreply, socket}
  end
end

非同步指派金鑰。

會將你的函數封裝到連結到呼叫者的任務中，錯誤會被封裝。傳遞至 assign_async/3 的每個金鑰都會指定給包含操作狀態和函數完成時結果的 %AsyncResult{} 結構。

只有當 socket 連線時，工作才會開始。

選項

• :supervisor - 允許你指定 Task.Supervisor 來監督任務。
• :reset - 當為 true 時，在非同步操作期間移除先前的結果。可能的數值為 true、false 或要重設的清單。預設為 false。

範例

def mount(%{"slug" => slug}, _, socket) do
  {:ok,
   socket
   |> assign(:foo, "bar")
   |> assign_async(:org, fn -> {:ok, %{org: fetch_org!(slug)}} end)
   |> assign_async([:profile, :rank], fn -> {:ok, %{profile: ..., rank: ...}} end)}
end

更多資訊，請見模組文件。

assign_async/3 和 send_update/3

由於 assign_async/3 內的程式碼會在個別程式中執行，所以 send_update(Component, data) 可以在 assign_async/3 內執行，因為 send_update/2 假設它會在 LiveView 程式中執行。解決方式為確實將更新傳送至 LiveView

parent = self()
assign_async(socket, :org, fn ->
  # ...
  send_update(parent, Component, data)
end)

將給定的 fun 透過 stage 中的生命週期 name 附加到 stage 中。

注意：此函數用於伺服器端的生命週期回呼。若要了解用戶端掛勾，請參閱 JS Interop 指南。

掛勾提供機制，以便在必要時點入 LiveView 生命週期的關鍵階段，以繫結/更新指定值，攔截事件、快取和一般訊息，並注入常見功能。在以下任一生命週期階段使用 attach_hook/1：:handle_params、:handle_event、:handle_info、:handle_async 和 :after_render。若要將掛勾附加至 :mount 階段，請使用 on_mount/1。

注意：目前僅在 LiveComponents 中支援 :after_render 和 :handle_event 掛勾。

傳回值

生命週期掛勾會在 LiveView 中呼叫給定生命週期回呼之前立即進行。除了 :after_render 外，掛勾可能會傳回 {:halt, socket} 以停止縮減，否則必須傳回 {:cont, socket}，這樣操作才能繼續進行，直到為目前階段呼叫所有掛勾。

對於 :after_render 鉤子，socket 本身必須傳回。任何更新至 socket 的指定 將不會 對用戶端觸發新的重新渲染或差異計算。

停止生命周期

請注意，從鉤子停止 會停止整個生命週期階段。這表示當鉤子傳回 {:halt, socket} 時，LiveView 回撥將 不會 被呼叫。這有一些含意。

對外掛作者的含意

在定義與特定回撥相符合的外掛時，必須 定義一個萬用子句，因為你的鉤子會被呼叫，即使在你不感興趣的事件中也是如此。

對最終使用者的含意

允許鉤子停止回撥呼叫，表示你可以附加鉤子來攔截特定事件，在分離之前，同時允許其他事件正常繼續。

回應事件

附加到 :handle_event 階段的鉤子，能夠透過傳回 {:halt, reply, socket} 來回應用戶端事件。這特別適用於 JavaScript 可互操作性，因為用戶端鉤子可以推送事件並接收回應。

範例

附加並分離鉤子

def mount(_params, _session, socket) do
  socket =
    attach_hook(socket, :my_hook, :handle_event, fn
      "very-special-event", _params, socket ->
        # Handle the very special event and then detach the hook
        {:halt, detach_hook(socket, :my_hook, :handle_event)}

      _event, _params, socket ->
        {:cont, socket}
    end)

  {:ok, socket}
end

回應用戶端事件

# JavaScript:
# /**
#  * @type {Object.<string, import("phoenix_live_view").ViewHook>}
#  */
# let Hooks = {}
# Hooks.ClientHook = {
#   mounted() {
#     this.pushEvent("ClientHook:mounted", {hello: "world"}, (reply) => {
#       console.log("received reply:", reply)
#     })
#   }
# }
# let liveSocket = new LiveSocket("/live", Socket, {hooks: Hooks, ...})

def render(assigns) do
  ~H"""
  <div id="my-client-hook" phx-hook="ClientHook"></div>
  """
end

def mount(_params, _session, socket) do
  socket =
    attach_hook(socket, :reply_on_client_hook_mounted, :handle_event, fn
      "ClientHook:mounted", params, socket ->
        {:halt, params, socket}

      _, _, socket ->
        {:cont, socket}
    end)

  {:ok, socket}
end

如果存在非同步作業，則取消。

使用 assign_async/3 時接受 %AsyncResult{} 或傳遞至 start_async/3 的金鑰。

如果傳遞原因時，基礎程序將會被殺死，或如果沒有傳遞原因則會 {:shutdown, :cancel}。對於 assign_async/3 操作，:failed 欄位將會設為 {:exit, reason}。對於 start_async/3，handle_async/3 回撥將會收到 {:exit, reason} 作為結果。

傳回 %Phoenix.LiveView.Socket{}。

範例

cancel_async(socket, :preview)
cancel_async(socket, :preview, :my_reason)
cancel_async(socket, socket.assigns.preview)

取消給定項目上傳作業。

範例

<%= for entry <- @uploads.avatar.entries do %>
  ...
  <button phx-click="cancel-upload" phx-value-ref={entry.ref}>cancel</button>
<% end %>

def handle_event("cancel-upload", %{"ref" => ref}, socket) do
  {:noreply, cancel_upload(socket, :avatar, ref)}
end

清除快閃訊息。

範例

iex> clear_flash(socket)

從快閃訊息中清除金鑰。

範例

iex> clear_flash(socket, :info)

如果套接字連線，則回傳 true。

用於在掛載檢視時檢查連線狀態。例如，在初始頁面渲染時，檢視會以靜態方式掛載、渲染，然後 HTML 傳送到用戶端。一旦客戶端連線到伺服器，就會衍生一個 LiveView，並在程序中以有狀態的方式掛載。使用 connected?/1 來有條件地執行有狀態的工作，例如訂閱 pubsub 主題、傳送訊息等。

範例

defmodule DemoWeb.ClockLive do
  use Phoenix.LiveView
  ...
  def mount(_params, _session, socket) do
    if connected?(socket), do: :timer.send_interval(1000, self(), :tick)

    {:ok, assign(socket, date: :calendar.local_time())}
  end

  def handle_info(:tick, socket) do
    {:noreply, assign(socket, date: :calendar.local_time())}
  end
end

消耗上傳的項目。

當仍有條目進行中時觸發。通常在提交表單時呼叫，以在表單資料中處理上傳的條目。對於表單提交，保證在呼叫提交事件之前，所有條目都已完成。一旦條目被使用，它們就會從上傳中移除。

傳遞給 consume 的函式可能會傳回形式 {:ok, my_result} 的標籤元組，以收集關於使用條目的結果，或形式 {:postpone, my_result} 的標籤元組，以收集結果，但延後檔案使用，稍後再執行。

範例

def handle_event("save", _params, socket) do
  uploaded_files =
    consume_uploaded_entries(socket, :avatar, fn %{path: path}, _entry ->
      dest = Path.join("priv/static/uploads", Path.basename(path))
      File.cp!(path, dest)
      {:ok, ~p"/uploads/#{Path.basename(dest)}"}
    end)
  {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))}
end

消耗單一上傳的項目。

當條目仍進行中時觸發。通常在提交表單時呼叫，以在表單資料中處理上傳的條目。一旦條目被使用，它們就會從上傳中移除。

這是一個比 consume_uploaded_entries/3 更底層的功能，對於在條目個別完成時使用條目的案例很有用。

和 consume_uploaded_entries/3 一樣，傳遞給 consume 的函式可能會傳回形式 {:ok, my_result} 的標籤元組，以收集關於使用條目的結果，或形式 {:postpone, my_result} 的標籤元組，以收集結果，但延後檔案使用，稍後再執行。

範例

def handle_event("save", _params, socket) do
  case uploaded_entries(socket, :avatar) do
    {[_|_] = entries, []} ->
      uploaded_files = for entry <- entries do
        consume_uploaded_entry(socket, entry, fn %{path: path} ->
          dest = Path.join("priv/static/uploads", Path.basename(path))
          File.cp!(path, dest)
          {:ok, ~p"/uploads/#{Path.basename(dest)}"}
        end)
      end
      {:noreply, update(socket, :uploaded_files, &(&1 ++ uploaded_files))}

    _ ->
      {:noreply, socket}
  end
end

將名稱為 name 的鉤子從生命週期 stage 中分離。

注意：此函數用於伺服器端的生命週期回呼。若要了解用戶端掛勾，請參閱 JS Interop 指南。

如果沒有找到掛鉤，這個函式是不會運作的。

範例

def handle_event(_, socket) do
  {:noreply, detach_hook(socket, :hook_that_was_attached, :handle_event)}
end

撤銷 allow_upload/3 先前允許上傳的項目。

範例

disallow_upload(socket, :avatar)

從套接字中取得給定的連線資訊金鑰。

支援下列金鑰： :peer_data、:trace_context_headers、:x_headers、:uri 和 :user_agent。

連線資訊只在掛載期間可用。在中斷渲染期間，所有金鑰都可用。在連線渲染期間，只有在 socket 中明確宣告的金鑰可用。請參閱 Phoenix.Endpoint.socket/3 以取得金鑰的完整說明。

範例

第一步是宣告您要接收的 connect_info。通常，至少包括工作階段，但您必須包含所有其他鍵，以便存取已連線掛載點，例如 :peer_data

socket "/live", Phoenix.LiveView.Socket,
  websocket: [connect_info: [:peer_data, session: @session_options]]

這些值現在可於已連線的掛載點上存取為 get_connect_info/2

def mount(_params, _session, socket) do
  peer_data = get_connect_info(socket, :peer_data)
  {:ok, assign(socket, ip: peer_data.address)}
end

如果鍵不可用，通常是因為它未在 connect_info 中指定，它會傳回 nil。

取得用戶端傳送用於連線掛載的連線參數。

連線參數只會在用戶端連線至伺服器時傳送，而且只在掛載期間可用。當在未連線狀態中呼叫時會傳回 nil，而在掛載之後呼叫則會引發 RuntimeError。

保留參數

以下參數在 LiveView 中具有特殊含義

• "_csrf_token" - 用戶連線時必須明確設定的 CSRF Token
• "_mounts" - 目前 LiveView 已掛載的次數。第一次掛載時為 0，然後在每次重新連線時增加。在導覽離開目前的 LiveView 或發生錯誤時重置
• "_track_static" - 自動設定為具備 phx-track-static 標註之所有標籤所述的 href/src 清單。如果沒有此類標籤，則不傳送任何內容
• "_live_referer" - 當從 push_navigate 或用戶端連結導覽發生即時導覽時，由用戶端傳送為 referrer URL。

範例

def mount(_params, _session, socket) do
  {:ok, assign(socket, width: get_connect_params(socket)["width"] || @width)}
end

宣告模組回呼，以便在 LiveView 掛載時呼叫。

提供模組中的函數，其名稱必須為 on_mount，將在已中斷與已連線的掛載點之前呼叫。鉤子可以選擇暫停或繼續掛載程序。如果您想重新導向 LiveView，您必須暫停，否則會引發錯誤。

提示：如果您需要定義多個 on_mount 回呼，請避免定義多個模組。改為傳遞組元，並使用樣式比對來處理不同狀況

def on_mount(:admin, _params, _session, socket) do
  {:cont, socket}
end

def on_mount(:user, _params, _session, socket) do
  {:cont, socket}
end

然後呼叫它為

on_mount {MyAppWeb.SomeHook, :admin}
on_mount {MyAppWeb.SomeHook, :user}

註冊 on_mount 鉤子可有效進行驗證，並透過 attach_hook/4 為其他回呼加入自訂行為。

on_mount 回呼可以傳回關鍵字清單，作為回傳組元的第三個元素。這些選項與 mount/3 中可選擇傳回的內容相同。

案例

以下展示如何透過 Phoenix.LiveView.Router.live_session/3 附加一個 hook

# lib/my_app_web/live/init_assigns.ex
defmodule MyAppWeb.InitAssigns do
  @moduledoc """
  Ensures common `assigns` are applied to all LiveViews attaching this hook.
  """
  import Phoenix.LiveView
  import Phoenix.Component

  def on_mount(:default, _params, _session, socket) do
    {:cont, assign(socket, :page_title, "DemoWeb")}
  end

  def on_mount(:user, params, session, socket) do
    # code
  end

  def on_mount(:admin, _params, _session, socket) do
    {:cont, socket, layout: {DemoWeb.Layouts, :admin}}
  end
end

# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  # pipelines, plugs, etc.

  live_session :default, on_mount: MyAppWeb.InitAssigns do
    scope "/", MyAppWeb do
      pipe_through :browser
      live "/", PageLive, :index
    end
  end

  live_session :authenticated, on_mount: {MyAppWeb.InitAssigns, :user} do
    scope "/", MyAppWeb do
      pipe_through [:browser, :require_user]
      live "/profile", UserLive.Profile, :index
    end
  end

  live_session :admins, on_mount: {MyAppWeb.InitAssigns, :admin} do
    scope "/admin", MyAppWeb.Admin do
      pipe_through [:browser, :require_user, :require_admin]
      live "/", AdminLive.Index, :index
    end
  end
end

將事件推送到用戶端。

事件可以透過兩種方式處理

1. 他們可以在 window 上透過 addEventListener 處理。一個 "phx:" 前綴會加入到事件名稱中。

2. 他們可以在一個 hook 中透過 handleEvent 處理。

事件被派送給客戶端上所有處理給定 event 的 active hook。如果您需要限定事件範圍，則必須透過命名空間來完成。

在 push_navigate 期間推出的事件目前會被捨棄，因為 LiveView 會立即卸載。

hook 範例

如果您從 LiveView 推出一個 "scores" 事件

{:noreply, push_event(socket, "scores", %{points: 100, user: "josé"})}

一個透過 phx-hook 宣告的 hook 可以透過 handleEvent 處理它

this.handleEvent("scores", data => ...)

window 範例

所有事件也會在 window 上派送。這意謂著您可以透過加入監聽器來處理他們。例如，如果您想要從頁面中移除一個元素，您可以這麼做

{:noreply, push_event(socket, "remove-el", %{id: "foo-bar"})}

現在您可以在 app.js 中註冊並處理它

window.addEventListener(
  "phx:remove-el",
  e => document.getElementById(e.detail.id).remove()
)

註解套接字，以便移動到另一個 LiveView。

目前的 LiveView 將會關閉而且一個新的將會掛載到它的位置上，而不會重新載入整個頁面。您也可以使用它來重新載入同一個 LiveView，以防您想要一個全新的開始。如果您想要導航到同一個 LiveView 而不需要重新掛載它，請改用 push_patch/2。

選項

• :to - 必要，要連結到的路徑。它必須永遠都是一個區域路徑
• :replace - 取代目前歷史記錄或推動一個新狀態的旗標。預設 false。

範例

{:noreply, push_navigate(socket, to: "/")}
{:noreply, push_navigate(socket, to: "/", replace: true)}

註解套接字，以便在當前 LiveView 內移動。

當導航到目前的 LiveView 時，handle_params/3 會立即被呼叫以處理參數與 URL 狀態的變更。接著新的狀態會被推送到客戶端，而無須重新載入整個頁面，並且也會維持目前的捲動位置。若要進行到另一個 LiveView 的動態導航，請使用 push_navigate/2。

選項

• :to - 必要，要連結到的路徑。它必須永遠都是一個區域路徑
• :replace - 取代目前歷史記錄或推動一個新狀態的旗標。預設 false。

範例

{:noreply, push_patch(socket, to: "/")}
{:noreply, push_patch(socket, to: "/", replace: true)}

新增快閃訊息至套接字，在顯示後將移除。

注意：雖然可以在 put_flash/3 內部使用 Phoenix.LiveComponent，但組件有自己的 @flash 指定。組件中的 @flash 僅會在組件呼叫 push_navigate/2 或 push_patch/2 時複製到其父系 LiveView 中。

注意：還必須將 Phoenix.LiveView.Router.fetch_live_flash/2 插入瀏覽器的管線中，取代 fetch_flash，如此一來才能支援 LiveView 閃爍訊息，例如

import Phoenix.LiveView.Router

pipeline :browser do
  ...
  plug :fetch_live_flash
end

範例

iex> put_flash(socket, :info, "It worked!")
iex> put_flash(socket, :error, "You can't access that page")

將新的私人金鑰與值放置在套接字中。

私密並不會追蹤變更。此儲存預期由使用者和程式庫使用，用於存放不需要追蹤變更的狀態。金鑰應以 app/library 名稱作為開頭。

範例

金鑰值可以放入私密中

put_private(socket, :myapp_meta, %{foo: "bar"})

然後再擷取

socket.private[:myapp_meta]

註解套接字，以便重新導向至目標路徑。

注意：LiveView 重新導向仰賴指示客戶端在提供的重新導向位置上執行 window.location 更新。整個頁面將重新載入，所有狀態將會捨棄。

選項

• :to - 要重新導向的路徑。它必須永遠是本機路徑
• :external - 要重新導向的外部路徑。字串或 {scheme, url} 以重新導向到自訂方案

範例

{:noreply, redirect(socket, to: "/")}
{:noreply, redirect(socket, external: "https://example.com")}

設定使用何種函數來呈現 LiveView/LiveComponent。

預設情況下，LiveView 會在定義 LiveView/LiveComponent 的相同模組中呼叫 render/1 函式，傳入 assigns 作為其唯一參數。此函式可讓您設定不同的儲存函式。

此函式的一個可能的使用案例是在離線儲存中設定不同的範本。當使用者第一次存取 LiveView 時，我們將執行離線儲存以傳送到瀏覽器。這有幾個好處，例如縮短首頁面繪製時間和搜尋引擎索引。

但是，當 LiveView 在驗證頁面後端使用時，在離線儲存中儲存暫存檔並在 WebSocket 連接後執行完整儲存會很有用。這可以使用 render_with/2 來達成，在複雜的頁面（例如控制台和報表）中特別有用。

若要執行此操作，您必須簡單地呼叫 render_with(socket, &some_function_component/1)，使用新的儲存函式組態您的 Socket。

非同步更新 Phoenix.LiveComponent 以獲得新指派。

pid 參數是選配的而且預設為目前的處理程序，這表示更新指示會發送給執行在同一個 LiveView 上的組件。如果目前的處理程序不是 LiveView 或你想發送更新給執行在另一個 LiveView 上的 Live 組件，你應明確傳遞 LiveView 的 pid。

第二個參數可以是 @myself 的值或 Live 組件的模組。如果你傳遞模組，然後用於識別組件的 :id 必須作為 assigns 的一部分傳遞。

當組件收到更新，update_many/1 會被呼叫，如果它已定義，否則 update/2 會被呼叫新的 assigns。如果 update/2 未定義，所有 assigns 都會簡單地合併進 Socket 中。接收為 update/2 回呼函式的第一個參數的 assigns 僅包括從此函式傳遞的新 assigns。現有的 assigns 可以在 socket.assigns 中找到。

儘管組件可能總是透過更新一些父項 assigns 而由父項更新，這會重新呈現子項，進而呼叫子項組件上的 update/2，send_update/3 對於更新完全管理其自己的狀態的組件，以及，掛載在同一個 LiveView 中的組件之間的訊息傳遞而言是有用的。

範例

def handle_event("cancel-order", _, socket) do
  ...
  send_update(Cart, id: "cart", status: "cancelled")
  {:noreply, socket}
end

def handle_event("cancel-order-asynchronously", _, socket) do
  ...
  pid = self()

  Task.Supervisor.start_child(MyTaskSup, fn ->
    # Do something asynchronously
    send_update(pid, Cart, id: "cart", status: "cancelled")
  end)

  {:noreply, socket}
end

def render(assigns) do
  ~H"""
  <.some_component on_complete={&send_update(@myself, completed: &1)} />
  """
end