LocationQueryValue - 查询参数值类型别名

LocationQueryValue 是一个类型别名，定义了查询参数值的标准数据类型。它用于表示 URL 查询字符串中单个参数值的可能类型。🔍

📋 类型定义

type LocationQueryValue = string | null

🎯 功能说明

这个类型别名定义了查询参数值的两种可能状态：

1. 字符串值 - 参数存在且有具体值
2. null 值 - 参数存在但没有值（如 ?flag）

🔧 类型结构

基础定义

// LocationQueryValue 的两种可能类型
type LocationQueryValue = 
  | string   // 有值的参数：?name=john → "john"
  | null     // 无值的参数：?flag → null

在 LocationQuery 中的使用

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

// 示例查询参数对象
const query: LocationQuery = {
  name: "john",        // string
  flag: null,          // null
  tags: ["vue", "js"]  // string[]
}

💡 实际应用示例

访问查询参数值

import { useRoute } from 'vue-router'

const route = useRoute()

// route.query 中的值都是 LocationQueryValue 类型
const searchTerm = route.query.q        // string | null
const category = route.query.category   // string | null
const debugMode = route.query.debug     // string | null

安全的参数处理

// 安全的参数提取函数
function getQueryParamValue(
  query: LocationQuery, 
  key: string
): string | undefined {
  const value = query[key]
  
  if (value === null) {
    return undefined // 无值参数视为未定义
  }
  
  if (Array.isArray(value)) {
    return value[0] || undefined // 取第一个值
  }
  
  return value || undefined // 字符串值
}

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

参数验证和转换

// 验证查询参数的类型
function validateQueryParam(
  value: LocationQueryValue, 
  expectedType: 'string' | 'number' | 'boolean'
): any {
  if (value === null) return undefined
  
  switch (expectedType) {
    case 'string':
      return value
    case 'number':
      const num = Number(value)
      return isNaN(num) ? undefined : num
    case 'boolean':
      return value === 'true' ? true : value === 'false' ? false : undefined
  }
}

// 使用示例
const pageSize = validateQueryParam(route.query.size, 'number') || 10
const isActive = validateQueryParam(route.query.active, 'boolean') || false

🎯 常见使用场景

搜索功能参数处理

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

const route = useRoute()

// 处理搜索参数
const searchQuery = computed(() => {
  const value = route.query.q
  return value === null ? '' : value || ''
})

const searchCategory = computed(() => {
  const value = route.query.category
  return value === null ? 'all' : value || 'all'
})
</script>

分页参数处理

// 分页参数处理工具
interface PaginationParams {
  page: number
  size: number
}

function getPaginationFromQuery(query: LocationQuery): PaginationParams {
  return {
    page: validateQueryParam(query.page, 'number') || 1,
    size: validateQueryParam(query.size, 'number') || 10
  }
}

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

筛选器参数处理

// 多值筛选器参数处理
function getFilterValues(query: LocationQuery, key: string): string[] {
  const value = query[key]
  
  if (value === null) {
    return [] // 无值参数返回空数组
  }
  
  if (Array.isArray(value)) {
    return value.filter(v => v !== null) as string[]
  }
  
  return value ? [value] : [] // 单值转换为数组
}

// 使用示例
const selectedCategories = getFilterValues(route.query, 'category')
const selectedTags = getFilterValues(route.query, 'tags')

🔧 实用工具函数

参数值标准化

// 将查询参数值标准化为字符串或未定义
function normalizeQueryValue(value: LocationQueryValue): string | undefined {
  if (value === null) return undefined
  return value || undefined
}

// 处理数组参数值
function normalizeQueryArray(value: LocationQueryValue | LocationQueryValue[]): string[] {
  if (value === null) return []
  
  if (Array.isArray(value)) {
    return value.filter(v => v !== null) as string[]
  }
  
  return value ? [value] : []
}

查询参数构建

// 构建安全的查询参数对象
function buildQueryParams(params: Record<string, string | number | boolean | undefined>): LocationQueryRaw {
  const query: LocationQueryRaw = {}
  
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined && value !== null) {
      query[key] = value.toString()
    }
  })
  
  return query
}

// 使用示例
const searchParams = buildQueryParams({
  q: 'vue router',
  page: 1,
  active: true
})

🔗 相关类型

• LocationQuery - 查询参数对象类型

💡 专业建议：在处理查询参数时，始终考虑 null 值的情况，并建立统一的参数处理策略，避免出现意外的运行时错误。