跳转至

模板

Alpine 提供了几个有用的指令来操作网页上的 DOM。

这里我们介绍一些基本的模板指令,但请务必查看侧边栏中可用的指令以获取完整列表。

文本内容

Alpine 使用 x-text 指令让控制元素的文本内容变得简单。

<div x-data="{ title: 'Start Here' }">
    <h1 x-text="title"></h1>
</div>

现在,Alpine 会将 <h1> 的文本内容设置为 title 的值("Start Here")。当 title 变化时,<h1> 的内容也会随之变化。

与 Alpine 中的所有指令一样,你可以使用任何你喜欢的 JavaScript 表达式。例如:

<span x-text="1 + 2"></span>

<span> 现在将包含"1"和"2"的和。

→ 阅读更多关于 x-text 的内容

切换元素

切换元素是网页和应用中的常见需求。下拉菜单、模态框、对话框、"显示更多"等都是很好的例子。

Alpine 提供了 x-showx-if 指令来切换页面上的元素。

x-show

以下是一个使用 x-show 的简单切换组件。

<div x-data="{ open: false }">
    <button @click="open = ! open">Expand</button>

    <div x-show="open">
        Content...
    </div>
</div>
Content...

现在,包含内容的整个 <div> 将根据 open 的值显示或隐藏。

在底层,Alpine 在元素应该隐藏时为其添加 CSS 属性 display: none;

→ 阅读更多关于 x-show 的内容

这在大多数情况下效果很好,但有时你可能想完全从 DOM 中添加和移除元素。这就是 x-if 的作用。

x-if

以下是之前相同的切换示例,但这次使用的是 x-if 而不是 x-show

<div x-data="{ open: false }">
    <button @click="open = ! open">Expand</button>

    <template x-if="open">
        <div>
            Content...
        </div>
    </template>
</div>

注意 x-if 必须在 <template> 标签上声明。这样 Alpine 可以利用 <template> 元素的现有浏览器行为,将其作为目标 <div> 的源,以便在页面上添加和移除。

open 为 true 时,Alpine 会将 <div> 追加到 <template> 标签中,并在 open 为 false 时将其移除。

→ 阅读更多关于 x-if 的内容

带过渡效果的切换

Alpine 使用 x-transition 指令让在"显示"和"隐藏"状态之间平滑过渡变得简单。

x-transition 仅适用于 x-show,不适用于 x-if

再次以简单的切换示例为例,这次应用了过渡效果:

<div x-data="{ open: false }">
    <button @click="open = ! open">Expands</button>

    <div x-show="open" x-transition>
        Content...
    </div>
</div>
Content...

让我们仔细看看模板中处理过渡的部分:

<div x-show="open" x-transition>

x-transition 本身会为切换应用合理的默认过渡效果(淡入淡出和缩放)。

有两种方式可以自定义这些过渡效果:

  • 过渡辅助修饰符
  • 过渡 CSS 类

让我们看看每种方法:

过渡辅助修饰符

假设你想让过渡持续时间更长,可以使用 .duration 修饰符手动指定:

<div x-show="open" x-transition.duration.500ms>
Content...

现在过渡将持续 500 毫秒。

如果你想为进入和离开过渡指定不同的值,可以使用 x-transition:enterx-transition:leave

<div
    x-show="open"
    x-transition:enter.duration.500ms
    x-transition:leave.duration.1000ms
>
Content...

此外,你可以添加 .opacity.scale 来仅过渡该属性。例如:

<div x-show="open" x-transition.opacity>
Content...

→ 阅读更多关于过渡辅助修饰符的内容

过渡 CSS 类

如果你需要对应用中的过渡效果进行更精细的控制,可以在过渡的特定阶段应用特定的 CSS 类,使用以下语法(此示例使用 Tailwind CSS):

<div
    x-show="open"
    x-transition:enter="transition ease-out duration-300"
    x-transition:enter-start="opacity-0 transform scale-90"
    x-transition:enter-end="opacity-100 transform scale-100"
    x-transition:leave="transition ease-in duration-300"
    x-transition:leave-start="opacity-100 transform scale-100"
    x-transition:leave-end="opacity-0 transform scale-90"
>...</div>
Content...

→ 阅读更多关于过渡 CSS 类的内容

绑定属性

你可以使用 x-bind 指令在 Alpine 中为元素添加 HTML 属性,如 classstyledisabled 等。

以下是一个动态绑定 class 属性的示例:

<button
    x-data="{ red: false }"
    x-bind:class="red ? 'bg-red' : ''"
    @click="red = ! red"
>
    Toggle Red
</button>

作为快捷方式,你可以省略 x-bind,直接使用简写 : 语法:

<button ... :class="red ? 'bg-red' : ''">

根据 Alpine 中的数据切换 class 的开关是一个常见需求。以下是一个使用 Alpine 的 class 绑定对象语法来切换 class 的示例:(注意:此语法仅适用于 class 属性)

<div x-data="{ open: true }">
    <span :class="{ 'hidden': ! open }">...</span>
</div>

现在,如果 open 为 false,hidden 类将添加到元素中;如果 open 为 true,则会移除该类。

循环元素

Alpine 允许使用 x-for 指令根据 JavaScript 数据迭代模板的各个部分。以下是一个简单示例:

<div x-data="{ statuses: ['open', 'closed', 'archived'] }">
    <template x-for="status in statuses">
        <div x-text="status"></div>
    </template>
</div>

x-if 类似,x-for 必须应用于 <template> 标签。在内部,Alpine 会为循环中的每次迭代追加 <template> 标签的内容。

如你所见,新的 status 变量在迭代模板的作用域内可用。

→ 阅读更多关于 x-for 的内容

Inner HTML

Alpine 使用 x-html 指令让控制元素的 HTML 内容变得简单。

<div x-data="{ title: '<h1>Start Here</h1>' }">
    <div x-html="title"></div>
</div>

现在,Alpine 会将 <div> 的文本内容设置为元素 <h1>Start Here</h1>。当 title 变化时,<h1> 的内容也会随之变化。

⚠️ 仅用于受信任的内容,绝不能用于用户提供的内容。⚠️ 动态渲染来自第三方的 HTML 很容易导致 XSS 漏洞。

→ 阅读更多关于 x-html 的内容