17 KiB
事件与交互
元素画出来之后,下一步是接住用户的操作:点击、按下、抬起、移动、悬停、滚轮。事件在容器与子元素之间有两个传递方向:冒泡是里面先生效,捕获是外面先生效。
一般更符合直觉的是冒泡。点一个按钮,应该先轮到按钮自己处理,而不是父容器先把事件接住;所以 onClick、onDown 这些默认事件都走冒泡。只有确实需要外层先处理时,才用 onClickCapture、onDownCapture 这类捕获写法。
内置事件及用法
TSX 里用 onXxx 绑定事件。常用事件如下:
| 冒泡阶段 | 捕获阶段 | 触发时机 |
|---|---|---|
onClick |
onClickCapture |
点击 |
onDown |
onDownCapture |
按下 |
onUp |
onUpCapture |
抬起 |
onMove |
onMoveCapture |
指针在元素上移动 |
onEnter |
— | 指针进入元素 |
onLeave |
— | 指针离开元素 |
onWheel |
onWheelCapture |
在元素上滚动滚轮 |
这些是元素属性,直接写在元素上即可。属性名写错不会报错,也不会触发。
事件回调建议先单独声明成函数,再把函数名传给属性,例如 const handleClick = (ev) => { ... },然后 onClick={handleClick}。只有需要额外参数时才内联包一层,例如 onClick={() => handleClick(param)};只用到事件对象时直接传函数,不必再写成 onClick={ev => handleClick(ev)}。需要标注类型时,可以从 @motajs/render 引入 IActionEvent / IWheelEvent。
onClick 不是单独的按下:按下与抬起都发生在同一个元素上,才会产生点击。按下后把指针移出元素、在元素外抬起,只会触发另一个元素的 onUp,当前元素不会触发 onClick。同一次抬起里,onUp 先处理完,然后才处理 onClick。
下面是一段完整的 UI 模板,按钮上同时挂了按下、抬起与点击:
import { defineComponent, ref } from 'vue';
import { GameUI, SetupComponentOptions } from '@motajs/system';
import { DefaultProps } from '@motajs/render-vue';
import { IGameUIPropsBase } from '@user/client-base';
import { FULL_LOC } from '@/client';
// 这里填写自定义的 UI 参数
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
const myPanelProps = {
props: ['controller', 'instance', 'state']
} satisfies SetupComponentOptions<MyPanelProps>;
const MyPanel = defineComponent<MyPanelProps>(props => {
// 收集本次交互的日志,只保留最近 6 条,避免文字越界
const log = ref<string[]>([]);
const push = (text: string) => {
// 按触发顺序追加日志
log.value = [...log.value, text].slice(-6);
};
const handleOuterCapture = () => push('外层捕获');
const handleOuterBubble = () => push('外层冒泡');
const handleDown = () => push('按下');
const handleUp = () => push('抬起');
const handleClick = () => push('点击');
return () => (
// 外层捕获先于子元素执行,冒泡时最后执行
<container
loc={FULL_LOC}
onClickCapture={handleOuterCapture}
onClick={handleOuterBubble}
>
{/* 蓝色矩形同时挂按下、抬起与点击 */}
<g-rect
loc={[40, 40, 160, 48]}
fillStyle="#2f6fed"
onDown={handleDown}
onUp={handleUp}
onClick={handleClick}
/>
{/* 日志按触发顺序拼成一行 */}
<text
loc={[40, 110]}
text={log.value.join(' → ')}
fillStyle="#ffffff"
/>
</container>
);
}, myPanelProps);
export const MyPanelUI = new GameUI('my-panel', MyPanel);
在已有 UI 中使用 props.controller.open(MyPanelUI, {}) 打开后,点击矩形,日志会先出现「按下」「抬起」,再出现点击的捕获与冒泡。
这个 live 把按下、抬起、点击、进入、离开、移动与滚轮放在一起。
事件对象
点击、按下、抬起、移动、滚轮的回调都会收到事件对象。下面按用途分开看。
target
每个处理元素拿到的 target 都是它自己,不是最初命中的元素。捕获从外层向内层走时,外层回调里的 target 是外层容器,内层回调里的 target 是内层元素;冒泡阶段复用同一份事件,target 仍然是该元素自己。所以父级回调里的 target 不会指向被点中的子元素;要知道最里面命中的是谁,只能在最内层的回调里记下来。
// setup
import type { IActionEvent } from '@motajs/render';
const outerTargetId = ref('');
const buttonTargetId = ref('');
const handleOuterCapture = (ev: IActionEvent) => {
// 外层捕获先执行,这里的 target 是 panel 自己
outerTargetId.value = ev.target.id;
};
const handleButtonClick = (ev: IActionEvent) => {
// 矩形冒泡时,target 才是 button 自己
buttonTargetId.value = ev.target.id;
};
// 组件内容
<container id="panel" onClickCapture={handleOuterCapture}>
<g-rect
id="button"
loc={[40, 40, 160, 48]}
fillStyle="#2f6fed"
onClick={handleButtonClick}
/>
</container>;
按键:type 与 buttons
type 是本次触发对应的按键,取值来自 MouseType,比如 Left、Middle、Right、Back、Forward。buttons 是当前还按住的所有键,按位组合。抬起与点击时,buttons 不包含刚刚抬起的那个键,所以「点击是否由左键触发」要看 type,不能看 buttons。移动与滚轮里的 type 不可靠,不要用它判断按键。
// setup
import type { IActionEvent } from '@motajs/render';
import { MouseType } from '@motajs/render';
const isLeftClick = (ev: { type: MouseType }) => {
// type 表示这次触发对应的按键
return ev.type === MouseType.Left;
};
const isHoldingLeft = (ev: { buttons: number }) => {
// 位运算:buttons 的第 0 位为 1 表示左键仍被按住
return (ev.buttons & MouseType.Left) !== 0;
};
const handleDown = (ev: IActionEvent) => {
// 按下时 type 是按下键,buttons 同时包含这个键
if (isLeftClick(ev) && isHoldingLeft(ev)) {
// 这里可以开始拖拽
}
};
const handleClick = (ev: IActionEvent) => {
// 点击时 type 仍是左键,但 buttons 已经不含刚抬起的左键
if (isLeftClick(ev)) {
// 这里可以处理左键点击
}
};
// 组件内容
<g-rect
loc={[40, 40, 160, 48]}
fillStyle="#2f6fed"
onDown={handleDown}
onClick={handleClick}
/>;
标识符与触摸
touch 表示这次操作来自触摸还是鼠标。identifier 是这次操作的编号:同一次按下、移动、抬起期间保持不变,用来在多指场景里把不同手指的操作串起来。鼠标也会带 identifier,但通常在多指触摸时才有意义。按下与抬起如果标识对不上,当前元素就不会产生点击。
// setup
import type { IActionEvent } from '@motajs/render';
const lastTouch = ref(0);
const handleDown = (ev: IActionEvent) => {
// 触摸时记下这次操作的 identifier
if (ev.touch) lastTouch.value = ev.identifier;
};
const handleUp = (ev: IActionEvent) => {
// 抬起时 identifier 与按下时相同;对不上就不会产生点击
if (ev.touch && ev.identifier === lastTouch.value) {
lastTouch.value = 0;
}
};
// 组件内容
<g-rect
loc={[40, 40, 160, 48]}
fillStyle="#2f6fed"
onDown={handleDown}
onUp={handleUp}
/>;
修饰键
altKey、shiftKey、ctrlKey、metaKey 是触发时四个修饰键的状态。metaKey 对应 Windows 键或 Mac 的 Command 键。
// setup
import type { IActionEvent } from '@motajs/render';
const shortcut = ref('普通点击');
const handleClick = (ev: IActionEvent) => {
// 按下的修饰键不同,走不同的快捷操作
if (ev.ctrlKey) shortcut.value = 'Ctrl + 点击';
else if (ev.shiftKey) shortcut.value = 'Shift + 点击';
else shortcut.value = '普通点击';
};
// 组件内容
<g-rect loc={[40, 40, 160, 48]} fillStyle="#2f6fed" onClick={handleClick} />;
坐标
offsetX / offsetY 是相对当前元素左上角的局部坐标;absoluteX / absoluteY 是相对整块画布左上角的坐标。事件进入子元素时,会用子元素的变换做逆运算:缩放不会改变局部坐标的范围,旋转会被反算,嵌套的每一层都会重新换算。因此在父级和子级拿到的是不同值,父级的 offset 与子级的 offset 不能混用。
// setup
import type { IActionEvent } from '@motajs/render';
const localOffset = ref('—');
const canvasOffset = ref('—');
const handleMove = (ev: IActionEvent) => {
// local 坐标以外层容器左上角为原点
localOffset.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
// absolute 坐标以整块画布左上角为原点
canvasOffset.value = `${Math.round(ev.absoluteX)}, ${Math.round(
ev.absoluteY
)}`;
};
// 组件内容
<container loc={[40, 40, 200, 120]} onMove={handleMove}>
<g-rect loc={[24, 24, 120, 64]} fillStyle="#2f6fed" />
</container>;
在内外两层容器中移动或点击,三组坐标会同时更新:offset 随元素变化,absolute 始终是画布坐标。
滚轮
滚轮事件额外带 wheelX / wheelY / wheelZ,分别表示横向、纵向和垂直屏幕方向的滚动量;wheelType 表示这些数值的单位,取值来自 WheelType:Pixel 是像素,Line 是行(每行长度随浏览器设置变化,约 1rem),Page 是页(一般为一屏高度)。纵向滚动通常读 wheelY,但它的单位可能随浏览器设置变化。
// setup
import type { IWheelEvent } from '@motajs/render';
import { WheelType } from '@motajs/render';
const handleWheel = (ev: IWheelEvent) => {
// wheelY 是纵向滚动量,wheelType 决定这个数值的单位
if (ev.wheelType === WheelType.Pixel) {
// 这里可以按像素处理 wheelY
}
};
// 组件内容
<g-rect loc={[40, 40, 240, 100]} fillStyle="#26364d" onWheel={handleWheel} />;
stopPropagation
stopPropagation() 用来停止事件继续传播,见后面的 stopPropagation:停止传播。
stopPropagation:传播控制
stopPropagation() 只做一件事:停止事件继续传播。
- 在捕获阶段调用:不再向内层元素捕获,同时这条链的冒泡也不会发生。
- 在冒泡阶段调用:不再向外层容器冒泡。
- 它不会阻止同一元素上、同一事件名的其它监听器执行。那些监听器在同一次事件分发里已经排好队,会全部执行完。
- 它不会阻止浏览器默认行为。滚动、文本选择之类的默认行为不受影响;它只影响这套画布事件系统的传播。
把 stopPropagation 放在三层结构的不同位置,日志结果不同:
| 调用位置 | 日志结果 |
|---|---|
| 按钮捕获 | 根捕获 → 面板捕获 → 按钮捕获 |
| 按钮冒泡 | 根捕获 → 面板捕获 → 按钮捕获 → 按钮冒泡 |
| 面板捕获 | 根捕获 → 面板捕获 |
| 面板冒泡 | 根捕获 → 面板捕获 → 按钮捕获 → 按钮冒泡 → 面板冒泡 |
| 根捕获 | 根捕获 |
| 根冒泡 | 完整六步 |
最后一行值得注意:在根容器的冒泡回调里调用 stopPropagation 时,已经没有更外层的元素可传播,所以日志看起来仍然是完整的六步。它只是让「不再向外」这一步没有实际效果。
live 只显示本次点击触发的事件;打开 stop 后,按钮的冒泡会被截断,外层不再收到,关闭 stop 时事件会完整走完捕获与冒泡。
noevent、cursor 与 actionStroke
这三个属性都影响命中,决定了事件会不会落到元素上。
hidden的元素不绘制,也不参与命中,事件会直接落到它后面的元素。noevent的元素照常绘制,但跳过命中。它不是只跳过自身,而是整个子树都不参与命中:容器加了noevent,里面的子元素也收不到事件,事件会下穿到兄弟或下层元素;cursor也同时失效。cursor写在元素上,指针悬停时生效,取值与浏览器的鼠标样式一致,例如pointer、text、default。多个元素同时命中时,最内层写了cursor的元素生效;元素被noevent跳过或hidden隐藏时,cursor不再生效。actionStroke只把描边算作命中,内部空白区域会下穿。它适合「只有边框看起来可点」的界面;命中宽度跟着lineWidth走,没有额外的最小热区。基础图形的命中细节见基础图形。
容器即使没有可见背景,也会按自身矩形参与命中;不想挡住下面的元素就用 noevent,而不是把背景设成透明。
事件的完整触发模型
前面的现象都由同一套流程决定:先确定最上层命中的元素,再从根容器到目标捕获、从目标到根容器冒泡。
命中目标
从根容器开始逐层检查子元素,找到指针下最上层、且没有被 hidden 或 noevent 跳过的元素。容器按自身矩形参与命中,图形按实际路径参与命中。
捕获与冒泡的方向
捕获从根容器向命中元素传递,父容器先收到;冒泡从命中元素向根容器传递,命中元素自己先收到。
sequenceDiagram
participant R as 根容器
participant P as 面板容器
participant B as 命中元素
R->>P: 捕获
P->>B: 捕获
B->>P: 冒泡
P->>R: 冒泡
同一次事件里,捕获一定先于冒泡;命中元素自己的捕获先执行,然后才是它自己的冒泡。同级的其它元素不会收到这次事件。
enter 与 leave:悬停集合的差集
onEnter / onLeave 不按捕获 / 冒泡传递。根节点维护一份当前悬停集合:每次指针移动时重新收集指针下的元素,再与上一次的集合比较,对离开的元素触发 leave、对新进入的元素触发 enter,顺序是先 leave 后 enter。
集合里包含命中链上的所有祖先,所以从父容器移到子元素时,父容器仍在集合里,不会触发 leave;从子元素移到同级另一个子元素时,共同父容器也不会触发任何事件。
父容器要感知悬停,就在父容器上挂 onEnter / onLeave,不要指望子元素的事件冒泡上来。
外层与内层分别显示进入 / 离开状态。从外层移到内层时,外层不会触发 leave;滚轮累计与 cursor 也跟随命中结果变化。
边界与注意
- 事件属性名写错不会报错,也不会触发。
- 捕获方向是父 → 子,冒泡方向是子 → 父。同级的其它元素不会收到事件。
hidden的元素既不绘制也不参与命中;需要「还看得见但不能点」时用noevent。noevent作用于整个子树,不是只跳过自身。stopPropagation只停止传播,不阻止同一元素上同一事件名的其它监听器,也不阻止浏览器默认行为。enter/leave不按普通冒泡传递,由根的悬停集合做差集触发;父级要监听就自己挂onEnter/onLeave。offsetX/offsetY是当前元素的局部坐标,经过变换反算;absoluteX/absoluteY才是画布坐标。actionStroke的命中宽度等于lineWidth,没有额外的最小热区。onClick只在按下与抬起都落在同一个元素上时产生;指针移出后在别处抬起,只会触发别处的onUp。