### GET Request Example

Source: https://doc.vben.pro/guide/essentials/server.html

Example of performing a GET request to fetch user information using the configured request client.

```typescript
import { requestClient } from '#/api/request';

export async function getUserInfoApi() {
  return requestClient.get<UserInfo>('/user/info');
}
```

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

### Install Live Server

Source: https://doc.vben.pro/guide/essentials/build.html

Install the 'live-server' globally to preview the 'dist' folder contents locally.

```bash
npm i -g live-server
```

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

### Nginx Configuration for Compression

Source: https://doc.vben.pro/guide/essentials/build.html

Example Nginx configuration to enable gzip and brotli compression for served files. Ensure necessary Nginx modules are installed.

```nginx
http {
  # 开启gzip
  gzip on;
  # 开启gzip_static
  # gzip_static 开启后可能会报错，需要安装相应的模块, 具体安装方式可以自行查询
  # 只有这个开启，vue文件打包的.gz文件才会有效果，否则不需要开启gzip进行打包
  gzip_static on;
  gzip_proxied any;
  gzip_min_length 1k;
  gzip_buffers 4 16k;
  #如果nginx中使用了多层代理 必须设置这个才可以开启gzip。
  gzip_http_version 1.0;
  gzip_comp_level 2;
  gzip_types text/plain application/javascript text/css application/xml text/javascript application/x-httpd-php image/jpeg image/gif image/png;
  gzip_vary off;
  gzip_disable "MSIE [1-6]\.";

  # 开启 brotli压缩
  # 需要安装对应的nginx模块,具体安装方式可以自行查询
  # 可以与gzip共存不会冲突
  brotli on;
  brotli_comp_level 6;
  brotli_buffers 16 8k;
  brotli_min_length 20;
  brotli_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript application/javascript image/svg+xml;
}
```

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

### Basic Route Configuration Example

Source: https://doc.vben.pro/guide/essentials/route.html

An example of a basic route configuration object with meta properties like icon and title.

```typescript
const routes = [
  {
    name: 'HomeIndex',
    path: '/home/index',
    meta: {
      icon: 'mdi:home',
      title: $t('page.home.index'),
    },
  },
];
```

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

### POST/PUT Request Examples

Source: https://doc.vben.pro/guide/essentials/server.html

Examples demonstrating how to perform POST and PUT requests to save user data. Includes a generic request method for conditional POST/PUT operations.

```typescript
import { requestClient } from '#/api/request';

export async function saveUserApi(user: UserInfo) {
  return requestClient.post<UserInfo>('/user', user);
}

export async function saveUserApi(user: UserInfo) {
  return requestClient.put<UserInfo>('/user', user);
}

export async function saveUserApi(user: UserInfo) {
  const url = user.id ? `/user/${user.id}` : '/user/';
  return requestClient.request<UserInfo>(url, {
    data: user,
    // 或者 PUT
    method: user.id ? 'PUT' : 'POST',
  });
}
```

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

### Preview with Live Server

Source: https://doc.vben.pro/guide/essentials/build.html

Navigate to the 'dist' directory and run 'live-server' to start a local preview. You can specify a port using the --port flag.

```bash
cd apps/web-antd/dist
# 本地预览，默认端口8080
live-server
# 指定端口
live-server --port=9000
```

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

### VCropper Usage Example with Various Cropping Options

Source: https://doc.vben.pro/components/common-ui/vben-cropper.html

Provides a comprehensive Vue.js example demonstrating how to use the VCropper component. It shows how to obtain cropped images as Blob objects or base64 strings, and how to export images with specific dimensions.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VCropper } from '@vben/common-ui';

const cropperRef = ref<InstanceType<typeof VCropper>>();
const imageUrl = ref('https://example.com/image.jpg');
const croppedImage = ref('');

// 获取裁剪后的 Blob 对象
const handleCropBlob = async () => {
  const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob');
  if (blob instanceof Blob) {
    // 上传到服务器或创建预览URL
    const url = URL.createObjectURL(blob);
    croppedImage.value = url;
  }
};

// 获取裁剪后的 base64 字符串
const handleCropBase64 = async () => {
  const base64 = await cropperRef.value?.getCropImage('image/png', 1, 'base64');
  if (typeof base64 === 'string') {
    croppedImage.value = base64;
  }
};

// 导出指定尺寸
const handleCropWithSize = async () => {
  const blob = await cropperRef.value?.getCropImage(
    'image/jpeg',
    0.9,
    'blob',
    200, // 目标宽度
    200, // 目标高度
  );
};
</script>

<template>
  <div>
    <VCropper
      ref="cropperRef"
      :img="imageUrl"
      :width="500"
      :height="400"
      aspect-ratio="1:1"
    />
    <button @click="handleCropBlob">裁剪</button>
    <img v-if="croppedImage" :src="croppedImage" />
  </div>
</template>
```

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

### API Request Example with Proxy

Source: https://doc.vben.pro/guide/essentials/server.html

Example of making an API request using axios with '/api' as the prefix. The request will be proxied to the configured backend server.

```typescript
import axios from 'axios';

axios.get('/api/user').then((res) => {
  console.log(res);
});
```

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

### Configure Production API URL

Source: https://doc.vben.pro/guide/essentials/server.html

Set the API endpoint in the .env.production file for production environments. This example sets it to 'https://mock-napi.vben.pro/api'.

```bash
VITE_GLOB_API_URL=https://mock-napi.vben.pro/api
```

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

### Install Lefthook Git Hooks

Source: https://doc.vben.pro/guide/project/standard.html

Install the configured Git hooks managed by lefthook. This ensures that checks are run automatically before commits and merges.

```bash
pnpm exec lefthook install
```

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

### Setup Vben Vxe Table Adapter

Source: https://doc.vben.pro/components/common-ui/vben-vxe-table.html

Configure default behaviors, custom renderers, and UI component library integration for vxe-table. This setup includes defining custom cell renderers for images and links.

```typescript
import { h } from 'vue';

import { setupVbenVxeTable, useVbenVxeGrid } from '@vben/plugins/vxe-table';

import { Button, Image } from 'antdv-next';

import { useVbenForm } from './form';

setupVbenVxeTable({
  configVxeTable: (vxeUI) => {
    vxeUI.setConfig({
      grid: {
        align: 'center',
        border: false,
        columnConfig: {
          resizable: true,
        },
        minHeight: 180,
        formConfig: {
          enabled: false,
        },
        proxyConfig: {
          autoLoad: true,
          response: {
            result: 'items',
            total: 'total',
            list: 'items',
          },
          showActiveMsg: true,
          showResponseMsg: false,
        },
        round: true,
        showOverflow: true,
        size: 'small',
      },
    });

    vxeUI.renderer.add('CellImage', {
      renderTableDefault(_renderOpts, params) {
        const { column, row } = params;
        return h(Image, { src: row[column.field] });
      },
    });

    vxeUI.renderer.add('CellLink', {
      renderTableDefault(renderOpts) {
        const { props } = renderOpts;
        return h(
          Button, 
          { size: 'small', type: 'link' }, 
          { default: () => props?.text },
        );
      },
    });
  },
  useVbenForm,
});

export { useVbenVxeGrid };

export type * from '@vben/plugins/vxe-table';
```

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

### Backend Menu Data Structure Example

Source: https://doc.vben.pro/guide/in-depth/access.html

Example of the menu data structure expected from the backend for route generation. It includes nested children and meta information like 'title' and 'noBasicLayout'.

```typescript
const dashboardMenus = [
  {
    meta: {
      order: -1,
      title: 'page.dashboard.title',
    },
    name: 'Dashboard',
    path: '/',
    redirect: '/analytics',
    children: [
      {
        name: 'Analytics',
        path: '/analytics',
        // 这里为页面的路径，需要去掉 views/ 和 .vue
        component: '/dashboard/analytics/index',
        meta: {
          affixTab: true,
          title: 'page.dashboard.analytics',
        },
      },
      {
        name: 'Workspace',
        path: '/workspace',
        component: '/dashboard/workspace/index',
        meta: {
          title: 'page.dashboard.workspace',
        },
      },
    ],
  },
  {
    name: 'Test',
    path: '/test',
    component: '/test/index',
    meta: {
      title: 'page.test',
      // 部分特殊页面如果不需要基础布局（页面顶部和侧边栏），可将noBasicLayout设置为true
      noBasicLayout: true,
    },
  },
];
```

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

### Route Refresh Example

Source: https://doc.vben.pro/guide/essentials/route.html

Demonstrates how to use the `useRefresh` hook to refresh the current route. Ensure the hook is imported before use.

```vue
<script setup lang="ts">
import { useRefresh } from '@vben/hooks';

const { refresh } = useRefresh();

// 刷新当前路由
refresh();
</script>
```

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

### Adding a New Dynamic Configuration Variable

Source: https://doc.vben.pro/guide/essentials/settings.html

Provides an example of adding a new VITE_GLOB_* prefixed variable to environment files and defining its type for dynamic configuration.

```bash
VITE_GLOB_OTHER_API_URL=https://mock-napi.vben.pro/other-api
```

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

### Vben Query Form Example

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Demonstrates the creation and configuration of a query form using the useVbenForm hook. This includes defining various input types like text, password, number with suffix, select, and date picker. It also shows how to set up submission handlers and layout options.

```vue
<script lang="ts" setup>
import { message } from 'antdv-next';

import { useVbenForm } from '#/adapter/form';

const [QueryForm] = useVbenForm({
  // 默认展开
  collapsed: false,
  // 所有表单项共用，可单独在表单内覆盖
  commonConfig: {
    // 所有表单项
    componentProps: {
      class: 'w-full',
    },
  },
  // 提交函数
  handleSubmit: onSubmit,
  // 垂直布局，label和input在不同行，值为vertical
  // 水平布局，label和input在同一行
  layout: 'horizontal',
  schema: [
    {
      // 组件需要在 #/adapter.ts内注册，并加上类型
      component: 'Input',
      // 对应组件的参数
      componentProps: {
        placeholder: '请输入用户名',
      },
      // 字段名
      fieldName: 'username',
      // 界面显示的label
      label: '字符串',
    },
    {
      component: 'InputPassword',
      componentProps: {
        placeholder: '请输入密码',
      },
      fieldName: 'password',
      label: '密码',
    },
    {
      component: 'InputNumber',
      componentProps: {
        placeholder: '请输入',
      },
      fieldName: 'number',
      label: '数字(带后缀)',
      suffix: () => '¥',
    },
    {
      component: 'Select',
      componentProps: {
        allowClear: true,
        filterOption: true,
        options: [
          {
            label: '选项1',
            value: '1',
          },
          {
            label: '选项2',
            value: '2',
          },
        ],
        placeholder: '请选择',
        showSearch: true,
      },
      fieldName: 'options',
      label: '下拉选',
    },
    {
      component: 'DatePicker',
      fieldName: 'datePicker',
      label: '日期选择框',
    },
  ],
  // 是否可展开
  showCollapseButton: true,
  submitButtonOptions: {
    content: '查询',
  },
  wrapperClass: 'grid-cols-1 md:grid-cols-2',
});
function onSubmit(values: Record<string, any>) {
  message.success({
    content: `form values: ${JSON.stringify(values)}`,
  });
}
</script>

<template>
  <QueryForm />
</template>

```

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

### Configure Lefthook Commands for Pre-Commit

Source: https://doc.vben.pro/guide/project/standard.html

Example configuration for lefthook's pre-commit hook, demonstrating parallel execution of linting and formatting commands for staged JavaScript/TypeScript files.

```yaml
pre-commit:
  parallel: true
  commands:
    lint-js:
      run: pnpm oxfmt {staged_files} && pnpm oxlint --fix {staged_files} && pnpm eslint --cache --fix {staged_files}
      glob: '*.{js,jsx,ts,tsx}'
```

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

### Install External Dependency with pnpm

Source: https://doc.vben.pro/guide/essentials/external-module.html

Install an external module like 'antdv-next' into a specific package using pnpm. Ensure you are in the correct package directory before running the command.

```bash
# cd /path/to/your/package
pnpm add antdv-next
```

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

### Basic Vben Vxe Table Usage

Source: https://doc.vben.pro/components/common-ui/vben-vxe-table.html

Create a basic table using `useVbenVxeGrid` and demonstrate dynamic manipulation of table options like borders, stripes, and loading states. This example includes event handling for cell clicks.

```vue
<script lang="ts" setup>
import type { VxeGridListeners, VxeGridProps } from '#/adapter/vxe-table';

import { Button, message } from 'antdv-next';

import { useVbenVxeGrid } from '#/adapter/vxe-table';

import { MOCK_TABLE_DATA } from '../table-data';

interface RowType {
  address: string;
  age: number;
  id: number;
  name: string;
  nickname: string;
  role: string;
}

const gridOptions: VxeGridProps<RowType> = {
  columns: [
    { title: '序号', type: 'seq', width: 50 },
    { field: 'name', title: 'Name' },
    { field: 'age', sortable: true, title: 'Age' },
    { field: 'nickname', title: 'Nickname' },
    { field: 'role', title: 'Role' },
    { field: 'address', showOverflow: true, title: 'Address' },
  ],
  data: MOCK_TABLE_DATA,
  pagerConfig: {
    enabled: false,
  },
  sortConfig: {
    multiple: true,
  },
};

const gridEvents: VxeGridListeners<RowType> = {
  cellClick: ({ row }) => {
    message.info(`cell-click: ${row.name}`);
  },
};

const [Grid, gridApi] = useVbenVxeGrid({ gridEvents, gridOptions });

const showBorder = gridApi.useStore((state) => state.gridOptions?.border);
const showStripe = gridApi.useStore((state) => state.gridOptions?.stripe);

function changeBorder() {
  gridApi.setGridOptions({
    border: !showBorder.value,
  });
}

function changeStripe() {
  gridApi.setGridOptions({
    stripe: !showStripe.value,
  });
}

function changeLoading() {
  gridApi.setLoading(true);
  setTimeout(() => {
    gridApi.setLoading(false);
  }, 2000);
}
</script>

<template>
  <!-- 此处的`vp-raw` 是为了适配文档的展示效果，实际使用时不需要 -->
  <div class="vp-raw w-full">
    <Grid>
      <template #toolbar-tools>
        <Button class="mr-2" type="primary" @click="changeBorder">
          {{ showBorder ? '隐藏' : '显示' }}边框
        </Button>
        <Button class="mr-2" type="primary" @click="changeLoading">
          显示loading
        </Button>
        <Button class="mr-2" type="primary" @click="changeStripe">
          {{ showStripe ? '隐藏' : '显示' }}斑马纹
        </Button>
      </template>
    </Grid>
  </div>
</template>

```

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

### Basic Vben Form Usage

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Demonstrates the fundamental setup of a Vben Form using the `useVbenForm` hook. It includes defining common configurations, a submit handler, layout options, and a comprehensive schema for various input fields. This snippet is suitable for creating a standard form with diverse input types.

```vue
<script lang="ts" setup>
import { message } from 'antdv-next';

import { useVbenForm } from '#/adapter/form';

const [BaseForm] = useVbenForm({
  // 所有表单项共用，可单独在表单内覆盖
  commonConfig: {
    // 所有表单项
    componentProps: {
      class: 'w-full',
    },
  },
  // 提交函数
  handleSubmit: onSubmit,
  // 垂直布局，label和input在不同行，值为vertical
  // 水平布局，label和input在同一行
  layout: 'horizontal',
  schema: [
    {
      // 组件需要在 #/adapter.ts内注册，并加上类型
      component: 'Input',
      // 对应组件的参数
      componentProps: {
        placeholder: '请输入用户名',
      },
      // 字段名
      fieldName: 'username',
      // 界面显示的label
      label: '字符串',
    },
    {
      component: 'InputPassword',
      componentProps: {
        placeholder: '请输入密码',
      },
      fieldName: 'password',
      label: '密码',
    },
    {
      component: 'InputNumber',
      componentProps: {
        placeholder: '请输入',
      },
      fieldName: 'number',
      label: '数字(带后缀)',
      suffix: () => '¥',
    },
    {
      component: 'Select',
      componentProps: {
        allowClear: true,
        filterOption: true,
        options: [
          {
            label: '选项1',
            value: '1',
          },
          {
            label: '选项2',
            value: '2',
          },
        ],
        placeholder: '请选择',
        showSearch: true,
      },
      fieldName: 'options',
      label: '下拉选',
    },
    {
      component: 'RadioGroup',
      componentProps: {
        options: [
          {
            label: '选项1',
            value: '1',
          },
          {
            label: '选项2',
            value: '2',
          },
        ],
      },
      fieldName: 'radioGroup',
      label: '单选组',
    },
    {
      component: 'Radio',
      fieldName: 'radio',
      label: '',
      renderComponentContent: () => {
        return {
          default: () => ['Radio'],
        };
      },
    },
    {
      component: 'CheckboxGroup',
      componentProps: {
        name: 'cname',
        options: [
          {
            label: '选项1',
            value: '1',
          },
          {
            label: '选项2',
            value: '2',
          },
        ],
      },
      fieldName: 'checkboxGroup',
      label: '多选组',
    },
    {
      component: 'Checkbox',
      fieldName: 'checkbox',
      label: '',
      renderComponentContent: () => {
        return {
          default: () => ['我已阅读并同意'],
        };
      },
    },
    {
      component: 'Mentions',
      componentProps: {
        options: [
          {
            label: 'afc163',
            value: 'afc163',
          },
          {
            label: 'zombieJ',
            value: 'zombieJ',
          },
        ],
        placeholder: '请输入',
      },
      fieldName: 'mentions',
      label: '提及',
    },
    {
      component: 'Rate',
      fieldName: 'rate',
      label: '评分',
    },
    {
      component: 'Switch',
      componentProps: {
        class: 'w-auto',
      },
      fieldName: 'switch',
      label: '开关',
    },
    {
      component: 'DatePicker',
      fieldName: 'datePicker',
      label: '日期选择框',
    },
    {
      component: 'RangePicker',
      fieldName: 'rangePicker',
      label: '范围选择器',
    },
    {
      component: 'TimePicker',
      fieldName: 'timePicker',
      label: '时间选择框',
    },
    {
      component: 'TreeSelect',
      componentProps: {
        allowClear: true,
        placeholder: '请选择',
        showSearch: true,
        treeData: [
          {
            label: 'root 1',
            value: 'root 1',
            children: [
              {
                label: 'parent 1',
                value: 'parent 1',
                children: [
                  {
                    label: 'parent 1-0',
                    value: 'parent 1-0',
                    children: [
                      {
                        label: 'my leaf',
                        value: 'leaf1',
                      },
                      {
                        label: 'your leaf',
                        value: 'leaf2',
                      },
                    ],
                  },
                  {
                    label: 'parent 1-1',
                    value: 'parent 1-1',
                  },
                ],
              },
              {
                label: 'parent 2',
                value: 'parent 2',
              },
            ],
          },
        ],
        treeNodeFilterProp: 'label',
      },
      fieldName: 'treeSelect',
      label: '树选择',
    },
  ],
  wrapperClass: 'grid-cols-1',
});

function onSubmit(values: Record<string, any>) {
  message.success({
    content: `form values: ${JSON.stringify(values)}`,
  });
}
</script>

<template>
  <BaseForm />
</template>
```

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

### Fixed Aspect Ratio Image Cropping

Source: https://doc.vben.pro/components/common-ui/vben-cropper.html

Shows how to use VCropper with a fixed aspect ratio using the `aspectRatio` prop. This example includes a dropdown to select different aspect ratios and demonstrates cropping with the chosen ratio. Ensure proper cleanup of object URLs.

```vue
<script lang="ts" setup>
import { onBeforeUnmount, ref } from 'vue';

import { VCropper } from '@vben/common-ui';

const cropperRef = ref<InstanceType<typeof VCropper>>();
const aspectRatio = ref('1:1');
const imageUrl = ref('https://picsum.photos/seed/cropper-ratio/800/600');
const croppedImage = ref('');

const aspectOptions = [
  { label: '1:1 (正方形)', value: '1:1' },
  { label: '16:9 (宽屏)', value: '16:9' },
  { label: '4:3 (标准)', value: '4:3' },
  { label: '3:4 (竖版)', value: '3:4' },
  { label: '3:2 (照片)', value: '3:2' },
];

// 释放旧的 object URL 以避免内存泄漏
const revokeCroppedImage = () => {
  if (croppedImage.value?.startsWith('blob:')) {
    URL.revokeObjectURL(croppedImage.value);
  }
};

const handleCrop = async () => {
  const blob = await cropperRef.value?.getCropImage('image/jpeg', 0.9, 'blob');
  if (blob instanceof Blob) {
    // 释放旧的 URL
    revokeCroppedImage();
    croppedImage.value = URL.createObjectURL(blob);
  }
};

const handleReset = () => {
  // 释放 URL
  revokeCroppedImage();
  croppedImage.value = '';
  imageUrl.value = `https://picsum.photos/seed/cropper-${Date.now()}/800/600`;
};

// 组件卸载时清理
onBeforeUnmount(() => {
  revokeCroppedImage();
});
</script>

<template>
  <div>
    <div class="mb-4">
      <label class="text-sm text-gray-500 mr-2">选择比例:</label>
      <select v-model="aspectRatio" class="px-3 py-1 border rounded text-sm">
        <option
          v-for="option in aspectOptions"
          :key="option.value"
          :value="option.value"
        >
          {{ option.label }}
        </option>
      </select>
    </div>

    <VCropper
      ref="cropperRef"
      :img="imageUrl"
      :width="500"
      :height="300"
      :aspect-ratio="aspectRatio"
    />

    <div class="mt-4 flex gap-2">
      <button
        class="px-4 py-2 bg-blue-500 rounded hover:bg-blue-600"
        @click="handleCrop"
      >
        裁剪图片
      </button>
      <button
        class="px-4 py-2 bg-gray-500 rounded hover:bg-gray-600"
        @click="handleReset"
      >
        重置
      </button>
    </div>

    <div v-if="croppedImage" class="mt-4">
      <p class="text-sm text-gray-500 mb-2">
        裁剪结果 (比例: {{ aspectRatio }}):
      </p>
      <img :src="croppedImage" class="max-w-full rounded border" />
    </div>

    <div class="mt-4">
      <p class="text-sm text-gray-500">提示:</p>
      <ul class="mt-2 text-xs text-gray-400 list-disc pl-4">
        <li>设置固定比例后，裁剪框始终维持该比例</li>
        <li>切换比例会自动重新计算裁剪框大小</li>
        <li>比例格式为 "宽:高"，如 "16:9"</li>
      </ul>
    </div>
  </div>
</template>

```

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

### Navigate with Custom Page Key

Source: https://doc.vben.pro/guide/essentials/route.html

Example of navigating to a route and setting a custom `pageKey` in the query parameters to control tab identification. This method has high priority.

```vue
<script setup lang="ts">
import { useRouter } from 'vue-router';
// 跳转路由
const router = useRouter();
router.push({
  path: 'path',
  query: {
    pageKey: 'key',
  },
});

```

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

### Nginx Configuration for Static File Deployment

Source: https://doc.vben.pro/guide/essentials/build.html

Example Nginx configuration for serving static files from the 'dist' folder. It includes cache control for HTML files and sets the root directory.

```nginx
location / {
  # 不缓存html，防止程序更新后缓存继续生效
  if ($request_filename ~* .*
(htm|html)$) {
    add_header Cache-Control "private, no-store, no-cache, must-revalidate, proxy-revalidate";
    access_log on;
  }
  # 这里是vue打包文件dist内的文件的存放路径
  root   /srv/www/project/;
  index  index.html index.htm;
}
```

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

### Drawer API Definition

Source: https://doc.vben.pro/components/common-ui/vben-drawer.html

Provides a TypeScript example of the `useVbenDrawer` hook, showing how to destructure the drawer component and its API. This snippet outlines the structure for accessing drawer properties and events.

```typescript
// Drawer 为弹窗组件
// drawerApi 为弹窗的方法
const [Drawer, drawerApi] = useVbenDrawer({
  // 属性
  // 事件
});
```

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

### Customizing Prefix and Separator for CountToAnimator

Source: https://doc.vben.pro/components/common-ui/vben-count-to-animator.html

Control the display format using `prefix`, `suffix`, `separator`, and `decimal`. This example shows how to add a currency prefix and a custom separator.

```vue
<script lang="ts" setup>
import { VbenCountToAnimator } from '@vben/common-ui';
</script>
<template>
  <VbenCountToAnimator
    :duration="3000"
    :end-val="2000000"
    :start-val="1"
    prefix="$"
    separator="/"
  />
</template>
```

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

### Remote Data Loading with Vben Vxe Table

Source: https://doc.vben.pro/components/common-ui/vben-vxe-table.html

Configure the proxyConfig.ajax.query to implement remote data loading. This example shows how to fetch data asynchronously using a mock API and display it in a Vxe Grid.

```vue
<script lang="ts" setup>
import type { DemoTableApi } from '../mock-api';

import type { VxeGridProps } from '#/adapter/vxe-table';

import { Button } from 'antdv-next';

import { useVbenVxeGrid } from '#/adapter/vxe-table';

import { MOCK_API_DATA } from '../table-data';

interface RowType {
  category: string;
  color: string;
  id: string;
  price: string;
  productName: string;
  releaseDate: string;
}

// 数据实例
// const MOCK_TREE_TABLE_DATA = [
//   {
//     date: '2020-08-01',
//     id: 10_000,
//     name: 'Test1',
//     parentId: null,
//     size: 1024,
//     type: 'mp3',
//   },
// ]

const sleep = (time = 1000) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(true);
    }, time);
  });
};

/**
 * 获取示例表格数据
 */
async function getExampleTableApi(params: DemoTableApi.PageFetchParams) {
  return new Promise<{ items: any; total: number }>((resolve) => {
    const { page, pageSize } = params;
    const items = MOCK_API_DATA.slice((page - 1) * pageSize, page * pageSize);

    sleep(1000).then(() => {
      resolve({
        total: items.length,
        items,
      });
    });
  });
}

const gridOptions: VxeGridProps<RowType> = {
  checkboxConfig: {
    highlight: true,
    labelField: 'name',
  },
  columns: [
    { title: '序号', type: 'seq', width: 50 },
    { align: 'left', title: 'Name', type: 'checkbox', width: 100 },
    { field: 'category', title: 'Category' },
    { field: 'color', title: 'Color' },
    { field: 'productName', title: 'Product Name' },
    { field: 'price', title: 'Price' },
    { field: 'releaseDate', formatter: 'formatDateTime', title: 'DateTime' },
  ],
  exportConfig: {},
  // height: 'auto', // 如果设置为 auto，则必须确保存在父节点且不允许存在相邻元素，否则会出现高度闪动问题
  keepSource: true,
  proxyConfig: {
    ajax: {
      query: async ({ page }) => {
        return await getExampleTableApi({
          page: page.currentPage,
          pageSize: page.pageSize,
        });
      },
    },
  },
  toolbarConfig: {
    custom: true,
    export: true,
    // import: true,
    refresh: true,
    zoom: true,
  },
};

const [Grid, gridApi] = useVbenVxeGrid({
  gridOptions,
});
</script>

<template>
  <div class="vp-raw w-full">
    <Grid>
      <template #toolbar-tools>
        <Button class="mr-2" type="primary" @click="() => gridApi.query()">
          刷新当前页面
        </Button>
        <Button type="primary" @click="() => gridApi.reload()">
          刷新并返回第一页
        </Button>
      </template>
    </Grid>
  </div>
</template>

```

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

### VbenTiptap with Image Upload Configuration

Source: https://doc.vben.pro/components/common-ui/vben-tiptap.html

Configures VbenTiptap to handle image uploads using a custom upload function. This example demonstrates setting accepted file types, max size, and simulating upload progress.

```vue
<script lang="ts" setup>
import { ref } from 'vue';

import { type ImageUploadOptions, VbenTiptap } from '@vben/plugins/tiptap';

const content = ref('');

// Mock upload function with progress simulation
const imageUpload: ImageUploadOptions = {
  accept: 'image/jpeg,image/png,image/gif,image/webp',
  maxSize: 5 * 1024 * 1024, // 5MB
  upload: async (_file, onProgress) => {
    // Simulate upload progress
    for (let i = 0; i <= 100; i += 10) {
      await new Promise((resolve) => setTimeout(resolve, 100));
      onProgress?.(i);
    }

    // Return a mock image URL (using picsum for demo)
    return `https://picsum.photos/seed/${Date.now()}/800/400`;
  },
  onUploadError: (error) => {
    console.error('Upload error:', error);
  },
};
</script>

<template>
  <div>
    <VbenTiptap
      v-model="content"
      :image-upload="imageUpload"
      placeholder="尝试拖拽或粘贴图片..."
    />
    <div class="mt-4">
      <p class="text-sm text-gray-500">提示:</p>
      <ul class="mt-2 text-xs text-gray-400 list-disc pl-4">
        <li>点击工具栏图片按钮可选择本地上传或 URL 插入</li>
        <li>拖拽图片到编辑器区域可直接上传</li>
        <li>粘贴图片也会触发上传</li>
        <li>上传过程中会显示进度条</li>
      </ul>
    </div>
  </div>
</template>
```

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

### Preview Project Locally (Recommended)

Source: https://doc.vben.pro/guide/essentials/build.html

Use this command to preview the built project locally before deployment. Access the preview at http://localhost:4173.

```bash
pnpm preview
```

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

### Vben Form with Value Formatting

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Demonstrates using valueFormat with RangePicker and DatePicker components to transform values. Includes examples for splitting a date range into start and end times, and directly returning a timestamp. This snippet requires the useVbenForm hook and Ant Design Vue components.

```vue
<script lang="ts" setup>
import { computed, nextTick, onMounted, ref, watch } from 'vue';

import { Button, Card, message, Space, Tag } from 'antdv-next';

import { useVbenForm } from '#/adapter/form';

const transformedValues = ref<Record<string, any>>({});
const liveValues = ref<Record<string, any>>({});

const [Form, formApi] = useVbenForm({
  commonConfig: {
    componentProps: {
      class: 'w-full',
    },
  },
  handleSubmit,
  schema: [
    {
      component: 'RangePicker',
      fieldName: 'reportRange',
      help: '通过 setValue 拆分为 startTime / endTime，并移除原字段',
      label: '统计时间范围',
      valueFormat(value, setValue) {
        setValue('startTime', value?.[0]?.valueOf());
        setValue('endTime', value?.[1]?.valueOf());
      },
    },
    {
      component: 'DatePicker',
      fieldName: 'deadline',
      help: '直接 return 时间戳，保留原字段名',
      label: '截止时间',
      valueFormat(value) {
        return value?.valueOf();
      },
    },
    {
      component: 'Input',
      componentProps: {
        placeholder: '请输入关键字',
      },
      fieldName: 'keyword',
      label: '关键字',
    },
  ],
  wrapperClass: 'grid-cols-1 md:grid-cols-2',
});

const liveValuesPreview = computed(() => formatJsonPreview(liveValues.value));

const transformedValuesPreview = computed(() => {
  return formatJsonPreview(transformedValues.value);
});

function formatJsonPreview(value: Record<string, any>) {
  return JSON.stringify(
    value,
    (_key, currentValue) => {
      return isFormattableDateValue(currentValue)
        ? currentValue.format('YYYY-MM-DD HH:mm:ss')
        : currentValue;
    },
    2,
  );
}

function isFormattableDateValue(
  value: unknown,
): value is { format: (template: string) => string } {
  return !!value && typeof value === 'object' && 'format' in value;
}

async function handleInspectValues() {
  await syncPreviewValues();
  message.success('已刷新 getValues 输出');
}

function handleSubmit(values: Record<string, any>) {
  transformedValues.value = values;
  message.success({
    content: `getValues output: ${JSON.stringify(values)}`,
  });
}

async function syncPreviewValues(values?: Record<string, any>) {
  liveValues.value = values ?? formApi.form?.values ?? {};
  transformedValues.value = await formApi.getValues();
}

onMounted(async () => {
  await nextTick();
  watch(
    () => formApi.form?.values,
    async (values) => {
      await syncPreviewValues(values);
    },
    {
      deep: true,
      immediate: true,
    },
  );
});
</script>

<template>
  <div class="space-y-4">
    <div class="flex flex-wrap gap-2">
      <Tag color="processing">return 值：回写当前字段</Tag>
      <Tag color="success">setValue：拆分写入其他字段</Tag>
      <Tag color="warning">return undefined：保持原字段删除</Tag>
    </div>

    <Card title="valueFormat 示例">
      <template #extra>
        <Space wrap>
          <Button type="primary" @click="handleInspectValues">
            查看 getValues 输出
          </Button>
        </Space>
      </template>
      <Form />
    </Card>

    <div class="grid gap-4 lg:grid-cols-2">
      <Card title="原始 form.values（组件值）">
        <pre class="bg-muted overflow-auto rounded-md p-4 text-sm">{{
          liveValuesPreview
        }}</pre>
      </Card>
      <Card title="getValues / submit 输出（valueFormat 后）">
        <pre class="bg-muted overflow-auto rounded-md p-4 text-sm">{{
          transformedValuesPreview
        }}</pre>
      </Card>
    </div>
  </div>
</template>

```

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

### DELETE Request Example

Source: https://doc.vben.pro/guide/essentials/server.html

Example of performing a DELETE request to remove a user by their ID.

```typescript
import { requestClient } from '#/api/request';

export async function deleteUserApi(userId: number) {
  return requestClient.delete<boolean>(`/user/${userId}`);
}
```

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

### Build Project

Source: https://doc.vben.pro/guide/essentials/build.html

Execute this command in the project root to build the project for production. The output will be in the 'dist' folder.

```bash
pnpm build
```

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

### Run Documentation Locally

Source: https://doc.vben.pro/guide/essentials/development.html

Execute this command in the project root to run the documentation site locally, allowing for adjustments and previews.

```bash
pnpm dev:docs
```

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

### Basic Drawer Usage

Source: https://doc.vben.pro/components/common-ui/vben-drawer.html

Demonstrates how to create and open a basic drawer component using the `useVbenDrawer` hook.

```vue
<script lang="ts" setup>
import { useVbenDrawer, VbenButton } from '@vben/common-ui';

const [Drawer, drawerApi] = useVbenDrawer();
</script>
<template>
  <div>
    <VbenButton @click="() => drawerApi.open()">Open</VbenButton>
    <Drawer class="w-150" title="基础示例"> drawer content </Drawer>
  </div>
</template>
```

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

### Environment File Types

Source: https://doc.vben.pro/guide/essentials/settings.html

Lists the different types of .env files and their loading rules, consistent with Vite's environment variable handling.

```bash
.env                # 在所有的环境中被载入
.env.local          # 在所有的环境中被载入，但会被 git 忽略
.env.[mode]         # 只在指定的模式中被载入
.env.[mode].local   # 只在指定的模式中被载入，但会被 git 忽略
```

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

### Complex Zod Validation with Refinement

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Example of a complex Zod validation involving minimum length and a custom refinement check.

```typescript
// 复杂校验
{
  z.string()
    .min(1, { message: '请输入' })
    .refine((value) => value === '123', {
      message: '值必须为123',
    });
}
```

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

### Accessing Dynamic Configuration

Source: https://doc.vben.pro/guide/essentials/settings.html

Illustrates how to retrieve dynamic configuration values using the useAppConfig hook, passing environment variables and production status.

```typescript
const { apiURL } = useAppConfig(import.meta.env, import.meta.env.PROD);
```

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

### Form Dependencies Configuration

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Example of configuring form item dependencies using the `dependencies` property in the schema for dynamic field behavior.

```typescript
dependencies: {
  // 触发字段。只有这些字段值变动时，联动才会触发
  triggerFields: ['name'],
  // 动态判断当前字段是否需要显示，不显示则直接销毁
  if(values,formApi){},
  // 动态判断当前字段是否需要显示，不显示用css隐藏
  show(values,formApi){},
  // 动态判断当前字段是否需要禁用
  disabled(values,formApi){},
  // 字段变更时，都会触发该函数
  trigger(values,formApi){},
  // 动态rules
  rules(values,formApi){},
  // 动态必填
  required(values,formApi){},
  // 动态组件参数
  componentProps(values,formApi){},
}
```

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

### Predefined Form Validation Rule: Required

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Example of using the predefined 'required' rule for form validation, typically used for mandatory fields.

```typescript
{
  rules: 'required';
}
```

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

### Accessing VCropper Methods via Ref

Source: https://doc.vben.pro/components/common-ui/vben-cropper.html

Demonstrates how to get a reference to the VCropper component using `ref` in Vue.js to call its methods, such as `getCropImage`.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VCropper } from '@vben/common-ui';

const cropperRef = ref<InstanceType<typeof VCropper>>();

const handleCrop = async () => {
  const result = await cropperRef.value?.getCropImage();
  // result 为 Blob 或 base64 字符串
};
</script>
```

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

### Predefined Form Validation Rule: Select Required

Source: https://doc.vben.pro/components/common-ui/vben-form.html

Example of using the predefined 'selectRequired' rule, suitable for fields like dropdowns where a selection is mandatory.

```typescript
{
  rules: 'selectRequired';
}
```

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

### Basic Usage of Vben Descriptions

Source: https://doc.vben.pro/components/common-ui/vben-descriptions.html

Demonstrates the basic usage of Vben Descriptions by passing an array of items to the `items` prop. Each item includes a `label` and `content`. Columns adapt to breakpoints by default.

```vue
<script lang="ts" setup>
import { VbenDescriptions } from '@vben/common-ui';

const items = [
  { content: 'Vben', label: '用户名' },
  { content: '13800138000', label: '手机号' },
  { content: '中国 · 杭州', label: '居住地' },
  { content: '前端工程师', label: '职位' },
  {
    content: '这是一段较长的备注信息，用于演示跨列展示。',
    label: '备注',
    span: 3,
  },
];
</script>
<template>
  <VbenDescriptions :items="items" />
</template>
```

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

### Nginx Configuration for API Proxy

Source: https://doc.vben.pro/guide/essentials/build.html

Example Nginx configuration to proxy API requests from '/api' to your backend server, effectively handling cross-origin issues.

```nginx
server {
  listen       8080;
  server_name  localhost;
  # 接口代理，用于解决跨域问题
  location /api {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    # 后台接口地址
    proxy_pass http://110.110.1.1:8080/api;
    rewrite "^/api/(.*)$" /$1 break;
    proxy_redirect default;
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Headers X-Requested-With;
    add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
  }
}
```

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

### Implementing useAppConfig for New Variable

Source: https://doc.vben.pro/guide/essentials/settings.html

Demonstrates how to update the useAppConfig function to include and return the newly added configuration variable.

```typescript
export function useAppConfig(
  env: Record<string, any>,
  isProduction: boolean,
): ApplicationConfig {
  // 生产环境下，直接使用 window._VBEN_ADMIN_PRO_APP_CONF_ 全局变量
  const config = isProduction
    ? window._VBEN_ADMIN_PRO_APP_CONF_
    : (env as VbenAdminProAppConfigRaw);

  const { VITE_GLOB_API_URL, VITE_GLOB_OTHER_API_URL } = config; 

  return {
    apiURL: VITE_GLOB_API_URL,
    otherApiURL: VITE_GLOB_OTHER_API_URL, 
  };
}
```