Access Control

For frontend applications, "access control" refers to whether pages are accessible and whether page elements are visible.

Setup

1. Install the plugin

NPM

$ npm add @winner-fed/plugin-access -D

YARN

$ yarn add @winner-fed/plugin-access -D

PNPM

$ pnpm add @winner-fed/plugin-access -D

BUN

$ bun add @winner-fed/plugin-access -D

2. Enable the plugin in the .winrc configuration file

import { defineConfig } from 'win';

export default defineConfig({
  plugins: ['@winner-fed/plugin-access'],
  routes: [{
    path: '/',
    name: 'Home',
    component: 'index',
    routes: [
      {
        path: 'admin',
        name: 'Admin',
        component: '@/components/admin'
      },
      {
        path: 'normal',
        name: 'Normal',
        component: '@/components/normal'
      }
    ]
  }],
  /**
   * @name Access Control Plugin
   * @doc https://winjs-dev.github.io/winjs-docs/plugins/access.html
   */
  access: {
    roles: {
      admin: ['/admin'],
      normal: ['/normal']
    }
  }
});

Introduction

In this plugin design, one page permission corresponds to one route. For example, when accessing the '/admin' route, if the current role doesn't have permission for this route, the component will not be rendered.

export default {
  access: {
    roles: {
      admin: ['/admin'],
      normal: ['/normal']
    }
  }
};

Usage example:

<template>
  <Access :id="accessId">Only visible to Admin</Access>
  <div v-access="accessId">Only visible to Admin</div>
</template>

<script setup lang="ts">
const accessId = '/admin';
</script>

Note

We uniformly refer to pages and page elements as resources, and use resource IDs to identify and distinguish them:

• The resource ID of a page defaults to the page's route path. For example, the route path of page pages/a.vue is /a. When the page accesses /a, the current page will be rendered, and /a is the page's accessId.
• Page elements' resource IDs have no default value and need to be customized. :::

Matching Rules

Exact Matching

The default matching rule for resources is exact matching. For example, if page pages/a.vue corresponds to route path /a, then /a is the page's resource ID. If we set:

access.setAccess(['/a']);

Since the permission list contains /a, it indicates having permission for this page.

Fuzzy Matching

Page @id.vue will be mapped to dynamic route /:id. There are two ways to match this page:

• access.setAccess(['/:id'])
• access.setAccess(['/*'])

The second is fuzzy matching, where * represents any path. For example, if role admin needs full permissions:

export default {
  access: {
    roles: {
      admin: ['*']
    }
  }
};

Compile-time Configuration

When executing win dev or win build, runtime code is generated through this configuration. Configure in the .winrc.js configuration file:

export default {
  access: {
    roles: {
      admin: ['/', '/admin', '/normal'],
    },
  },
};

roles

• Type: Record<string, []>;

• Default: {}

• Details:

  Predefined role list. key is the role ID, and value is the resource list corresponding to the role ID.

Runtime Configuration

Configure in app.js

unAccessHandler

• Type: Function

• Default: null

• Details: When entering a route, if the page corresponding to the route doesn't belong to the visible resource list, entry will be paused and the unAccessHandler function will be called.

• Parameters

  • router: Router instance created by createRouter
  • to: Route being navigated to
  • from: Route being navigated away from
  • next: next function

Example:

import { access as accessApi } from 'winjs';

export const access = {
  unAccessHandler ({ to, next }) {
    const accesssIds = accessApi.getAccess();
    if (to.path === '/404') {
      accessApi.setAccess(accesssIds.concat(['/404']));
      return next('/404');
    }
    if (!accesssIds.includes('/403')) {
      accessApi.setAccess(accesssIds.concat(['/403']));
    }
    next('/403');
  },
};

noFoundHandler

• Type: Function
• Default: null
• Details: When entering a route, if the page corresponding to the route doesn't exist, the noFoundHandler function will be called.
• Parameters
  • router: Router instance created by createRouter
  • to: Route being navigated to
  • from: Route being navigated away from
  • next: next function

Example:

import { access as accessApi } from 'winjs';

export const access = {
  noFoundHandler ({ next }) {
    const accesssIds = accessApi.getAccess();
    if (!accesssIds.includes('/404')) {
      accessApi.setAccess(accesssIds.concat(['/404']));
    }
    next('/404');
  },
};

ignoreAccess

• Type: Array<string>
• Default: null
• Details: Configure pages that should ignore access control validation.

Example:

export const access = {
  ignoreAccess: ['/login'],
};

API

WinJS uses custom directives, specifically the v-access directive, passing in the object returned by useAccess to control component rendering.

Plugin APIs are exported through winjs:

import { access } from 'winjs';

access.hasAccess

• Type: ( accessId: string | number ) => Promise\<boolean\>
• Details: Determine whether a resource is visible.
• Parameters:
  • accessId: Resource ID
• Returns: Whether access is granted

access.isDataReady

• Type: () => boolean
• Details: Permissions can be set using asynchronous data. isDataReady is used to determine whether asynchronous data has finished loading.
• Parameters: null
• Returns: Boolean

import { access } from 'winjs';

console.log(access.isDataReady());

access.setRole

• Type: Function
• Details: Set the current role.
• Parameters:
• roleId: Role ID, has two types:
  • String: Corresponds to the key in the roles configuration object.
  • Promise: The result of Promise resolve should correspond to the key in the roles configuration object.

import { access } from 'winjs';

access.setRole('admin');

access.getRole

• Type: Function
• Details: Get the current role.

import { access } from 'winjs';

access.getRole();

access.setAccess

• Type: Function
• Details: Set the current access permissions.
• Parameters:
• accessIds: Array of resource IDs, has two types:
  • Array: Array items correspond to the key in the roles configuration object.
  • Promise: The result of Promise resolve should be Array<accessId>.

import { access } from 'winjs';

access.setAccess(['/a', '/b', '/c']);

access.getAccess

• Type: Function
• Details: Return the current list of visible resources.
• Parameters: null

import { access } from 'winjs';

access.getAccess();

useAccess

• Type: Composition function
• Details: Determine whether a resource is visible.
• Parameters:
  • accessId: Resource ID
• Returns: ref

<template>
  <div v-if="accessOnepicess">accessOnepicess</div>
</template>
<script>
import { useAccess } from 'winjs';

export default {
  setup () {
    const accessOnepicess = useAccess('/onepiece1');
    return {
      accessOnepicess,
    };
  },
};
</script>

v-access

Pass accessId into the v-access directive. When accessId has permission, the DOM will be displayed; when there's no permission, the DOM will be hidden.

<template>
  <div v-access="accessId">accessOnepicess</div>
</template>
<script>
export default {
  setup () {
    return {
      accessId: 'accessOnepicess',
    };
  },
};
</script>

Access Component

Pass accessId into the Access component. When accessId has permission, this component will be rendered; when there's no permission, this component will be hidden.

<template>
  <access :id="accessId"> accessOnepicess</access>
</template>
<script>
export default {
  setup () {
    return {
      accessId: 'accessOnepicess',
    };
  },
};
</script>