一、概述
1. Helpers允许你向你的模板添加超出在Ember中开箱即用的额外的功能。辅助器是最有用的,用于将来自模型和组件的原始值转换成更适合于用户的格式。
2. 例如,假设我们有一个Invoice model,它包含一个totalDue属性,它代表那个invoice的总数。由于我们不希望我们的公司由于奇怪的JavaScript舍入误差而倒闭,我们把这个值存为美分,而不是浮点美元值(we store this value in cents instead of a floating point dollar value)。
3. 然而,如果我们向我们的用户显示美元值为"100¢"而不是"$1.00",他们可能会非常困惑。我们可以编写一个辅助器去格式化这些值为合适的人类可读的形式。
4. 让我们创建一个format-currency helper,以一个整数计算每份并且把它格式化为美元。为了使用format-currency helper,在模板中使用花括号来调用它:
Your total is {{format-currency model.totalDue}}.
5. 让我们来实现这个辅助器。辅助器是functions,它携带一个或者两个输入并且返回一个单一的输出,这个输出应该放入进HTML。
6. 为了添加一个新的辅助器,在应用程序的helpers文件夹中创建一个和helper名字相同的文件。你也可以用命令行让Ember为你生成这个文件:
ember generate helper format-currency
这个文件应该用Ember.Helper.helper()封装导出一个function:
import Ember from "ember"; export default Ember.Helper.helper(function(params) {
let value = params[0],
dollars = Math.floor(value / 100),
cents = value % 100,
sign = '$'; if (cents.toString().length === 1) { cents = '0' + cents; }
return `${sign}${dollars}.${cents}`;
});
在这个例子中,这个function接收一个美分的金额作为第一个参数(params[0])。然后我们使用原始的JS把美分数量转换成一个格式化过的字符串,例如"$5.00"。
7. 不管什么时候你在一个模板中使用你的辅助器,Ember将会调用这个function并且把从你的辅助器返回的结果插入到DOM中。
所里,例如,如果我们有一个模板,比如我们传递一个值到format-currency中:
Your total is {{format-currency 250}}.
Ember将用格式化过的amout替换{{}}中的内容:
Your total is $2.50.
不管什么时候你改变传递给一个辅助器的参数,无论它们来自一个model还是一个component,Ember将会使用新的值再次自动调用你的辅助器并且更新DOM。
二、Helper Names
不像组件,辅助器不要求在它们的名字中有一个中划线(-)。
三、Helper Arguments
你可以传递一个或者更多个参数到这个function。在上面的例子中,我们传送的美分金额作为第一个并且是唯一的参数。
为了传送多个参数到一个辅助器,在辅助器的name后添加它们,中间有空格分隔:
{{my-helper "hello" "world"}}
一个这些参数的数组被传递到辅助器的function:
app/helpers/my-helper.js
import Ember from "ember"; export default Ember.Helper.helper(function(params) {
let arg1 = params[0];
let arg2 = params[1]; console.log(arg1); // => "hello"
console.log(arg2); // => "world"
});
你也可以使用JS的写法来简化代码。这个例子等同于上面的例子(注意function签名):
app/helpers/my-helper.js
import Ember from "ember"; export default Ember.Helper.helper(function([arg1, arg2]) {
console.log(arg1); // => "hello"
console.log(arg2); // => "world"
});
四、Named Arguments
1. 常规的参数是有用的,用于传递传递数据到辅助器的functions。然而,因为你传递参数的顺序很重要,通常不要让helpers获得多余一个或两个参数是最好的。
2. 也就是说,有时候你可能希望辅助器的行为是可以开发人员配置的,他们从模板调用它。例如,让我们放弃我们的美国方式并且更新我们的format-currency helper,带有一个可选的配置来决定展示什么货币符号。
3. 辅助器允许你以一个JS对象的形式传递命名的参数,包含参数的名称和一个关联的值。命名参数的顺序不影响功能。
在这个例子中,我们可以为ormat-currency helper传递一个sign参数:
{{format-currency 350 sign="£"}}
我们希望我们的辅助器打印出英镑而不是美元:
£3.50
这个对象包含命名参数,它作为第二个参数被传递到helper的function。把上面例子更新为支持可选的sign选项:
app/helpers/format-currency.js
import Ember from "ember"; export default Ember.Helper.helper(function(params, namedArgs) {
let value = params[0],
dollars = Math.floor(value / 100),
cents = value % 100,
sign = namedArgs.sign === undefined ? '$' : namedArgs.sign; if (cents.toString().length === 1) { cents = '0' + cents; }
return `${sign}${dollars}.${cents}`;
});
4. 你想传递几个命名的参数就传递几个。它们会添加到namedArgs参数传递到function:
{{my-helper option1="hello" option2="world" option3="goodbye cruel world"}}
app/helpers/my-helper.js
import Ember from "ember";
export default Ember.Helper.helper(function(params, namedArgs) {
console.log(namedArgs.option1); // => "hello"
console.log(namedArgs.option2); // => "world"
console.log(namedArgs.option3); // => "goodbye cruel world"
});
简化代码:
app/helpers/my-helper.js
import Ember from "ember";
export default Ember.Helper.helper(function(params, { option1, option2, option3 }) {
console.log(option1); // => "hello"
console.log(option2); // => "world"
console.log(option3); // => "goodbye cruel world"
});
5. 总之,参数是传递值很好的方式:
{{format-date currentDate}}
Hashes对于配置一个辅助器的行为是非常有用的:
{{print-current-date format="YYYY MM DD"}}
只要你想,你可以有无数多个,只要参数放在第一个:
{{format-date-and-time date time format="YYYY MM DD h:mm" locale="en"}}
- 上例中包含两个参数:
- date
- time
- 两个命名参数:
- format="YYY MM DD h:mm"
- locale="en"
五、Stateful Helpers
1. 默认情况下,helpers是无状态的。输入传入它们,它们在这些输入上采取操作并且返回一个单一的输出。它们没有副作用,并且把保存任何信息由于该函数的随后运行。
2. 在某些情况下,然而,你可能需要编写一个helper和你的应用程序的其他部分进行交互。你可以创建状态化的heplers,可以访问在应用程序中的服务,并且也可以有选择的保存状态。
3. 为了创建一个状态化的辅助器,而不是返回一个简单的function,你应该返回一个Ember.Helper的子类。Helper类必须包含一个compute方法,和传递给Ember.Helper.helper同样的行为。
4. 实际上,我们可以重构上面你的无状态辅助器为一个有状态的辅助器,仅仅通过把这个function变为在类上的compute方法:
app/helpers/format-currency.js
import Ember from "ember"; export default Ember.Helper.extend({
compute(params, hash) {
let value = params[0],
dollars = Math.floor(value / 100),
cents = value % 100,
sign = hash.sign === undefined ? '$' : hash.sign; if (cents.toString().length === 1) { cents = '0' + cents; }
return `${sign}${dollars}.${cents}`;
}
});
这确实等同于上面的例子。如果它不要求任何状态,对于长类形式你可以认为函数版本是一个简写。
六、Adding Services
状态化的辅助器可以获取应用程序中的服务。为了获取一个服务,你必须首先把它注入这个状态化辅助器。一旦添加了,你可以调用这个服务的方法或者访问它的属性,来自内部的compute()方法。
app/helpers/is-authenticated.js
import Ember from "ember"; export default Ember.Helper.extend({
authentication: Ember.inject.service()
compute() {
let authentication = this.get('authentication'); if (authentication.get('isAuthenticated')) {
return "Welcome back, " + authentication.get('username');
} else {
return "Not logged in";
}
}
});
七、Escaping Html Content
1. 为了保护你的应用程序避免XSS攻击,Ember自定转移从辅助器返回的任何值,这样浏览器不会把它解释为HTML。
2. 例如,这里一个make-bold辅助器,它返回一个包含HTML的字符串:
app/helpers/make-bold.js
import Ember from "ember";
export default Ember.Helper.helper(function(params) {
return `<b>${params[0]}</b>`;
});
你可以这样调用它:
{{make-bold "Hello world"}}
Ember将会转移HTML标签,像这样:
<b>Hello world</b>
3. 这里向用户展示非法的字符串<b>Hello world</b>,而不是你期望的黑体文字。我们可以告诉Ember不要转移返回的值通过使用htmlSafe:
app/helpers/make-bold.js
import Ember from "ember";
export default Ember.Helper.helper(function(params) {
return Ember.String.htmlSafe(`<b>${params[0]}</b>`);
});
如果你返回一个SafeString(一个字符串被htmlSafe封装),Ember知道你已经确认了它的行为,它不包含恶意的HTML。
4. 然而,注意,在上面的例子中我们可能只是无意中把一个XSS漏洞引入到了我们的应用程序中!通过盲目的标记字符串安全,恶意用户可以获取它们自己的HTML到我们引用程序,允许它们做的事情比如获取敏感的客户数据。
例如,假设我们有一个chat app并且使用我们的make-bold
helper来欢迎进入频道的新用户:
Welcome back! {{make-bold model.firstName}} has joined the channel.
现在,一个恶意用户仅仅需要设置这个firstName为一个包含HTML标签的字符串(像一个<script>标签,发送客户的隐私数据到它们的服务器),并且聊天室里的每个用户都受到了损害。
5. 通常,如果你想要封装你的内容到HTML中你应该跟喜欢使用组件。然而,如果你真的希望把来自models混合的HTML和values包含进你的helper返回的内容中,确保你转义了任何可能来自一个不受信任的用户的东西,使用escapeExpression
:
import Ember from "ember";
export default Ember.Helper.helper(function(params) {
let value = Handlebars.Utils.escapeExpression(params[0]);
return Ember.String.htmlSafe(`<b>${value}</b>`);
});
现在,传递进这个辅助器的值的HTML已经被转义,但是我们希望包裹着值的可信任的<b>标签没有被转义。一个而已用户设置它的firstName为一些包含HTML的内容,HTML会变成这样:
Welcome back! <b><script
type="javascript">alert('pwned!');</script></b> has joined the channel.