BizRolePermMatrix 角色权限矩阵

角色 × 权限点勾选矩阵：权限点按模块分组为行、角色为列，单元格勾选维护 roleId → 权限点列表（v-model）；模块行整组勾选（半选态）、底部每角色授权数汇总（吸底）、表头吸顶 + 首列吸左双吸附滚动。RBAC 授权编辑页的矩阵区，配一个提交按钮即成页。

基础用法

模块分组行整组勾选（半选态联动），单元格勾选维护 v-model 映射。

<script setup lang="ts">
/** 场景：基础——模块行整组勾选（半选态联动），单元格维护 v-model 授权映射 */
import { ref } from 'vue'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'admin', name: '系统管理员', description: '拥有全部权限，负责账号与配置' },
  { id: 'manager', name: '运营主管', description: '业务数据管理，不含系统配置' },
  { id: 'operator', name: '一线运营', description: '日常业务操作' },
]

const permissions: BizRolePermModule[] = [
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看', description: '查询与查看订单详情' },
      { id: 'order:edit', name: '订单编辑' },
      { id: 'order:export', name: '订单导出' },
      { id: 'order:refund', name: '退款处理', description: '发起并审批退款' },
    ],
  },
  {
    id: 'goods',
    name: '商品管理',
    permissions: [
      { id: 'goods:view', name: '商品查看' },
      { id: 'goods:edit', name: '商品编辑' },
      { id: 'goods:shelf', name: '上下架', description: '控制商品售卖状态' },
    ],
  },
]

const checked = ref<Record<string, string[]>>({
  admin: ['order:view', 'order:edit', 'order:export', 'order:refund', 'goods:view', 'goods:edit', 'goods:shelf'],
  manager: ['order:view', 'order:export', 'goods:view', 'goods:edit'],
  operator: ['order:view'],
})
</script>

<template>
  <div>
    <BizRolePermMatrix v-model="checked" :roles="roles" :permissions="permissions" />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      manager / operator 当前为部分勾选——对应模块行呈半选态
    </p>
  </div>
</template>

事件联动

change 外抛单点 / 整组勾选（整组时 permId 为数组），可做变更留痕。

<script setup lang="ts">
/** 场景：change 事件——单点勾选 permId 为 string，整组勾选为数组，可做变更留痕 */
import { ref } from 'vue'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'admin', name: '管理员' },
  { id: 'operator', name: '运营' },
]

const permissions: BizRolePermModule[] = [
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看' },
      { id: 'order:edit', name: '订单编辑' },
      { id: 'order:export', name: '订单导出' },
    ],
  },
]

const checked = ref<Record<string, string[]>>({ admin: ['order:view'], operator: [] })
const logs = ref<string[]>([])

const onChange = (roleId: string, permId: string | string[], checkedNow: boolean): void => {
  const scope = Array.isArray(permId) ? `${permId.length} 项` : permId
  logs.value.unshift(`${roleId} ${checkedNow ? '授权' : '取消'} ${scope}`)
  if (logs.value.length > 6) logs.value.pop()
}
</script>

<template>
  <div>
    <BizRolePermMatrix v-model="checked" :roles="roles" :permissions="permissions" @change="onChange" />
    <p v-for="(log, i) in logs" :key="i" style="margin: 6px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      {{ log }}
    </p>
  </div>
</template>

汇总与吸附滚动

多模块多角色：表头吸顶、首列吸左、汇总吸底，maxHeight 控制可视高度。

<script setup lang="ts">
/** 场景：多模块多角色——表头吸顶、首列吸左、汇总吸底（maxHeight 控制可视高度） */
import { ref } from 'vue'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'r1', name: '超级管理员' },
  { id: 'r2', name: '运营主管' },
  { id: 'r3', name: '一线运营' },
  { id: 'r4', name: '财务管理' },
  { id: 'r5', name: '只读审计' },
  { id: 'r6', name: '外部合作' },
]

const permNames = ['查看', '新增', '编辑', '删除', '导入', '导出', '审核', '停用']

const permissions: BizRolePermModule[] = ['订单中心', '商品中心', '会员中心', '营销中心', '数据中心'].map(
  (moduleName, moduleIndex) => ({
    id: `m${moduleIndex}`,
    name: moduleName,
    permissions: permNames.map((action, actionIndex) => ({
      id: `m${moduleIndex}:${actionIndex}`,
      name: `${moduleName}${action}`,
      description: `${moduleName} - ${action}权限点`,
    })),
  }),
)

const checked = ref<Record<string, string[]>>({
  r1: permissions.flatMap((m) => m.permissions.map((p) => p.id)),
  r5: permissions.map((m) => m.permissions[0].id),
})
</script>

<template>
  <div>
    <BizRolePermMatrix
      v-model="checked"
      :roles="roles"
      :permissions="permissions"
      :max-height="300"
      :show-summary="true"
    />
    <p style="margin: 10px 0 0; font-size: 12px; color: var(--el-text-color-secondary)">
      纵向滚动表头吸附、横向滚动首列吸附；底部汇总行随滚动保持可见
    </p>
  </div>
</template>

程序化操作

expose：单角色全选 / 清空、单权限点全员设置、清空全部、取值。

<script setup lang="ts">
/** 场景：expose 程序化操作——单角色全选/清空、单权限全员设置、清空全部、取值 */
import { ref } from 'vue'
import { ElButton } from 'element-plus'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermMatrixInstance, BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'admin', name: '管理员' },
  { id: 'operator', name: '运营' },
]

const permissions: BizRolePermModule[] = [
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看' },
      { id: 'order:edit', name: '订单编辑' },
      { id: 'order:export', name: '订单导出' },
    ],
  },
  {
    id: 'goods',
    name: '商品管理',
    permissions: [
      { id: 'goods:view', name: '商品查看' },
      { id: 'goods:edit', name: '商品编辑' },
    ],
  },
]

const checked = ref<Record<string, string[]>>({ admin: ['order:view'], operator: [] })
const matrixRef = ref<BizRolePermMatrixInstance | null>(null)
</script>

<template>
  <div>
    <BizRolePermMatrix ref="matrixRef" v-model="checked" :roles="roles" :permissions="permissions" />
    <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-top: 10px">
      <ElButton size="small" @click="matrixRef?.setRoleAll('operator', true)">运营全选</ElButton>
      <ElButton size="small" @click="matrixRef?.setRoleAll('admin', false)">管理员清空</ElButton>
      <ElButton size="small" @click="matrixRef?.togglePermAll('order:export', true)">「订单导出」全员开通</ElButton>
      <ElButton size="small" type="danger" plain @click="matrixRef?.clearAll()">清空全部</ElButton>
      <ElButton size="small" @click="console.log(matrixRef?.getCheckedMap())">打印授权结果</ElButton>
    </div>
  </div>
</template>

禁用

disabled 整矩阵只读（查看场景）。

<script setup lang="ts">
/** 场景：disabled 整矩阵只读——权限查看场景 */
import { ref } from 'vue'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'admin', name: '系统管理员' },
  { id: 'operator', name: '一线运营' },
]

const permissions: BizRolePermModule[] = [
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看' },
      { id: 'order:edit', name: '订单编辑' },
    ],
  },
]

const checked = ref<Record<string, string[]>>({
  admin: ['order:view', 'order:edit'],
  operator: ['order:view'],
})
</script>

<template>
  <BizRolePermMatrix v-model="checked" :roles="roles" :permissions="permissions" disabled />
</template>

自定义单元格

role / module / perm 插槽接管对应单元格内容（图标、说明等）。

<script setup lang="ts">
/** 场景：role / module / perm 插槽接管单元格——图标与辅助说明自由扩展 */
import { ref } from 'vue'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'admin', name: '系统管理员' },
  { id: 'operator', name: '一线运营' },
]

const permissions: BizRolePermModule[] = [
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看' },
      { id: 'order:refund', name: '退款处理' },
    ],
  },
]

const checked = ref<Record<string, string[]>>({ admin: ['order:view', 'order:refund'], operator: [] })
</script>

<template>
  <BizRolePermMatrix v-model="checked" :roles="roles" :permissions="permissions">
    <template #role="{ role }">
      {{ role.name }}
      <span class="demo-rpm-badge">{{ role.id === 'admin' ? '内置' : '自定义' }}</span>
    </template>
    <template #module="{ module }">
      <span class="demo-rpm-module">◈ {{ module.name }}</span>
    </template>
    <template #perm="{ perm }">
      {{ perm.name }}
      <span v-if="perm.id === 'order:refund'" class="demo-rpm-danger">高危</span>
    </template>
  </BizRolePermMatrix>
</template>

<style scoped>
.demo-rpm-badge {
  margin-left: 4px;
  padding: 0 5px;
  border-radius: var(--el-border-radius-base);
  background-color: var(--el-fill-color);
  color: var(--el-text-color-secondary);
  font-size: 11px;
  font-weight: 400;
}

.demo-rpm-module {
  color: var(--el-color-primary);
}

.demo-rpm-danger {
  margin-left: 4px;
  color: var(--el-color-danger);
  font-size: 11px;
}
</style>

变更留痕

业务层持有初始快照与 v-model 逐角色 diff，提交前展示新增 / 移除明细。

<script setup lang="ts">
/** 场景：变更留痕——与初始授权对比，实时统计已改动角色数与增减明细 */
import { computed, ref } from 'vue'
import { ElTag } from 'element-plus'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles: BizRolePermRole[] = [
  { id: 'manager', name: '运营主管' },
  { id: 'operator', name: '一线运营' },
]

const permissions: BizRolePermModule[] = [
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看' },
      { id: 'order:edit', name: '订单编辑' },
      { id: 'order:export', name: '订单导出' },
    ],
  },
]

const initial: Record<string, string[]> = {
  manager: ['order:view', 'order:export'],
  operator: ['order:view'],
}

const checked = ref<Record<string, string[]>>({
  manager: [...initial.manager],
  operator: [...initial.operator],
})

/** 与初始快照逐角色对比：新增 / 移除 明细 */
const diff = computed(() => {
  const rows: Array<{ role: string; added: string[]; removed: string[] }> = []
  for (const role of roles) {
    const before = new Set(initial[role.id] ?? [])
    const after = new Set(checked.value[role.id] ?? [])
    const added = [...after].filter((id) => !before.has(id))
    const removed = [...before].filter((id) => !after.has(id))
    if (added.length > 0 || removed.length > 0) rows.push({ role: role.name, added, removed })
  }
  return rows
})
</script>

<template>
  <div>
    <BizRolePermMatrix v-model="checked" :roles="roles" :permissions="permissions" :show-summary="false" />
    <p style="margin: 10px 0 4px; font-size: 12px; color: var(--el-text-color-secondary)">
      变更留痕（业务层持有初始快照自行 diff，提交前确认）：
    </p>
    <p v-if="diff.length === 0" style="margin: 0; font-size: 12px; color: var(--el-color-success)">
      与初始授权一致，无改动
    </p>
    <p v-for="(row, i) in diff" :key="i" style="margin: 4px 0 0; font-size: 12px">
      <b>{{ row.role }}</b>
      <ElTag v-for="a in row.added" :key="a" size="small" type="success" style="margin-left: 6px">+ {{ a }}</ElTag>
      <ElTag v-for="r in row.removed" :key="r" size="small" type="danger" style="margin-left: 6px">- {{ r }}</ElTag>
    </p>
  </div>
</template>

空数据占位

权限 / 角色

订单管理

订单查看

订单编辑

暂无角色

已授权 / 总数

无角色 / 无权限配置时给出对应占位提示。

<script setup lang="ts">
/** 场景：空数据占位——无角色 / 无权限配置两种占位态切换 */
import { ref } from 'vue'
import { ElButton } from 'element-plus'
import { BizRolePermMatrix } from 'vue3-ep-biz-lib'
import type { BizRolePermModule, BizRolePermRole } from 'vue3-ep-biz-lib'

const roles = ref<BizRolePermRole[]>([])
const permissions = ref<BizRolePermModule[]>([
  {
    id: 'order',
    name: '订单管理',
    permissions: [
      { id: 'order:view', name: '订单查看' },
      { id: 'order:edit', name: '订单编辑' },
    ],
  },
])

/** 注入角色后即可正常勾选（v-model 受控回写） */
const modelValue = ref<Record<string, string[]>>({})
</script>

<template>
  <div>
    <div style="margin-bottom: 10px; display: flex; gap: 8px">
      <ElButton size="small" @click="roles = [{ id: 'admin', name: '管理员' }]">注入角色</ElButton>
      <ElButton size="small" @click="permissions = []">清空权限配置</ElButton>
    </div>
    <BizRolePermMatrix v-model="modelValue" :roles="roles" :permissions="permissions" />
  </div>
</template>

Props

属性名	类型	默认值	说明
v-model	`Record<string, string[]>`	`{}`	授权结果：roleId → 已授权权限点 id 列表
roles	`BizRolePermRole[]`	`[]`	角色列表（矩阵列，id / name / description）
permissions	`BizRolePermModule[]`	`[]`	权限模块列表（矩阵行，按模块分组）
disabled	`boolean`	`false`	整体只读
show-summary	`boolean`	`true`	底部每角色授权数汇总行（吸底）
max-height	`number \| string`	`420`	表体最大高度（超出滚动）

Events

事件名	参数	说明
update:modelValue	`(value: Record<string, string[]>)`	授权结果变化
change	`(roleId, permId, checked)`	勾选变化；单点 permId 为 string，整组 / 全员为 string[]（全员 roleId 为 `'*'`）

Slots

插槽名	作用域	说明
role	`{ role }`	列头角色名单元格
module	`{ module }`	模块分组行名单元格
perm	`{ module, perm }`	权限点行名单元格

Expose

名称	类型	说明
getCheckedMap	`() => Record<string, string[]>`	取授权结果（深拷贝）
setRoleAll	`(roleId, checked) => void`	单角色全选 / 清空
togglePermAll	`(permId, checked) => void`	单权限点对所有角色统一设置
clearAll	`() => void`	清空全部授权

TIP

权限点 id 需跨模块唯一；授权结果是纯数据映射，提交与 diff（与初始值对比）由业务层完成——配合 BizDiffViewer 可做变更预览。

BizRolePermMatrix 角色权限矩阵 ​

基础用法 ​

事件联动 ​

汇总与吸附滚动 ​

程序化操作 ​

禁用 ​

自定义单元格 ​

变更留痕 ​

空数据占位 ​

Props ​

Events ​

Slots ​

Expose ​