Adding the.once modifier to the event listener ensures that the listener is called only once. This is especially useful for events that you only want to call once, such as requesting HTML fragments.

Adding.passive modifier to the event listener will make it passive, meaning preventDefault() won’t work. This can help deal with sliding performance issues on touch devices.

. Debounce Modifier For example:

The Debounce modifier allows you to “shock proof” the event handler. In other words, the event handler will wait some time after the last firing before firing again. The last call will be processed when the processor is ready.

The default “wait” time is 250 milliseconds.

If you want to customize it, you can specify it like this:

<input x-on:input.debounce.750="fetchSomething()">
<input x-on:input.debounce.750ms="fetchSomething()">
Copy the code

For example:

The camel modifier is used to mount an event listener equivalent to the camel script. In the example above, the expression will be executed when the eventName event is triggered.

x-model

X-model adds “two-way data binding” to an element. In other words, the value of the input element remains synchronized with the value of the data item in the component.

Note: THE X-Model can intelligently detect input, checkbox, Radio button, textarea, select and multi selects. His behavior and usage are the same as Vue’s.

Number modifiers for example:

The number modifier converts the input value to a numeric data type and returns the original value if it cannot be successfully converted.

. Debounce modifier for example:

The debounce modifier allows you to “guard” against updates to a value. In other words, the event handler will wait some time after the last firing before firing again. The last call will be processed when the processor is ready.

The default “wait” time is 250 milliseconds.

If you want to customize it, you can specify it like this:

<input x-model.debounce.750="search">
<input x-model.debounce.750ms="search">
Copy the code

x-text

X-text is very similar to X-bind, except that when the value in the attribute is updated, it updates the innerText of the element.

x-html

For example:

X-html is very similar to X-bind, except that it updates the innerHTML of the element when the value in the attribute is updated.

: Warning: Use only for trusted content, never display user content directly: Warning:

Dynamically rendering HTML from a third party source can be very vulnerable to XSS vulnerabilities.

x-ref

For example: < div x – ref = “foo” > < / div > < button x – on: click = “$refs. Foo. The innerText = ‘bar'” > < / button >

Structure: < div X-ray ref = “[ref name]” > < / div > < button x – on: click = “$refs. [ref name]. The innerText = ‘bar'” > < / button >

X-ref provides an easy way to get raw DOM elements outside the component. By setting the X-Ref attribute on the element, you can retrieve the DOM from the built-in object (the magic attribute) $refs and the tag’s refName in any event handling.

It helps you replace setting the id and then selecting it by document.querySelector anywhere.

Note: you can also bind a dynamic value to x-ref if you want.

x-if

For example:

Sometimes x-show can be awkward (it adds display: None to elements when the value is false), and x-if can actually remove elements from the DOM completely.

Note, however, that x-if can only be used in the
tag, because Alpine doesn’t use the virtual DOM. This implementation allows Alpine to keep it simple and use the real DOM directly for dynamic parts (magic).

Note: X-if requires a single root element in the
tag.

Note: When using Template in an SVG tag, you need to add Polyfill to run Alpine before initializing it.

x-for

Such as:

<template x-for="item in items" :key="item">
    <div x-text="item"></div>
</template>
Copy the code

Note: : Key binding is optional, but highly recommended, and is necessary for list rendering.

X-for can be used to create a new DOM node for each item in the array. This feature is very similar to v-for in Vue, which also needs to be used on the template tag, not a normal DOM element.

If you want to use an index in the current iteration, you can write it like this:

<template x-for="(item, index) in items" :key="index">
    <! You can use the index value index if necessary. -->
    <div x-text="index"></div>
</template>
Copy the code

If you need to access the original array object in an iteration, you can write:

<template x-for="(item, index, collection) in items" :key="index">
    <div>
        <! You can use the original collection value of the array if needed. -->
        <! -- Current item -->
        <div x-text="item"></div>
        <! Same as previous line -->
        <div x-text="collection[index]"></div>
        <! -- Previous item -->
        <div x-text="collection[index - 1]"></div>
    </div>
</template>
Copy the code

Note: X-for requires a single root element in the
tag.

Note: When using Template in an SVG tag, you need to add Polyfill to run Alpine before initializing it.

nestedx-for

You can nest x-for loops, but you must wrap one element around each loop, as follows:

<template x-for="item in items">
    <div>
        <template x-for="subItem in item.subItems">
            <div x-text="subItem"></div>
        </template>
    </div>
</template>
Copy the code

Scope iteration

Alpine supports the I in N syntax, which accomplishes the goal of iterating over a fixed range when n is an integer.

<template x-for="i in 10">
    <span x-text="i"></span>
</template>
Copy the code

x-transition

Such as:

<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>
Copy the code

<template x-if="open">
    <div
        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>
</template>
Copy the code

This example uses the classes provided in the Tailwind CSS.

Alpine provides six different Transition directives for implementing different classes at different stages of Transition in the show/hide state. These commands can be used with x-show and X-if.

These behaviors are completely consistent with VueJS transition instructions. It’s just a little bit clearer naming.

x-spread

Such as:

<div x-data="dropdown()">
    <button x-spread="trigger">Open Dropdown</button>

    <span x-spread="dialogue">Dropdown Contents</span>
</div>

<script>
    function dropdown() {
        return {
            open: false.trigger: {['@click'] () {this.open = true}},dialogue: {['x-show'] () {return this.open
                },
                ['@click.away'] () {this.open = false}}}},</script>
Copy the code

X-spread allows you to expand a reusable object, including the Alpine binding of elements.

The key of this object is an instruction (which can also include modifiers), and the value is a callback that Alpine executes.

Note: The following two points need to be noted about x-spread

• When the instruction being expanded isx-forYou need to return an expression string in the callback, such as:['x-for']() { return 'item in items' }.
• x-data 和 x-initCannot be used in the “spread” object.

x-cloak

Cloak =”{}” x-cloak>

The X-Cloak property will be removed after Alpine initializes. This is very useful for hiding uninitialized DOM, and a typical way to do this through global style is as follows:

<style>
    [x-cloak] {
        display: none ! important;
    }
</style>
Copy the code

Magic Properties

With the exception of $el, magic properties are not available in X-data because the component is not initialized at that time.

$el

Such as:

<div x-data>
    <button @click="$el.innerHTML = 'foo'">Replace me with "foo"</button>
</div>
Copy the code

$EL is a magic property that gets the DOM node of the root component.

$refs

Such as:

<span x-ref="foo"></span>

<button x-on:click="$refs.foo.innerText = 'bar'"></button>
Copy the code

$refs is a magic property used to get native DOM elements in components. This will help you manually retrieve the original DOM elements if needed.

$event

Such as:

<input x-on:input="alert($event.target.value)">
Copy the code

$event is a magic property that accepts the browser’s native “event” object in the event listener.

Note: The $event attribute is valid only in DOM expressions.

If you need to use $event in a JavaScript function, you can do so:

<button x-on:click="myFunction($event)"></button>

$dispatch

Such as:

<div @custom-event="console.log($event.detail.foo)">
    <button @click="$dispatch('custom-event', { foo: 'bar' })">
    <! -- When clicked, console.log is triggered -->
</div>
Copy the code

About Event Propagation

Note that because of the event bubbling mechanism, you need to add the.window modifier when you need to intercept triggered events from nodes at the same level:

Such as:

<div x-data>
    <span @custom-event="console.log($event.detail.foo)"></span>
    <button @click="$dispatch('custom-event', { foo: 'bar' })">
<div>
Copy the code

The above example is an error demonstration and does not work because when a custom-event is triggered, it only propagates to the common ancestor, the parent div element.

Distribute to components

The same technique can also be used to communicate between components:

Such as:

<div x-data @custom-event.window="console.log($event.detail)"></div>

<button x-data @click="$dispatch('custom-event', 'Hello World! ')">
<! -- Console. log "Hello World!" when clicked . -- -- >
Copy the code

$dispatch is a shortcut to create a CustomEvent and distribute it using its internal.dispatchEvent(). There are many excellent use cases that use custom events to pass data between components. Refer to this document for more information about CustomEvents in the browser.

Note that the data placed in the second parameter of $dispatch(‘some-event’, {some: ‘data’}) is available on the new event via the ‘detail’ property: $event.detail.some. Attaching data for custom events to the.detail property is standard practice for CustomEvents in browsers. See this document (in English) for more information.

You can also use $dispatch() to trigger data updates for the X-Model binding. Such as:

<div x-data="{ foo: 'bar' }">
    <span x-model="foo">
        <button @click="$dispatch('input', 'baz')">
        <! When the button is clicked, 'x-model' will get a bubbling 'input' event and update foo to 'baz'. -->
    </span>
</div>
Copy the code

Note: The $dispatch attribute is valid only in DOM expressions.

If you need to use $dispatch in a JavaScript function, you can just do it:

<button x-on:click="myFunction($dispatch)"></button>

$nextTick

Such as:

<div x-data="{ fruit: 'apple' }">
    <button
        x-on:click=" fruit = 'pear'; $nextTick(() => { console.log($event.target.innerText) }); "
        x-text="fruit"
    ></button>
</div>
Copy the code

$nextTick is a command that executes a given expression after you make a responsive DOM update in Alpine. This is useful when you need to interact with THE DOM state after a data update.

$watch

Such as:

<div x-data="{ open: false }" x-init="$watch('open', value => console.log(value))">
    <button @click="open = ! open">Toggle Open</button>
</div>
Copy the code

You can “listen” on a component property using the $watch magic method. In the example above, when the button is clicked and open is changed, the callback function you provided is called, console.log new value.

Security-related Security

If you find a security breach, email us at [email protected].

Alpine relies on a custom implementation of the Function object to run the directive. Although safer than Eval (), this method is not available in some environments, such as the restricted Content Security Policy/CSP used by Google Chrome App.

If you’re working with sensitive data on a site that uses Alpin, you’ll need to set up CSP to include safe-Eval. Proper security policies can help protect users’ private data.

Because policy Settings apply to all scripts on the page, it’s important to check for other external dependencies that the page introduces to prevent them from opening XSS vulnerabilities and injecting malicious code through EVAL () DOM modification.

V3 Roadmap Roadmap

• fromx-refMigration torefTo be consistent with Vue?
• newAlpine.directive()
• newAlpine.component('foo', {... })(by__init()Magic method)
• Distribute Alpine’s “loaded”, “transition-start” and other events (#299)?
• removex-bind:class="{ 'foo': true }"Syntax for using objects (and arrays) in# 236And increase instyleSupport for using objects in
• To optimize thex-forIs responsive effect (# 165)
• Added “deep watching” support (#294)
• increase$elA shortcut
• Modify the@click.away 为 @click.outside?

The permit License

Copyright © 2019-2020 Caleb Porzio and All Contributors to the Warehouse

Open source under the MIT LICENSE, see license.md for details.