业务组件权限接入指南¶

📄 创建: 未记录

https://doc.xpku.com/raw/tech/frontend/permission/guide.md

概述¶

本指南用于帮助业务组件使用 @bams-app/permission 权限管理包，实现按钮、功能级别的权限控制。业务组件可以直接使用，无需额外安装或配置。

三种权限控制方式¶

方式一：指令方式（推荐）¶

使用 v-permission 指令直接控制元素的显示与隐藏：

<!-- 单个权限码 -->
<el-button v-permission="'meter:export'">导出</el-button>

<!-- 多个权限码（满足其中一个即可） -->
<el-button v-permission="['meter:export', 'meter:delete']">操作</el-button>

方式二：组件方式¶

使用 <AuthPermission /> 组件包裹需要权限控制的内容：

<AuthPermission code="meter:delete">
  <el-button>删除</el-button>
</AuthPermission>

<!-- 多个权限码 -->
<AuthPermission :code="['meter:delete', 'meter:edit']">
  <el-button>编辑</el-button>
</AuthPermission>

方式三：JS 函数判断¶

在逻辑代码中使用 hasPerm 函数进行判断：

import { hasPerm } from "@bams-app/permission";

if (hasPerm("meter:config")) {
  // 执行有权限时的逻辑
  console.log("用户拥有配置权限");
}

权限数据结构¶

权限数据来源于 @bams-app/store：

// userStore 中的权限数据结构
{
  permissionMap: {
    "/meter/list": ["meter:view", "meter:export", "meter:delete"],
    "/meter/config": ["meter:config", "meter:edit"]
  },
  role: "user" // 或 "admin"（超级管理员，拥有所有权限）
}

// menuStore 中的当前菜单路径
{
  selectedMenu: {
    path: "/meter/list"
  }
}

API 说明¶

AuthPermission Props¶

参数	说明	类型	默认值
code	权限码或权限码数组	`string \\| string[]`	-

hasPerm Function¶

/**
 * @param {string | string[]} value - 权限码或权限码数组
 * @returns {boolean} - 是否拥有权限
 */
function hasPerm(value): boolean

权限码层级说明¶

权限码支持多级嵌套结构，采用冒号（:）分隔，格式为 模块：子模块：操作，支持通配符（*）匹配。

层级规则¶

模块级授权：meter - 匹配 meter 模块下的所有权限
操作级授权：meter:export - 可匹配 meter:export，也可兼容更细粒度权限如 meter:list:export
细粒度权限：meter:list:export - 表示 meter 模块下 list 场景的 export 操作
通配符授权：meter:*、system:user:* - 匹配对应前缀下的所有权限

权限匹配逻辑¶

权限判断支持以下几类规则：

精确匹配：meter:export 命中 meter:export
模块级匹配：meter 可匹配 meter:view、meter:list:export
向上兼容：meter:export 可匹配 meter:list:export
通配符匹配：meter:*、system:user:* 可匹配对应前缀下所有权限

示例¶

// permissionMap 配置示例
{
  "/meter/list": [
    "meter:view",
    "meter:export",
    "meter:delete"
  ],
  "/system/user": [
    "system:user:*",       // 匹配 system:user 下所有操作
    "system:role:view"     // 仅匹配 system:role:view
  ]
}

// hasPerm 判断示例
hasPerm("meter:view")           // true - 精确匹配
hasPerm("meter:list:view")      // true - 向上兼容匹配到 meter:view
hasPerm("meter:list:export")    // true - 可被 meter 或 meter:export 命中
hasPerm("system:user:add")      // true - 通配符匹配 system:user:*
hasPerm("system:user:delete")   // true - 通配符匹配 system:user:*
hasPerm("system:role:edit")     // false - 仅配置了 system:role:view

注意事项¶

权限码格式建议采用 模块：操作 或 模块：子模块：操作 的形式
多个权限码使用 Or 逻辑，只要满足其中一个即可
如果传入空值或空数组，默认返回 true（不进行权限控制）
超级管理员（role === 'admin'）默认拥有所有权限
使用指令方式时，没有权限的元素会被直接从 DOM 中移除
通配符 * 仅支持在最后一个层级使用，如 meter:*

示例代码¶

完整示例：

<template>
  <div>
    <!-- 指令方式 -->
    <el-button v-permission="'meter:view'">查看</el-button>
    <el-button v-permission="'meter:export'">导出</el-button>
    <el-button v-permission="'meter:delete'">删除</el-button>

    <!-- 组件方式 -->
    <AuthPermission code="meter:config">
      <el-button type="primary">配置</el-button>
    </AuthPermission>
  </div>
</template>

<script setup>
  import { hasPerm } from "@bams-app/permission";

  const handleClick = () => {
    if (hasPerm("meter:edit")) {
      // 执行编辑操作
    }
  };
</script>