Setting and Optimizing URL Query Parameters with Vue-Router

Core Principles of Vue-Router Query Parameter Setting

In Vue.js single-page application development, Vue-Router, as the official routing manager, provides powerful URL management capabilities. Query parameters are key-value pairs following the ? in the URL, commonly used to pass page state information without triggering page navigation.

Basic Query Parameter Setting Methods

Vue-Router provides two methods to modify URLs: router.push and router.replace. The router.replace method replaces the current history entry without creating a new one. The basic syntax is as follows:

// Using path approach
this.$router.replace({ path: '/current-path', query: { q1: "value1", q2: "value2" } })

// Using named route approach
this.$router.replace({ name: "route-name", query: { q1: "value1" } })

Solving Page Scroll Position Reset Issues

When using router.replace, you might encounter the issue of the page scrolling to the top. This happens because Vue-Router's default scroll behavior resets the scroll position. The solution is to customize scrollBehavior in the route configuration:

export default new Router({
  mode: 'history',
  scrollBehavior: (to, from, savedPosition) => {
    // Return to saved position if available
    if (savedPosition) {
      return savedPosition
    }
    // Scroll to element if hash is present
    if (to.hash) {
      return { selector: to.hash }
    }
    // Otherwise maintain current position
    return false
  },
  routes: [
    { name: 'user-view', path: '/user/:id', component: UserView }
  ]
})

Combining Named Routes with Dynamic Parameters

In routes containing dynamic parameters, it's recommended to use named routes for setting query parameters, as this provides clearer parameter management:

// Route configuration
routes: [
  { 
    name: 'user-view', 
    path: '/user/:id', 
    component: UserView 
  }
]

// Usage in component methods
methods: {
  updateQueryParams() {
    this.$router.replace({ 
      name: "user-view", 
      params: { id: this.userId },
      query: { 
        q1: this.searchQuery,
        filter: this.currentFilter
      } 
    })
  }
}

Parameter Access and Reactive Handling

Route parameters and query parameters can be easily accessed within components:

<template>
  <div>
    <p>User ID: {{ $route.params.id }}</p>
    <p>Query Parameter q1: {{ $route.query.q1 }}</p>
  </div>
</template>

<script>
export default {
  watch: {
    '$route.query.q1': function(newVal, oldVal) {
      // Execute actions when query parameter q1 changes
      this.handleQueryChange(newVal)
    },
    '$route.params.id': function(newId, oldId) {
      // Reload user data when dynamic parameter id changes
      this.loadUserData(newId)
    }
  },
  
  methods: {
    handleQueryChange(queryValue) {
      // Logic for handling query parameter changes
      console.log('Query parameter updated:', queryValue)
    },
    
    loadUserData(userId) {
      // Logic for loading user data
      console.log('Loading user data:', userId)
    }
  }
}
</script>

Handling Route Changes with Composition API

In Vue 3's Composition API, you can use useRoute and watch to respond to route changes:

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

const route = useRoute()

// Watch for query parameter changes
watch(
  () => route.query.q1,
  (newQuery, oldQuery) => {
    // Respond to query parameter changes
    console.log('Query parameter q1 changed from', oldQuery, 'to', newQuery)
  }
)

// Watch for dynamic parameter changes
watch(
  () => route.params.id,
  (newId, oldId) => {
    // Respond to dynamic parameter changes
    console.log('User ID changed from', oldId, 'to', newId)
  }
)
</script>

Application of Navigation Guards

Using the beforeRouteUpdate navigation guard allows handling parameter changes when components are reused:

export default {
  async beforeRouteUpdate(to, from) {
    // Called when route updates but component is reused
    if (to.params.id !== from.params.id) {
      // User ID changed, reload data
      this.userData = await this.fetchUserData(to.params.id)
    }
    
    if (to.query.q1 !== from.query.q1) {
      // Query parameter changed, update search state
      this.performSearch(to.query.q1)
    }
  },
  
  methods: {
    async fetchUserData(userId) {
      // Async method to fetch user data
      return await api.getUser(userId)
    },
    
    performSearch(query) {
      // Logic for performing search
      console.log('Performing search:', query)
    }
  }
}

Practical Application Scenario Example

Consider a user list page that needs to support search and filtering functionality:

<template>
  <div>
    <input 
      v-model="searchText" 
      @input="updateSearchQuery" 
      placeholder="Search users..."
    />
    
    <select v-model="selectedFilter" @change="updateFilterQuery">
      <option value="all">All</option>
      <option value="active">Active Users</option>
      <option value="inactive">Inactive Users</option>
    </select>
    
    <!-- User list display -->
  </div>
</template>

<script>
export default {
  data() {
    return {
      searchText: this.$route.query.search || '',
      selectedFilter: this.$route.query.filter || 'all'
    }
  },
  
  methods: {
    updateSearchQuery() {
      // Debounce to avoid frequent URL updates
      clearTimeout(this.searchTimeout)
      this.searchTimeout = setTimeout(() => {
        this.$router.replace({
          name: 'user-list',
          query: {
            ...this.$route.query,
            search: this.searchText || undefined,
            filter: this.selectedFilter
          }
        })
      }, 300)
    },
    
    updateFilterQuery() {
      this.$router.replace({
        name: 'user-list',
        query: {
          ...this.$route.query,
          search: this.searchText || undefined,
          filter: this.selectedFilter
        }
      })
    }
  },
  
  watch: {
    '$route.query': {
      handler(newQuery) {
        // Update local state when URL query parameters change
        this.searchText = newQuery.search || ''
        this.selectedFilter = newQuery.filter || 'all'
        this.loadUsers()
      },
      immediate: true
    }
  },
  
  methods: {
    loadUsers() {
      // Load user data based on current query parameters
      const params = {
        search: this.searchText,
        filter: this.selectedFilter
      }
      // Call API to load data...
    }
  }
}
</script>

Best Practices and Considerations

When setting query parameters with Vue-Router, keep the following points in mind:

1. Always Provide Route Identifier: When using router.replace, you must specify either name or path parameters; otherwise, the route cannot be matched correctly.
2. Use Debouncing Appropriately: For frequently updated input fields, use debouncing techniques to avoid excessive route updates.
3. Handle Parameter Cleanup: Consider removing parameters from the URL when their values are empty or undefined.
4. Browser History Management: Understand the difference between push and replace and choose the appropriate method based on the scenario.
5. Performance Optimization: For complex data loading, consider using caching and lazy loading strategies.

By properly utilizing Vue-Router's query parameter functionality, you can create single-page applications with excellent user experience, achieving shareable and backtrackable URL states.