### Install IIP UI Utils Package

Source: https://iip-ui-docs.netlify.app/utils/utils

Instructions on how to install the @bingwu/iip-ui-utils package using pnpm. This is the first step to using the utility functions in your project.

```bash
# 安装工具包
pnpm add @bingwu/iip-ui-utils
```

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

### Usage Example

Source: https://iip-ui-docs.netlify.app/components/dialog-select

A TypeScript example demonstrating how to use the component and access its properties.

```APIDOC
## Usage Example

### Description

Example of how to use the component and its instance properties.

### Code Example

```typescript
import type { DialogSelectInstance } from '@bingwu/iip-ui-components'

interface EmployeeRow {
  id: number
  name: string
}

const dialogRef = ref<DialogSelectInstance<EmployeeRow>>()

// ✅ dialogRef.value.tableData type is Readonly<Ref<EmployeeRow[]>>
```
```

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

### Component Usage Example

Source: https://iip-ui-docs.netlify.app/components/dropdown-list

Demonstrates how to use the IipDropdownList component with basic configuration and event handling.

```APIDOC
## Component Usage Example

### Basic Usage

```vue
<template>
  <div>
    <IipDropdownList
      ref="dropdownRef"
      :dropdown-list="dropdownList"
      :dropdown-props="{ trigger: 'click', onCommand: handleCommand }"
    >
      <el-button type="primary">操作</el-button>
    </IipDropdownList>

    <el-button @click="handleShowDropdown">显示下拉菜单</el-button>
    <el-button @click="handleHideDropdown">隐藏下拉菜单</el-button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { IipDropdownList } from '@bingwu/iip-ui-components'
import type { DropdownListInstance, DropdownListItemType } from '@bingwu/iip-ui-components'

const dropdownRef = ref<DropdownListInstance>()

const dropdownList: DropdownListItemType[] = [
  { content: '查看', command: 'view', show: true },
  { content: '编辑', command: 'edit', show: true },
  { content: '删除', command: 'delete', show: true }
]

const handleCommand = (command: string | number | object) => {
  console.log('执行操作:', command)
}

const handleShowDropdown = () => {
  // 调用 Element Plus Dropdown 的 handleOpen 方法
  dropdownRef.value?.handleOpen?.()
}

const handleHideDropdown = () => {
  // 调用 Element Plus Dropdown 的 handleClose 方法
  dropdownRef.value?.handleClose?.()
}
</script>
```

### Dynamic Configuration with Closures

This example shows how to use closures to capture data and dynamically configure the dropdown list.

```typescript
// 1. Define data type
interface Order {
  id: number
  orderNo: string
  status: '待支付' | '已支付' | '已发货'
  amount: number
}

// 2. Define dropdown list generation function (captures row data via closure)
const getOrderDropdownList = (row: Order): DropdownListItemType[] => {
  return [
    { content: '查看详情', command: 'view', show: true },
    {
      content: '确认支付',
      command: 'pay',
      show: row.status === '待支付'
    },
    {
      content: `订单金额：¥${row.amount}`,
      command: 'detail',
      show: true
    }
  ]
}

// 3. Use in template
/*
<IipDropdownList
  :dropdown-list="getOrderDropdownList(row)"
  :dropdown-props="{
    trigger: 'click',
    onCommand: command => handleCommand(command, row)
  }"
/>
*/
```
```

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

### VXE-Table Plugin Installation and Registration for IIP UI Components

Source: https://iip-ui-docs.netlify.app/guide/quickstart

Provides the necessary steps to install and correctly register the dependencies for the Table component within IIP UI, which relies on vxe-table. This includes installing `vxe-table`, `vxe-pc-ui`, and `xe-utils`, and then importing and using `VxeUITable` and `VxePCUI` with the Vue application instance.

```typescript
// 确保已安装依赖
// pnpm add vxe-table@^4.15.6 vxe-pc-ui@~4.8.15 xe-utils@^3.7.8

// 正确注册插件（顺序不影响）
import VxeUITable from 'vxe-table'
import VxePCUI from 'vxe-pc-ui'
import IipUI from '@bingwu/iip-ui-components'

app.use(VxeUITable)
app.use(VxePCUI)
app.use(IipUI)
```

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

### Use Utility Functions from IIP UI Utils

Source: https://iip-ui-docs.netlify.app/guide/quickstart

Demonstrates how to manually import and use utility functions provided by the '@bingwu/iip-ui-utils' package. Examples include debouncing a function, checking email validity, and performing a deep clone.

```typescript
// Manual import
import { debounce, isEmail, deepClone } from '@bingwu/iip-ui-utils'

// Usage examples
const debouncedFn = debounce(() => {}, 300)
const isValid = isEmail('test@example.com')
```

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

### Generic Usage Example for PaginationSelect

Source: https://iip-ui-docs.netlify.app/components/pagination-select

Demonstrates how to use generics with the PaginationSelect component in TypeScript. This example shows defining custom option types, how `fetchData` parameters are inferred, and how component events and instances benefit from generic type safety.

```typescript
// 1. 定义选项数据类型
interface UserOption {
  id: number
  name: string
  email: string
}

// 2. fetchData 参数会自动推导
const fetchData = async (
  params: FetchDataParams<UserOption>
): Promise<FetchDataResult<UserOption>> => {
  // ✅ params.page: number (必填)
  // ✅ params.pageSize: number (必填)
  // ✅ params.keyword: string (必填)
  // ✅ params.name?: string (可选)
  // ✅ params.email?: string (可选)
  // ❌ params.foo - 类型错误，不存在的字段

  const { page, pageSize, keyword, name, email } = params
  // ... 业务逻辑
  return { data: [], total: 0 }
}

// 3. 组件使用时类型完全推导
const selectedUser = ref<UserOption | null>(null)

// 4. change 事件类型推导
const handleChange = (value: UserOption | null, option?: OptionItem<UserOption>) => {
  // ✅ value 和 option 类型已推导
  console.log(value, option)
}

// 5. 组件实例类型推导
const selectRef = ref<PaginationSelectInstance<UserOption>>()
// ✅ selectRef.value.options 类型为 Readonly<Ref<OptionItem<UserOption>[]>>
```

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

### Form Validation Example (TypeScript)

Source: https://iip-ui-docs.netlify.app/utils/utils

Shows how to implement form validation logic using the imported validation functions from '@bingwu/iip-ui-utils'. This example defines an interface for a registration form and a validation function that checks for email, phone, password strength, and password confirmation. It returns an object indicating validity and any errors found.

```typescript
import { isEmail, isPhone, getPasswordStrength } from '@bingwu/iip-ui-utils'

// 用户注册表单验证
interface RegisterForm {
  email: string
  phone: string
  password: string
  confirmPassword: string
}

function validateRegisterForm(form: RegisterForm) {
  const errors: string[] = []

  // 验证邮箱
  if (!form.email) {
    errors.push('邮箱不能为空')
  } else if (!isEmail(form.email)) {
    errors.push('请输入有效的邮箱地址')
  }

  // 验证手机号
  if (!form.phone) {
    errors.push('手机号不能为空')
  } else if (!isPhone(form.phone)) {
    errors.push('请输入有效的手机号')
  }

  // 验证密码
  if (!form.password) {
    errors.push('密码不能为空')
  } else {
    const strength = getPasswordStrength(form.password)
    if (strength < 3) {
      errors.push('密码强度太低，请包含大小写字母和数字')
    }
  }

  // 验证确认密码
  if (form.password !== form.confirmPassword) {
    errors.push('两次输入的密码不一致')
  }

  return {
    valid: errors.length === 0,
    errors
  }
}

// 使用示例
const formData = {
  email: 'user@example.com',
  phone: '13812345678',
  password: 'MyPassword123',
  confirmPassword: 'MyPassword123'
}

const validation = validateRegisterForm(formData)
console.log(validation) // { valid: true, errors: [] }
```

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

### Vue Multiselect Example with iip-ui-components

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

This Vue component demonstrates how to use the `openDialogSelect` function from `@bingwu/iip-ui-components` to implement a multiselect feature for products within a project table. It configures the dialog with custom options, handles data fetching with pagination and filtering, and updates the table with the selected product names. The `multiple` option is set to `true` to enable multiselection.

```vue
<template>
  <div>
    <el-table :data="tableData" border>
      <el-table-column prop="id" label="ID" width="80" />
      <el-table-column prop="projectName" label="项目名称" />
      <el-table-column prop="productsDisplay" label="已选产品">
        <template #default="{ row }">
          <span class="cell-link" @click="handleProductsClick(row)">
            {{ row.productsDisplay || '点击选择' }}
          </span>
        </template>
      </el-table-column>
    </el-table>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { openDialogSelect } from '@bingwu/iip-ui-components'
import type {
  FetchDialogSelectDataParams,
  FetchDialogSelectDataResult,
  DialogSelectOptions,
  TableRowItem
} from '@bingwu/iip-ui-components'
import { ElMessage } from 'element-plus'

const tableData = ref([
  { id: 1, projectName: '电商平台开发', products: [], productsDisplay: '' },
  { id: 2, projectName: '移动应用设计', products: [], productsDisplay: '' }
])

// 模拟产品数据
const mockProducts = Array.from({ length: 50 }, (_, i) => ({
  id: `PROD-${String(i + 1).padStart(3, '0')}`,
  name: `产品${i + 1}`,
  price: (Math.random() * 1000).toFixed(2),
  category: ['电子产品', '服装', '食品', '家居'][i % 4]
}))

// DialogSelect 选项配置
const productDialogSelectOptions: DialogSelectOptions = [
  { field: 'id', title: '产品ID', columnProps: { width: 120 } },
  { field: 'name', title: '产品名称', columnProps: { width: 150 } },
  { field: 'price', title: '价格', columnProps: { width: 100 } },
  { field: 'category', title: '分类', columnProps: { width: 120 } },
  {
    field: 'name',
    title: '产品名称',
    useForm: true,
    formItemProps: {
      formType: 'input',
      placeholder: '请输入产品名称'
    }
  },
  {
    field: 'category',
    title: '分类',
    useForm: true,
    formItemProps: {
      formType: 'select',
      placeholder: '请选择分类',
      options: [
        { label: '电子产品', value: '电子产品' },
        { label: '服装', value: '服装' },
        { label: '食品', value: '食品' },
        { label: '家居', value: '家居' }
      ]
    }
  }
]

// 获取产品数据
const fetchProductData = async (
  params: FetchDialogSelectDataParams
): Promise<FetchDialogSelectDataResult> => {
  // 模拟网络延迟
  await new Promise(resolve => setTimeout(resolve, 300))

  const { page, pageSize, name, category } = params

  // 根据筛选条件过滤
  let filteredProducts = mockProducts
  if (name) {
    filteredProducts = filteredProducts.filter(product => product.name.includes(name as string))
  }
  if (category) {
    filteredProducts = filteredProducts.filter(product => product.category === category)
  }

  // 分页处理
  const start = (page - 1) * pageSize
  const end = start + pageSize
  const data = filteredProducts.slice(start, end)

  return {
    data,
    total: filteredProducts.length
  }
}

// 点击单元格选择产品（多选）
const handleProductsClick = async (row: any) => {
  try {
    const result = await openDialogSelect({
      fetchData: fetchProductData,
      dialogSelectOptions: productDialogSelectOptions,
      multiple: true, // 启用多选
      valueKey: 'id',
      labelKey: 'name',
      dialogTitle: '选择产品',
      initialValue: row.products // 传入当前选中的值数组
    })

    // result 是选中的对象数组（多选模式）
    if (result && Array.isArray(result)) {
      row.products = result
      row.productsDisplay = result.map((item: any) => item.name).join(', ')
      ElMessage.success(`已选择 ${result.length} 个产品`)
    }
  } catch (error: any) {
    console.log('取消选择:', error.message)
  }
}
</script>

```

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

### Handling User Cancellation vs. Other Errors (TypeScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Provides a practical example of how to distinguish between a user intentionally canceling a selection and other types of errors when using `openDialogSelect`. It relies on checking the error message within a catch block.

```typescript
try {
  const result = await openDialogSelect({ ... })
  // 用户确认，result 是选中的值
} catch (error: any) {
  if (error.message === '用户取消选择') {
    // 用户取消
  }
}
```

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

### DateRange: Passing props to start and end date pickers (Vue)

Source: https://iip-ui-docs.netlify.app/components/date-range

Shows how to configure individual props for the start and end date pickers. This example passes custom placeholders, `clearable` status, and `size` attributes to both pickers using `start-props` and `end-props`.

```vue
<template>
  <iip-date-range
    v-model="dateRange"
    :start-props="{
      placeholder: 'Please select start date',
      clearable: true,
      size: 'large'
    }"
    :end-props="{
      placeholder: 'Please select end date',
      clearable: true,
      size: 'large'
    }"
    @change="handleDateChange"
  />
</template>

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

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('Date range changed:', value)
}
</script>
```

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

### Fetch Product Data with Filtering and Pagination (JavaScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Asynchronously fetches product data, allowing filtering by name and category, along with pagination. It simulates a 300ms delay and returns a paginated list of products and their total count. Relies on `mockProducts` and `FetchDialogSelectDataParams`.

```javascript
const fetchProductDataForDialog = async (
  params: FetchDialogSelectDataParams
): Promise<FetchDialogSelectDataResult> => {
  await new Promise(resolve => setTimeout(resolve, 300))

  const { page, pageSize, name, category } = params

  let filteredProducts = mockProducts
  if (name) {
    filteredProducts = filteredProducts.filter(product => product.name.includes(name as string))
  }
  if (category) {
    filteredProducts = filteredProducts.filter(product => product.category === category)
  }

  const start = (page - 1) * pageSize
  const end = start + pageSize
  const data = filteredProducts.slice(start, end)

  return {
    data,
    total: filteredProducts.length
  }
}
```

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

### TypeScript Usage Example for Dialog Select

Source: https://iip-ui-docs.netlify.app/components/dialog-select

This TypeScript example demonstrates how to instantiate and use the Dialog Select component with a custom data type 'EmployeeRow'. It shows how to get a reference to the dialog component and access its properties like `tableData`, which is typed as Readonly<Ref<EmployeeRow[]>>.

```typescript
import type { DialogSelectInstance } from '@bingwu/iip-ui-components'

interface EmployeeRow {
  id: number
  name: string
}

const dialogRef = ref<DialogSelectInstance<EmployeeRow>>()

// ✅ dialogRef.value.tableData 类型为 Readonly<Ref<EmployeeRow[]>>
```

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

### Open Dialog for Single Assignee Selection with Initial Value (JavaScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Demonstrates opening a dialog to select a single assignee, pre-filled with an initial value. It uses the `fetchEmployeeData` function and `employeeDialogSelectOptions`. The `employeeKeyGetter` ensures correct identification. On successful selection, it updates the row's assignee details and shows a success message. Errors during cancellation are logged. Dependencies include `openDialogSelect`, `fetchEmployeeData`, `employeeDialogSelectOptions`, and `employeeKeyGetter`.

```javascript
const handleAssigneeClick = async (row: any) => {
  try {
    const result = await openDialogSelect({
      fetchData: fetchEmployeeData,
      dialogSelectOptions: employeeDialogSelectOptions,
      keyGetter: employeeKeyGetter,
      dialogTitle: '选择指派人',
      initialValue: row.assigneeData
    })

    if (result && typeof result === 'object' && !Array.isArray(result)) {
      row.assignee = result.name as string
      row.assigneeData = result
      ElMessage.success(`已指派给：${result.name}`)
    }
  } catch (error: any) {
    console.log('取消选择:', error.message)
  }
}
```

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

### Using iip-date-range Slots for Customization (Vue)

Source: https://iip-ui-docs.netlify.app/components/date-range

Demonstrates how to use slots to customize the appearance and behavior of the start and end date pickers within the iip-date-range component. It shows examples for adding icons, custom buttons, and default text.

```vue
<iip-date-range v-model="dateRange">
  <template #start-prefix>
    <el-icon><Calendar /></el-icon>
  </template>
  
  <template #end-suffix>
    <el-button size="small" type="text">清空</el-button>
  </template>
  
  <template #start-default="{ value }">
    <span style="color: #409eff;">{{ value || '请选择开始日期' }}</span>
  </template>
</iip-date-range>
```

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

### Open Dialog for Multiple Product Selection (JavaScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Opens a dialog for selecting multiple products. It's configured with data fetching, column definitions, a custom key getter, and options for multiple selections, value/label keys, and initial values. Upon successful selection, it updates the row's product information and displays a confirmation message. Handles cancellation errors. Dependencies include `openDialogSelect`, `fetchProductDataForDialog`, `productDialogSelectOptions`, and `productKeyGetter`.

```javascript
const handleProductsClick = async (row: any) => {
  try {
    const result = await openDialogSelect({
      fetchData: fetchProductDataForDialog,
      dialogSelectOptions: productDialogSelectOptions,
      keyGetter: productKeyGetter,
      multiple: true,
      valueKey: 'id',
      labelKey: 'name',
      dialogTitle: '选择产品',
      initialValue: row.products
    })

    if (result && Array.isArray(result)) {
      row.products = result
      row.productsDisplay = result.map((item: any) => item.name).join(', ')
      ElMessage.success(`已选择 ${result.length} 个产品`)
    }
  } catch (error: any) {
    console.log('取消选择:', error.message)
  }
}
```

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

### Create Custom Range Selectors with Slots in Vue

Source: https://iip-ui-docs.netlify.app/components/date-range

Shows how to use slots to create more complex and visually distinct range selectors for the iip-date-range component. This example customizes the default slot for both start and end dates, applying unique styling and content, including icons and gradient text.

```vue
<template>
  <div>
    <h3>自定义范围选择器</h3>
    <iip-date-range v-model="dateRange" @change="handleDateChange">
      <!-- 自定义开始日期的输入框样式 -->
      <template #start-default="{ value }">
        <div class="custom-date-input">
          <el-icon class="date-icon"><Calendar /></el-icon>
          <span class="date-text">{{ value || '开始日期' }}</span>
        </div>
      </template>

      <!-- 自定义结束日期的输入框样式 -->
      <template #end-default="{ value }">
        <div class="custom-date-input">
          <span class="date-text">{{ value || '结束日期' }}</span>
          <el-icon class="date-icon"><Calendar /></el-icon>
        </div>
      </template>
    </iip-date-range>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Calendar } from '@element-plus/icons-vue'

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('自定义日期范围变化:', value)
}
</script>

<style scoped>
.custom-date-input {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 4px 8px;
  background: linear-gradient(90deg, #409eff, #67c23a);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  font-weight: bold;
}

.date-icon {
  color: #409eff;
}
</style>
```

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

### Handle Form Editing with Initial Values (Vue)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Demonstrates how to open a dialog to select an owner for a form and pre-fill it with the current formData.owner value. It uses `openDialogSelect` for selection and updates the form data upon successful selection. Includes basic try-catch for error handling.

```vue
<script setup>
const handleEdit = async (formData: any) => {
  try {
    const result = await openDialogSelect({
      fetchData: fetchEmployeeData,
      dialogSelectOptions: employeeDialogSelectOptions,
      dialogTitle: '选择负责人',
      // 传入当前表单中的值作为初始值
      initialValue: formData.owner
    })

    // 更新表单数据
    formData.owner = result
  } catch (error) {
    // 用户取消，不做处理
  }
}
</script>
```

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

### Passing vxe-grid Configuration Options (TypeScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Illustrates how to pass specific configuration options for the underlying `vxe-grid` component used within the dialog via the `gridConfig` parameter. This allows for customization of grid appearance and behavior.

```typescript
await openDialogSelect({
  fetchData: fetchData,
  dialogSelectOptions: options,
  gridConfig: {
    border: false,
    height: '600px',
    stripe: true
  }
})
```

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

### DateRange: Customizing start and end date picker styles (Vue)

Source: https://iip-ui-docs.netlify.app/components/date-range

Demonstrates how to apply custom CSS styles to the start and end date input elements. It uses the `start-picker-css` and `end-picker-css` props to modify width and border color for each picker individually.

```vue
<template>
  <iip-date-range
    v-model="dateRange"
    :gap="20"
    :start-picker-css="{ width: '200px', borderColor: '#409eff' }"
    :end-picker-css="{ width: '200px', borderColor: '#67c23a' }"
    @change="handleDateChange"
  />
</template>

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

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('Date range changed:', value)
}
</script>
```

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

### Using keyGetter for Composite Keys (TypeScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Explains and demonstrates the use of the `keyGetter` option in `openDialogSelect`. This is useful when a unique key for data items needs to be constructed from multiple properties, such as combining `id` and `category`.

```typescript
const productKeyGetter = (row: TableRowItem) => {
  return `${row.id}-${row.category}`
}

const result = await openDialogSelect({
  fetchData: fetchProductData,
  dialogSelectOptions: productOptions,
  keyGetter: productKeyGetter
})
```

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

### Open Dialog for Single Employee Selection (JavaScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Opens a dialog to select a single employee. It configures the dialog with data fetching, selection options, a key getter, and an initial value. Handles successful selection by updating the row's owner information and displays a success message. Catches and logs any cancellation errors. Dependencies include `openDialogSelect`, `fetchEmployeeData`, `employeeDialogSelectOptions`, and `employeeKeyGetter`.

```javascript
const handleOwnerClick = async (row: any) => {
  try {
    const result = await openDialogSelect({
      fetchData: fetchEmployeeData,
      dialogSelectOptions: employeeDialogSelectOptions,
      keyGetter: employeeKeyGetter,
      dialogTitle: '选择负责人',
      initialValue: row.ownerData
    })

    if (result && typeof result === 'object' && !Array.isArray(result)) {
      row.owner = result.name as string
      row.ownerData = result
      ElMessage.success(`已选择负责人：${result.name}`)
    }
  } catch (error: any) {
    console.log('取消选择:', error.message)
  }
}
```

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

### Configure Date Validation Logic in Vue

Source: https://iip-ui-docs.netlify.app/components/date-range

Demonstrates how to leverage the iip-date-range component's built-in date validation logic. This includes restricting future dates (configurable via `selectFutureTime`), ensuring the start date is not after the end date, and the component's smart linkage behavior where selecting a start date can automatically set the end date.

```vue
<template>
  <div>
    <h3>日期验证示例</h3>
    <iip-date-range v-model="dateRange" :select-future-time="false" @change="handleDateChange" />
    <div style="margin-top: 10px; color: #666;">
      <p>验证规则：</p>
      <ul>
        <li>不能选择未来日期</li>
        <li>开始日期不能晚于结束日期</li>
        <li>结束日期不能早于开始日期</li>
      </ul>
    </div>
  </div>
</template>

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

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('验证通过的日期范围:', value)
}
</script>
```

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

### Fetch Employee Data with Filtering and Pagination (JavaScript)

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

Asynchronously fetches employee data based on pagination and filtering criteria (name, department). It simulates network latency and returns a paginated list of employees along with the total count. Dependencies include `mockEmployees` and `FetchDialogSelectDataParams`.

```javascript
const fetchEmployeeData = async (
  params: FetchDialogSelectDataParams
): Promise<FetchDialogSelectDataResult> => {
  await new Promise(resolve => setTimeout(resolve, 300))

  const { page, pageSize, name, department } = params

  let filteredEmployees = mockEmployees
  if (name) {
    filteredEmployees = filteredEmployees.filter(employee => employee.name.includes(name as string))
  }
  if (department) {
    filteredEmployees = filteredEmployees.filter(employee => employee.department === department)
  }

  const start = (page - 1) * pageSize
  const end = start + pageSize
  const data = filteredEmployees.slice(start, end)

  return {
    data,
    total: filteredEmployees.length
  }
}
```

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

### Vue Utility Functions (JavaScript)

Source: https://iip-ui-docs.netlify.app/utils/utils

A set of utility functions specifically designed for Vue.js development. These include helpers for installing components and functions, and a tool for creating component namespaces.

```javascript
withInstall(component)
withInstallFunction(fn, name)
createNamespace(name)
```

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

### 安装 IIP UI Vue3 组件库 (npm)

Source: https://iip-ui-docs.netlify.app/guide/quickstart

使用 npm 包管理器安装 IIP UI Vue3 核心组件库、工具库以及其必要的第三方依赖，包括 vxe-table, vxe-pc-ui, xe-utils 和 Element Plus。

```bash
# 安装组件库
npm install @bingwu/iip-ui-components @bingwu/iip-ui-utils

# 安装必要的第三方依赖
npm install vxe-table@^4.15.6 vxe-pc-ui@~4.8.15 xe-utils@^3.7.8

# 安装 Element Plus (提供基础 UI 组件)
npm install element-plus@^2.11.2 @element-plus/icons-vue@^2.1.0
```

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

### Slot Customization

Source: https://iip-ui-docs.netlify.app/components/date-range

Demonstrates how to customize the start and end date pickers using Element Plus DatePicker slots. You can prefix slot names with `start-` or `end-` to target specific date pickers.

```APIDOC
## Slot Customization

### Description

Customize the start and end date pickers by leveraging Element Plus DatePicker's slots. Prefix slot names with `start-` or `end-` to apply customizations to the respective date inputs.

### Usage Example

```vue
<template>
  <div>
    <h3>Custom Slot Example</h3>
    <iip-date-range v-model="dateRange" @change="handleDateChange">
      <!-- Custom prefix icon for start date picker -->
      <template #start-prefix>
        <el-icon><Calendar /></el-icon>
      </template>

      <!-- Custom suffix icon for end date picker -->
      <template #end-suffix>
        <el-icon><Clock /></el-icon>
      </template>

      <!-- Custom default slot for start date picker -->
      <template #start-default="{ value }">
        <span style="color: #409eff;">{{ value || 'Select start date' }}</span>
      </template>
    </iip-date-range>

    <p style="margin-top: 10px;">
      Selected date range: {{ dateRange.startTime }} ~ {{ dateRange.endTime }}
    </p>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Calendar, Clock } from '@element-plus/icons-vue'

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('Date range changed:', value)
}
</script>
```

### Customizing Range Selector

Create more complex custom interfaces using slots:

```vue
<template>
  <div>
    <h3>Custom Range Selector</h3>
    <iip-date-range v-model="dateRange" @change="handleDateChange">
      <!-- Custom input style for start date -->
      <template #start-default="{ value }">
        <div class="custom-date-input">
          <el-icon class="date-icon"><Calendar /></el-icon>
          <span class="date-text">{{ value || 'Start Date' }}</span>
        </div>
      </template>

      <!-- Custom input style for end date -->
      <template #end-default="{ value }">
        <div class="custom-date-input">
          <span class="date-text">{{ value || 'End Date' }}</span>
          <el-icon class="date-icon"><Calendar /></el-icon>
        </div>
      </template>
    </iip-date-range>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Calendar } from '@element-plus/icons-vue'

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('Custom date range changed:', value)
}
</script>

<style scoped>
.custom-date-input {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 4px 8px;
  background: linear-gradient(90deg, #409eff, #67c23a);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  font-weight: bold;
}

.date-icon {
  color: #409eff;
}
</style>
```
```

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

### 完整引入 IIP UI Vue3 组件库 (main.ts)

Source: https://iip-ui-docs.netlify.app/guide/quickstart

在 `main.ts` 文件中完整引入 IIP UI Vue3 组件库、Element Plus、Element Plus 图标、vxe-table 和 vxe-pc-ui。此方法简单但可能影响打包体积。

```typescript
// main.ts
import { createApp } from 'vue'

// Element Plus (基础 UI 组件)
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import * as ElementPlusIconsVue from '@element-plus/icons-vue'

// vxe-table 相关插件 (Table 组件依赖)
import VxeUITable from 'vxe-table'
import 'vxe-table/lib/style.css'
import VxePCUI from 'vxe-pc-ui'
import 'vxe-pc-ui/lib/style.css'

// IIP UI 组件库
import IipUI from '@bingwu/iip-ui-components'
import '@bingwu/iip-ui-components/dist/style.css'

import App from './App.vue'

const app = createApp(App)

// 注册 Element Plus 图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component)
}

// 注册插件
app.use(VxeUITable)
app.use(VxePCUI)
app.use(ElementPlus)
app.use(IipUI)

app.mount('#app')
```

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

### Vue 表格与带初始值选择器集成

Source: https://iip-ui-docs.netlify.app/components/dialog-select-function

此代码片段展示了一个 Vue 组件，其中包含一个 Element Plus 表格。表格的“指派人”列允许用户点击并弹出一个对话框来选择指派人。该对话框集成了 `@bingwu/iip-ui-components` 库的 `openDialogSelect` 函数，支持数据检索、分页，并且能够接收并显示初始选中的值，当用户取消选择或未选择时，会捕获错误信息。

```vue
<template>
  <div>
    <el-table :data="tableData" border>
      <el-table-column prop="id" label="ID" width="80" />
      <el-table-column prop="ticketNo" label="工单号" />
      <el-table-column prop="title" label="标题" />
      <el-table-column prop="assignee" label="指派人" width="150">
        <template #default="{ row }">
          <span class="cell-link" @click="handleAssigneeClick(row)">
            {{ row.assignee || '点击选择' }}
          </span>
        </template>
      </el-table-column>
    </el-table>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { openDialogSelect } from '@bingwu/iip-ui-components'
import type {
  FetchDialogSelectDataParams,
  FetchDialogSelectDataResult,
  DialogSelectOptions,
  TableRowItem
} from '@bingwu/iip-ui-components'
import { ElMessage } from 'element-plus'

const tableData = ref([
  {
    id: 1,
    ticketNo: 'TK-001',
    title: '系统登录异常',
    assignee: '员工3',
    assigneeData: {
      id: 3,
      name: '员工3',
      department: '运营部'
    }
  },
  {
    id: 2,
    ticketNo: 'TK-002',
    title: '页面加载缓慢',
    assignee: '',
    assigneeData: null
  }
])

// 模拟员工数据
const mockEmployees = Array.from({ length: 100 }, (_, i) => ({
  id: i + 1,
  name: `员工${i + 1}`,
  department: ['技术部', '产品部', '运营部', '市场部', '人事部'][i % 5],
  email: `employee${i + 1}@example.com`,
  phone: `138${String(i + 1).padStart(8, '0')}`,
  status: i % 3 === 0 ? '在职' : '离职'
}))

// DialogSelect 选项配置
const employeeDialogSelectOptions: DialogSelectOptions = [
  { field: 'id', title: 'ID', columnProps: { width: 80 } },
  { field: 'name', title: '姓名', columnProps: { width: 120 } },
  { field: 'department', title: '部门', columnProps: { width: 120 } },
  { field: 'email', title: '邮箱', columnProps: { width: 200 } },
  { field: 'phone', title: '电话', columnProps: { width: 150 } },
  { field: 'status', title: '状态', columnProps: { width: 100 } },
  {
    field: 'name',
    title: '姓名',
    useForm: true,
    formItemProps: {
      formType: 'input',
      placeholder: '请输入姓名'
    }
  },
  {
    field: 'department',
    title: '部门',
    useForm: true,
    formItemProps: {
      formType: 'select',
      placeholder: '请选择部门',
      options: [
        { label: '技术部', value: '技术部' },
        { label: '产品部', value: '产品部' },
        { label: '运营部', value: '运营部' },
        { label: '市场部', value: '市场部' },
        { label: '人事部', value: '人事部' }
      ]
    }
  }
]

// 获取员工数据
const fetchEmployeeData = async (
  params: FetchDialogSelectDataParams
): Promise<FetchDialogSelectDataResult> => {
  // 模拟网络延迟
  await new Promise(resolve => setTimeout(resolve, 300))

  const { page, pageSize, name, department } = params

  // 根据筛选条件过滤
  let filteredEmployees = mockEmployees
  if (name) {
    filteredEmployees = filteredEmployees.filter(employee => employee.name.includes(name as string))
  }
  if (department) {
    filteredEmployees = filteredEmployees.filter(employee => employee.department === department)
  }

  // 分页处理
  const start = (page - 1) * pageSize
  const end = start + pageSize
  const data = filteredEmployees.slice(start, end)

  return {
    data,
    total: filteredEmployees.length
  }
}

// 点击单元格选择指派人（带初始值）
const handleAssigneeClick = async (row: any) => {
  try {
    const result = await openDialogSelect({
      fetchData: fetchEmployeeData,
      dialogSelectOptions: employeeDialogSelectOptions,
      dialogTitle: '选择指派人',
      // 传入初始值，会在弹窗打开时自动选中
      initialValue: row.assigneeData
    })

    if (result && typeof result === 'object' && !Array.isArray(result)) {
      row.assignee = result.name as string
      row.assigneeData = result
      ElMessage.success(`已指派给：${result.name}`)
    }
  } catch (error: any) {
    console.log('取消选择:', error.message)
  }
}
</script>

<style>
.cell-link {
  color: var(--el-color-primary);
  cursor: pointer;
}
</style>
```

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

### Frontend Mapping of Backend Data

Source: https://iip-ui-docs.netlify.app/components/pagination-select

Provides a TypeScript example of how to map flattened backend data into a more structured object format suitable for frontend forms or state management. This pattern helps in organizing data and improving type safety.

```typescript
form.value = {
  user: {
    id: data.userId,
    name: data.userName
  },
  category: {
    id: data.categoryId,
    name: data.categoryName
  }
}
```

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

### Implement Quick Search with Debounce and Request Manager

Source: https://iip-ui-docs.netlify.app/utils/utils

Illustrates using the Request Manager in conjunction with a debounce function for rapid search scenarios. This pattern ensures that only the results from the latest search query are processed and displayed, preventing UI updates from stale results due to rapid user input. It requires a debounce utility and the `managedRequest` method.

```typescript
// 用户快速输入搜索关键词时，只处理最新的搜索结果
const handleQuickSearch = debounce(async (keyword: string) => {
  await requestManager.managedRequest(
    async requestId => {
      return searchAPI(keyword)
    },
    results => {
      // 只有最新搜索的结果会更新UI
      searchResults.value = results
    }
  )
}, 200)
```

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

### IipPaginationSelect: Custom Attribute Names (Vue)

Source: https://iip-ui-docs.netlify.app/components/pagination-select

Explains how to configure IipPaginationSelect to use custom attribute names for values and labels using the `valueKey` and `labelKey` props. This example shows three scenarios with different key name configurations.

```vue
<template>
  <div>
    <!-- Using default attribute names value and label -->
    <IipPaginationSelect v-model="selection1" :fetch-data="fetchData1" />

    <!-- Custom attribute names id and name -->
    <IipPaginationSelect
      v-model="selection2"
      value-key="id"
      label-key="name"
      :fetch-data="fetchData2"
    />

    <!-- Custom attribute names code and title -->
    <IipPaginationSelect
      v-model="selection3"
      value-key="code"
      label-key="title"
      :fetch-data="fetchData3"
    />
  </div>
</template>

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

// selection1: { value: 1, label: '选项一' } or null
const selection1 = ref(null)

// selection2: { id: 1, name: '张三' } or null
const selection2 = ref(null)

// selection3: { code: 'A001', title: '商品A' } or null
const selection3 = ref(null)
</script>
```

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

### DateRange: Allow selecting future dates (Vue)

Source: https://iip-ui-docs.netlify.app/components/date-range

Illustrates how to enable the selection of future dates using the `select-future-time` prop. This example shows the component configured to allow users to pick dates beyond the current day.

```vue
<template>
  <iip-date-range v-model="dateRange" :select-future-time="true" @change="handleDateChange" />
</template>

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

const dateRange = ref({
  startTime: '',
  endTime: ''
})

const handleDateChange = (value: { startTime: string; endTime: string }) => {
  console.log('Date range changed:', value)
}
</script>
```