WARNING: query params are an experimental feature. You must be using a recent canary build of Ember, and enable the query-params-new feature flag. For more info on enabling feature flags visit the Feature Flags guide

查询参数 编辑页面

英文原文：http://emberjs.com/guides/routing/query-params/

通常情况下，URL的动态段是模型的一种序列化表示，最常见的是模型的ID。然后，有时候还需要将应用的其他状态也序列化到URL中。这可能是对从服务器端加载模型有影响的一些参数，比如要查看的是那一页结果；也可能是一些关于客户端状态的信息，比如在客户端实现排序时的记录排序规则。

当然URL中还可以被序列化一些更为全局性的信息，例如包含一个身份令牌到URL中，或者在应用里全局的过滤模型。除此之外，还可以包含任何不适合包含在常规动态段中的一些参数。必须在一个地图视图上，可能需要保存一系列在地图上可见图层的横坐标、纵坐标和缩放比例等参数。虽然这些也可以通过动态段来实现，不过那样就显得不那么自然。对于这样的一些应用场景，就可以考虑使用查询参数来替代了。

控制器驱动查询参数

对查询参数的支持被内置到控制器中，这与在路由层指定和管理的URL的其他部分不同。在控制器层实现的对查询参数的一流支持，使得可以提供一个强大的API来更新和响应查询参数的变更，而不需要开发者手动的安装和管理绑定/观察器来保持URL与控制器状态的同步。

指定查询参数

查询参数可以通过路由驱动的控制器来设置。回想一下，给定一个this.route('articles');指定的路由，ArticlesRoute的model钩子获取到的值将被加载到ArticlesController作为model属性。虽然ArticlesRoute可以在setupController钩子中加载数据到其他的控制器，但ArticlesController被认为是“路由驱动”的控制器，因此能够设定查询参数。

这里假设需要添加一个category查询参数，用来过滤那些没有被分类到流行的分类的文章。为了实现这个功能，可以指定'category'为ArticlesController的queryParams：

1
2
3
4

App.ArticlesController = Ember.ArrayController.extend({
  queryParams: ['category'],
  category: null
});

上述代码设定了URL查询参数category与ArticlesController的category属性之间的绑定。换句话说，当进入到articles路由时，URL中查询参数category的改变都会自动更新ArticlesController中的category属性，反之亦然。

接下来只需要定义一个articles模板渲染时需要使用的分类数组的计算属性即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

App.ArticlesController = Ember.ArrayController.extend({
  queryParams: ['category'],
  category: null,

  filteredArticles: function() {
    var category = this.get('category');
    var articles = this.get('model');

    if (category) {
      return articles.filterProperty('category', category);
    } else {
      return articles;
    }
  }.property('category', 'model')
});

上述代码主要完成了：

  1. 如果用户导航到/articles，category值为null，因此文章不会被过滤。
  2. 如果用户导航到/articles?articles[category]=recent，category被设置为"recent"，因此文章将被过滤。
  3. 一旦在articles路由里，改变ArticlesController中category属性的值，便会导致URL中对应的查询参数被更新。默认情况下，一个查询参数的改变并不会导致一次完整的路由过渡（例如：不会调用model和setupController钩子等）；只会更新URL。

link-to助手通过query-params子表达式助手可以支持指定查询参数。

1
2
3
4
5
6

// Explicitly set target query param
{{#link-to 'posts' (query-params direction="asc")}}Sort{{/link-to}}

// Binding is also supported
{{#link-to 'posts' (query-params
direction=otherDirection)}}Sort{{/link-to}}

上例中，direction是PostsController的一个假定的查询参数，它可以是posts路由层次结构上关联任意一个控制器的direction属性，该属性定义在匹配的一个叶节点控制器。

link-to助手当判断其是否是active状态的时候会考虑查询参数，并正确的设定样式类。active状态在点击一个链接的时候被计算出来，那么查询参数是否也是一样呢？其实并不需要提供所有的当前的活跃的查询参数。

transitionTo

Route#transitionTo（和Controller#transitionToRoute）增加了一个参数，该参数一个键值为queryParams的对象。

1
2
3
4
5
6

this.transitionTo('post', object, {queryParams: {showDetails: true}});
this.transitionTo('posts', {queryParams: {sort: 'title'}});

// if you just want to transition the query parameters without changing
the route
this.transitionTo({queryParams: {direction: 'asc'}});

当然也可以将查询参数加到URL过渡中：

1

this.transitionTo("/posts/1?sort=date&showDetails=true");

选择进入一个完整过渡

需要记住一点，transitionTo和link-to提供的参数只负责改变查询参数的值，并不改变路由的层次结构，也不会当做一个完整的过渡，这也就意味着model和setupController钩子默认不会被触发，仅仅会使用新的查询参数的值，更新控制器的属性的值和URL。

但是也有时查询参数的改变需要重新从服务器端加载数据，这种情况下就需要一次完整的过渡。当控制器查询参数属性变化时，为了实现一个完整的过渡，可以使用·Route中与对应控制器关联的可选的queryParams配置哈希，并将查询参数的refreshModel配置属性设置为true：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

App.ArticlesRoute = Ember.Route.extend({
  queryParams: {
    category: {
      refreshModel: true
    }
  },
  model: function(params) {
    // This gets called upon entering 'articles' route
    // for the first time, and we opt in refiring it
    // upon query param changes via `queryParamsDidChange` action

    // params has format of { category: "someValueOrJustNull" },
    // which we can just forward to the server.
    return this.store.findQuery('articles', params);
  }
});

App.ArticlesController = Ember.ArrayController.extend({
  queryParams: ['category'],
  category: null
});

使用replaceState来更新URL

缺省情况下，Ember使用pushState来更新地址栏中的URL来响应控制器查询参数属性的变化，然而也可以通过使用replaceState来实现（这会阻止在浏览器的历史中增加附加的条目），通过设定Route的queryParams配置哈希来启用，例如（接上例）：

1
2
3
4
5
6
7

App.ArticlesRoute = Ember.Route.extend({
  queryParams: {
    category: {
      replace: true
    }
  }
});

需要注意配置属性名及其默认false值与link-to助手的相似，需要通过设定replace=true来启用replaceState过渡。

将控制器的属性映射到不同的查询参数键值

缺省情况下，指定foo作为控制器的查询参数属性将会绑定一个键值为foo的查询参数，例如?foo=123。采用类似classNameBindings的冒号语法示例可以将控制器的属性绑定到一个不同的查询参数键值。

1
2
3
4

App.ArticlesController = Ember.ArrayController.extend({
  queryParams: ['category:articles_category'],
  category: null
});

上述代码会使得改变ArticlesController的category时更新articles_category查询参数，反之亦然。

默认值和反序列化

在下述例子中，控制器查询参数page默认值被设置为1。

1
2
3
4

App.ArticlesController = Ember.ArrayController.extend({
  queryParams: 'page',
  page: 1
});

这对查询参数行为的影响有两种方式：

  1. 在设置控制器值前，会使用默认值的类型来完成在URL中的查询参数值的类型转换。因此，在给定的上例中，如果用户点击后退按钮使得URL从/?page=3变为/?page=2，Ember会采用转换后的数值2来更新控制器的page属性，而非字符串的"2"，这是因为默认值1是数值型。这也使得布尔型参数的缺省值能在反序列化的时候被正确的转换。

  2. 当控制器的查询参数被设置为默认值时，该值不会被序列化到URL中。因此在上例中，如果page值为1，URL可能就是/articles，但是如果page的值被设置为2，那么URL应该就是/articles?page=2。

示例