cssmagic/action

API Documentation / API 文档

cssmagic opened this issue · 2 comments

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

术语约定

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

HTML 接口

页面中的 DOM 元素可以通过 data-action 属性来声明自己被点击时要执行的动作。比如点击下面的链接和按钮就可以分别触发名为 foobar 的动作(即执行对应的动作函数)。

<a href="#" data-action="foo">Link</a>
<button data-action="bar">Button</button>

(值得一提的是,动作函数将以触发元素作为执行上下文。这跟事件的回调函数是类似的。)

对于链接元素,你还可以这样声明它的动作(似乎看起来更有语义,对用户也更友好一些):

<a href="#foo" data-action>Link</a>

注意事项

  • 只要元素具有 data-action 属性,其点击事件的默认行为就会被阻止。
  • 如果元素声明的动作名还没有定义,则不会执行任何动作函数。
  • 如果链接元素同时指定了 hrefdata-action 属性的值,则只有后者会被视为动作名声明。
  • 如果链接元素通过 href 属性来声明动作名,则 href 属性值必须以 # 开头。
  • 元素声明的动作名的开头所有 #! 和空白符都将被忽略,结尾的空白符也将被忽略,这意味着 #foo#!foo ## !! foo 都会被视为 foo

JavaScript 接口

action.define(actions)

定义一个或多个动作。

参数

  • actions -- 纯对象。需要定义的动作。对象的键名为动作名,键值为动作函数。

返回值

(无)

示例

以下代码将定义两个名为 foobar 的动作。

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

示例

如果你已经在上面定义了 foobar 两个动作,那么以下代码将会触发名为 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 详细讨论。谢谢。