### Clone Repository and Start Development Server (Bash)

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/README.md

This snippet demonstrates how to clone the vue-vben-admin-doc repository using Git, install project dependencies with pnpm, and start the local development server. Ensure you have Git and pnpm installed on your system.

```bash
# 克隆本仓库
$ git clone git@github.com:vbenjs/vue-vben-admin-doc.git

# 或者使用 yarn
$ pnpm install

# 启动开发服务器
$ pnpm dev
```

--------------------------------

### Install Project Dependencies with pnpm

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

This command installs all the necessary project dependencies using pnpm. It should be executed in the root directory of the cloned project. This process might take some time, and patience is recommended. If husky installation fails, it might be due to the absence of a .git folder, which can be resolved by initializing a git repository.

```bash
# Install dependencies
pnpm i
```

--------------------------------

### Install pnpm Globally

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

This command installs pnpm (Performant npm) globally on your system using npm. pnpm is the recommended package manager for this project. If you encounter issues with other package managers, using pnpm is advised. After installation, verify it by checking the version.

```bash
# Install pnpm globally
npm install -g pnpm
# Verify pnpm installation
pnpm -v
```

--------------------------------

### Verify Node.js and npm Installation

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

These commands verify that Node.js and npm (Node Package Manager) are installed and display their respective versions. This is a crucial step to ensure your environment meets the project's requirements. Node.js version 14.x or higher is recommended, with 20.x or above being preferred.

```bash
# Verify npm version
npm -v
# Verify Node.js version
node -v
```

--------------------------------

### Reinstall Project Dependencies

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

This command is used to perform a clean reinstallation of project dependencies. It first removes the `node_modules` directory, `pnpm-lock.yaml`, and `package-lock.json` files, and then proceeds to install dependencies using the `bootstrap` script (which typically runs `pnpm install`). This process can significantly increase installation time but helps resolve dependency-related issues.

```bash
rimraf pnpm-lock.yaml && rimraf package.lock.json && rimraf node_modules && npm run bootstrap
```

--------------------------------

### Clone Vue-vben-admin from GitHub

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

This command clones the Vue-vben-admin project from its official GitHub repository. Ensure you have Git installed on your system. The directory and its parent directories should not contain non-ASCII characters or spaces to avoid potential issues during dependency installation and project startup.

```bash
git clone https://github.com/vbenjs/vue-vben-admin.git
```

--------------------------------

### Setup and Dynamic Locale Loading

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/dep/i18n.md

Logic for initializing the i18n instance during application startup and handling asynchronous language loading for switching locales.

```typescript
export async function setupI18n(app: App) {
  const options = await createI18nOptions();
  i18n = createI18n(options) as I18n;
  app.use(i18n);
}

async function changeLocale(locale: LocaleType) {
  const globalI18n = i18n.global;
  const langModule = ((await import(`./lang/${locale}.ts`)) as any).default as LangModule;
  const { message, momentLocale, momentLocaleName } = langModule;
  globalI18n.setLocaleMessage(locale, message);
  moment.updateLocale(momentLocaleName, momentLocale);
  setI18nLanguage(locale);
}
```

--------------------------------

### Vue Loading Component Usage Example

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/loading.md

Demonstrates how to use the Loading component within a Vue.js application. It shows how to control the loading state, tip text, and positioning (full screen or container-specific). This example requires the Vue and Vben components to be set up.

```vue
<template>
  <div class="p-5" ref="wrapEl" v-loading="loadingRef" loading-tip="加载中...">
    <a-button class="my-4 mr-4" type="primary" @click="openCompFullLoading">全屏 Loading</a-button>
    <a-button class="my-4" type="primary" @click="openCompAbsolute">容器内 Loading</a-button>
    <Loading :loading="loading" :absolute="absolute" :tip="tip" />
  </div>
</template>
<script lang="ts">
  import { defineComponent, reactive, toRefs, ref } from 'vue';
  import { Loading } from '/@/components/Loading';
  export default defineComponent({
    components: { Loading },
    setup() {
      const compState = reactive({
        absolute: false,
        loading: false,
        tip: '加载中...',
      });

      function openLoading(absolute: boolean) {
        compState.absolute = absolute;
        compState.loading = true;
        setTimeout(() => {
          compState.loading = false;
        }, 2000);
      }

      function openCompFullLoading() {
        openLoading(false);
      }

      function openCompAbsolute() {
        openLoading(true);
      }

      return {
        openCompFullLoading,
        openCompAbsolute,
        ...toRefs(compState),
      };
    },
  });
</script>
```

--------------------------------

### Vue Button Usage Example

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/glob/button.md

Demonstrates how to use the globally registered `a-button` component in a Vue template. It shows examples of creating buttons with different color themes like success, error, and warning.

```vue
<template>
  <a-button color="success">成功按钮</a-button>
  <a-button color="error">错误按钮</a-button>
  <a-button color="warning">警告按钮</a-button>
</template>
```

--------------------------------

### Clone Vue-vben-admin from Gitee

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

This command clones the Vue-vben-admin project from a Gitee mirror. This can be a faster alternative if cloning from GitHub is slow. Note that the Gitee version might not always be the latest. Similar to the GitHub clone, ensure the target directory and its parents are free of non-ASCII characters and spaces.

```bash
git clone https://gitee.com/annsion/vue-vben-admin.git
```

--------------------------------

### Vue-vben-admin npm Scripts

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/index.md

This JSON object defines various npm scripts for managing the Vue-vben-admin project. These scripts cover tasks such as installing dependencies, building the project for different environments (production, analyze, docker, test), linting code with ESLint, Prettier, and Stylelint, preparing git hooks, previewing builds, and reinstalling dependencies.

```json
{
  "scripts": {
    "bootstrap": "pnpm install",
    "build": "cross-env NODE_ENV=production NODE_OPTIONS=--max-old-space-size=8192 pnpm vite build",
    "build:analyze": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpm vite build --mode analyze",
    "build:docker": "vite build --mode docker",
    "build:no-cache": "pnpm clean:cache && npm run build",
    "build:test": "cross-env NODE_OPTIONS=--max-old-space-size=8192 pnpm vite build --mode test",
    "commit": "czg",
    "dev": "pnpm vite",
    "preinstall": "npx only-allow pnpm",
    "postinstall": "turbo run stub",
    "lint": "turbo run lint",
    "lint:eslint": "eslint --cache --max-warnings 0  \"{src,mock}/**/*.{vue,ts,tsx}\" --fix",
    "lint:prettier": "prettier --write .",
    "lint:stylelint": "stylelint \"**/*.{vue,css,less,scss}\" --fix --cache --cache-location node_modules/.cache/stylelint/",
    "prepare": "husky install",
    "preview": "npm run build && vite preview",
    "reinstall": "rimraf pnpm-lock.yaml && rimraf package.lock.json && rimraf node_modules && npm run bootstrap",
    "serve": "npm run dev",
    "test:gzip": "npx http-server dist --cors --gzip -c-1",
    "type:check": "vue-tsc --noEmit --skipLibCheck"
  }
}
```

--------------------------------

### Create Production Mock Server Setup

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/mock.md

Implement a production mock server by importing mock modules and registering them with createProdMockServer. This script dynamically loads mock files to be used in the production build.

```typescript
import { createProdMockServer } from 'vite-plugin-mock/es/createProdMockServer';

const modules = import.meta.globEager('./**/*.ts');

const mockModules: any[] = [];
Object.keys(modules).forEach((key) => {
  if (key.includes('/_')) {
    return;
  }
  mockModules.push(...modules[key].default);
});

export function setupProdMockServer() {
  createProdMockServer(mockModules);
}
```

--------------------------------

### Install ant-design-vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/lib.md

This command installs the ant-design-vue library using Yarn. Ensure you have Yarn installed and are in your project's root directory.

```bash
yarn add ant-design-vue
```

--------------------------------

### 依赖安装失败时的本地缓存清理与重装命令

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/other/faq.md

当遇到依赖安装失败或启动报错时，可以尝试删除`yarn.lock`文件和`node_modules`目录，然后重新运行`yarn install`命令来解决。这有助于清除可能损坏的依赖缓存。

```bash
rm -rf yarn.lock node_modules
yarn install
```

--------------------------------

### On-demand Component Registration in Vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/introduction.md

Demonstrates the recommended pattern for importing and registering components locally within a Vue application. This approach avoids global registration, utilizing the ConfigProvider from ant-design-vue as an example.

```vue
<template>
  <ConfigProvider>
    <router-view />
  </ConfigProvider>
</template>

<script lang="ts">
  import { defineComponent } from 'vue';
  import { ConfigProvider } from 'ant-design-vue';
  export default defineComponent({
    name: 'App',
    components: { ConfigProvider },
  });
</script>
```

--------------------------------

### Implement Dynamic Transition Effects in Vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/transition.md

This example demonstrates how to import and utilize various transition components such as Fade, Scale, and Slide. It uses a dynamic component binding to switch between different transition wrappers based on user selection.

```vue
<template>
  <div class="p-4">
    <div class="flex">
      <Select
        :options="options"
        v-model:value="value"
        placeholder="选择动画"
        :style="{ width: '150px' }"
      />
      <a-button type="primary" class="ml-4" @click="start"> start </a-button>
    </div>
    <component :is="`${value}Transition`">
      <div class="box" v-show="show"></div>
    </component>
  </div>
</template>
<script lang="ts">
  import { defineComponent, ref } from 'vue';
  import { Select } from 'ant-design-vue';
  import {
    FadeTransition,
    ScaleTransition,
    SlideYTransition,
    ScrollYTransition,
    SlideYReverseTransition,
    ScrollYReverseTransition,
    SlideXTransition,
    ScrollXTransition,
    SlideXReverseTransition,
    ScrollXReverseTransition,
    ScaleRotateTransition,
    ExpandXTransition,
    ExpandTransition,
  } from '/@/components/Transition/index';

  const transitionList = [
    'Fade',
    'Scale',
    'SlideY',
    'ScrollY',
    'SlideYReverse',
    'ScrollYReverse',
    'SlideX',
    'ScrollX',
    'SlideXReverse',
    'ScrollXReverse',
    'ScaleRotate',
    'ExpandX',
    'Expand',
  ];
  const options = transitionList.map((item) => ({
    label: item,
    value: item,
    key: item,
  }));

  export default defineComponent({
    components: {
      Select,
      FadeTransition,
      ScaleTransition,
      SlideYTransition,
      ScrollYTransition,
      SlideYReverseTransition,
      ScrollYReverseTransition,
      SlideXTransition,
      ScrollXTransition,
      SlideXReverseTransition,
      ScrollXReverseTransition,
      ScaleRotateTransition,
      ExpandXTransition,
      ExpandTransition,
    },
    setup() {
      const value = ref('Fade');
      const show = ref(true);
      function start() {
        show.value = false;
        setTimeout(() => {
          show.value = true;
        }, 300);
      }
      return { options, value, start, show };
    },
  });
</script>
<style lang="less" scoped>
  .box {
    width: 150px;
    height: 150px;
    margin-top: 20px;
    background: pink;
  }
</style>
```

--------------------------------

### Implement Global Setting Hook

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/settings.md

Example of a hook function used to retrieve and return global configuration values within the application.

```javascript
const { 
  VITE_GLOB_APP_TITLE, 
  VITE_GLOB_API_URL, 
  VITE_GLOB_APP_SHORT_NAME, 
  VITE_GLOB_API_URL_PREFIX, 
  VITE_GLOB_UPLOAD_URL, 
} = ENV;

export const useGlobSetting = (): SettingWrap => {
  const glob: Readonly<GlobConfig> = {
    title: VITE_GLOB_APP_TITLE,
    apiUrl: VITE_GLOB_API_URL,
    shortName: VITE_GLOB_APP_SHORT_NAME,
    urlPrefix: VITE_GLOB_API_URL_PREFIX,
    uploadUrl: VITE_GLOB_UPLOAD_URL
  };
  return glob as Readonly<GlobConfig>;
};
```

--------------------------------

### Implement Permission Management

Source: https://context7.com/doukemao/vue-vben-admin-doc/llms.txt

Provides examples for role-based access control, including route-level restrictions, functional hooks, component wrappers, and custom directives.

```typescript
import { usePermission } from '/@/hooks/web/usePermission';

export default defineComponent({
  setup() {
    const { hasPermission, changeRole } = usePermission();
    const canView = hasPermission([RoleEnum.SUPER, RoleEnum.TEST]);
    return { canView };
  }
});
```

```html
<template>
  <Authority :value="[RoleEnum.SUPER]">
    <a-button type="primary">仅Super可见的按钮</a-button>
  </Authority>
  <a-button v-auth="RoleEnum.SUPER">Super权限可见</a-button>
</template>
```

--------------------------------

### Transformed Menu Structure Example (TypeScript)

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/menu.md

Illustrates the resulting menu structure after processing a menu module. This shows how the `path` for child routes is automatically prefixed with the parent's path, and how the structure is represented as an array of route objects.

```typescript
[
  {
    path: '/dashboard',
    name: t('routes.dashboard.dashboard'),
    children: [
      {
        path: 'dashboard/analysis',
        name: t('routes.dashboard.analysis'),
      },
      {
        path: 'dashboard/workbench',
        name: t('routes.dashboard.workbench'),
      },
    ],
  },
]
```

--------------------------------

### Implement BasicDrawer with useDrawer and useDrawerInner Hooks (Vue)

Source: https://context7.com/doukemao/vue-vben-admin-doc/llms.txt

Illustrates the implementation of a custom drawer component 'BasicDrawer' by wrapping Ant Design Vue's Drawer. It supports features like drag and adaptive height. The example showcases the usage of `useDrawer` and `useDrawerInner` hooks for managing drawer state and data, including displaying detailed information.

```vue
<template>
  <BasicDrawer
    v-bind="$attrs"
    @register="registerDrawer"
    title="详情信息"
    width="600px"
    showFooter
    @ok="handleSubmit"
  >
    <Description :data="detailData" :schema="descSchema" :column="2" />
  </BasicDrawer>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import { BasicDrawer, useDrawerInner } from '/@/components/Drawer';
import { Description } from '/@/components/Description';

const descSchema = [
  { field: 'name', label: '姓名' },
  { field: 'age', label: '年龄' },
  { field: 'address', label: '地址', span: 2 },
  { field: 'createTime', label: '创建时间' },
];

export default defineComponent({
  components: { BasicDrawer, Description },
  setup() {
    const detailData = ref({});

    const [registerDrawer, { setDrawerProps, closeDrawer }] = useDrawerInner((data) => {
      detailData.value = data.record || {};
    });

    function handleSubmit() {
      closeDrawer();
    }

    return { registerDrawer, detailData, descSchema, handleSubmit };
  },
});
</script>

```

```vue
<template>
  <div>
    <a-button @click="handleOpenDrawer">查看详情</a-button>
    <DetailDrawer @register="registerDrawer" />
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { useDrawer } from '/@/components/Drawer';
import DetailDrawer from './Drawer.vue';

export default defineComponent({
  components: { DetailDrawer },
  setup() {
    const [registerDrawer, { openDrawer }] = useDrawer();

    function handleOpenDrawer() {
      openDrawer(true, {
        record: { name: '张三', age: 25, address: '北京市朝阳区', createTime: '2024-01-01' },
      });
    }

    return { registerDrawer, handleOpenDrawer };
  },
});
</script>

```

--------------------------------

### Basic Table Usage in Vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/table.md

Demonstrates the basic integration of the BasicTable component in a Vue template. It shows how to configure columns, data, and toolbar actions. This example requires the BasicTable component and helper functions for columns and data.

```vue
<template>
  <div class="p-4">
    <BasicTable
      title="基础示例"
      titleHelpMessage="温馨提醒"
      :columns="columns"
      :dataSource="data"
      :canResize="canResize"
      :loading="loading"
      :striped="striped"
      :bordered="border"
      :pagination="{ pageSize: 20 }"
    >
      <template #toolbar>
        <a-button type="primary"> 操作按钮 </a-button>
      </template>
    </BasicTable>
  </div>
</template>
<script lang="ts">
  import { defineComponent, ref } from 'vue';
  import { BasicTable } from '/@/components/Table';
  import { getBasicColumns, getBasicData } from './tableData';

  export default defineComponent({
    components: { BasicTable },
    setup() {
      return {
        columns: getBasicColumns(),
        data: getBasicData(),
      };
    },
  });
</script>
```

--------------------------------

### Implement BasicModal with useModal and useModalInner Hooks (Vue)

Source: https://context7.com/doukemao/vue-vben-admin-doc/llms.txt

Demonstrates the implementation of a custom modal component 'BasicModal' by encapsulating Ant Design Vue's Modal. It extends functionality with drag, fullscreen, and adaptive height features. The example shows how to use the `useModal` and `useModalInner` hooks for managing modal state and data flow, including form integration and submission handling.

```vue
<template>
  <BasicModal
    v-bind="$attrs"
    @register="registerModal"
    title="用户编辑"
    :helpMessage="['提示1: 必填项请完整填写', '提示2: 保存后立即生效']"
    :minHeight="200"
    @ok="handleSubmit"
  >
    <BasicForm @register="registerForm" />
  </BasicModal>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { BasicModal, useModalInner } from '/@/components/Modal';
import { BasicForm, useForm } from '/@/components/Form';
import { useMessage } from '/@/hooks/web/useMessage';

const formSchemas = [
  { field: 'id', component: 'Input', label: 'ID', show: false },
  { field: 'name', component: 'Input', label: '姓名', required: true },
  { field: 'email', component: 'Input', label: '邮箱', required: true },
];

export default defineComponent({
  components: { BasicModal, BasicForm },
  emits: ['success'],
  setup(_, { emit }) {
    const { createMessage } = useMessage();

    const [registerForm, { setFieldsValue, resetFields, validate }] = useForm({
      labelWidth: 80,
      schemas: formSchemas,
      showActionButtonGroup: false,
    });

    const [registerModal, { setModalProps, closeModal }] = useModalInner(async (data) => {
      // 接收外部传入的数据
      resetFields();
      if (data?.record) {
        setFieldsValue(data.record);
      }
    });

    async function handleSubmit() {
      try {
        const values = await validate();
        setModalProps({ confirmLoading: true });

        // 模拟API请求
        await new Promise((resolve) => setTimeout(resolve, 1000));

        createMessage.success('保存成功');
        closeModal();
        emit('success');
      } catch (error) {
        console.error(error);
      } finally {
        setModalProps({ confirmLoading: false });
      }
    }

    return { registerModal, registerForm, handleSubmit };
  },
});
</script>

```

```vue
<template>
  <div>
    <a-button type="primary" @click="handleOpen">打开弹窗</a-button>
    <UserModal @register="registerModal" @success="handleSuccess" />
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { useModal } from '/@/components/Modal';
import UserModal from './Modal.vue';

export default defineComponent({
  components: { UserModal },
  setup() {
    const [registerModal, { openModal }] = useModal();

    function handleOpen() {
      openModal(true, { record: { id: 1, name: '张三', email: 'test@example.com' } });
    }

    function handleSuccess() {
      console.log('保存成功，刷新列表');
    }

    return { registerModal, handleOpen, handleSuccess };
  },
});
</script>

```

--------------------------------

### Implement BasicUpload component in Vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/upload.md

Demonstrates how to import and use the BasicUpload component within a Vue 3 script setup or composition API component. It includes binding the upload API and handling the change event to process uploaded file lists.

```vue
<template>
  <BasicUpload :maxSize="20" :maxNumber="10" @change="handleChange" :api="uploadApi" />
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicUpload } from '/@/components/Upload';
  import { uploadApi } from '/@/api/sys/upload';

  export default defineComponent({
    components: { BasicUpload },
    setup() {
      return {
        uploadApi,
        handleChange: (list: string[]) => {
          createMessage.info(`已上传文件${JSON.stringify(list)}`);
        },
      };
    },
  });
</script>
```

--------------------------------

### Production Environment API URL Configuration

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/mock.md

This configuration example shows how to set the production API URL in the `.env.production` file. It primarily involves setting the `VITE_GLOB_API_URL` variable. For cross-origin issues in production, it suggests using Nginx or enabling CORS on the backend.

```bash
# Example API URL
VITE_GLOB_API_URL=http://localhost:3000
```

--------------------------------

### Implement BasicTree Component in Vue

Source: https://context7.com/doukemao/vue-vben-admin-doc/llms.txt

Demonstrates the usage of the BasicTree component, which wraps Ant Design Vue's Tree with added features like search, context menus, and action buttons. It requires defining tree data, action lists, and event handlers within a Vue component setup.

```vue
<template>
  <BasicTree
    :treeData="treeData"
    :actionList="actionList"
    :rightMenuList="rightMenuList"
    checkable
    toolbar
    search
    title="组织架构"
    @select="handleSelect"
  />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import { BasicTree, TreeItem, ActionItem, ContextMenuItem } from '/@/components/Tree';

export default defineComponent({
  components: { BasicTree },
  setup() {
    const treeData: TreeItem[] = [
      {
        title: '总公司',
        key: '0',
        icon: 'ant-design:bank-outlined',
        children: [
          {
            title: '技术部',
            key: '0-1',
            children: [
              { title: '前端组', key: '0-1-1' },
              { title: '后端组', key: '0-1-2' },
            ],
          },
          {
            title: '产品部',
            key: '0-2',
            children: [
              { title: '产品组', key: '0-2-1' },
              { title: '设计组', key: '0-2-2' },
            ],
          },
        ],
      },
    ];

    const actionList: ActionItem[] = [
      {
        render: (node) => h(Icon, { icon: 'ant-design:plus-outlined', onClick: () => handleAdd(node) }),
      },
    ];

    const rightMenuList: ContextMenuItem[] = [
      { label: '新增', icon: 'ant-design:plus-outlined', handler: ({ node }) => handleAdd(node) },
      { label: '删除', icon: 'ant-design:delete-outlined', handler: ({ node }) => handleDelete(node) },
    ];

    function handleSelect(keys: string[]) {
      console.log('选中节点:', keys);
    }

    function handleAdd(node: any) {
      console.log('添加子节点:', node);
    }

    function handleDelete(node: any) {
      console.log('删除节点:', node);
    }

    return { treeData, actionList, rightMenuList, handleSelect };
  },
});
</script>
```

--------------------------------

### Configure Project Settings and Environment Variables

Source: https://context7.com/doukemao/vue-vben-admin-doc/llms.txt

Shows how to define global project configurations including theme, layout, menu, and component settings. It also illustrates the structure of environment variable files for API and application settings.

```typescript
// src/settings/projectSetting.ts
const setting: ProjectConfig = {
  permissionMode: PermissionModeEnum.ROUTE_MAPPING,
  themeColor: '#0960bd',
  grayMode: false,
  colorWeak: false,
  headerSetting: {
    bgColor: '#ffffff',
    fixed: true,
    show: true,
    showFullScreen: true,
    showNotice: true,
    showSearch: true,
  },
  menuSetting: {
    bgColor: '#273352',
    fixed: true,
    collapsed: false,
    menuWidth: 210,
    mode: MenuModeEnum.INLINE,
    type: MenuTypeEnum.SIDEBAR,
    theme: MenuThemeEnum.DARK,
    split: false,
  },
  multiTabsSetting: {
    cache: true,
    show: true,
    canDrag: true,
    showQuick: true,
  },
  transitionSetting: {
    enable: true,
    basicTransition: RouterTransitionEnum.FADE_SIDE,
    openPageLoading: true,
  },
  openKeepAlive: true,
  showBreadCrumb: true,
  showFooter: false,
  useErrorHandle: true,
};

// 环境变量配置 .env.development
VITE_PORT=3100
VITE_GLOB_APP_TITLE=Vben Admin
VITE_USE_MOCK=true
VITE_GLOB_API_URL=/api
VITE_GLOB_UPLOAD_URL=/upload

// 组件全局配置 src/settings/componentSetting.ts
export default {
  table: {
    fetchSetting: {
      pageField: 'page',
      sizeField: 'pageSize',
      listField: 'items',
      totalField: 'total',
    },
    defaultPageSize: 10,
  },
};
```

--------------------------------

### esbuild模式下避免LEGACY打包失败的配置建议

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/other/faq.md

在`build.minify`设置为`esbuild`时，不能同时启用`LEGACY`打包，否则会导致打包失败。用户需要在这两者之间选择一个进行配置。

```text
如果将  build.minify 设置为 'esbuild'，且不能启用 LEGACY，否则打包将会报错，两者选其一即可打包。
```

--------------------------------

### Example API Request Function with Proxy

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/mock.md

This TypeScript code demonstrates an example of a user login API function within the Vue Vben Admin project. It utilizes an enum for API paths and the `http.request` method for making POST requests. The configuration assumes that the `.env.development` file is set up to proxy `/basic-api` requests.

```typescript
// .env.development
// VITE_PROXY=[["/basic-api","http://localhost:3000"]]
// VITE_GLOB_API_URL=/basic-api

enum Api {
  Login = '/login',
}

/**
 * @description: 用户登陆
 */
export function loginApi(params: LoginParams) {
  return http.request<LoginResultModel>({
    url: Api.Login,
    method: 'POST',
    params,
  });
}
```

--------------------------------

### Configure Modular and Multi-level Routes

Source: https://context7.com/doukemao/vue-vben-admin-doc/llms.txt

Demonstrates how to define modular routes using AppRouteModule, including nested children and meta configuration for layout, icons, and keep-alive settings.

```typescript
import type { AppRouteModule } from '/@/router/types';
import { LAYOUT, getParentLayout } from '/@/router/constant';
import { t } from '/@/hooks/web/useI18n';

const dashboard: AppRouteModule = {
  path: '/dashboard',
  name: 'Dashboard',
  component: LAYOUT,
  redirect: '/dashboard/analysis',
  meta: { icon: 'ion:grid-outline', title: t('routes.dashboard.dashboard'), orderNo: 1 },
  children: [
    {
      path: 'analysis',
      name: 'Analysis',
      component: () => import('/@/views/dashboard/analysis/index.vue'),
      meta: { affix: true, title: t('routes.dashboard.analysis'), icon: 'ant-design:dashboard-outlined' },
    }
  ]
};

const multiLevel: AppRouteModule = {
  path: '/level',
  name: 'Level',
  component: LAYOUT,
  children: [
    {
      path: 'menu1',
      name: 'Menu1',
      component: getParentLayout('Menu1'),
      children: [
        { path: 'menu1-1', name: 'Menu1-1', component: () => import('/@/views/demo/level/Menu1-1.vue') }
      ]
    }
  ]
};
```

--------------------------------

### vite.config.ts或.env文件修改后Vite自动重启

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/other/faq.md

当修改`.env`等环境配置文件或`vite.config.ts`文件时，Vite开发服务器会自动重启以应用更改。如果在重启过程中遇到问题，尝试重新运行项目即可解决。

```text
当修改 `.env` 等环境文件及 `vite.config.ts` 文件时，vite 会自动重启服务。
自动重启有几率出现问题，请重新运行项目即可解决.
```

--------------------------------

### Define Backend Menu Structure

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/auth.md

Example structure of the route configuration returned by the backend API. It must include the base home route defined in PageEnum.

```json
[
  {
    "path": "/dashboard",
    "name": "Dashboard",
    "component": "/dashboard/welcome/index",
    "meta": {
      "title": "routes.dashboard.welcome",
      "affix": true,
      "icon": "ant-design:home-outlined"
    }
  },
  {
    "path": "/permission",
    "name": "Permission",
    "component": "LAYOUT",
    "redirect": "/permission/front/page",
    "meta": {
      "icon": "carbon:user-role",
      "title": "routes.demo.permission.permission"
    },
    "children": [
      {
        "path": "back",
        "name": "PermissionBackDemo",
        "meta": {
          "title": "routes.demo.permission.back"
        },
        "children": [
          {
            "path": "page",
            "name": "BackAuthPage",
            "component": "/demo/permission/back/index",
            "meta": {
              "title": "routes.demo.permission.backPage"
            }
          }
        ]
      }
    ]
  }
]
```

--------------------------------

### Initialize useLoading Composable

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/functional/loading.md

Shows the syntax for importing and initializing the useLoading hook, which returns methods to control the loading state and update the loading message.

```typescript
import { useLoading } from '/@/components/Loading';

const [open, close, setTip] = useLoading(opt: Partial<LoadingProps> | Partial<UseLoadingOptions>);
```

--------------------------------

### Global Less Configuration

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/design.md

Demonstrates how Less variables are implicitly injected into components via the global config.less file, eliminating the need for manual imports.

```html
<style lang="less" scoped>
  // 这里已经隐式注入了 config.less
</style>
```

--------------------------------

### Define Language Module

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/dep/i18n.md

Example of a language module file that imports messages and locale-specific configurations for libraries like Ant Design Vue and Moment.js.

```typescript
import { genMessage } from '../helper';
import antdLocale from 'ant-design-vue/es/locale/zh_CN';
import momentLocale from 'moment/dist/locale/zh-cn';

const modules = import.meta.globEager('./zh_CN/**/*.ts');
export default {
  message: {
    ...genMessage(modules, 'zh_CN'),
    antdLocale,
  },
  momentLocale,
  momentLocaleName: 'zh-cn',
};
```

--------------------------------

### 启动报错：Node.js版本不兼容问题

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/other/faq.md

当启动项目时遇到类似`TypeError: str.matchAll is not a function`的错误，并且错误堆栈指向`@purge-icons/core`等库，这通常表明当前的Node.js版本过低，不兼容某些ES6+特性。请确保Node.js版本符合项目要求（推荐14+，不支持13）。

```bash
TypeError: str.matchAll is not a function
at Object.extractor (vue-vben-admin-main\node_modules@purge-icons\core\dist\index.js:146:27)
at Extract (vue-vben-admin-main\node_modules@purge-icons\core\dist\index.js:173:54)
```

--------------------------------

### Implement BasicTree Component Usage

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/tree.md

Demonstrates how to import and use the BasicTree component within a Vue 3 setup, including the definition of the tree data structure using the TreeItem interface.

```vue
<template>
  <BasicTree :treeData="treeData" />
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { BasicTree } from '/@/components/Tree/index';
  import { treeData } from './data';
  import { CollapseContainer } from '/@/components/Container/index';
  import { TreeItem } from '/@/components/Tree/index';

  export const treeData: TreeItem[] = [
    {
      title: 'parent 1',
      key: '0-0',
      icon: 'home|svg',
      children: [
        { title: 'leaf', key: '0-0-0' },
        {
          title: 'leaf',
          key: '0-0-1',
          children: [
            { title: 'leaf', key: '0-0-0-0' },
            { title: 'leaf', key: '0-0-0-1' },
          ],
        },
      ],
    },
  ];
  export default defineComponent({
    components: { BasicTree, CollapseContainer },
    setup() {
      return { treeData };
    },
  });
</script>
```

--------------------------------

### Vue ScrollContainer Usage Example

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/scroll-container.md

Demonstrates how to use the ScrollContainer component in a Vue application. It includes buttons to trigger scrolling actions and displays a list within the scrollable area. Requires Vue and the ScrollContainer component.

```vue
<template>
  <div class="p-4">
    <div class="my-4">
      <a-button @click="scrollTo(100)">滚动到100px位置</a-button>
      <a-button @click="scrollTo(800)">滚动到800px位置</a-button>
      <a-button @click="scrollTo(0)">滚动到顶部</a-button>
      <a-button @click="scrollBottom()">滚动到底部</a-button>
    </div>
    <div class="scroll-wrap">
      <ScrollContainer ref="scrollRef">
        <ul>
          <template v-for="index in 100" :key="index">
            <li>{{ index }}</li>
          </template>
        </ul>
      </ScrollContainer>
    </div>
  </div>
</template>
<script lang="ts">
  import { defineComponent, ref, unref } from 'vue';
  import { CollapseContainer } from '/@/components/Container/index';
  import { ScrollContainer, ScrollActionType } from '/@/components/Container/index';
  export default defineComponent({
    components: { CollapseContainer, ScrollContainer },
    setup() {
      const scrollRef = ref<Nullable<ScrollActionType>>(null);
      const getScroll = () => {
        const scroll = unref(scrollRef);
        if (!scroll) {
          throw new Error('scroll is Null');
        }
        return scroll;
      };

      function scrollTo(top: number) {
        getScroll()?.scrollTo(top);
      }

      function scrollBottom() {
        getScroll()?.scrollBottom();
      }

      return {
        scrollTo,
        scrollRef,
        scrollBottom,
      };
    },
  });
</script>
<style lang="less" scoped>
  .scroll-wrap {
    width: 50%;
    height: 300px;
    background: #fff;
  }
</style>
```

--------------------------------

### Implement Image Preview Component in Vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/functional/preview.md

Demonstrates how to import and use the createImgPreview function within a Vue component to display single or multiple images in a preview modal.

```vue
<template>
  <div class="p-4">
    <Alert message="有预览图" type="info" />
    <div class="flex justify-center mt-4">
      <img :src="img" v-for="img in imgList" :key="img" class="mr-2" @click="handleClick(img)" />
    </div>
    <Alert message="无预览图" type="info" />
    <a-button @click="handlePreview" type="primary" class="mt-4">预览图片</a-button>
  </div>
</template>
<script lang="ts">
  import { defineComponent } from 'vue';
  import { Alert } from 'ant-design-vue';
  import { createImgPreview } from '/@/components/Preview/index';
  const imgList: string[] = [
    'https://picsum.photos/id/66/346/216',
    'https://picsum.photos/id/67/346/216',
    'https://picsum.photos/id/68/346/216',
  ];
  export default defineComponent({
    components: { Alert },
    setup() {
      function handleClick(img: string) {
        createImgPreview({ imageList: [img] });
      }

      function handlePreview() {
        createImgPreview({ imageList: imgList });
      }
      return { imgList, handleClick, handlePreview };
    },
  });
</script>
```

--------------------------------

### Menu Module Structure and Export (TypeScript)

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/menu.md

Demonstrates how to define a menu module in TypeScript. Each file in `src/router/menus` is treated as a module, and this example shows how to structure the `menu` object with an `orderNo` for sorting and nested `children`.

```typescript
import type { MenuModule } from '/@/router/types';
import { t } from '/@/hooks/web/useI18n';

const menu: MenuModule = {
  orderNo: 10,
  menu: {
    name: t('routes.dashboard.dashboard'),
    path: '/dashboard',

    children: [
      {
        path: 'analysis',
        name: t('routes.dashboard.analysis'),
      },
      {
        path: 'workbench',
        name: t('routes.dashboard.workbench'),
      },
    ],
  },
};

export default menu;
```

--------------------------------

### Git代码同步与分支管理示例

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/other/faq.md

为了同步开源项目的最新代码并进行开发，可以克隆项目，添加公司Git源，然后提交代码到公司Git，并根据需要拉取公司或开源代码。注意处理可能出现的代码冲突。

```bash
git clone https://github.com/vbenjs/vue-vben-admin-thin-next.git
# up 为源名称,可以随意设置
# gitUrl为开源最新代码
git remote add up gitUrl;

# 提交代码到自己公司
# main为分支名 需要自行根据情况修改
git push up main

# 同步公司的代码
# main为分支名 需要自行根据情况修改
git pull up main

# 如何同步开源最新代码
git pull origin main
```

--------------------------------

### Change the Default Home Route

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/router.md

The default home route, which is the initial route loaded when the application starts (if logged in), can be changed by modifying the `BASE_HOME` constant in `pageEnum.ts`. This determines the fixed tab displayed on startup.

```typescript
export enum PageEnum {
    // basic home path
    // 更改此处即可
    BASE_HOME = '/dashboard',
}
```

--------------------------------

### Locally Use ant-design-vue Button Component in Vue

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/guide/lib.md

This example shows how to import and use a specific component, Button, from ant-design-vue locally within a Vue single-file component. It registers the component in the script section.

```vue
<template>
  <Button>text</Button>
</template>

<script>
  import { defineComponent } from 'vue';
  import { Button } from 'ant-design-vue';
  export default defineComponent({
    components: {
      Button,
    },
  });
</script>
```

--------------------------------

### 配置国内NPM镜像源以解决依赖安装问题

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/other/faq.md

如果通过常规方式安装依赖仍然失败，可以尝试在项目根目录创建`.npmrc`文件，并配置国内镜像源，如`registry = https://registry.npmmirror.com/`。之后执行`yarn run reinstall`来安装依赖。

```bash
# .npmrc
registry = https://registry.npmmirror.com/

yarn run reinstall
```

--------------------------------

### Vue Tinymce Component Usage

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/tinymce.md

Demonstrates how to integrate and use the Tinymce rich text editor component in a Vue.js application. It shows basic setup with v-model for content binding and an event handler for content changes.

```vue
<template>
  <Tinymce v-model="value" @change="handleChange" width="100%" />
</template>
<script lang="ts">
  import { defineComponent, ref } from 'vue';
  import { Tinymce } from '/@/components/Tinymce/index';

  export default defineComponent({
    components: { Tinymce },
    setup() {
      const value = ref('hello world!');
      function handleChange(value: string) {
        console.log(value);
      }
      return { handleChange, value };
    },
  });
</script>
```

--------------------------------

### Vue QrCode Component Usage

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/qrcode.md

Demonstrates how to use the QrCode component in a Vue.js application. It shows basic integration with a URL and includes a method to trigger a download of the generated QR code. Dependencies include Vue's `defineComponent`, `ref`, `unref`, and the `QrCode` component itself.

```vue
<template>
  <QrCode :value="qrCodeUrl" />
</template>
<script lang="ts">
  import { defineComponent, ref, unref } from 'vue';
  import { QrCode, QrCodeActionType } from '/@/components/Qrcode/index';
  import LogoImg from '/@/assets/images/logo.png';
  const qrCodeUrl = 'https://www.vvbin.cn';
  export default defineComponent({
    components: { QrCode },
    setup() {
      const qrRef = ref<Nullable<QrCodeActionType>>(null);
      function download() {
        const qrEl = unref(qrRef);
        if (!qrEl) return;
        qrEl.download('文件名');
      }
      return {
        qrCodeUrl,
        LogoImg,
        download,
        qrRef,
      };
    },
  });
</script>
<style scoped>
  .qrcode-demo-item {
    width: 30%;
    margin-right: 1%;
  }
</style>
```

--------------------------------

### Vue Authority Component Usage Example

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/auth.md

Demonstrates how to use the Authority component to conditionally render content based on user roles. It requires the Authority component and defines its usage within a Vue template and script.

```vue
<template>
  <div>
    <Authority :value="RoleEnum.ADMIN">
      <a-button type="primary" block> 只有admin角色可见 </a-button>
    </Authority>
  </div>
</template>
<script>
  import { Authority } from '/@/components/Authority';
  import { defineComponent } from 'vue';
  export default defineComponent({
    components: { Authority },
  });
</script>
```

--------------------------------

### Display BasicHelp component

Source: https://github.com/doukemao/vue-vben-admin-doc/blob/main/components/basic.md

The BasicHelp component renders a help icon that displays a tooltip when hovered. It is highly configurable, allowing for custom text, font sizes, colors, and placement.

```vue
<template>
  <div>
    <BasicHelp :text="['提示1', '提示2']" />
    <BasicHelp text="提示" />
  </div>
</template>
<script>
  import { BasicHelp } from '/@/components/Basic/index';
  import { defineComponent } from 'vue';
  export default defineComponent({
    components: { BasicHelp },
  });
</script>
```