LocationQuery - 位置查询参数类型

LocationQuery 是一个类型别名，定义了路由位置中查询参数的标准数据结构。它用于表示 URL 查询字符串（?key=value 部分）的解析结果。🔍

📋 类型定义

type LocationQuery = Record<string, LocationQueryValue>

🎯 功能说明

这个类型就像是查询参数的"数据容器"，提供：

1. 类型安全 - 确保查询参数操作的类型正确性
2. 数据结构统一 - 标准化查询参数的存储格式
3. 空值处理 - 统一处理未定义或空值的查询参数

🔧 类型结构

基础结构

// LocationQuery 的实际结构
interface LocationQuery {
  [key: string]: LocationQueryValue | LocationQueryValue[]
}

查询参数值的类型

type LocationQueryValue = string | null
type LocationQueryValueRaw = LocationQueryValue | number | undefined

💡 实际应用示例

访问查询参数

import { useRoute } from 'vue-router'

const route = useRoute()

// route.query 的类型就是 LocationQuery
const query = route.query

// 访问单个参数（可能是 string | null）
const searchTerm = query.search

// 访问数组参数（可能是 string[] | null）
const categories = query.categories

类型安全的参数处理

// 安全的参数提取函数
function getQueryParam(
  query: LocationQuery, 
  key: string
): string | null {
  const value = query[key]
  return Array.isArray(value) ? value[0] : value
}

// 使用示例
const search = getQueryParam(route.query, 'search')
if (search) {
  performSearch(search)
}

处理数组参数

// 处理多值查询参数
function getQueryArray(
  query: LocationQuery, 
  key: string
): string[] {
  const value = query[key]
  if (Array.isArray(value)) {
    return value.filter(v => v !== null) as string[]
  } else if (value !== null) {
    return [value]
  }
  return []
}

// 使用示例
const tags = getQueryArray(route.query, 'tags')
// 对于 URL: ?tags=vue&tags=router → tags = ['vue', 'router']

🎯 常见使用场景

搜索功能

<template>
  <input 
    v-model="searchInput" 
    @input="updateSearch" 
    placeholder="搜索..."
  />
</template>

<script setup>
import { useRouter, useRoute } from 'vue-router'
import { ref, watch } from 'vue'

const router = useRouter()
const route = useRoute()
const searchInput = ref(route.query.search || '')

// 监听搜索输入变化
watch(searchInput, (newValue) => {
  router.push({
    path: route.path,
    query: {
      ...route.query,
      search: newValue || undefined // 空值时移除参数
    }
  })
})
</script>

筛选和排序

<script setup>
import { useRouter, useRoute } from 'vue-router'

const route = useRoute()
const router = useRouter()

// 设置排序参数
const setSort = (field: string, order: 'asc' | 'desc') => {
  router.push({
    path: route.path,
    query: {
      ...route.query,
      sort: field,
      order: order
    }
  })
}

// 获取当前排序设置
const sortField = route.query.sort || 'name'
const sortOrder = route.query.order || 'asc'
</script>

分页功能

// 分页参数处理
interface PaginationParams {
  page: number
  limit: number
}

function getPaginationFromQuery(query: LocationQuery): PaginationParams {
  return {
    page: parseInt(query.page as string) || 1,
    limit: parseInt(query.limit as string) || 10
  }
}

// 设置分页参数
function setPagination(page: number, limit: number) {
  router.push({
    path: route.path,
    query: {
      ...route.query,
      page: page.toString(),
      limit: limit.toString()
    }
  })
}

🔧 实用工具函数

查询参数序列化

function serializeQuery(query: LocationQuery): string {
  const params = new URLSearchParams()
  
  Object.entries(query).forEach(([key, value]) => {
    if (Array.isArray(value)) {
      value.forEach(v => v && params.append(key, v))
    } else if (value) {
      params.append(key, value)
    }
  })
  
  return params.toString()
}

查询参数解析

function parseQueryString(queryString: string): LocationQuery {
  const params = new URLSearchParams(queryString)
  const result: LocationQuery = {}
  
  for (const [key, value] of params.entries()) {
    if (key in result) {
      const existing = result[key]
      if (Array.isArray(existing)) {
        existing.push(value)
      } else {
        result[key] = [existing as string, value]
      }
    } else {
      result[key] = value
    }
  }
  
  return result
}

🔗 相关类型

• LocationQueryValue - 查询参数值类型
• RouteLocationRaw - 路由位置参数类型

💡 专业建议：在处理查询参数时，始终进行类型检查和空值处理，避免运行时错误。使用 TypeScript 可以获得更好的类型安全保证。