mirror of
https://github.com/motajs/template.git
synced 2026-11-21 04:04:30 +08:00
401 lines
17 KiB
Markdown
401 lines
17 KiB
Markdown
# 事件与交互
|
||
|
||
元素画出来之后,下一步是接住用户的操作:点击、按下、抬起、移动、悬停、滚轮。事件在容器与子元素之间有两个传递方向:**冒泡**是里面先生效,**捕获**是外面先生效。
|
||
|
||
一般更符合直觉的是冒泡。点一个按钮,应该先轮到按钮自己处理,而不是父容器先把事件接住;所以 `onClick`、`onDown` 这些默认事件都走冒泡。只有确实需要外层先处理时,才用 `onClickCapture`、`onDownCapture` 这类捕获写法。
|
||
|
||
## 前置知识
|
||
|
||
阅读本篇前,建议先读完:
|
||
|
||
- [容器与坐标](../basics/container-and-coordinates.md)
|
||
- [响应式](./reactivity.md)
|
||
|
||
## 内置事件及用法
|
||
|
||
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 模板,按钮上同时挂了按下、抬起与点击:
|
||
|
||
```tsx
|
||
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, {})` 打开后,点击矩形,日志会先出现「按下」「抬起」,再出现点击的捕获与冒泡。
|
||
|
||
<ClientOnly>
|
||
<RenderDemo :loader="eventsBasicLoader" :width="480" :height="320" />
|
||
<template #fallback>
|
||
渲染示例需要浏览器环境。
|
||
</template>
|
||
</ClientOnly>
|
||
|
||
这个 live 把按下、抬起、点击、进入、离开、移动与滚轮放在一起。
|
||
|
||
## 事件对象
|
||
|
||
点击、按下、抬起、移动、滚轮的回调都会收到事件对象。下面按用途分开看。
|
||
|
||
### target
|
||
|
||
每个处理元素拿到的 `target` 都是它自己,不是最初命中的元素。捕获从外层向内层走时,外层回调里的 `target` 是外层容器,内层回调里的 `target` 是内层元素;冒泡阶段复用同一份事件,`target` 仍然是该元素自己。所以父级回调里的 `target` 不会指向被点中的子元素;要知道最里面命中的是谁,只能在最内层的回调里记下来。
|
||
|
||
```tsx
|
||
// 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` 不可靠,不要用它判断按键。
|
||
|
||
```tsx
|
||
// 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`,但通常在多指触摸时才有意义。按下与抬起如果标识对不上,当前元素就不会产生点击。
|
||
|
||
```tsx
|
||
// 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 键。
|
||
|
||
```tsx
|
||
// 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` 不能混用。
|
||
|
||
```tsx
|
||
// 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>;
|
||
```
|
||
|
||
<ClientOnly>
|
||
<RenderDemo :loader="eventsCoordinatesLoader" :width="480" :height="320" />
|
||
<template #fallback>
|
||
渲染示例需要浏览器环境。
|
||
</template>
|
||
</ClientOnly>
|
||
|
||
在内外两层容器中移动或点击,三组坐标会同时更新:`offset` 随元素变化,`absolute` 始终是画布坐标。
|
||
|
||
### 滚轮
|
||
|
||
滚轮事件额外带 `wheelX` / `wheelY` / `wheelZ`,分别表示横向、纵向和垂直屏幕方向的滚动量;`wheelType` 表示这些数值的单位,取值来自 `WheelType`:`Pixel` 是像素,`Line` 是行(每行长度随浏览器设置变化,约 1rem),`Page` 是页(一般为一屏高度)。纵向滚动通常读 `wheelY`,但它的单位可能随浏览器设置变化。
|
||
|
||
```tsx
|
||
// 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:停止传播](#stop-propagation)。
|
||
|
||
## stopPropagation:传播控制 {#stop-propagation}
|
||
|
||
`stopPropagation()` 只做一件事:停止事件继续传播。
|
||
|
||
- 在捕获阶段调用:不再向内层元素捕获,同时这条链的冒泡也不会发生。
|
||
- 在冒泡阶段调用:不再向外层容器冒泡。
|
||
- 它不会阻止同一元素上、同一事件名的其它监听器执行。那些监听器在同一次事件分发里已经排好队,会全部执行完。
|
||
- 它不会阻止浏览器默认行为。滚动、文本选择之类的默认行为不受影响;它只影响这套画布事件系统的传播。
|
||
|
||
把 `stopPropagation` 放在三层结构的不同位置,日志结果不同:
|
||
|
||
| 调用位置 | 日志结果 |
|
||
| -------- | -------------------------------------------------- |
|
||
| 按钮捕获 | 根捕获 → 面板捕获 → 按钮捕获 |
|
||
| 按钮冒泡 | 根捕获 → 面板捕获 → 按钮捕获 → 按钮冒泡 |
|
||
| 面板捕获 | 根捕获 → 面板捕获 |
|
||
| 面板冒泡 | 根捕获 → 面板捕获 → 按钮捕获 → 按钮冒泡 → 面板冒泡 |
|
||
| 根捕获 | 根捕获 |
|
||
| 根冒泡 | 完整六步 |
|
||
|
||
最后一行值得注意:在根容器的冒泡回调里调用 `stopPropagation` 时,已经没有更外层的元素可传播,所以日志看起来仍然是完整的六步。它只是让「不再向外」这一步没有实际效果。
|
||
|
||
<ClientOnly>
|
||
<RenderDemo :loader="eventsPropagateLoader" :width="480" :height="320" />
|
||
<template #fallback>
|
||
渲染示例需要浏览器环境。
|
||
</template>
|
||
</ClientOnly>
|
||
|
||
live 只显示本次点击触发的事件;打开 stop 后,按钮的冒泡会被截断,外层不再收到,关闭 stop 时事件会完整走完捕获与冒泡。
|
||
|
||
## noevent、cursor 与 actionStroke
|
||
|
||
这三个属性都影响命中,决定了事件会不会落到元素上。
|
||
|
||
- `hidden` 的元素不绘制,也不参与命中,事件会直接落到它后面的元素。
|
||
- `noevent` 的元素照常绘制,但跳过命中。它不是只跳过自身,而是**整个子树都不参与命中**:容器加了 `noevent`,里面的子元素也收不到事件,事件会下穿到兄弟或下层元素;`cursor` 也同时失效。
|
||
- `cursor` 写在元素上,指针悬停时生效,取值与浏览器的鼠标样式一致,例如 `pointer`、`text`、`default`。多个元素同时命中时,最内层写了 `cursor` 的元素生效;元素被 `noevent` 跳过或 `hidden` 隐藏时,`cursor` 不再生效。
|
||
- `actionStroke` 只把描边算作命中,内部空白区域会下穿。它适合「只有边框看起来可点」的界面;命中宽度跟着 `lineWidth` 走,没有额外的最小热区。基础图形的命中细节见[基础图形](../basics/basic-shapes.md)。
|
||
|
||
容器即使没有可见背景,也会按自身矩形参与命中;不想挡住下面的元素就用 `noevent`,而不是把背景设成透明。
|
||
|
||
## 事件的完整触发模型
|
||
|
||
前面的现象都由同一套流程决定:先确定最上层命中的元素,再从根容器到目标捕获、从目标到根容器冒泡。
|
||
|
||
### 命中目标 {#命中测试事件先找最上层元素}
|
||
|
||
从根容器开始逐层检查子元素,找到指针下最上层、且没有被 `hidden` 或 `noevent` 跳过的元素。容器按自身矩形参与命中,图形按实际路径参与命中。
|
||
|
||
### 捕获与冒泡的方向
|
||
|
||
捕获从根容器向命中元素传递,父容器先收到;冒泡从命中元素向根容器传递,命中元素自己先收到。
|
||
|
||
```mermaid
|
||
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`,不要指望子元素的事件冒泡上来。
|
||
|
||
<ClientOnly>
|
||
<RenderDemo :loader="eventsHoverLoader" :width="480" :height="320" />
|
||
<template #fallback>
|
||
渲染示例需要浏览器环境。
|
||
</template>
|
||
</ClientOnly>
|
||
|
||
外层与内层分别显示进入 / 离开状态。从外层移到内层时,外层不会触发 `leave`;滚轮累计与 `cursor` 也跟随命中结果变化。
|
||
|
||
<script setup>
|
||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||
|
||
const eventsBasicLoader = () =>
|
||
import('../../.vitepress/components/demos/ui/events-basic-demo.tsx');
|
||
const eventsCoordinatesLoader = () =>
|
||
import('../../.vitepress/components/demos/ui/events-coordinates-demo.tsx');
|
||
const eventsPropagateLoader = () =>
|
||
import('../../.vitepress/components/demos/ui/events-propagate-demo.tsx');
|
||
const eventsHoverLoader = () =>
|
||
import('../../.vitepress/components/demos/ui/events-hover-demo.tsx');
|
||
</script>
|
||
|
||
## 边界与注意
|
||
|
||
- 事件属性名写错不会报错,也不会触发。
|
||
- 捕获方向是父 → 子,冒泡方向是子 → 父。同级的其它元素不会收到事件。
|
||
- `hidden` 的元素既不绘制也不参与命中;需要「还看得见但不能点」时用 `noevent`。
|
||
- `noevent` 作用于整个子树,不是只跳过自身。
|
||
- `stopPropagation` 只停止传播,不阻止同一元素上同一事件名的其它监听器,也不阻止浏览器默认行为。
|
||
- `enter` / `leave` 不按普通冒泡传递,由根的悬停集合做差集触发;父级要监听就自己挂 `onEnter` / `onLeave`。
|
||
- `offsetX` / `offsetY` 是当前元素的局部坐标,经过变换反算;`absoluteX` / `absoluteY` 才是画布坐标。
|
||
- `actionStroke` 的命中宽度等于 `lineWidth`,没有额外的最小热区。
|
||
- `onClick` 只在按下与抬起都落在同一个元素上时产生;指针移出后在别处抬起,只会触发别处的 `onUp`。
|