编辑“︁Pinia Actions”︁（章节）

= Pinia Actions =

== 介绍 ==
'''Pinia Actions''' 是 Pinia 状态管理库中用于封装业务逻辑的核心功能，类似于 Vuex 中的 mutations + actions 组合。Actions 允许您定义可复用的方法，这些方法可以：
* 修改状态（通过直接访问 <code>this</code>）
* 执行异步操作（如 API 调用）
* 组合多个状态变更
* 调用其他 actions

与 Vuex 不同，Pinia 的 actions 同时支持同步和异步操作，无需区分 mutations/actions，简化了开发流程。

== 基本语法 ==
Actions 在 store 定义中通过 <code>actions</code> 属性声明：

<syntaxhighlight lang="javascript">
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0
  }),
  actions: {
    // 同步action
    increment() {
      this.count++
    },
    // 异步action
    async fetchData() {
      const response = await fetch('/api/data')
      this.data = await response.json()
    }
  }
})
</syntaxhighlight>

== 关键特性 ==

=== 访问状态 ===
在 action 内部通过 <code>this</code> 直接访问整个 store 实例：

<syntaxhighlight lang="javascript">
actions: {
  doubleCount() {
    this.count *= 2 // 直接修改状态
  }
}
</syntaxhighlight>

=== 参数传递 ===
Actions 可以接受任意数量的参数：

<syntaxhighlight lang="javascript">
actions: {
  add(value) {
    this.count += value
  }
}

// 调用
store.add(5)
</syntaxhighlight>

=== 异步操作 ===
Pinia 自动处理异步 actions 的 Promise 解析：

<syntaxhighlight lang="javascript">
actions: {
  async fetchUser(id) {
    try {
      this.user = await api.fetchUser(id)
    } catch (error) {
      this.error = error
    }
  }
}
</syntaxhighlight>

== 高级用法 ==

=== 组合 Actions ===
Actions 可以互相调用：

<syntaxhighlight lang="javascript">
actions: {
  reset() {
    this.count = 0
  },
  async resetAndFetch() {
    this.reset() // 调用其他action
    await this.fetchData()
  }
}
</syntaxhighlight>

=== 订阅 Actions ===
可以通过 <code>store.$onAction()</code> 监听 action 调用：

<syntaxhighlight lang="javascript">
const unsubscribe = store.$onAction(({ name, store, args, after, onError }) => {
  console.log(`Action "${name}" started`)
  
  after((result) => {
    console.log(`Action "${name}" completed`)
  })
  
  onError((error) => {
    console.error(`Action "${name}" failed:`, error)
  })
})

// 取消订阅
unsubscribe()
</syntaxhighlight>

== 实际案例 ==

=== 购物车场景 ===
<mermaid>
sequenceDiagram
    participant Component
    participant Store
    participant API
    Component->>Store: addToCart(productId, quantity)
    Store->>API: POST /cart
    API-->>Store: Updated cart data
    Store->>Store: update cart state
    Store-->>Component: Updated cart
</mermaid>

对应实现：

<syntaxhighlight lang="javascript">
// cartStore.js
actions: {
  async addToCart(productId, quantity) {
    const currentItems = this.cartItems
    const existingItem = currentItems.find(item => item.id === productId)
    
    if (existingItem) {
      existingItem.quantity += quantity
    } else {
      currentItems.push({ id: productId, quantity })
    }
    
    try {
      await api.updateCart(currentItems)
      this.cartItems = currentItems
    } catch (error) {
      // 回滚变更
      this.cartItems = await api.getCart()
      throw error
    }
  }
}
</syntaxhighlight>

=== 用户认证流程 ===
<syntaxhighlight lang="javascript">
// authStore.js
actions: {
  async login(credentials) {
    this.loading = true
    try {
      const user = await authService.login(credentials)
      this.user = user
      this.isAuthenticated = true
      router.push('/dashboard')
    } catch (error) {
      this.error = error.message
    } finally {
      this.loading = false
    }
  }
}
</syntaxhighlight>

== 最佳实践 ==

1. '''单一职责''': 每个 action 应该只做一件事
2. '''错误处理''': 始终处理异步操作中的潜在错误
3. '''可组合性''': 将复杂操作拆分为多个小 actions
4. '''命名约定''': 使用动词命名 actions (如 <code>fetchUser</code>, <code>updateSettings</code>)
5. '''避免直接修改参数''': 对传入参数进行深拷贝（如需修改）

== 数学表示 ==
Action 可以看作状态转换函数：

<math>
action: (State \times Args) \rightarrow State' \times Result
</math>

其中：
* <math>State</math> 是当前状态
* <math>Args</math> 是输入参数
* <math>State'</math> 是新状态
* <math>Result</math> 是 action 返回值

== 总结 ==
Pinia Actions 提供了灵活的方式来组织业务逻辑，具有以下优势：
* 统一处理同步/异步操作
* 直接访问和修改状态
* 支持 TypeScript 类型推断
* 可组合和可订阅

通过合理使用 actions，可以使您的状态管理代码更加模块化和可维护。

[[Category:前端框架]]
[[Category:Vue.js]]
[[Category:Pinia状态管理]]