@composy/permission-vue

@composy/permission-vue

@composy/permission-vue 是 @composy/permission-core 的 Vue 3 适配层，统一提供：

• 原生 Vue Plugin 用法
• @composy/engine-core plugin 用法
• usePermission / useRole
• v-permission / v-role
• PermissionGuard / RoleGuard

设计原则

• 权限算法、角色继承、策略评估、缓存和错误上报全部来自 @composy/permission-core。
• Vue 层只维护响应式桥接、生命周期清理、指令 DOM 行为、Guard 渲染和路由守卫。
• 权限和角色输入会复用 core 的 normalizePermissionList / normalizeRoleList，保证与非 Vue 场景一致。
• PermissionManager.subscribe() 是 Vue 响应式状态更新的唯一来源，避免在组件层重复实现缓存或权限判断。

安装

pnpm add @composy/permission-core @composy/permission-vue

原生 Vue Plugin

import { createPermissionPlugin } from '@composy/permission-vue'
import { createApp } from 'vue'

const app = createApp(App)

app.use(
  createPermissionPlugin({
    superRole: 'admin',
    onError(error) {
      console.warn(error.phase, error.event)
    },
    permissionProvider: () => authStore.permissions,
    roleProvider: () => authStore.roles,
    roles: [
      { id: 'admin', name: '管理员', permissions: ['*'], isSuper: true },
      { id: 'editor', name: '编辑者', permissions: ['article:write'], parent: 'user' },
    ],
  })
)

Engine Plugin

import { createPermissionEnginePlugin } from '@composy/permission-vue'

const permissionPlugin = createPermissionEnginePlugin({
  permissionProvider: () => authStore.permissions,
  roleProvider: () => authStore.roles,
  installVuePlugin: true,
})

console.info(permissionPlugin.name)

Composables

import { usePermission, useRole } from '@composy/permission-vue'

const { permissions, can, refresh } = usePermission()
const { roles, is } = useRole()

const canEditArticle = can(['article:read', 'article:write'])
const isAdmin = is('admin')

console.info(permissions.value, roles.value, canEditArticle.value, isAdmin.value, refresh)

Directives

<template>
  <button v-permission="'user:create'">
    创建用户
  </button>
  <button v-permission.disable="'user:delete'">
    删除用户
  </button>
  <div v-role.any="['admin', 'manager']">
    管理区
  </div>
</template>

Guard 组件

<template>
  <PermissionGuard :permissions="['user:create']">
    <button>创建用户</button>

    <template #fallback>
      <span>无权限</span>
    </template>
  </PermissionGuard>

  <RoleGuard :roles="['admin', 'manager']" mode="any">
    <AdminPanel />
  </RoleGuard>
</template>

主要导出

• createPermissionPlugin
• createPermissionEnginePlugin
• usePermission
• useRole
• createPermissionDirective
• createRoleDirective
• PermissionGuard
• RoleGuard

Core refresh lifecycle

Vue adapters consume the core manager snapshot. Provider replacement and manager disposal are generation guarded in core, so late asynchronous refresh results cannot overwrite the state observed by Vue.

Build configuration

This adapter uses @composy/builder with Rolldown and depends on @composy/permission-core. Its authoritative TypeScript and ESLint configs are in .ldesign/; package-root config files are compatibility shims.