查看來源 Phoenix.HTML (Phoenix.HTML v4.1.1)

用於處理 Phoenix 中 HTML 的基塊。

此程式庫提供三個主要功能

HTML 安全
表單抽象
一個用於增強程式的微小 JavaScript 程式庫

HTML 安全

此套件的主要責任之一是提供方便的功能來跳脫並標記 HTML 程式碼為安全。

預設情況下，模板中輸出資料不被視為安全

<%= "<hello>" %>

將顯示為

&lt;hello&gt;

使用者資料或從資料庫中來的資料幾乎從來不會被視為安全。然而，在某些情況下，您可能想要標記它為安全並顯示其「原始」內容

<%= raw "<hello>" %>

表單處理

請參閱 Phoenix.HTML.Form。

JavaScript 程式庫

此專案附帶微小的 JavaScript，它監聽所有點選事件，以

支援 data-confirm="message" 屬性，它會顯示具有特定訊息的確認視窗
支援 data-method="patch|post|put|delete" 屬性，它會將目前的點選作為 PATCH/POST/PUT/DELETE HTTP 要求傳送。您需要新增 data-to 和 URL，以及 data-csrf 和 CSRF 令牌值
傳送「phoenix.link.click」事件。您可以監聽此事件以自訂上述行為。由此事件傳回 false 將會停用 data-method。停止傳播將會停用 data-confirm

若要使用上述功能，您必須將 priv/static/phoenix_html.js 載入到您的建構工具中。

覆寫預設的確認行為

您可以藉由連接到 phoenix.link.click 來覆寫預設實作。以下是一個範例

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);

摘要

類型

safe()

保證安全

unsafe()

可能是安全或不安全（即需要轉換）

函式

attributes_escape(attrs)

跳脫可列舉屬性，傳回 iodata。

html_escape(safe)

跳脫特定項目中 HTML 實體，傳回安全 iodata。

javascript_escape(data)

跳脫 HTML 內容，插入到 JavaScript 字串。

raw(value)

將提供的內容標記為原始內容。

safe_to_string(arg)

將安全結果轉換為字串。

類型

safe()

@type safe() :: {:safe, iodata()}

保證安全

unsafe()

@type unsafe() :: Phoenix.HTML.Safe.t()

可能是安全或不安全（即需要轉換）

函數

attributes_escape(attrs)

跳脫可列舉屬性，傳回 iodata。

屬性會依給定的順序呈現。注意，如果給定的是映射，無法保證按鍵順序排列。

只要實作了 Phoenix.HTML.Safe 通訊協定，鍵和值可以是任意形狀。另外，如果鍵是原子，它會被「破折號化」。換句話說，:phx_value_id 會轉換成 phx-value-id。

此外，下列屬性提供行為

:aria、:data 和 :phx - 它們接受關鍵字清單作為值。data: [confirm: "are you sure?"] 會轉換成 data-confirm="are you sure?"。
:class - 它接受一個類別清單作為參數。清單中的每個元素都以空白分隔。nil 和 false 元素會被捨棄。class: ["foo", nil, "bar"] 接著會變成 class="foo bar"。
:id - 它會經過驗證，如果給定數字作為 ID，就會引發錯誤，這是 HTML 規範不允許的，而且會導致不可預測的行為。

範例

iex> safe_to_string attributes_escape(title: "the title", id: "the id", selected: true)
" title=\"the title\" id=\"the id\" selected"

iex> safe_to_string attributes_escape(%{data: [confirm: "Are you sure?"]})
" data-confirm=\"Are you sure?\""

iex> safe_to_string attributes_escape(%{phx: [value: [foo: "bar"]]})
" phx-value-foo=\"bar\""

html_escape(safe)

@spec html_escape(unsafe()) :: safe()

跳脫特定項目中 HTML 實體，傳回安全 iodata。

iex> html_escape("<hello>")
{:safe, [[[] | "&lt;"], "hello" | "&gt;"]}

iex> html_escape('<hello>')
{:safe, ["&lt;", 104, 101, 108, 108, 111, "&gt;"]}

iex> html_escape(1)
{:safe, "1"}

iex> html_escape({:safe, "<hello>"})
{:safe, "<hello>"}

javascript_escape(data)

@spec javascript_escape(binary()) :: binary()

@spec javascript_escape(safe()) :: safe()

跳脫 HTML 內容，插入到 JavaScript 字串。

當需要轉譯由其他範本呈現的 HTML 時，此函數在 JavaScript 回應中很有用，如下所示

$("#container").append("<%= javascript_escape(render("post.html", post: @post)) %>");

它會轉譯引號（雙引號和單引號）、雙反斜線和其他人。

raw(value)

@spec raw(iodata() | safe() | nil) :: safe()

將提供的內容標記為原始內容。

這表示提供的字串中的任何 HTML 程式碼都不會被轉譯。

iex> raw("<hello>")
{:safe, "<hello>"}
iex> raw({:safe, "<hello>"})
{:safe, "<hello>"}
iex> raw(nil)
{:safe, ""}

safe_to_string(arg)

@spec safe_to_string(safe()) :: String.t()

將安全結果轉換為字串。

如果結果不安全，則會失敗。在這種情況下，你可以分別先呼叫 html_escape/1 或 raw/1。

你可以合併 html_escape/1 和 safe_to_string/1 將資料結構轉換成轉譯後的字串

data |> html_escape() |> safe_to_string()