4.9 Routing -- Query Parameters

一、概述

1. 在URL中查询参数是可选的key-value对，出现在?的右边。例如，下面的URL有两个查询参数，sort和page，对应的值分别是ASC和2。

example:http://example.com/articles?sort=ASC&page=2

2. Query params允许那些不能融入URL路径的额外的应用程序状态被序列化到URL中（比如?左边的任何东西）。常见的使用案例查询参数包括：分页集合中的当前页码，筛选条件，或排序标准。

二、Specifying query parameters

1. 查询参数被声明在路由驱动controllers中。例如，配置查询参数活动在articles路由中，它们必须被声明在controller:articles中。

2. 添加一个category查询参数将过滤出所有没有被归类为popular的文章，我们指定'category'作为controller:article的其中一个查询参数：

app/controller/articles.js

export default Ember.Controller.extend({
  queryParams: ['category'],
  category: null
});

• 这设置一个在URL中category查询参数和controller:articles中category属性的绑定。换句话说，一旦进入articles路由，URL中category查询参数的任何改变都会更新controller:articles中的category属性，反之亦然。

3. 现在我们仅仅需要为我们的类别过滤的数组定义一个计算属性，articles模板将会渲染：

app/controllers/articles.js

export default Ember.Controller.extend({
  queryParams: ['category'],
  category: null,

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

    if (category) {
      return articles.filterBy('category', category);
    } else {
      return articles;
    }
  })
});

用上面的代码，我们建立了以下操作：

• 如果用户导航到/articles，category将会是null，所以articles不会被过滤。
• 如果用户导航到/articles?category=recent，category将会被设置为"recent"，所以articles将会被过滤。
• 一旦在articles路由中，controller:articles中category属性的任何改变都会引起URL更新查询参数。默认的，一个查询参数属性改变不会引起整个路由器的跳转（它不回调用model hooks和setupController），它只是更新URL。

三、Link-To Helper

1. link-to辅助器通过使用子表达式辅助器query-params支持指定查询参数。

// Explicitly set target query params
{{#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想必是controller:post中的一个查询参数属性，但是它可以是任何与post路由层级相关的controllers的一个direction属性，用提供的属性名匹配最里层的controller（leaf-most controller）。

2. link-to辅助器当确定"active"状态时会考虑查询参数，并且设置适当的类。激活状态是通过计算查询参数点击一个链接后是否最终相同决定。

您不必提供所有当前的，活动的查询参数是正确的。

四、Transitions To

1. Route#transitionTo和controller#transitionToRoute接收一个最终的参数，它是一个key为queryParams的对象。

app/routes/some-route.js

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'}});

2. 你也可以为URL transitions加上查询参数：

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

五、Opting into a full transition（选择进入一个完全跳转）

1. 被提供给transitionTo或者link-to的参数仅仅对应在查询参数值中的一个变化，而不是路由层次上的变化，它不认为是一个完全跳转，这意味着像model和setupController的hooks默认的不会被启动，但是只有控制器属性将会用一个新的查询参数被更新，URL也是如此。

2. 但是一些查询参数改变从服务器上必要的加载数据，在这种情况下理想的是选择进入一个完全跳转。当一个controller的查询参数属性改变时，选择进入一个完全跳转，可以使用在相关controller的Route中可选的配置queryParams，并且设置查询参数的refreshModel配置属性为true：

app/routes/articles.js

export default Ember.Route.extend({
  queryParams: {
    category: {
      refreshModel: true
    }
  },
  model(params) {
    // This gets called upon entering 'articles' route
    // for the first time, and we opt into refiring it upon
    // query param changes by setting `refreshModel:true` above.

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

app/controllers/articles.js

export default Ember.Controller.extend({
  queryParams: ['category'],
  category: null
});

六、Update URL with replaceState instead

默认的，Ember将使用pushState来更新地址栏中的URL去响应一个controller的查询参数属性的变化，但是如果你想用replaceState代替（防止添加额外的条目到浏览器的历史记录中），你可以在Route的queryParams config hash中指定它。继续上面的例子：

app/routes/articles.js

export default Ember.Route.extend({
  queryParams: {
    category: {
      replace: true
    }
  }
});

注意，这个配置属性的名字和它的默认值false和link-to的有一点像，它也让你通过replace=true选择进入replaceState跳转。

七、Map a controller's property to a different query param key

1. 默认的，指定foo作为一个controller的查询属性将会绑定一个查询参数，它的key是foo，例如?foo=123。你也可以映射一个controller的属性到一个不同的查询参数key，通过使用下面的配置语法：

app/controllers/articles.js

export default Ember.Controller.extend({
  queryParams: {
    category: "articles_category"
  },
  category: null
});

这将会引起controller:articles的cateogry属性改变去更新查询字符串articles_category，反之亦然。

2. 需要注意的是需要额外的定制，可以与查询参数数组中的字符串一起提供的查询参数。

app/controllers/article.js

export default Ember.Controller.extend({
  queryParams: [ "page", "filter", {
    category: "articles_category"
  }],
  category: null,
  page: 1,
  filter: "recent"
});

八、Default values and deserialization

在下面的例子中，controller的查询参数属性page被认为有一个默认值是1：

app/controllers/articles.js

export default Ember.Controller.extend({
  queryParams: 'page',
  page: 1
});

这会在两个方面影响查询参数的行为：

• 查询参数的值转换为相同的数据类型作为默认值，例如一个URL从/?page=3变为/?page=2将会设置controller:articles的page属性为数字2，而不是字符串"2"。同样适用于默认的布尔值。
• 当一个controller的查询参数属性当前被设置为它的默认值，值不会被序列化到URL中。所以，在上面的例子中，如果page是1，URL将会类似/articles，但是一旦设置page的值为2，URL将会变成/articles?page=2。

九、Sticky query param values(置顶的查询参数值)

1. 默认的，在Ember中查询参数值是"sticky"，原因是，如果你改变一个查询参数，然后离开并重新输入路由，该查询参数的新值将被保留（而不是重置为默认值）。当您在路由之间来回浏览时，对维护排序/过滤器参数来说，这是一个特别方便的默认。

2. 此外，这些置顶的查询参数值根据加载到路径中的模型被记住/恢复。所以假定一个team路由有动态字段/:team_name并且controlle的查询参数"filter"，如果你导航到/badgers并且通过"rookies"筛选，然后导航到/bear并且通过"best"筛选，然后导航到/potatoes并且通过"lamest"筛选，然后将定下面是导航栏链接：

{{#link-to 'team' 'badgers'}}Badgers{{/link-to}}
{{#link-to 'team' 'bears'   }}Bears{{/link-to}}
{{#link-to 'team' 'potatoes'}}Potatoes{{/link-to}}

生成的link是：

<a href="/badgers?filter=rookies">Badgers</a>
<a href="/bears?filter=best">Bears</a>
<a href="/potatoes?filter=lamest">Potatoes</a>

这说明一旦变更查询参数，它被存储和绑到加载的路径的模型中。

3. 如果你想要重新设置一个查询参数，你有两种选择：

• 明确的传入默认值到link-to或者transitionTo。
• 使用Route.resetController hook设置查询参数值返回到它们存在的路由或者路由模型改变之前的默认值。
• 在下面的例子中，controller的page查询参数被设置为1，同时还作用于重定向之前的ArticlesRoute model。这样做的结果是，所有指向后退到出口的路由将会使用新设置的值1作为page查询参数的值。
• app/routes/articles.js

• export default Ember.Route.extend({
    resetController (controller, isExiting, transition) {
      if (isExiting) {
        // isExiting would be false if only the route's model was changing
        controller.set('page', 1);
      }
    }
  });

4. 在有些情况下，你可能不希望sticky查询参数的值作用于路由的模型，但宁愿重用一个查询参数的值甚至作为一个路由的模型改变。这可以通过设置到controller的queryParams config hash中的scope选项来实现：

app/controllers/articles/js

export default Ember.Controller.extend({
  queryParams: [{
    showMagnifyingGlass: {
      scope: "controller"
    }
  }]
});

5. 下面说明你可以如何重写一个单一的controller查询参数属性的scope和查询参数 URL key：

app/controllers/articles.js

export default Ember.Controller.extend({
  queryParams: [ "page", "filter",
    {
      showMagnifyingGlass: {
        scope: "controller",
        as: "glass",
      }
    }
  ]
});