事件

用法

zin 提供了 on 类通过 on::xxx() 方法实现前端 $().on() 形式的绑定。可以通过如下形式来绑定事件：

php

/** 绑定事件并调用 JS 回调函数。 */
on::eventName()->call(string $jsCallbackName, mixed ...$jsCallbackArgs): on

/** 绑定事件并执行 JS 代码。 */
on::eventName()->do(string|js ...$jsCode): on

以上 eventName 为事件名称，如 click、change 等。下面为一个完整的例子：

php

btn
(
    text('访问 ZIN 开发文档'),

    /* 通过链式调用 call 指定事件触发时要执行 JS 回调函数： */
    on::click()->call('window.open', 'https://openzui.com/zin/', '_blank')
    /* 以上等价于：通过链式调用 do 指定事件触发时要执行 JS 代码： */
    // on::click()->do('window.open("https://openzui.com/zin/", "_blank");')
);

事件委托

事件委托允许将事件绑定在父级元素上，通过选择器指定要监听的事件触发子元素，当子元素触发事件时，父级元素会接收到事件并执行绑定的回调函数。通过 on::xxx() 方法的第一个参数指定选择器，调用形式如下：

php

/** 绑定委托事件并调用 JS 回调函数。 */
on::eventName($selector)->call(string $jsCallbackName, mixed ...$jsCallbackArgs): on

/** 绑定委托事件并执行 JS 代码。 */
on::eventName($selector)->do(string|js ...$jsCode): on

以上 $selector 指定要监听事件触发的子元素。下面为一个完整的例子：

php

btnGroup
(
    /* 当 btnGroup 中 ID 为 #btn-2 的按钮点击时，通过链式调用 call 指定事件触发时要执行 JS 回调函数： */
    on::click('#btn-2')->call('console.log', 'this is btn-2'),
    /* 以上等价于： */
    // on::click('#btn-2')->do('console.log("this is btn-2");'),

    btn('btn-1', setID('btn-1')),
    btn('btn-2', setID('btn-2')),
    btn('btn-3', setID('btn-3'))
);

事件回调函数

通过 on 类定义事件回调函数

on 类继承了 js 类和继承了 jsHelper 类，因此可以使用 js 类和 jsHelper 类中的方法来生成回调函数。下面为一个综合的例子：

php

btn
(
    text('访问 ZIN 开发文档', setID('btnText')),

    /* 通过链式调用 call 指定事件触发时要执行 JS 回调函数： */
    on::click()
        ->call('console.log', 'you click the button.')
        ->addClass('$element', 'primary')
        ->toggleClass('body', 'dark')
        ->do
        (
            js::zui()->alert('you click the button.'),
            jQuery('#btnText')->text('you click the button.')
        )
);

通过 jsCallback 定义事件回调函数

当事件回调函数比较复杂时，可以将事件回调函数通过 jsCallback() 进行定义，存放在一个变量中，然后通过 on::click() 指定变量即可。下面为一个完整的例子：

php

/* 通过 jsCallback 定义回调函数。 */
$jsCallback = jsCallback()
    /* 执行当前回调函数中可以访问的方法： */
    ->call('console.log', 'you click the button.')

    /* 为当前元素添加 CSS 类： */
    ->addClass('$element', 'primary')

    /* 在 <body> 上切换 CSS 类： */
    ->toggleClass('body', 'dark')

    /* 根据条件来移除 CSS 类： */
    ->removeClassIf('$(this).hasClass("primary")', 'secondary')

    /* 通过 do() 来在回调函数中执行更多操作： */
    ->do
    (
        /* 直接指定要执行的 JS 代码： */
        'console.log("You clicked the button", event.target)',

        /* 通过 js::zui() 访问页面上 `window.zui` 对象并调用上面的方法： */
        js::zui()->alert('you click the button.'),

        /* 通过 jQuery() 访问页面上的 `$(selector)` 对象并调用上面的方法： */
        jQuery('#btnText')                   // 选择页面上 ID 为 #btnText 的元素。
            ->addClass('text-primary')       // 为该元素添加 CSS 类。
            ->text('you click the button.')  // 设置该元素的文本内容。
    );

btn
(
    span('访问 ZIN 开发文档', setID('btnText')),

    /* 通过指定回调函数变量绑定事件： */
    on::click($jsCallback)
);

回调函数预定义变量

在回调函数中，zin 会预定义一些变量，这些变量可以在回调函数中直接使用，下面为预定义变量列表：

变量名	作用
`$element`	当前事件绑定的元素。
`event`	当前事件对象。
`this`	当前事件触发元素。
`$this`	当前事件绑定的元素的 Cash（jQuery）实例。
`target`	当前事件触发目标元素，即 `event.target`。

示例：

php

$handleBtnClick = jsCallback()
    ->do(
        js::console()
            ->log('$element', jsRaw('$element'))
            ->log('this',     jsRaw('this'))
            ->log('event',    jsRaw('event'))
            ->log('$this',    jsRaw('$this'))
            ->log('target',   jsRaw('target'))
    );

btn
(
    text('访问 ZIN 开发文档', setID('btnText')),

    /* 通过链式调用 call 指定事件触发时要执行 JS 回调函数： */
    on::click($handleBtnClick)
);

事件修饰

zin 支持四类事件修饰符:

修饰符	作用	实现语句
self	只执行直接作用在该元素上的事件	`if(ele !== e.target) return;`
prevent	阻止默认动作执行	`e.preventDefault();`
stop	阻止捕获和冒泡阶段中当前事件的进一步传播	`e.stopPropagation();`

zin 中有两种方式使用事件修饰符：

在 $eventType 参数中添加后缀 __{'self'|'prevent'|'stop'}
调用 on 类的 self()、prevent()、stop() 方法

下面为一个完整的例子：

php

btn
(
    text('访问 ZIN 开发文档'),
    set::url('https://openzui.com/zin/'),

    /* 调用 prevent 阻止默认动作： */
    on::click()->prevent()->call('window.open', 'https://openzui.com/zin/', '_blank')

    /* 以上等价于： */
    // on::click__precent()->call('window.open', 'https://openzui.com/zin/', '_blank')
);

事件 ​

用法 ​

事件委托 ​

事件回调函数 ​

通过 on 类定义事件回调函数 ​

通过 jsCallback 定义事件回调函数 ​

回调函数预定义变量 ​

事件修饰 ​

事件