API Documentation / API 文档
cssmagic opened this issue · 2 comments
如果你还不清楚这个库的用处,请参阅《简介》。
术语约定
- 动作 -- 你有一件特定的事情要做,可以将它定义为一个 “动作”,以便在必要时触发它。
- 动作名 -- 每个动作都需要有一个名字,即 “动作名”。
- 动作函数 -- 每个动作的行为使用函数来描述,即 “动作函数”。
HTML 接口
页面中的 DOM 元素可以通过 data-action
属性来声明自己被点击时要执行的动作。比如点击下面的链接和按钮就可以分别触发名为 foo
和 bar
的动作(即执行对应的动作函数)。
<a href="#" data-action="foo">Link</a>
<button data-action="bar">Button</button>
(值得一提的是,动作函数将以触发元素作为执行上下文。这跟事件的回调函数是类似的。)
对于链接元素,你还可以这样声明它的动作(似乎看起来更有语义,对用户也更友好一些):
<a href="#foo" data-action>Link</a>
注意事项
- 只要元素具有
data-action
属性,其点击事件的默认行为就会被阻止。 - 如果元素声明的动作名还没有定义,则不会执行任何动作函数。
- 如果链接元素同时指定了
href
和data-action
属性的值,则只有后者会被视为动作名声明。 - 如果链接元素通过
href
属性来声明动作名,则href
属性值必须以#
开头。 - 元素声明的动作名的开头所有
#
、!
和空白符都将被忽略,结尾的空白符也将被忽略,这意味着#foo
、#!foo
和## !! foo
都会被视为foo
。
JavaScript 接口
action.define(actions)
定义一个或多个动作。
参数
actions
-- 纯对象。需要定义的动作。对象的键名为动作名,键值为动作函数。
返回值
(无)
示例
以下代码将定义两个名为 foo
和 bar
的动作。
action.define({
'foo': function () {
alert('You triggered action `foo`!')
},
'bar': function () {
this.bar = true
alert('You triggered action `bar`!')
}
})
注意事项
- 在定义动作时,动作名的开头所有
#
、!
和空白符都将被忽略,结尾的空白符也将被忽略。 - 无法定义一个动作名为空字符串的动作。
- 如果在定义动作时使用了已经存在的动作名,则相当于用新的动作函数替换原有的动作函数。原因在于每个动作名只能对应一个动作函数。
action.add()
⚠️
此方法系 action.define()
的别名。
⚠️ 注意:从 v0.4 起不建议使用.add()
,请使用.define()
代替。
action.trigger(actionName, [context])
除了页面元素可以触发动作外,这个方法还允许你在 JS 代码中触发指定动作(甚至你还可以指定动作函数的执行上下文)。
这个方法可能并不常用,只是提供了另一种途径来调用你定义的动作。
参数
actionName
-- 字符串。动作名。context
-- 可选。对象。动作函数的执行上下文,默认为window
。
返回值
- 返回动作函数执行后的返回值。
- 触发一个不存在的动作时,返回值为
undefined
。
示例
如果你已经在上面定义了 foo
和 bar
两个动作,那么以下代码将会触发名为 foo
的动作。
action.trigger('foo')
以下代码将会触发名为 bar
的动作,而且动作函数将以 <body>
元素作为执行上下文(即函数内部的 this
在此次执行时会指向 document.body
)。
//document.body.bar === undefined
action.trigger('bar', document.body)
//document.body.bar === true
注意事项
- 在触发指定动作时,动作名的开头所有
#
、!
和空白符都将被忽略,结尾的空白符也将被忽略。 - 如果触发一个不存在的动作,则不会执行任何动作函数。
为什么到处都有 !
和 #
?
对于链接元素,可以用 href
属性来声明动作名。而此时 href
值通常是个 hash,需要把 #
过滤掉;滤 hash 就顺便滤一下 hashbang。由于链接的 href
值(动作名)可能不经修改就被复制到了别处,所以各处都会滤一下这些特殊字符。
简而言之,这是一个容错机制。这些过滤对日常开发几乎没有影响,应该不会有人特意用这些特殊字符来命名或区分动作名吧。
目前是这样设计的。如果觉得不妥,请开个 issue 详细讨论。谢谢。