Fantastic-admin

https://fantastic-admin.hurui.me/guide/
Admin
Fantastic-admin is a comprehensive, Vue-based administrative dashboard template and framework...
Tokens:68,510
Snippets:213
Trust Score:4.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Fantastic Admin Guides

Source: https://fantastic-admin.hurui.me/guide/devtools

Comprehensive guide covering various aspects of Fantastic Admin, including getting started, configuration, routing, state management, and more. It also covers advanced topics such as internationalization, code generation, and UI component replacement.

```APIDOC
Guides:
  - Introduction: [文档说明](https://fantastic-admin.hurui.me/guide/intro.html)
  - Why Choose Us?: [为什么选择我们 ?](https://fantastic-admin.hurui.me/guide/why.html)
  - Changelog: [更新日志](https://fantastic-admin.hurui.me/guide/changelog.html)

Getting Started:
  - Prerequisites: [准备工作](https://fantastic-admin.hurui.me/guide/ready.html)
  - Quick Start: [开始](https://fantastic-admin.hurui.me/guide/start.html)
  - Coding Standards: [代码规范](https://fantastic-admin.hurui.me/guide/coding-standard.html)
  - Terminology: [术语](https://fantastic-admin.hurui.me/guide/term.html)
  - Configuration: [配置](https://fantastic-admin.hurui.me/guide/configure.html)
  - Developer Tools: [开发者工具](https://fantastic-admin.hurui.me/guide/devtools.html)
  - Routing: [路由（导航）](https://fantastic-admin.hurui.me/guide/router.html)
  - Server Interaction: [与服务端交互](https://fantastic-admin.hurui.me/guide/axios.html)
  - Global State Management: [全局状态管理](https://fantastic-admin.hurui.me/guide/store.html)
  - Resources: [资源](https://fantastic-admin.hurui.me/guide/resources.html)
  - Icons: [图标](https://fantastic-admin.hurui.me/guide/icon.html)
  - Build and Preview: [构建与预览](https://fantastic-admin.hurui.me/guide/build.html)

Intermediate Topics:
  - Login: [登录相关](https://fantastic-admin.hurui.me/guide/login.html)
  - Permissions: [权限](https://fantastic-admin.hurui.me/guide/permission.html)
  - Home Page: [主页](https://fantastic-admin.hurui.me/guide/home.html)
  - Layout: [布局](https://fantastic-admin.hurui.me/guide/layout.html)
  - Themes: [主题](https://fantastic-admin.hurui.me/guide/theme.html)
  - Dynamic Titles: [动态标题](https://fantastic-admin.hurui.me/guide/title.html)
  - Navigation Menu: [导航菜单](https://fantastic-admin.hurui.me/guide/menu.html)
  - Top Bar: [顶栏](https://fantastic-admin.hurui.me/guide/topbar.html)
  - Tab Bar: [标签栏](https://fantastic-admin.hurui.me/guide/tabbar.html)
  - Toolbar: [工具栏](https://fantastic-admin.hurui.me/guide/toolbar.html)
  - Hotkeys: [快捷键](https://fantastic-admin.hurui.me/guide/hotkeys.html)
  - Copyright: [版权信息](https://fantastic-admin.hurui.me/guide/copyright.html)

Advanced Topics:
  - Page Caching: [页面缓存](https://fantastic-admin.hurui.me/guide/keep-alive.html)
  - Internationalization: [国际化](https://fantastic-admin.hurui.me/guide/i18n.html)
  - Slots: [预留插槽](https://fantastic-admin.hurui.me/guide/slots.html)
  - RTL Mode: [RTL 模式](https://fantastic-admin.hurui.me/guide/rtl.html)
  - Code Generation: [代码文件自动生成](https://fantastic-admin.hurui.me/guide/plop.html)
  - Standard Modules: [标准模块](https://fantastic-admin.hurui.me/guide/plop-module.html)
  - Common APIs: [常用 API](https://fantastic-admin.hurui.me/guide/api.html)
  - Private Storage: [私有 Storage 数据](https://fantastic-admin.hurui.me/guide/storage.html)
  - Initial Loading: [首屏 Loading](https://fantastic-admin.hurui.me/guide/loading.html)
  - Watermarks: [页面水印](https://fantastic-admin.hurui.me/guide/watermark.html)
  - Update Checks: [检查更新](https://fantastic-admin.hurui.me/guide/check-updates.html)
  - Error Logging: [错误日志](https://fantastic-admin.hurui.me/guide/error-log.html)
  - Custom Fonts: [自定义字体](https://fantastic-admin.hurui.me/guide/font.html)
  - User Preferences: [用户偏好设置](https://fantastic-admin.hurui.me/guide/preferences.html)
  - JSX: [JSX](https://fantastic-admin.hurui.me/guide/jsx.html)
  - File-Based Routing: [基于文件系统的路由](https://fantastic-admin.hurui.me/guide/file-system-route.html)
  - Composition API: [使用 Composition API 开发](https://fantastic-admin.hurui.me/guide/vue3-composition-api.html)

UI Library Replacement:
  - Ant Design Vue: [替换为 Ant Design Vue](https://fantastic-admin.hurui.me/guide/replace-to-antd.html)
  - Arco Design Vue: [替换为 Arco Design Vue](https://fantastic-admin.hurui.me/guide/replace-to-arco.html)
  - Naive UI: [替换为 Naive UI](https://fantastic-admin.hurui.me/guide/replace-to-naive.html)
  - TDesign: [替换为 TDesign](https://fantastic-admin.hurui.me/guide/replace-to-tdesign.html)
  - Vexip UI: [替换为 Vexip UI](https://fantastic-admin.hurui.me/guide/replace-to-vexip.html)
  - iDux: [替换为 iDux](https://fantastic-admin.hurui.me/guide/replace-to-idux.html)
```

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

### Install Dependencies and Run Project

Source: https://fantastic-admin.hurui.me/guide/start

Execute these commands in the root directory of the source code to install project dependencies using pnpm and start the development server. The project will automatically open in your browser at http://localhost:9000 upon successful execution.

```bash
# Install dependencies
# Note: You must use pnpm to install dependencies, do not use npm or yarn
pnpm install
# Run
pnpm run dev
```

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

### Environment Configuration (.env.development) Example

Source: https://fantastic-admin.hurui.me/guide/configure

This YAML block shows example environment variables for a development setup, including application title, API base URL, and debugging tools. It highlights essential variables like VITE_APP_TITLE and VITE_APP_API_BASEURL.

```yaml
# 应用配置面板
VITE_APP_SETTING = true
# 页面标题
VITE_APP_TITLE = Fantastic-admin
# 接口请求地址，会设置到 axios 的 baseURL 参数上
VITE_APP_API_BASEURL = /
# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
VITE_APP_DEBUG_TOOL =
# 是否禁用开发者工具，可防止被调试
VITE_APP_DISABLE_DEVTOOL = false
# 是否开启代理
VITE_OPEN_PROXY = false
# 是否开启开发者工具
VITE_OPEN_DEVTOOLS = false
```

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

### Perform GET and POST API Requests

Source: https://fantastic-admin.hurui.me/guide/axios

Demonstrates how to use the framework's API instance for making GET and POST requests. It includes examples of passing parameters for GET requests and data payloads for POST requests, along with handling responses.

```ts
import api from '@/api'
// GET 请求
api.get('news/list', {
  params: {
    page: 1,
    size: 10,
  },
}).then((res) => {
  // 后续业务代码
})
// POST 请求
api.post('news/create', {
  title: '新闻标题',
  content: '新闻内容',
}).then((res) => {
  // 后续业务代码
})
```

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

### Environment Configuration (.env.test) Example

Source: https://fantastic-admin.hurui.me/guide/configure

This YAML block provides example environment variables for a test environment, enabling Mock during build and enabling sourcemaps. It includes settings for compression.

```yaml
# 应用配置面板
VITE_APP_SETTING = false
# 页面标题
VITE_APP_TITLE = Fantastic-admin
# 接口请求地址，会设置到 axios 的 baseURL 参数上
VITE_APP_API_BASEURL = /
# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
VITE_APP_DEBUG_TOOL =
# 是否禁用开发者工具，可防止被调试
VITE_APP_DISABLE_DEVTOOL = false
# 是否在打包时启用 Mock
VITE_BUILD_MOCK = true
# 在构建时生成 sourcemap
VITE_BUILD_SOURCEMAP = true
# 在构建时开启压缩，支持 gzip 和 brotli
VITE_BUILD_COMPRESS =
# 是否在打包后生成存档，支持 zip 和 tar
VITE_BUILD_ARCHIVE =
```

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

### Environment Configuration (.env.production) Example

Source: https://fantastic-admin.hurui.me/guide/configure

This YAML block shows example environment variables for a production build, disabling Mock, disabling sourcemaps, and enabling gzip/brotli compression. It also includes settings for archive generation.

```yaml
# 应用配置面板
VITE_APP_SETTING = false
# 页面标题
VITE_APP_TITLE = Fantastic-admin
# 接口请求地址，会设置到 axios 的 baseURL 参数上
VITE_APP_API_BASEURL = /
# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
VITE_APP_DEBUG_TOOL =
# 是否禁用开发者工具，可防止被调试
VITE_APP_DISABLE_DEVTOOL = false
# 是否在打包时启用 Mock
VITE_BUILD_MOCK = false
# 在构建时生成 sourcemap
VITE_BUILD_SOURCEMAP = false
# 在构建时开启压缩，支持 gzip 和 brotli
VITE_BUILD_COMPRESS = gzip,brotli
# 是否在打包后生成存档，支持 zip 和 tar
VITE_BUILD_ARCHIVE =
```

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

### Install Naive UI Dependencies

Source: https://fantastic-admin.hurui.me/guide/replace-to-naive

Installs project dependencies and adds Naive UI as a development dependency using pnpm. This is the initial step for integrating Naive UI.

```sh
pnpm install
pnpm add naive-ui -D
```

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

### Install Vexip UI

Source: https://fantastic-admin.hurui.me/guide/replace-to-vexip

Installs project dependencies and adds the Vexip UI library to your project using pnpm. This is the initial step for integrating Vexip UI.

```sh
pnpm install
pnpm add vexip-ui
```

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

### 配置 IDE 启动器

Source: https://fantastic-admin.hurui.me/guide/devtools

配置 Vue DevTools 以在浏览器中选择组件时自动在 IDE 中打开源文件。默认使用 VSCode，但可以通过在 `.env.development.local` 文件中设置 `VITE_VUE_DEVTOOLS_LAUNCH_EDITOR` 来指定其他支持的 IDE。

```yaml
VITE_VUE_DEVTOOLS_LAUNCH_EDITOR = cursor
```

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

### API Request Methods

Source: https://fantastic-admin.hurui.me/guide/api

Demonstrates how to import and use the API module for making HTTP requests. It shows basic GET and POST calls.

```ts
import api from '@/api'
api.get()
api.post()
```

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

### 启用 Vue DevTools

Source: https://fantastic-admin.hurui.me/guide/devtools

在开发环境配置文件 `.env.development` 中设置此变量为 `true`，即可在本地运行时启用 Vue DevTools。启用后，页面底部通常会显示一个开发者工具的入口按钮。

```yaml
# 是否开启开发者工具
VITE_OPEN_DEVTOOLS = true
```

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

### Build Compression Configuration

Source: https://fantastic-admin.hurui.me/guide/build

Environment variable settings to enable compression for build output files (.gz or .br). Requires corresponding Nginx modules to be installed and enabled for runtime.

```APIDOC
VITE_BUILD_COMPRESS:
  description: Enables compression for build output files.
  options:
    - gzip: Generates .gz files.
    - brotli: Generates .br files (higher compression ratio).
    - gzip,brotli: Generates both .gz and .br files.
  example:
    # Enable gzip compression
    VITE_BUILD_COMPRESS = gzip
    # Enable brotli compression
    VITE_BUILD_COMPRESS = brotli
    # Enable both gzip and brotli compression
    VITE_BUILD_COMPRESS = gzip,brotli
```

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

### Authentication Functions

Source: https://fantastic-admin.hurui.me/guide/api

Shows how to use the `useAuth` hook to access authentication functions. It includes examples for `auth` and `authAll`.

```ts
const { auth, authAll } = useAuth()
auth()
authAll()
```

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

### Navigation Switching

Source: https://fantastic-admin.hurui.me/guide/api

Provides an example of how to switch the main navigation using the `useMenu` hook. The `index` parameter specifies the navigation item.

```ts
const { switchTo } = useMenu()
switchTo(index)
```

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

### Global Settings for Navigation Source

Source: https://fantastic-admin.hurui.me/guide/file-system-route

Example TypeScript configuration snippet demonstrating how to set the navigation data source to 'backend' within the global application settings.

```typescript
const globalSettings: Settings.all = {
  menu: {
    /**
     * Navigation data source, effective when `app.routeBaseOn: 'filesystem'`
     * @default 'frontend' (frontend)
     * @options 'backend' (backend)
     */
    baseOn: 'backend',
  },
}
```

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

### Mock Server Setup with vite-plugin-fake-server

Source: https://fantastic-admin.hurui.me/guide/axios

Illustrates how to set up a mock server for development using `vite-plugin-fake-server` and `faker.js`. Mock files are placed in `/src/mock/` and can be organized by module. The plugin automatically updates mocks without requiring a server restart.

```ts
import { faker } from '@faker-js/faker/locale/zh_CN'
import { defineFakeRoute } from 'vite-plugin-fake-server/client'

export default defineFakeRoute([
  {
    url: '/mock/user/list',
    method: 'get',
    response: () => {
      const list: any[] = []
      for (let i = 0; i < 50; i++) {
        list.push({
          id: i + 1,
          account: faker.person.firstName(),
          name: faker.person.fullName(),
          sex: faker.number.int(2),
          mobile: faker.phone.number({ style: 'international' }),
          status: faker.datatype.boolean(),
        })
      }
      return {
        error: '',
        status: 1,
        data: list,
      }
    },
  },
])

// Parameter handling for requests:
// GET: ({ query }) => { }
// POST: ({ body }) => { }
```

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

### Configure Vite Base Path

Source: https://fantastic-admin.hurui.me/guide/build

Example of how to configure the 'base' option in vite.config.ts. This is crucial when deploying the application to a sub-path of a domain (e.g., '/app/').

```javascript
export default defineConfig({
  // ... other configurations
  base: '/app/' // Set to '/app/' if your app is served at https://www.example.com/app
});
```

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

### Multi-level Routing Example

Source: https://fantastic-admin.hurui.me/guide/router

Demonstrates setting up nested routes without a component for intermediate levels, explaining the rationale for KeepAlive caching. This structure is useful for organizing complex navigation hierarchies.

```typescript
import type { RouteRecordRaw } from 'vue-router'
const routes: RouteRecordRaw = {
  path: '/example',
  component: () => import('@/layouts/index.vue'),
  redirect: '/example/level/index',
  name: 'Example',
  meta: {
    title: '演示',
  },
  children: [
    {
      path: 'level',
      name: 'ExampleLevel',
      // 无需设置 componment
      meta: {
        title: '中间层级',
      },
      children: [
        {
          path: 'index',
          name: 'ExampleLevelIndex',
          component: () => import('@/views/example/index.vue'),
          meta: {
            title: '演示页面',
          },
        },
      ],
    },
  ],
}
export default routes
```

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

### Vue Router Configuration Example

Source: https://fantastic-admin.hurui.me/guide/router

Demonstrates a typical route module structure for the Fantastic Admin project using Vue Router. It includes path, component, redirect, name, and meta properties for defining routes and their associated metadata.

```typescript
import type { RouteRecordRaw } from 'vue-router'
const routes: RouteRecordRaw = {
  path: '/example',
  component: () => import('@/layouts/index.vue'),
  redirect: '/example/index',
  name: 'Example',
  meta: {
    title: '演示',
  },
  children: [
    {
      path: 'index',
      name: 'ExampleIndex',
      component: () => import('@/views/example/index.vue'),
      meta: {
        title: '演示页面',
      },
    },
  ],
}
export default routes
```

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

### Fantastic-admin UI Component Replacement

Source: https://fantastic-admin.hurui.me/guide/layout

Guides on how to replace the default UI component library with alternatives like Ant Design Vue, Arco Design Vue, Naive UI, TDesign, Vexip UI, and iDux.

```APIDOC
## 替换 UI 组件库 (Replace UI Component Library)

This section details the process of swapping the default UI component library with other popular Vue UI frameworks.

### Replace with Ant Design Vue (`replace-to-antd.html`)

-   Steps to integrate Ant Design Vue.
-   Mapping of Fantastic-admin components to Ant Design Vue equivalents.
-   Configuration adjustments required.

### Replace with Arco Design Vue (`replace-to-arco.html`)

-   Instructions for integrating Arco Design Vue.
-   Component mapping and necessary configuration changes.

### Replace with Naive UI (`replace-to-naive.html`)

-   Guide to integrating Naive UI.
-   Component mapping and setup procedures.

### Replace with TDesign (`replace-to-tdesign.html`)

-   Steps for integrating TDesign.
-   Component mapping and configuration details.

### Replace with Vexip UI (`replace-to-vexip.html`)

-   Instructions on integrating Vexip UI.
-   Component mapping and necessary adjustments.

### Replace with iDux (`replace-to-idux.html`)

-   Guide to integrating iDux.
-   Component mapping and setup procedures.
```

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

### Storage Class API and Usage (v5.5.0+)

Source: https://fantastic-admin.hurui.me/guide/storage

Demonstrates how to use the framework's rewritten localStorage and sessionStorage, including new methods for checking existence and getting count, after setting a prefix.

```typescript
// localStorage
localStorage.has(key)
localStorage.get(key)
localStorage.set(key, value)
localStorage.remove(key)
localStorage.clear()

// sessionStorage
sessionStorage.has(key)
sessionStorage.get(key)
sessionStorage.set(key, value)
sessionStorage.remove(key)
sessionStorage.clear()

// Get count of prefixed keys
localStorage.length
sessionStorage.length
```

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

### Configure TDesign Provider (Basic Version)

Source: https://fantastic-admin.hurui.me/guide/replace-to-tdesign

Sets up the TDesign provider in the Vue application for the basic version, importing the library and its CSS. This involves creating an install function that uses app.use(TDesign).

```ts
import type { App } from 'vue'
import TDesign from 'tdesign-vue-next'
import 'tdesign-vue-next/es/style/index.css'
function install(app: App) {
  app.use(TDesign)
}
export default { install }
```

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

### Troubleshooting npm Registry Issues

Source: https://fantastic-admin.hurui.me/guide/start

If dependency installation fails due to npm registry access issues, you can switch to a domestic mirror source like npmmirror.com. This involves configuring pnpm or using tools like nrm. After switching, remove the node_modules folder and reinstall.

```bash
# Switch to a domestic npm mirror source
pnpm config set registry https://registry.npmmirror.com/
# Then delete the /node_modules folder and reinstall dependencies
```

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

### Git Commit Hooks 移除配置 (package.json)

Source: https://fantastic-admin.hurui.me/guide/coding-standard

从 `package.json` 中移除 `simple-git-hooks` 配置项及其 `postinstall` 脚本，并手动删除 `.git/hooks/pre-commit` 文件，以禁用提交前的代码规范校验。

```json
{
  "scripts": {
    "postinstall": "simple-git-hooks" 
  },
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged", 
    "preserveUnused": true
  }
}
```

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

### Preview Build Output Locally

Source: https://fantastic-admin.hurui.me/guide/build

Commands to preview the built project files locally before deployment. This allows verification of the build output for different environments.

```bash
pnpm run serve
pnpm run serve:test
```

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

### Build Project with pnpm

Source: https://fantastic-admin.hurui.me/guide/build

Commands to build the project for production or testing environments. The build process generates output files in the 'dist' or 'dist-test' directory respectively.

```bash
pnpm run build
pnpm run build:test
```

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

### Get Current Tab ID (TypeScript)

Source: https://fantastic-admin.hurui.me/guide/api

Retrieves the unique identifier (`tabId`) of the currently active tab using the `getId` function from the `useTabbar` composable.

```ts
const { getId } = useTabbar()
getId()
```

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

### Stylelint 配置与使用

Source: https://fantastic-admin.hurui.me/guide/coding-standard

配置 `stylelint.config.js` 文件来定义 CSS/SCSS 等样式文件的代码风格规则。可通过 `pnpm run lint:stylelint` 命令进行格式校验和自动修复。`ignoreFiles` 配置可用于忽略特定文件的校验。

```APIDOC
Stylelint Configuration:
  File: stylelint.config.js
  Purpose: Defines code style rules for CSS, SCSS, etc.
  Commands:
    - pnpm run lint:stylelint: Runs Stylelint for validation and auto-fixing.
  Configuration Options:
    - ignoreFiles: Array of paths or glob patterns to ignore during linting (e.g., third-party code).
  Example `stylelint.config.js` structure:
  ```javascript
  // stylelint.config.js
  module.exports = {
    extends: 'stylelint-config-standard',
    rules: {
      // Your custom rules or overrides
    },
    ignoreFiles: [
      'dist/**/*.{css,scss}',
      'node_modules/**/*.{css,scss}',
    ],
  };
  ```
```

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

### Fantastic-admin API Reference

Source: https://fantastic-admin.hurui.me/guide/layout

This section provides an overview of commonly used APIs within the Fantastic-admin framework. It details methods for interacting with various aspects of the application, such as storage, routing, and UI elements.

```APIDOC
## 常用 API (Common APIs)

This section covers frequently used APIs for interacting with the Fantastic-admin framework.

### Private Storage Data (`storage.js`)

Provides methods for managing private data stored locally.

-   `set(key, value)`: Stores a key-value pair.
    -   Parameters:
        -   `key` (string): The key to store the data under.
        -   `value` (any): The data to store.
    -   Returns: void

-   `get(key)`: Retrieves data associated with a key.
    -   Parameters:
        -   `key` (string): The key of the data to retrieve.
    -   Returns: any | null: The stored data or null if not found.

-   `remove(key)`: Removes data associated with a key.
    -   Parameters:
        -   `key` (string): The key of the data to remove.
    -   Returns: void

### Page Caching (`keep-alive`)

Details on how to manage page caching using Vue's `keep-alive` component.

-   Configuration for enabling/disabling page caching.
-   Methods for explicitly including or excluding routes from caching.

### Internationalization (`i18n`)

Information on integrating and using internationalization features.

-   Setup for language switching.
-   Usage of translation functions.

### Custom Font (`font.html`)

Instructions for customizing application fonts.

-   Methods for loading and applying custom font files.

### User Preferences (`preferences.html`)

APIs related to managing user-specific settings.

-   Saving and loading user preferences.

### Error Logging (`error-log.html`)

Details on how the error logging mechanism works and how to use it.

-   Methods for reporting errors.
-   Configuration for error reporting levels.

### First Screen Loading (`loading.html`)

Configuration and customization of the initial page loading indicator.

-   Methods to control the loading state.

### Page Watermark (`watermark.html`)

APIs for applying and managing watermarks on pages.

-   Functions to add, remove, or update watermarks.

### Check Updates (`check-updates.html`)

Information on how to check for application updates.

-   API endpoints or methods for update checks.
```

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

### Plop 模式详解

Source: https://fantastic-admin.hurui.me/guide/plop

详细说明了 plop 在 Fantastic-admin 项目中支持的五种模式及其生成规则和目录：page (页面文件), component (组件文件), store (pinia 全局状态文件), mock (mock 文件), module (页面模块文件)。

```APIDOC
Plop Modes:

- page:
  - Description: Generates page files.
  - Location: Creates files within `/src/views/`.
  - Features: Replaces key placeholders like `<page-header />` title with Chinese names, automatically generates unique page names based on directory and filename.

- component:
  - Description: Generates component files.
  - Location: Can create public components in `/src/components/` or local components within specified directories in `/src/views/`.

- store:
  - Description: Generates Pinia global state files.
  - Location: Creates files in `/src/store/modules/`.

- mock:
  - Description: Generates mock data files.
  - Location: Creates files in `/src/mock/`.
  - Features: Generates standard CURD mock data.

- module (Pro version):
  - Description: Generates a standard module template.
  - Location: Creates a module folder in a specified directory.
  - Features: Includes list page, edit (detail) page, and related local components. Refer to "Standard Module" documentation for details.
```

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

### Tab Bar Management API

Source: https://fantastic-admin.hurui.me/guide/api

Comprehensive API for managing the tab bar, including getting current tab info, opening, closing, and manipulating tabs based on their state or position.

```APIDOC
Tab Bar API:

- getCurrentTabId(): string
  - Description: Retrieves the unique identifier (tabId) of the currently active tab.
  - Returns: The tabId of the current tab.

- openNewTab(url: string, title?: string, tabId?: string): void
  - Description: Opens a new tab with the specified URL. Optionally set a title and a specific tabId.
  - Parameters:
    - url: The URL to load in the new tab.
    - title: Optional title for the new tab.
    - tabId: Optional unique identifier for the new tab.

- goBackTab(): void
  - Description: Navigates to the previous tab in the history.

- replaceCurrentTab(url: string, title?: string, tabId?: string): void
  - Description: Replaces the current tab's content with a new URL. Optionally update title and tabId.
  - Parameters:
    - url: The URL to load.
    - title: Optional new title for the tab.
    - tabId: Optional new tabId.

- closeCurrentTab(): void
  - Description: Closes the currently active tab.

- closeSpecificTab(tabId: string): void
  - Description: Closes a tab identified by its specific tabId.
  - Parameters:
    - tabId: The tabId of the tab to close.

- closeTabsToSide(tabId: string, direction: 'left' | 'right' | 'both'): void
  - Description: Closes tabs located to the left, right, or both sides of a specified tabId.
  - Parameters:
    - tabId: The reference tabId.
    - direction: 'left', 'right', or 'both' to specify which adjacent tabs to close.

- closeLeftTabs(tabId: string): void
  - Description: Closes all tabs to the left of the specified tabId.
  - Parameters:
    - tabId: The reference tabId.

- closeRightTabs(tabId: string): void
  - Description: Closes all tabs to the right of the specified tabId.
  - Parameters:
    - tabId: The reference tabId.

- checkClosableTabs(tabId: string, direction: 'left' | 'right' | 'both'): boolean
  - Description: Checks if there are any closable tabs to the left, right, or both sides of a specified tabId.
  - Parameters:
    - tabId: The reference tabId.
    - direction: 'left', 'right', or 'both'.
  - Returns: True if closable tabs exist, false otherwise.

- checkClosableLeftTabs(tabId: string): boolean
  - Description: Checks if there are any closable tabs to the left of the specified tabId.
  - Parameters:
    - tabId: The reference tabId.
  - Returns: True if closable tabs exist, false otherwise.

- checkClosableRightTabs(tabId: string): boolean
  - Description: Checks if there are any closable tabs to the right of the specified tabId.
  - Parameters:
    - tabId: The reference tabId.
  - Returns: True if closable tabs exist, false otherwise.
```

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

### Application Configuration (/src/settings.ts)

Source: https://fantastic-admin.hurui.me/guide/configure

This TypeScript snippet demonstrates how to configure application settings in `/src/settings.ts`. It covers options for permissions, dynamic titles, layout adaptations, menu behavior, topbar, and toolbar features.

```ts
// 这是基础版演示源码里的自定义配置示例
const globalSettings: Settings.all = {
  app: {
    enablePermission: true,
    enableDynamicTitle: true,
  },
  layout: {
    enableMobileAdaptation: true,
  },
  menu: {
    enableSubMenuCollapseButton: true,
    enableHotkeys: true,
  },
  topbar: {
    mode: 'fixed',
  },
  toolbar: {
    enableFullscreen: true,
    enablePageReload: true,
    enableColorScheme: true,
  },
}
```

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

### Configure ArcoVue Provider (Base Version)

Source: https://fantastic-admin.hurui.me/guide/replace-to-arco

Sets up the Arco Design Vue provider for the application in the base version. It imports ArcoVue and its CSS, and defines an install function to use the plugin.

```ts
import type { App } from 'vue'
import ArcoVue from '@arco-design/web-vue'
import '@arco-design/web-vue/dist/arco.css'
function install(app: App) {
  app.use(ArcoVue)
}
export default { install }
```

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

### Enable File System Routing

Source: https://fantastic-admin.hurui.me/guide/file-system-route

配置 `app.routeBaseOn` 为 'filesystem' 来启用基于文件系统的路由。此功能依赖于 vite-plugin-pages 和 vite-plugin-vue-layouts。

```ts
const globalSettings: Settings.all = {
  app: {
    /**
     * 路由数据来源
     * @默认值 'frontend' 前端
     * @可选值 'backend' 后端
     * @可选值 'filesystem' 文件系统
     */
    routeBaseOn: 'filesystem',
  },
}
```

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

### Nested Route Permissions Example

Source: https://fantastic-admin.hurui.me/guide/router

Illustrates how to apply `auth` meta properties across multiple levels of nested routes. Access is granted only if the user possesses all required permissions defined at each hierarchical level.

```typescript
import type { RouteRecordRaw } from 'vue-router'
const routes: RouteRecordRaw = {
  path: '/system',
  meta: {
    title: '系统管理',
  },
  children: [
    {
      path: 'department',
      meta: {
        title: '部门管理',
        auth: 'a',
      },
      children: [
        {
          path: 'job',
          meta: {
            title: '职位管理',
          },
          children: [
            {
              path: 'member',
              meta: {
                title: '人员管理',
                auth: 'b', // 只有当用户权限里同时含有 a 和 b 时，才能访问该路由
              },
            },
          ],
        },
      ],
    },
  ],
}
export default routes
```

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

### ESLint 配置与使用

Source: https://fantastic-admin.hurui.me/guide/coding-standard

配置 `eslint.config.js` 文件以定义代码风格规则，使用 antfu/eslint-config 作为基础。可通过 `pnpm run lint:eslint` 命令进行格式校验和自动修复。`ignores` 配置可用于忽略特定文件或目录的校验。

```APIDOC
ESLint Configuration:
  File: eslint.config.js
  Base: antfu/eslint-config
  Purpose: Defines code style rules for JavaScript/TypeScript.
  Commands:
    - pnpm run lint:eslint: Runs ESLint for validation and auto-fixing.
  Configuration Options:
    - ignores: Array of paths or glob patterns to ignore during linting (e.g., third-party code).
  Example `eslint.config.js` structure:
  ```javascript
  // eslint.config.js
  import antfu from '@antfu/eslint-config';

  export default antfu({
    // Your overrides or custom rules here
    ignores: [
      '**/dist/**',
      '**/node_modules/**',
    ],
  });
  ```
```

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

### Reference Route Title in Meta

Source: https://fantastic-admin.hurui.me/guide/i18n

Example of how to set a route's title using the internationalized key defined in the language files. This allows the title to be dynamically translated based on the current application language.

```ts
meta: {
  title: 'route.page',
}
```

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

### Advanced Troubleshooting (Not Recommended)

Source: https://fantastic-admin.hurui.me/guide/start

In rare cases where the project still fails to run, you can attempt to bypass the pnpm lock and use alternative package managers like npm or yarn. This is not recommended as it may lead to dependency version inconsistencies and unpredictable issues.

```bash
# Delete node_modules and pnpm-lock.yaml
# Remove "preinstall": "npx only-allow pnpm" from package.json
# Install dependencies using npm or yarn
# Example using npm:
npm install
```

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

### Configure Vexip UI Provider (Pro Version)

Source: https://fantastic-admin.hurui.me/guide/replace-to-vexip

Configures the UI provider for the professional version, enabling Vexip UI installation and providing support for multiple locales (Chinese Simplified, Chinese Traditional, English).

```ts
import type { App } from 'vue'
import { install as vexipInstall, zhCNLocale, zhTWLocale, enUSLocale } from 'vexip-ui'
import 'vexip-ui/css/index.css'
import 'vexip-ui/css/dark/index.css'
function install(app: App) {
  app.use(vexipInstall, {
    prefix: 'vxp',
  })
}
// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
const locales: Record<string, any> = {
  'zh-cn': zhCNLocale(),
  'zh-tw': zhTWLocale(),
  'en': enUSLocale(),
}
export default { install }
export { locales }
```

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

### Configure Vue App Provider for Naive UI (Base Version)

Source: https://fantastic-admin.hurui.me/guide/replace-to-naive

Modifies the Vue application provider to install Naive UI globally for the base version. This sets up the necessary context for Naive UI components.

```ts
import type { App } from 'vue'
import naive from 'naive-ui'
function install(app: App) {
  app.use(naive)
}
export default { install }
```

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

### Update and Reset Watermark Content in Vue

Source: https://fantastic-admin.hurui.me/guide/watermark

Provides an example of how to dynamically update the watermark's text and other configurations using the `useWatermarkStore` in a Vue 3 application. It also shows how to reset the watermark to its default settings.

```vue
<script setup lang="ts">
const watermarkStore = useWatermarkStore()
watermarkStore.update({
  text: '设置水印',
  // 更多设置项请查看 /src/utils/watermark.ts 中 settingsType 类型定义
})
// 重置水印，恢复到默认设置
watermarkStore.update()
</script>
```

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

### UnoCSS Example in Vue

Source: https://fantastic-admin.hurui.me/guide/resources

Demonstrates using UnoCSS utility classes for styling elements within a Vue component. It showcases classes for layout, text alignment, and animations, providing a concise way to style components.

```vue
<template>
  <div class="flex flex-1 flex-col select-none text-center all:transition-400">
    <div class="ma">
      <div class="animate-bounce-alt animate-duration-1s animate-count-infinite text-5xl fw100">
        UnoCSS
      </div>
    </div>
  </div>
</template>
```

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

### Plop 代码生成器命令

Source: https://fantastic-admin.hurui.me/guide/plop

使用 pnpm run new 命令启动 plop 代码生成器，可以选择预设的模式来快速创建项目文件，如页面、组件、store、mock 和模块。

```bash
pnpm run new
```

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

### SCSS Syntax in Vue

Source: https://fantastic-admin.hurui.me/guide/resources

Provides an example of using SCSS syntax within a Vue component's style block. It highlights SCSS features such as variables, nested selectors, and media queries for efficient and organized styling.

```vue
<style lang="scss" scoped>
$width: 500px;
.phone {
  &_title {
    width: $width;
    @media (max-width: $width) {
      width: auto;
    }
    body.is_dark & {
      color: white;
    }
  }
  img {
    display: block;
  }
}
</style>
```

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

### Git Commit Hooks 配置 (package.json)

Source: https://fantastic-admin.hurui.me/guide/coding-standard

配置 `package.json` 以集成 `simple-git-hooks` 和 `lint-staged`，在代码提交前自动执行 ESLint 和 Stylelint 检查。若 Git 仓库与项目目录不同，需调整 `pre-commit` 脚本中的路径。

```json
{
  "simple-git-hooks": {
    "pre-commit": "cd ./fantastic-admin/ && pnpm lint-staged",
    "preserveUnused": true
  }
}
```

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

### Configure Vue App Provider for Naive UI (Pro Version)

Source: https://fantastic-admin.hurui.me/guide/replace-to-naive

Modifies the Vue application provider to install Naive UI globally for the pro version, including support for multiple locales. It exports locale configurations for internationalization.

```ts
import type { App } from 'vue'
import naive, { dateEnUS, dateZhCN, dateZhTW, enUS, zhCN, zhTW } from 'naive-ui'
function install(app: App) {
  app.use(naive)
}
// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
const locales: Record<string, any> = {
  'zh-cn': {
    ui: zhCN,
    date: dateZhCN,
  },
  'zh-tw': {
    ui: zhTW,
    date: dateZhTW,
  },
  'en': {
    ui: enUS,
    date: dateEnUS,
  },
}
export default { install }
export { locales }
```

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

### Route Meta Configuration

Source: https://fantastic-admin.hurui.me/guide/file-system-route

路由的元信息（如 title, icon 等）被转移到 SFC 单文件组件的 `<route>` 标签内进行配置。支持多种元参数，部分为专业版功能。

```yaml
<route lang="yaml">
meta:
  title: "列表页"
  icon: "list"
  activeIcon: "list-active" # 专业版
  permanent: true # 专业版
  auth: ["admin", "editor"]
  activeMenu: "/example/list"
  cache: true
  noCache: true # 专业版
  copyright: "© 2023"
</route>
```
Tokens:
Raw