alpinejs

AlpineJS 最佳实践

黄金法则：保持属性简短

绝不要在 HTML 属性中编写复杂逻辑。如果你的 x-data、x-init 或任何指令超过约 50 个字符，请将其提取出来。

指令速查表

指令	用途	示例
x-data	声明响应式组件状态	x-data="{ open: false }"
x-init	在组件初始化时运行代码	x-init="fetchData()"
x-show	切换可见性（CSS display）	x-show="open"
x-if	条件渲染（必须包裹 <template>）	<template x-if="show">
x-for	循环（必须包裹 <template>）	<template x-for="item in items">
x-bind: / :	将属性绑定到表达式	:class="{ active: isActive }"
x-on: / @	监听事件	@click="open = !open"
x-model	对表单输入进行双向绑定	x-model="email"
x-text	设置文本内容	x-text="message"
x-html	设置内部 HTML	x-html="htmlContent"
x-ref	通过 $refs 引用元素	x-ref="input"
x-cloak	在 Alpine 初始化前隐藏元素	x-cloak（添加 CSS：[x-cloak] { display: none; }）
x-transition	应用进入/离开过渡效果	x-transition 或 x-transition.duration.300ms
x-effect	运行响应式副作用	x-effect="console.log(count)"
x-ignore	跳过 Alpine 初始化	x-ignore
x-teleport	将元素移动到其他位置	x-teleport="#modals"
x-modelable	暴露属性以供外部绑定	x-modelable="value"

魔法属性

属性	说明
$el	当前 DOM 元素
$refs	访问带有 x-ref 的元素
$store	访问全局 Alpine 存储
$watch	监听属性变化
$dispatch	派发自定义事件
$nextTick	在 DOM 更新后运行
$root	组件的根元素
$data	访问组件数据对象
$id	生成唯一 ID

模式

❌ 错误：冗长的内联 JavaScript

<div x-data="{ items: [], loading: true, error: null, async fetchItems() { this.loading = true; try { const res = await fetch('/api/items'); this.items = await res.json(); } catch (e) { this.error = e.message; } finally { this.loading = false; } } }" x-init="fetchItems()">

✅ 正确：提取为函数

<script>
function itemList() {
  return {
    items: [],
    loading: true,
    error: null,
    
    async fetchItems() {
      this.loading = true;
      try {
        const res = await fetch('/api/items');
        this.items = await res.json();
      } catch (e) {
        this.error = e.message;
      } finally {
        this.loading = false;
      }
    }
  };
}
</script>

<div x-data="itemList()" x-init="fetchItems()">
  
</div>

✅ 正确：简单的内联状态

<div x-data="{ open: false, count: 0 }">
  <button @click="open = !open">Toggle</button>
  <div x-show="open" x-transition>Content</div>
</div>

✅ 正确：使用全局存储共享状态

<script>
document.addEventListener('alpine:init', () => {
  Alpine.store('cart', {
    items: [],
    add(item) { this.items.push(item); },
    get total() { return this.items.reduce((sum, i) => sum + i.price, 0); }
  });
});
</script>

<div x-data>
  <span x-text="$store.cart.total"></span>
</div>

✅ 正确：使用 Alpine.data() 创建可复用组件

<script>
document.addEventListener('alpine:init', () => {
  Alpine.data('dropdown', () => ({
    open: false,
    toggle() { this.open = !this.open; },
    close() { this.open = false; }
  }));
});
</script>

<div x-data="dropdown" @click.outside="close()">
  <button @click="toggle()">Menu</button>
  <ul x-show="open" x-transition>
    <li>Item 1</li>
  </ul>
</div>

✅ 正确：带验证的表单

<script>
function contactForm() {
  return {
    email: '',
    message: '',
    errors: {},
    
    validate() {
      this.errors = {};
      if (!this.email.includes('@')) this.errors.email = 'Invalid email';
      if (this.message.length < 10) this.errors.message = 'Too short';
      return Object.keys(this.errors).length === 0;
    },
    
    submit() {
      if (this.validate()) {
        // submit logic
      }
    }
  };
}
</script>

<form x-data="contactForm()" @submit.prevent="submit()">
  <input x-model="email" type="email">
  <span x-show="errors.email" x-text="errors.email" class="error"></span>
  
  <textarea x-model="message"></textarea>
  <span x-show="errors.message" x-text="errors.message" class="error"></span>
  
  <button type="submit">Send</button>
</form>

事件修饰符

@click.prevent     
@click.stop        
@click.outside     
@click.window      
@click.document    
@click.once        
@click.debounce    
@click.throttle    
@keydown.enter     
@keydown.escape    

过渡修饰符

x-transition                           
x-transition.duration.300ms            
x-transition.opacity                   
x-transition.scale.90                  
x-transition:enter.duration.500ms      
x-transition:leave.duration.200ms      

快速决策指南

1. 状态只有 1–3 个简单属性？ → 内联 x-data="{ open: false }"
2. 包含方法或复杂逻辑？ → 提取为 function componentName() { return {...} }
3. 在多个页面重复使用？ → 使用 Alpine.data('name', () => ({...}))
4. 需要共享全局状态？ → 使用 Alpine.store('name', {...})
5. 属性字符串太长？ → 这样做不对。把它提取出来。