查看源代码 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)

转义要插入 JavaScript 字符串的 HTML 内容。

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

转义要插入 JavaScript 字符串的 HTML 内容。

此函数在 JavaScript 响应中很有用，当需要转义来自其他模板（如以下）的 HTML 呈现时

$("#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()