API Documentation / API 文档

cssmagic commented 9 years ago

如果你还不清楚这个库的用处，请参阅《简介》。

术语约定

动作 -- 你有一件特定的事情要做，可以将它定义为一个 “动作”，以便在必要时触发它。
动作名 -- 每个动作都需要有一个名字，即 “动作名”。
动作函数 -- 每个动作的行为使用函数来描述，即 “动作函数”。

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

注意事项

在触发指定动作时，动作名的开头所有 #、! 和空白符都将被忽略，结尾的空白符也将被忽略。
如果触发一个不存在的动作，则不会执行任何动作函数。

antife-yinyue commented 9 years ago

为什么到处都有 ! 和 #？

cssmagic commented 9 years ago

对于链接元素，可以用 href 属性来声明动作名。而此时 href 值通常是个 hash，需要把 # 过滤掉；滤 hash 就顺便滤一下 hashbang。由于链接的 href 值（动作名）可能不经修改就被复制到了别处，所以各处都会滤一下这些特殊字符。

简而言之，这是一个容错机制。这些过滤对日常开发几乎没有影响，应该不会有人特意用这些特殊字符来命名或区分动作名吧。

目前是这样设计的。如果觉得不妥，请开个 issue 详细讨论。谢谢。

cssmagic / action