mirror of
https://github.com/motajs/template.git
synced 2026-11-21 04:04:30 +08:00
docs: add render guide and migrate UI documentation
This commit is contained in:
1 parent
2a4b3220ed
commit
c4096f4bfb
40 files changed
+1815
-563
No files matched your search
@@ -0,0 +1,402 @@
|
||||
# 内置组件:基础
|
||||
|
||||
`@user/client-base` 里已经有一批常用的基础组件。它们和普通组件一样,在 TSX 里按名字使用,属性名写成 camelCase。下面每个组件都先说它解决什么问题,再给最小写法,常用参数跟着讲,最后接一个 live。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [什么是组件](./what-is-component.md)
|
||||
|
||||
## Input
|
||||
|
||||
要接收用户文字输入,用 `Input`。
|
||||
|
||||
第一步:用 `v-model:value` 绑定一个字符串拿到输入内容,`loc` 给位置与大小,宽度决定输入区的宽度。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Input } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const name = ref('');
|
||||
|
||||
// 组件内容
|
||||
<Input loc={[40, 56, 240, 32]} v-model:value={name.value} />;
|
||||
```
|
||||
|
||||
输入框还没有内容时,想给一句提示,加 `placeholder`:
|
||||
|
||||
```tsx
|
||||
<Input
|
||||
loc={[40, 56, 240, 32]}
|
||||
v-model:value={name.value}
|
||||
placeholder="输入名字"
|
||||
/>
|
||||
```
|
||||
|
||||
需要多行编辑就加 `multiline`,这时输入框允许换行,高度由 `loc` 的第四项决定:
|
||||
|
||||
```tsx
|
||||
const note = ref('');
|
||||
|
||||
<Input
|
||||
loc={[40, 104, 320, 80]}
|
||||
v-model:value={note.value}
|
||||
multiline
|
||||
placeholder="多行备注"
|
||||
/>;
|
||||
```
|
||||
|
||||
常用参数都在 `loc` 与外观上:`loc` 给位置和大小,宽度决定输入区宽度;`placeholder` 是空内容时的提示;`border` 是边框颜色,默认 `'#ddd'`;`borderWidth` 是边框宽度,默认 `1`;`circle` 是边框圆角,写法与 `g-rectr` 一致,例如 `[4]`;`pad` 是文字与边框之间的内边距,默认 `4`。
|
||||
|
||||
`value` 就是 `v-model:value` 绑定的那个值。想知道每次输入的内容加 `onInput`,想只在确认时取值加 `onChange`,两者都收到当前字符串。
|
||||
|
||||
全部参数:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------- | ---------------------------------------- | ------------ |
|
||||
| `loc` | 位置与大小,宽度决定输入区宽度 | 必填 |
|
||||
| `value` | 输入内容,配合 `v-model:value` 双向绑定 | `''` |
|
||||
| `placeholder` | 空内容时的提示文字 | 无 |
|
||||
| `multiline` | 多行输入,高度由 `loc` 的第四项决定 | `false` |
|
||||
| `border` | 边框颜色 | `'#ddd'` |
|
||||
| `borderWidth` | 边框宽度 | `1` |
|
||||
| `circle` | 边框圆角,写法同 `g-rectr` | 无 |
|
||||
| `pad` | 文字与边框之间的内边距 | `4` |
|
||||
| `font` | 输入文字的字体,排版参数同 `TextContent` | 默认字体 |
|
||||
| `fillStyle` | 文字颜色 | 白色 |
|
||||
| `onInput` | 每次输入都触发,收到当前字符串 | 无 |
|
||||
| `onChange` | 确认输入时触发,收到当前字符串 | 无 |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="inputLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
单行占位、填入内容与多行输入三种状态。
|
||||
|
||||
## Icons
|
||||
|
||||
要显示现成的图标,直接导入图标组件,按名字用,不用自己画。
|
||||
|
||||
每个图标只接受 `loc`:前两项是位置,后两项是宽高。
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ----- | ---------------- | ------------ |
|
||||
| `loc` | 图标的位置与大小 | 必填 |
|
||||
|
||||
```tsx
|
||||
import { PlayIcon, PauseIcon, RollbackIcon } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<PlayIcon loc={[40, 40, 32, 32]} />
|
||||
<PauseIcon loc={[88, 40, 32, 32]} />
|
||||
<RollbackIcon loc={[136, 40, 32, 32]} />
|
||||
</container>;
|
||||
```
|
||||
|
||||
内置图标共 17 个,都从 `@user/client-base` 导入:
|
||||
|
||||
`RollbackIcon`、`RetweetIcon`、`ViewMapIcon`、`DanmakuIcon`、`ReplayIcon`、
|
||||
`NumpadIcon`、`PlayIcon`、`PauseIcon`、`DoubleArrow`、`StepForward`、
|
||||
`SoundVolume`、`Fullscreen`、`ExitFullscreen`、`ArrowLeftTailless`、
|
||||
`ArrowRightTailless`、`ArrowUpTailless`、`ArrowDownTailless`。
|
||||
|
||||
图标内部的线条样式不在组件参数里展开,需要改的时候按 API 列表里的参数查找。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="iconsLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
九个图标按 `loc` 排在网格里,名字写在图标下方。
|
||||
|
||||
## Arrow
|
||||
|
||||
要画一条带箭头的线,用 `Arrow`。
|
||||
|
||||
`arrow` 依次是起点 `x1`、`y1` 和终点 `x2`、`y2`;不用写 `loc`,位置由两端决定。
|
||||
|
||||
```tsx
|
||||
import { Arrow } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<Arrow arrow={[40, 40, 400, 120]} />;
|
||||
```
|
||||
|
||||
箭头头部想大一点,改 `head`,默认 `8`:
|
||||
|
||||
```tsx
|
||||
<Arrow arrow={[40, 40, 400, 120]} head={18} />
|
||||
```
|
||||
|
||||
想改线条和箭头的颜色,加 `color`:
|
||||
|
||||
```tsx
|
||||
<Arrow arrow={[40, 40, 400, 120]} head={18} color="#f2b84b" />
|
||||
```
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------- | ----------------------------------------- | ------------ |
|
||||
| `arrow` | 起点与终点,依次是 `x1`、`y1`、`x2`、`y2` | 必填 |
|
||||
| `head` | 箭头头部的大小 | `8` |
|
||||
| `color` | 线条与箭头的颜色 | 描边默认色 |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="arrowLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
三条箭头分别把 `head` 改成 `8`、`18`、`30`,颜色也各不相同。
|
||||
|
||||
## Selection
|
||||
|
||||
要画一个选中框,用 `Selection`。
|
||||
|
||||
`Selection` 只负责画框,不处理点击;点击和选中状态放在外层容器上自己维护。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Selection } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const selected = ref(0);
|
||||
|
||||
// 组件内容
|
||||
<container loc={[40, 40, 220, 32]} onClick={() => (selected.value = 1)}>
|
||||
<Selection loc={[0, 0, 220, 32]} color="#2f6fed" border="#7aa2ff" />
|
||||
<text loc={[12, 8]} text="被选中的项" fillStyle="#ffffff" />
|
||||
</container>;
|
||||
```
|
||||
|
||||
`loc` 是框的位置与大小,通常和外层容器一样大;`color` 是框内填充色,`border` 是边框颜色。框会自己闪烁,想改闪烁的深浅用 `alphaRange`,先低后高,默认 `[0.25, 0.55]`。
|
||||
|
||||
```tsx
|
||||
<Selection
|
||||
loc={[0, 0, 220, 32]}
|
||||
color="#2f6fed"
|
||||
border="#7aa2ff"
|
||||
alphaRange={[0.4, 0.8]}
|
||||
/>
|
||||
```
|
||||
|
||||
需要现成的选中素材时,改用 `winskin`,不再写颜色。
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------ | ---------------------------- | -------------- |
|
||||
| `loc` | 框的位置与大小 | 必填 |
|
||||
| `color` | 框内填充色 | 无 |
|
||||
| `border` | 边框颜色 | 无 |
|
||||
| `winskin` | 换成现成的选中素材 | 无 |
|
||||
| `alphaRange` | 闪烁的不透明度范围,先低后高 | `[0.25, 0.55]` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="selectionLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
两组 `color` 与 `border` 画出的选中框,第二组用 `alphaRange` 调大了闪烁深浅,最后一行没有选中框。
|
||||
|
||||
## Progress
|
||||
|
||||
要显示进度,用 `Progress`。
|
||||
|
||||
`loc` 前两项是位置,第三项是进度条长度;`progress` 是完成比例,`0` 是空、`1` 是满。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Progress } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const progress = ref(0.6);
|
||||
|
||||
// 组件内容
|
||||
<Progress loc={[40, 40, 300, 10]} progress={progress.value} />;
|
||||
```
|
||||
|
||||
默认已完成部分是绿色、未完成部分是灰色;想换颜色,用 `success` 给已完成部分、`background` 给未完成部分:
|
||||
|
||||
```tsx
|
||||
<Progress
|
||||
loc={[40, 40, 300, 10]}
|
||||
progress={progress.value}
|
||||
success="#7ee787"
|
||||
background="#26364d"
|
||||
/>
|
||||
```
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------ | ---------------------------- | ------------ |
|
||||
| `loc` | 进度条的位置与宽度 | 必填 |
|
||||
| `progress` | 完成比例,`0` 是空,`1` 是满 | 必填 |
|
||||
| `success` | 已完成部分的颜色 | `green` |
|
||||
| `background` | 未完成部分的颜色 | `gray` |
|
||||
| `lineWidth` | 线条宽度 | `2` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="progressLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
`progress` 分别取 `0.3`、`0.6` 与 `1`。
|
||||
|
||||
## Background
|
||||
|
||||
要画一块背景框,用 `Background`。
|
||||
|
||||
`loc` 给位置与大小,`color` 是填充色,`border` 是边框颜色。
|
||||
|
||||
```tsx
|
||||
import { Background } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<Background loc={[24, 24, 432, 272]} color="#1d2b45" border="#3a5a8c" />;
|
||||
```
|
||||
|
||||
想用现成的背景素材,就只写 `winskin`,不再写 `color` / `border`:给了 `winskin` 就画素材,否则按颜色画圆角矩形。
|
||||
|
||||
```tsx
|
||||
<Background loc={[24, 24, 432, 272]} winskin="winskin.png" />
|
||||
```
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| --------- | ------------------ | ------------ |
|
||||
| `loc` | 背景的位置与大小 | 必填 |
|
||||
| `color` | 填充色 | 无 |
|
||||
| `border` | 边框颜色 | 无 |
|
||||
| `winskin` | 换成现成的背景素材 | 无 |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="backgroundLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一块背景换两组 `color` 与 `border`。
|
||||
|
||||
## Slider
|
||||
|
||||
要让用户拖拽调数值,用 `Slider`。
|
||||
|
||||
`loc` 给位置与大小,`value` 是当前值;拖动时用 `v-model:value` 双向绑定。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Slider } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const volume = ref(40);
|
||||
|
||||
// 组件内容
|
||||
<Slider loc={[40, 80, 240, 24]} v-model:value={volume.value} />;
|
||||
```
|
||||
|
||||
`min` / `max` 给范围,`step` 给每次变化的最小差值:
|
||||
|
||||
```tsx
|
||||
<Slider
|
||||
loc={[40, 80, 240, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
/>
|
||||
```
|
||||
|
||||
右侧默认显示当前值;不想显示就写 `showValue={false}`:
|
||||
|
||||
```tsx
|
||||
<Slider
|
||||
loc={[40, 80, 240, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
showValue={false}
|
||||
/>
|
||||
```
|
||||
|
||||
移动端拖动滑动条不方便,建议在它旁边再放两个按钮,分别增减数值:
|
||||
|
||||
```tsx
|
||||
const decrease = () => (volume.value = Math.max(0, volume.value - 5));
|
||||
const increase = () => (volume.value = Math.min(100, volume.value + 5));
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<Slider
|
||||
loc={[40, 80, 240, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
/>
|
||||
<container loc={[40, 120, 64, 28]} onClick={decrease}>
|
||||
<g-rectr loc={[0, 0, 64, 28]} circle={[4]} fillStyle="#2f6fed" />
|
||||
<text loc={[32, 14]} anc={[0.5, 0.5]} text="-" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[116, 120, 64, 28]} onClick={increase}>
|
||||
<g-rectr loc={[0, 0, 64, 28]} circle={[4]} fillStyle="#3a2f5f" />
|
||||
<text loc={[32, 14]} anc={[0.5, 0.5]} text="+" fillStyle="#ffffff" />
|
||||
</container>
|
||||
</container>;
|
||||
```
|
||||
|
||||
全部参数:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------- | ------------------------------------- | --------------- |
|
||||
| `loc` | 位置与大小 | 必填 |
|
||||
| `value` | 当前值,配合 `v-model:value` 双向绑定 | `min` |
|
||||
| `min` | 最小值 | `0` |
|
||||
| `max` | 最大值 | `0` |
|
||||
| `step` | 每次变化的最小差值 | `1` |
|
||||
| `showValue` | 右侧是否显示当前值 | `true` |
|
||||
| `valueWidth` | 右侧数值区域的宽度 | `40` |
|
||||
| `font` | 右侧数值的字体 | `12` 号默认字体 |
|
||||
| `lineWidth` | 滑动条的线宽 | `2` |
|
||||
| `padding` | 线两端距容器边缘的距离 | `4` |
|
||||
| `filledStyle` | 控制点左侧(已选部分)的颜色 | `'#0ff'` |
|
||||
| `emptyStyle` | 控制点右侧(未选部分)与描边的颜色 | `'#888'` |
|
||||
| `radius` | 控制点的半径 | `4` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="sliderLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
拖动滑动条或点两侧按钮,右侧数值会跟着变。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const inputLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-input-demo.tsx');
|
||||
const iconsLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-icons-demo.tsx');
|
||||
const arrowLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-arrow-demo.tsx');
|
||||
const selectionLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-selection-demo.tsx');
|
||||
const progressLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-progress-demo.tsx');
|
||||
const backgroundLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-background-demo.tsx');
|
||||
const sliderLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-slider-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,300 @@
|
||||
# 内置组件:布局
|
||||
|
||||
这一篇讲四个负责区域与列表的组件:`Scroll`、`Page`、`List`、`ListPage`。它们都先说要解决什么,再给最小写法,常用参数跟着讲,最后接一个 live。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [什么是组件](./what-is-component.md)
|
||||
- [内置组件:基础](./builtin-basic.md)
|
||||
|
||||
## Scroll
|
||||
|
||||
内容超过视口时,用 `Scroll` 给一块区域加滚动。
|
||||
|
||||
`loc` 是视口的位置与大小。总长度按**直接子元素**的包围盒计算,所以每一行都要直接挂在 `Scroll` 下面,不要先用一个大容器把所有内容包起来。
|
||||
|
||||
```tsx
|
||||
import { Scroll } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const rows = Array.from({ length: 12 }, (_, index) => `第 ${index + 1} 行`);
|
||||
|
||||
// 组件内容
|
||||
<Scroll loc={[40, 40, 300, 220]}>
|
||||
{rows.map((row, index) => (
|
||||
<container key={row} loc={[0, index * 32, 280, 32]}>
|
||||
<text loc={[8, 8]} text={row} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
))}
|
||||
</Scroll>;
|
||||
```
|
||||
|
||||
每一行的高度与顺序由子元素自己的 `loc` 决定。
|
||||
|
||||
想横向滚动,加 `hor`,子元素改为从左往右排:
|
||||
|
||||
```tsx
|
||||
<Scroll loc={[40, 40, 300, 120]} hor>
|
||||
{rows.map((row, index) => (
|
||||
<container key={row} loc={[index * 120, 0, 120, 100]}>
|
||||
<text loc={[8, 8]} text={row} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
))}
|
||||
</Scroll>
|
||||
```
|
||||
|
||||
滚动条默认可以手动滚;不想显示滚动条时,加 `noscroll`,滚轮与拖拽滚动仍然可用。
|
||||
|
||||
滚到末尾想多留一点空白,用 `padEnd` 给额外长度,默认 `0`。
|
||||
|
||||
参数汇总:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ---------- | ------------------------ | ------------ |
|
||||
| `loc` | 视口的位置与大小 | 必填 |
|
||||
| `hor` | 改为横向滚动 | `false` |
|
||||
| `noscroll` | 隐藏滚动条 | `false` |
|
||||
| `padEnd` | 滚到末尾时额外填充的长度 | `0` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="scrollLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
直接子元素从上往下排,右侧是滚动条。
|
||||
|
||||
## Page
|
||||
|
||||
内容分页用 `Page`。
|
||||
|
||||
`pages` 是总页数,`loc` 决定内容与页码条的位置和大小;当前页用 `v-model:page` 绑定。默认 slot 收到当前页索引,从 `0` 开始,按索引渲染对应内容。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Page } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const page = ref(0);
|
||||
const pages = ['第一页内容', '第二页内容', '第三页内容'];
|
||||
|
||||
// 组件内容
|
||||
<Page pages={3} v-model:page={page.value} loc={[40, 40, 300, 200]}>
|
||||
{(index: number) => (
|
||||
<text loc={[8, 8]} text={pages[index] ?? ''} fillStyle="#e8f0ff" />
|
||||
)}
|
||||
</Page>;
|
||||
```
|
||||
|
||||
页码条占 `loc` 的底部,内容只能放在剩下的高度里。
|
||||
|
||||
只有一页时页码条没有意义,加 `hideIfSingle` 隐藏它:
|
||||
|
||||
```tsx
|
||||
<Page pages={1} hideIfSingle loc={[40, 40, 300, 200]}>
|
||||
{() => <text loc={[8, 8]} text="只有一页" fillStyle="#e8f0ff" />}
|
||||
</Page>
|
||||
```
|
||||
|
||||
参数汇总:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| -------------- | ------------------------ | ------------ |
|
||||
| `pages` | 总页数 | 必填 |
|
||||
| `loc` | 内容与页码条的位置和大小 | 必填 |
|
||||
| `page` | 当前页索引,从 `0` 开始 | `0` |
|
||||
| `font` | 页码字体 | 默认字体 |
|
||||
| `hideIfSingle` | 只有一页时隐藏页码条 | `false` |
|
||||
|
||||
页码变化时触发 `pageChange`,同时用 `update:page` 同步 `v-model:page`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="pageLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
点底部的页码或两侧箭头切换三页内容。
|
||||
|
||||
## List
|
||||
|
||||
要显示一列可选择项,用 `List`。
|
||||
|
||||
`list` 是 `[id, 文本]` 数组,每项第一项是 id、第二项是列表里显示的文字。`loc` 是列表视口的位置与大小,内容超出时由内部的 `Scroll` 滚动。`selected` / `v-model:selected` 是当前选中项的 id,初值取列表第一项。`List` 自身没有默认 slot,行文字完全来自 `list`。
|
||||
|
||||
`lineHeight` 是每行的固定高度,默认 `24`,**不会随字体自动调整**;改了 `font` 的字号后必须同时设置合适的 `lineHeight`,否则行与文字可能重叠。
|
||||
|
||||
`font` 控制行文字;`winskin`、`color`、`border`、`alphaRange` 控制选中光标,分别指定光标图片、填充色、边框色与闪烁的不透明度范围。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { List } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const items: [string, string][] = [
|
||||
['basic', '基础设置'],
|
||||
['sound', '声音'],
|
||||
['key', '按键']
|
||||
];
|
||||
const selected = ref(items[0][0]);
|
||||
|
||||
// 组件内容
|
||||
<List
|
||||
loc={[40, 40, 300, 160]}
|
||||
list={items}
|
||||
lineHeight={32}
|
||||
v-model:selected={selected.value}
|
||||
/>;
|
||||
```
|
||||
|
||||
选中某一行时触发 `update` 与 `update:selected`,参数都是该行的 id。
|
||||
|
||||
参数汇总:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------ | ----------------------------------------- | -------------- |
|
||||
| `list` | `[id, 文本][]`,id 用于选中,文本用于显示 | 必填 |
|
||||
| `loc` | 列表视口的位置与大小 | 必填 |
|
||||
| `selected` | 当前选中项的 id,支持 `v-model:selected` | 第一项 id |
|
||||
| `lineHeight` | 每行固定高度,不随字号自动调整 | `24` |
|
||||
| `font` | 行文字字体 | 默认字体 |
|
||||
| `winskin` | 用作选中光标的图片 | 无 |
|
||||
| `color` | 选中光标的填充色 | 默认填充 |
|
||||
| `border` | 选中光标的边框色 | 默认描边 |
|
||||
| `alphaRange` | 选中光标闪烁的不透明度范围 | `[0.25, 0.55]` |
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="listLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
四项列表,选中项高亮,点击任意一行切换。
|
||||
|
||||
## ListPage
|
||||
|
||||
左边列表、右边详情,用 `ListPage`。
|
||||
|
||||
`list` 是 `[id, 文本]` 数组,每项第一项是 id、第二项是列表里显示的文字;`loc` 是整个组件的位置与大小。当前选中项用 `v-model:selected` 绑定,默认 slot 收到选中的 id,按 id 渲染右侧内容。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { ListPage } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const items: [string, string][] = [
|
||||
['basic', '基础设置'],
|
||||
['sound', '声音'],
|
||||
['key', '按键']
|
||||
];
|
||||
const detail: Record<string, string> = {
|
||||
basic: '这里放基础设置的说明。',
|
||||
sound: '这里放音量与音效的说明。',
|
||||
key: '这里放按键改绑的说明。'
|
||||
};
|
||||
const selected = ref(items[0][0]);
|
||||
|
||||
// 组件内容
|
||||
<ListPage
|
||||
loc={[40, 40, 400, 240]}
|
||||
list={items}
|
||||
v-model:selected={selected.value}
|
||||
>
|
||||
{(key: string) => (
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text={detail[key] ?? '没有内容'}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
)}
|
||||
</ListPage>;
|
||||
```
|
||||
|
||||
`selected` 的初值取列表第一项的 id,左侧高亮和右侧内容才会从同一项开始。
|
||||
|
||||
左侧列表默认占整宽的 `0.3`;想改比例用 `basis`:
|
||||
|
||||
```tsx
|
||||
<ListPage
|
||||
loc={[40, 40, 400, 240]}
|
||||
list={items}
|
||||
basis={0.4}
|
||||
v-model:selected={selected.value}
|
||||
>
|
||||
{(key: string) => (
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text={detail[key] ?? '没有内容'}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
)}
|
||||
</ListPage>
|
||||
```
|
||||
|
||||
想把列表放到右侧,加 `right`。需要关闭按钮时加 `close`,按钮位置用 `closeLoc` 给,相对于 `loc`:
|
||||
|
||||
```tsx
|
||||
<ListPage
|
||||
loc={[40, 40, 400, 240]}
|
||||
list={items}
|
||||
right
|
||||
close
|
||||
closeLoc={[360, 8]}
|
||||
v-model:selected={selected.value}
|
||||
>
|
||||
{(key: string) => (
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text={detail[key] ?? '没有内容'}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
)}
|
||||
</ListPage>
|
||||
```
|
||||
|
||||
`ListPage` 复用 `List` 的全部参数,并额外提供列表比例、排列方向与关闭按钮:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| ------------ | --------------------------------------------- | -------------- |
|
||||
| `list` | `[id, 文本][]`,id 用于选中,文本用于列表显示 | 必填 |
|
||||
| `loc` | 整个组件的位置与大小 | 必填 |
|
||||
| `selected` | 当前选中项的 id,支持 `v-model:selected` | 第一项 id |
|
||||
| `lineHeight` | 每行固定高度,不随字号自动调整 | `24` |
|
||||
| `font` | 列表与关闭按钮的字体 | 默认字体 |
|
||||
| `winskin` | 用作选中光标的图片 | 无 |
|
||||
| `color` | 选中光标的填充色 | 默认填充 |
|
||||
| `border` | 选中光标的边框色 | 默认描边 |
|
||||
| `alphaRange` | 选中光标闪烁的不透明度范围 | `[0.25, 0.55]` |
|
||||
| `basis` | 列表占整宽的比例 | `0.3` |
|
||||
| `right` | 列表排在右侧 | `false` |
|
||||
| `close` | 显示关闭按钮 | `false` |
|
||||
| `closeLoc` | 关闭按钮位置,相对于 `loc` | 无 |
|
||||
|
||||
列表项点击同样触发 `update` 与 `update:selected`;点关闭按钮触发 `close`。默认 slot 收到选中项 id,也可以按 id 写具名 slot,选中哪项就优先用哪项的 slot。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="listPageLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
左侧是三项列表,选中项高亮,右侧显示对应说明。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const scrollLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-scroll-demo.tsx');
|
||||
const pageLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-page-demo.tsx');
|
||||
const listLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-list-demo.tsx');
|
||||
const listPageLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-listpage-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,223 @@
|
||||
# 内置组件:文本
|
||||
|
||||
文字元素只画一行。要让长文字按宽度折行、逐字显示或自动向上滚动时,用内置的文本组件。这一篇讲 `TextContent` 和 `ScrollText`,每个都先说它解决什么问题,再给最小写法,最后接一个 live。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [什么是组件](./what-is-component.md)
|
||||
- [内置组件:基础](./builtin-basic.md)
|
||||
|
||||
## TextContent
|
||||
|
||||
要让长文字按宽度自动折行,用 `TextContent`。
|
||||
|
||||
第一步:必须给 `width`,排版只按这个宽度折行;`text` 放内容,`loc` 前两项决定位置。
|
||||
|
||||
```tsx
|
||||
import { TextContent } from '@user/client-base';
|
||||
|
||||
// 组件内容
|
||||
<TextContent
|
||||
loc={[40, 40]}
|
||||
width={360}
|
||||
text="这段文字会按 width 折行,超出的部分换到下一行。"
|
||||
/>;
|
||||
```
|
||||
|
||||
高度默认由 `loc` 的第四项决定;不想自己算高度时加 `autoHeight`,组件按内容算高度。
|
||||
|
||||
想让文字逐字显示,加 `interval`,单位是毫秒,`0` 表示一次显示完:
|
||||
|
||||
```tsx
|
||||
<TextContent
|
||||
loc={[40, 40]}
|
||||
width={360}
|
||||
autoHeight
|
||||
interval={30}
|
||||
text="这段文字会按 width 折行,并逐字显示。"
|
||||
/>
|
||||
```
|
||||
|
||||
打字结束时要做点什么,用 `onTypeEnd`。
|
||||
|
||||
```tsx
|
||||
<TextContent
|
||||
loc={[40, 40]}
|
||||
width={360}
|
||||
autoHeight
|
||||
interval={30}
|
||||
text="打完这段文字后会触发回调。"
|
||||
onTypeEnd={() => {
|
||||
// 打字结束时执行
|
||||
}}
|
||||
/>
|
||||
```
|
||||
|
||||
全部参数:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| --------------------------- | ------------------------------------------- | ------------------- |
|
||||
| `text` | 显示的文字 | `''` |
|
||||
| `width` | 折行宽度 | 必填 |
|
||||
| `loc` | 位置与高度 | `[]`(即 `[0, 0]`) |
|
||||
| `autoHeight` | 按内容计算高度 | `false` |
|
||||
| `interval` | 逐字间隔,单位毫秒 | `0` |
|
||||
| `font` | 文字字体 | `new Font()` |
|
||||
| `lineHeight` | 行与行之间的额外间距 | `0` |
|
||||
| `fill` / `stroke` | 填充 / 描边文字 | `true` / `false` |
|
||||
| `fillStyle` / `strokeStyle` | 填充 / 描边颜色 | `#fff` / `#000` |
|
||||
| `strokeWidth` | 描边线宽 | `2` |
|
||||
| `textAlign` | 多行文字左对齐 / 居中 / 右对齐 | `TextAlign.Left` |
|
||||
| `wordBreak` | 断词规则:不换行 / 空格与 CJK 处 / 任意字符 | `WordBreak.Space` |
|
||||
| `breakChars` | 额外参与分词的字符 | `''` |
|
||||
| `ignoreLineStart` | 不放在行首的字符 | `''` |
|
||||
| `ignoreLineEnd` | 不放在行尾的字符 | `''` |
|
||||
| `onTypeStart` / `onTypeEnd` | 开始 / 结束打字时触发 | 无 |
|
||||
| `onUpdateHeight` | 高度重算后触发,参数为新高度 | 无 |
|
||||
|
||||
多行文字时,`lineHeight` 默认为 `0`,行与行会贴得比较紧;通常设成 `8` 左右阅读起来更舒展。
|
||||
|
||||
需要重播或立刻显示全文时,组件实例还暴露 `retype()`、`showAll()` 和 `getHeight()`。
|
||||
|
||||
### 文本标记
|
||||
|
||||
要在文本里改颜色,写 `[c=颜色]...[/c]`:
|
||||
|
||||
```tsx
|
||||
<TextContent loc={[40, 40]} width={360} text="[c=#f2b84b]这一段是黄色[/c]" />
|
||||
```
|
||||
|
||||
要改字号,写 `[s=字号]...[/s]`:
|
||||
|
||||
```tsx
|
||||
<TextContent loc={[40, 40]} width={360} text="[s=20]这一段字更大[/s]" />
|
||||
```
|
||||
|
||||
要换行,写 `\n`;在 TSX 里用模板字符串或字符串拼接:
|
||||
|
||||
```tsx
|
||||
<TextContent loc={[40, 40]} width={360} text={'第一行\n第二行'} />
|
||||
```
|
||||
|
||||
`[[` 输出一个普通的 `[`,`]]` 输出一个普通的 `]`。要显示 `[[` 和 `]]` 本身,源文本里写成 `[[[[` 和 `]]]]`:
|
||||
|
||||
```tsx
|
||||
<TextContent loc={[40, 40]} width={360} text="这里显示 [[[[方括号]]]] 本身" />
|
||||
```
|
||||
|
||||
`[c=...]` 与 `[s=...]` 要成对闭合,可以嵌套,例如 `[c=#f2b84b][s=20]标题[/s][/c]`。只写 `[c]` 没有颜色参数,不会按标记处理,会原样显示。
|
||||
|
||||
需要粗体、斜体、换字体、等待或图标时,再用这些标记:
|
||||
|
||||
| 标记 | 作用 |
|
||||
| ------------------- | ------------------ |
|
||||
| `[b]` | 切换粗体 |
|
||||
| `[i]` | 切换斜体 |
|
||||
| `[f=字体名]...[/f]` | 改字体族 |
|
||||
| `[w=字数]` | 等待若干个字的时间 |
|
||||
| `[icon=图标名]` | 插入图标 |
|
||||
|
||||
`[b]` 和 `[i]` 是切换,不是成对闭合:写一次切换一次。标记可以组合使用,也可以跨行书写。
|
||||
|
||||
把颜色、字号、换行与方括号放在一起:
|
||||
|
||||
```tsx
|
||||
<TextContent
|
||||
loc={[40, 40]}
|
||||
width={360}
|
||||
autoHeight
|
||||
lineHeight={8}
|
||||
text={
|
||||
'[c=#f2b84b][s=20]标题[/s][/c]\n' +
|
||||
'[c=#7ee787]正文里的 [[[[方括号]]]] 会原样显示[/c]\n' +
|
||||
'[c=#8aa0b8][s=13]小字注释[/s][/c]'
|
||||
}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="textContentLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一段文字里混用了颜色、字号、手动换行与方括号字面量,长句会按 `width` 折行。
|
||||
|
||||
## ScrollText
|
||||
|
||||
要让文字自动向上滚动,用 `ScrollText`。
|
||||
|
||||
基本写法里,`width` 是文字的最大宽度,`speed` 是每秒滚动的像素数,`text` 放内容,`loc` 是滚动区域的视口。
|
||||
|
||||
```tsx
|
||||
import { ScrollText } from '@user/client-base';
|
||||
|
||||
// setup
|
||||
const notice = '这是一条会自己向上滚动的公告。'.repeat(8);
|
||||
|
||||
// 组件内容
|
||||
<ScrollText
|
||||
loc={[40, 40, 400, 160]}
|
||||
width={400}
|
||||
speed={50}
|
||||
text={notice}
|
||||
fillStyle="#e8f0ff"
|
||||
/>;
|
||||
```
|
||||
|
||||
文字从下往上滚过视口,超出视口的部分不显示。
|
||||
|
||||
开始滚动前想先留一点空白,用 `pad` 给预留的像素数,默认 `16`:
|
||||
|
||||
```tsx
|
||||
<ScrollText
|
||||
loc={[40, 40, 400, 160]}
|
||||
width={400}
|
||||
speed={50}
|
||||
pad={32}
|
||||
text={notice}
|
||||
/>
|
||||
```
|
||||
|
||||
排版参数与 `TextContent` 相同,`fillStyle`、`font`、`lineHeight` 照常写。`width` 是滚动区宽度,文字实际按 `width - 16` 折行;`loc` 的第四项是视口高度,省略时取 `width`。
|
||||
|
||||
全部参数:
|
||||
|
||||
| 属性 | 作用 | 默认或常用值 |
|
||||
| --------------------------- | ------------------------------------------- | ----------------- |
|
||||
| `loc` | 滚动视口的位置与大小 | 必填 |
|
||||
| `width` | 滚动区宽度 | 必填 |
|
||||
| `speed` | 每秒滚动像素数 | 必填 |
|
||||
| `pad` | 开始滚动前预留的像素 | `16` |
|
||||
| `text` | 滚动文字 | `''` |
|
||||
| `font` | 文字字体 | `new Font()` |
|
||||
| `fillStyle` / `strokeStyle` | 填充 / 描边颜色 | `#fff` / `#000` |
|
||||
| `fill` / `stroke` | 填充 / 描边文字 | `true` / `false` |
|
||||
| `strokeWidth` | 描边线宽 | `2` |
|
||||
| `lineHeight` | 行与行之间的额外间距 | `0` |
|
||||
| `textAlign` | 多行文字左对齐 / 居中 / 右对齐 | `TextAlign.Left` |
|
||||
| `wordBreak` | 断词规则:不换行 / 空格与 CJK 处 / 任意字符 | `WordBreak.Space` |
|
||||
| `onScrollEnd` | 滚动到底时触发一次,随后停止 | 无 |
|
||||
|
||||
需要中途控制滚动时,组件实例还暴露 `pause()`、`resume()`、`setSpeed(speed)` 和 `rescroll()`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="scrollTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
公告在固定视口里持续向上滚动。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const textContentLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-textcontent-demo.tsx');
|
||||
const scrollTextLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/builtin-scrolltext-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,361 @@
|
||||
# 条件渲染与循环渲染
|
||||
|
||||
TSX 里没有模板指令。要不要显示一块内容、要不要重复一组元素,都是普通表达式:条件用 `hidden` 或三元,循环用 `.map()`。
|
||||
|
||||
绝大多数情况用 `hidden` 更划算:它只跳过绘制与命中,元素、状态和事件监听都还在。虽然会多占一点内存,但一般影响很小;TSX 也更平整,不需要为条件分支多套一层缩进。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [响应式](./reactivity.md)
|
||||
- [事件与交互](./events.md)
|
||||
|
||||
## 条件渲染与 hidden
|
||||
|
||||
大多数情况推荐 `hidden`,不推荐三元:它只多占一点内存,一般影响很小,TSX 也更平整。
|
||||
|
||||
`hidden` 不会把节点从树上拿走,只是不绘制、不参与命中。实例、内部状态、子元素和事件监听都保留,再次显示时直接接上。
|
||||
|
||||
坐标是相对父容器的绝对定位,不参与布局流。所以 `hidden` 不会让下面的兄弟元素上移,也不会留下一个「空格」。
|
||||
|
||||
```tsx
|
||||
// hidden 只切换显示与交互,面板状态不会被重置
|
||||
import { ref } from 'vue';
|
||||
|
||||
// setup
|
||||
const open = ref(true);
|
||||
|
||||
const togglePanel = () => {
|
||||
open.value = !open.value;
|
||||
};
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<container loc={[40, 32, 180, 36]} onClick={togglePanel}>
|
||||
<g-rect loc={[0, 0, 180, 36]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 10]} text="隐藏 / 显示面板" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
<container loc={[40, 100, 240, 160]} hidden={!open.value}>
|
||||
<g-rect loc={[0, 0, 240, 160]} fill fillStyle="#26364d" />
|
||||
<text loc={[16, 16]} text="面板内容" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>;
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="conditionalHiddenLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
面板隐藏 / 显示,面板内部的计数状态保留。
|
||||
|
||||
## 三元与节点卸载
|
||||
|
||||
三元不推荐作为默认方案。三元为假时返回 `null`,节点从树上移除:组件卸载,状态重置,下次显示时重新创建。只有元素必须真正不存在(不能留下占位或命中区域),或者每次打开都要从初始状态开始时,才用三元。
|
||||
|
||||
```tsx
|
||||
// 三元为 false 时面板被卸载,再显示时重新创建
|
||||
// setup
|
||||
const open = ref(true);
|
||||
|
||||
const togglePanel = () => {
|
||||
open.value = !open.value;
|
||||
};
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<container loc={[40, 32, 180, 36]} onClick={togglePanel}>
|
||||
<g-rect loc={[0, 0, 180, 36]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 10]} text="隐藏 / 显示面板" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
{open.value ? (
|
||||
<container loc={[40, 100, 240, 160]}>
|
||||
<g-rect loc={[0, 0, 240, 160]} fill fillStyle="#26364d" />
|
||||
<text loc={[16, 16]} text="面板内容" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
) : null}
|
||||
</container>;
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="conditionalTernaryLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
面板用三元切换,重新显示时内部计数从 0 开始。
|
||||
|
||||
## 循环与 map
|
||||
|
||||
TSX 里没有循环指令,直接把数组映射成元素数组:
|
||||
|
||||
```tsx
|
||||
// 固定顺序、无内部状态的列表不需要 key
|
||||
const labels = ['攻击', '防御', '生命'];
|
||||
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
{labels.map((label, index) => (
|
||||
<text loc={[40, 60 + index * 32]} text={label} fillStyle="#ffffff" />
|
||||
))}
|
||||
</container>;
|
||||
```
|
||||
|
||||
这个列表顺序固定、每一项都没有内部状态,所以不需要 `key`。加 `key` 反而多了一层身份管理,没有收益。`.map()` 必须放在渲染函数返回的元素树里,外层要有父容器;返回的数组会成为父容器的子元素列表。
|
||||
|
||||
如果列表项会增删、重排,或者列表项本身是有状态的组件,就需要 `key`。下一节说明原因。
|
||||
|
||||
## key 与元素身份
|
||||
|
||||
`key` 的作用是让 Vue 认出「这一项还是原来那一项」。列表 diff 时,Vue 按 `key` 匹配新旧节点:匹配上就复用,匹配不上就卸载旧的、挂载新的。
|
||||
|
||||
```tsx
|
||||
// 会增删或重排的列表用稳定 id 作为 key
|
||||
// 每一项都带 id,重排后 Vue 能认回原来那一项
|
||||
interface Row {
|
||||
id: number;
|
||||
label: string;
|
||||
}
|
||||
|
||||
// setup
|
||||
const rows = ref<Row[]>([
|
||||
{ id: 1, label: '第一项' },
|
||||
{ id: 2, label: '第二项' }
|
||||
]);
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
{rows.value.map((row, index) => (
|
||||
<text
|
||||
key={row.id}
|
||||
loc={[40, 40 + index * 28]}
|
||||
text={row.label}
|
||||
fillStyle="#7ee787"
|
||||
/>
|
||||
))}
|
||||
</container>;
|
||||
```
|
||||
|
||||
`key` 取稳定且唯一的值,通常来自数据自己的 id。不要用数组下标代替会变化的身份:在下标 0 处插入一项后,原来的第一项变成第二项,下标全变,Vue 会以为每一项都换了人,状态跟着错位。
|
||||
|
||||
实用规则:
|
||||
|
||||
- 会增删、重排的列表,用稳定的 `row.id` 作为 `key`。
|
||||
- 不要用会变化的数组下标当身份。
|
||||
- 静态固定列表可以不用 `key`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="conditionalKeyLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
左右两份列表轮流切换顺序:左边用 `key=id`,计数跟着项走;右边用 `key=index`,计数留在原位置。
|
||||
|
||||
## 列表数据的更新
|
||||
|
||||
列表用 `ref` 保存,渲染时读 `rows.value`。`push`、`splice`、改某一项的字段、整体替换 `rows.value`,都会自动更新画面。
|
||||
|
||||
```tsx
|
||||
// 列表放在 ref 里,渲染时读 rows.value
|
||||
interface Row {
|
||||
id: number;
|
||||
label: string;
|
||||
}
|
||||
|
||||
// setup
|
||||
const rows = ref<Row[]>([
|
||||
{ id: 1, label: '红药水' },
|
||||
{ id: 2, label: '蓝药水' }
|
||||
]);
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
{rows.value.map((row, index) => (
|
||||
<text
|
||||
key={row.id}
|
||||
loc={[40, 40 + index * 28]}
|
||||
text={row.label}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
))}
|
||||
</container>;
|
||||
```
|
||||
|
||||
`shallowRef` 只认整体替换 `rows.value = [...]`,`rows.value.push(...)` 不会触发更新;普通数组怎么改都不会触发;`reactive` 数组可以用 `push` / `splice`,但不要把变量整体替换成新数组。
|
||||
|
||||
过滤、排序这类派生列表用 `computed`,渲染时读 `computed.value`:
|
||||
|
||||
```tsx
|
||||
// setup:过滤后的列表用 computed 派生,依赖变化时自动重算
|
||||
import { computed, ref } from 'vue';
|
||||
|
||||
const keyword = ref('');
|
||||
const rows = ref<Row[]>([
|
||||
{ id: 1, label: '红药水' },
|
||||
{ id: 2, label: '蓝药水' }
|
||||
]);
|
||||
|
||||
const visibleRows = computed(() =>
|
||||
rows.value.filter(row => row.label.includes(keyword.value))
|
||||
);
|
||||
|
||||
// 组件内容:渲染时读 visibleRows.value
|
||||
{
|
||||
visibleRows.value.map((row, index) => (
|
||||
<text
|
||||
key={row.id}
|
||||
loc={[40, 40 + index * 28]}
|
||||
text={row.label}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
));
|
||||
}
|
||||
```
|
||||
|
||||
改了数据但画面没动,先确认渲染函数里读的是响应式变量本身(或它的 `.value`),不是普通数组或副本。
|
||||
|
||||
## 条件/列表的树形示意
|
||||
|
||||
把开关、列表和右侧详情放进同一棵树:面板用 `hidden` 控制显隐,列表用 `.map()` 生成,详情也用 `hidden` 控制。整段代码使用与模板页一致的标准 UI 模板。
|
||||
|
||||
```tsx
|
||||
// 面板开关只切换 hidden;列表颜色与右侧详情都由选中态派生
|
||||
import { computed, 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';
|
||||
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
interface Row {
|
||||
id: number;
|
||||
label: string;
|
||||
}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
const open = ref(true);
|
||||
const rows = ref<Row[]>([
|
||||
{ id: 1, label: '红药水' },
|
||||
{ id: 2, label: '蓝药水' }
|
||||
]);
|
||||
const selectedId = ref<number | null>(null);
|
||||
|
||||
// 选中项从列表里派生,右侧详情只读结果
|
||||
const selected = computed(
|
||||
() => rows.value.find(row => row.id === selectedId.value) ?? null
|
||||
);
|
||||
|
||||
// 每行颜色在 setup 里算好,属性里只读结果
|
||||
const fillById = computed(() => {
|
||||
const map = new Map<number, string>();
|
||||
for (const row of rows.value) {
|
||||
let color = '#26364d';
|
||||
if (row.id === selectedId.value) {
|
||||
color = '#2f6fed';
|
||||
}
|
||||
map.set(row.id, color);
|
||||
}
|
||||
return map;
|
||||
});
|
||||
|
||||
const togglePanel = () => {
|
||||
open.value = !open.value;
|
||||
};
|
||||
|
||||
// 事件交给命名函数,用 row.id 定位
|
||||
const selectRow = (id: number) => {
|
||||
selectedId.value = id;
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
<container loc={[40, 32, 160, 32]} onClick={togglePanel}>
|
||||
<g-rect loc={[0, 0, 160, 32]} fillStyle="#2f6fed" />
|
||||
<text loc={[12, 8]} text="隐藏 / 显示" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
{/* 开关只改 hidden,面板和里面的状态都留在树上 */}
|
||||
<container loc={[40, 88, 400, 160]} hidden={!open.value}>
|
||||
{rows.value.map((row, index) => (
|
||||
<container
|
||||
key={row.id}
|
||||
loc={[0, index * 36, 180, 32]}
|
||||
onClick={() => selectRow(row.id)}
|
||||
>
|
||||
<g-rect
|
||||
loc={[0, 0, 180, 32]}
|
||||
fillStyle={fillById.value.get(row.id) ?? '#26364d'}
|
||||
/>
|
||||
<text
|
||||
loc={[12, 8]}
|
||||
text={row.label}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
))}
|
||||
{/* 右侧详情也用 hidden 控制显隐,不需要三元 */}
|
||||
<container
|
||||
loc={[220, 0, 180, 120]}
|
||||
hidden={selected.value === null}
|
||||
>
|
||||
<g-rect loc={[0, 0, 180, 120]} fillStyle="#1c2633" />
|
||||
<text loc={[12, 12]} text="已选中" fillStyle="#8b98a8" />
|
||||
<text
|
||||
loc={[12, 44]}
|
||||
text={selected.value?.label ?? ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
这段树里:
|
||||
|
||||
- 开关按钮点击只改 `open`,`hidden={!open.value}` 只切换面板是否绘制,面板、列表项和详情都不卸载。
|
||||
- 点击列表项时,`selectRow(row.id)` 只改 `selectedId`;`fillById` 重新算出每行颜色,列表颜色跟着更新。
|
||||
- 右侧详情的显隐由 `hidden={selected.value === null}` 控制,选中项变化时只切显示,不会重建。
|
||||
- 整个过程没有三元分支,也没有因为显隐而卸载或重建任何节点。
|
||||
|
||||
## 三种写法的选择
|
||||
|
||||
| 需求 | 写法 | 结果 |
|
||||
| -------------------------- | --------------------- | ------------------------------------ |
|
||||
| 绝大多数情况,需要保留状态 | `hidden={!open}` | 推荐:不显示、不交互,元素与状态仍在 |
|
||||
| 必须不存在,或每次都要重置 | `open ? <A /> : null` | 不推荐作为默认:卸载与重建,状态重置 |
|
||||
| 固定顺序、无状态列表 | `.map()` | 每次渲染生成一组元素,不需要身份 |
|
||||
| 会增删、重排、带状态的列表 | `.map()` + `key` | 保留元素身份,状态跟着正确的项走 |
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const conditionalHiddenLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/conditional-hidden-demo.tsx');
|
||||
const conditionalTernaryLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/conditional-ternary-demo.tsx');
|
||||
const conditionalKeyLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/conditional-key-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `hidden` 的元素仍在树里,数量和层级照旧,也不影响兄弟元素的坐标。大量长期不用的重子树应该用三元释放。
|
||||
- 三元反复切换会反复重建,成本在组件初始化与状态重置,不在绘制本身。
|
||||
- `.map()` 返回的每一项都要有稳定结构。列表项是组件时,`key` 写在组件标签上。
|
||||
- `key` 只在同一父级的兄弟之间比较,不需要全局唯一;嵌套列表各用各的。
|
||||
- `ref` 数组的 `push` / `splice` / 整体替换都会触发;`shallowRef` 只认整体替换;普通数组不会触发。
|
||||
- 「改了数组但画面没动」先查数据是不是响应式、改的是不是副本,不要先怀疑渲染器。
|
||||
- `key` 不是性能开关,也不是修复重挂载问题的手段;它只表达「这是同一项」。
|
||||
@@ -0,0 +1,316 @@
|
||||
# 自定义组件
|
||||
|
||||
前面的页面已经能用容器、文字、图形与内置组件拼出整块 UI。当同一段 UI 要在多处出现时,把这块 UI 拆成一个自定义组件,声明一次,在各处调用。
|
||||
|
||||
这一篇只讲怎么用:怎么接收参数、怎么发事件、怎么留出内容位置,以及怎么把属性透传给内部元素。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [什么是组件](./what-is-component.md)
|
||||
- [内置组件:基础](./builtin-basic.md)
|
||||
|
||||
## props
|
||||
|
||||
组件的外部参数叫 props。父组件把值写在组件标签的属性上,子组件通过 `props.x` 读取。声明分三步:
|
||||
|
||||
1. 定义 Props 接口,普通组件继承 `DefaultProps`;
|
||||
2. 在 `SetupComponentOptions` 的 `props` 数组里列出用到的键;
|
||||
3. 用 `defineComponent<Props>(setup, options)` 声明组件。
|
||||
|
||||
```tsx
|
||||
import { computed, defineComponent } from 'vue';
|
||||
|
||||
// setup
|
||||
interface ItemCardProps extends DefaultProps {
|
||||
label: string;
|
||||
color?: string;
|
||||
}
|
||||
|
||||
const itemCardProps = {
|
||||
props: ['label', 'color']
|
||||
} satisfies SetupComponentOptions<ItemCardProps>;
|
||||
|
||||
const ItemCard = defineComponent<ItemCardProps>(props => {
|
||||
// 组件内容
|
||||
const color = computed(() => props.color ?? '#f2b84b');
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 220, 64]}>
|
||||
<g-rect loc={[0, 0, 220, 64]} fillStyle={color.value} />
|
||||
<text loc={[16, 22]} text={props.label} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
}, itemCardProps);
|
||||
```
|
||||
|
||||
父组件把值写在标签上;不传 `color` 时使用默认颜色:
|
||||
|
||||
```tsx
|
||||
<ItemCard label="卡片 A" color="#2f6fed" />
|
||||
```
|
||||
|
||||
## emits
|
||||
|
||||
props 负责把数据从父组件传下来,emits 负责把子组件里「发生了什么」报告上去。两者方向相反:父组件通过 props 给子组件输入,子组件通过 emits 通知父组件某个动作已经发生,例如点击、选中、内容变化。父组件收到事件后,用 `on事件名` 挂上处理函数。
|
||||
|
||||
事件需要先声明。做法和 props 一致:先定义 Emits 类型,再把事件名写进 `SetupComponentOptions` 的 `emits` 数组,最后让 `defineComponent` 的第二个泛型对应 Emits、第三个泛型对应事件名的联合类型。事件名既出现在类型里,也出现在 `emits` 数组里,两处保持一致。
|
||||
|
||||
子组件只通过 `emit` 发事件,不直接改父组件的数据。父组件自己的状态由父组件修改,子组件只负责把「用户点了哪张卡片」这类信息报告出去。
|
||||
|
||||
先声明类型与选项:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
interface ItemCardProps extends DefaultProps {
|
||||
label: string;
|
||||
}
|
||||
|
||||
type ItemCardEmits = {
|
||||
pick: (label: string) => void;
|
||||
};
|
||||
|
||||
const itemCardProps = {
|
||||
props: ['label'],
|
||||
emits: ['pick']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemCardProps,
|
||||
ItemCardEmits,
|
||||
keyof ItemCardEmits
|
||||
>;
|
||||
```
|
||||
|
||||
组件内部用 `emit('pick', ...)` 发出事件:
|
||||
|
||||
```tsx
|
||||
const ItemCard = defineComponent<
|
||||
ItemCardProps,
|
||||
ItemCardEmits,
|
||||
keyof ItemCardEmits
|
||||
>((props, { emit }) => {
|
||||
// 组件内容
|
||||
const handleClick = () => {
|
||||
emit('pick', props.label);
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 220, 64]} onClick={handleClick}>
|
||||
<g-rect loc={[0, 0, 220, 64]} fillStyle="#26364d" />
|
||||
<text loc={[16, 22]} text={props.label} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
}, itemCardProps);
|
||||
```
|
||||
|
||||
父组件在标签上写 `on事件名`,事件的参数会传进处理函数:
|
||||
|
||||
```tsx
|
||||
const handlePick = (label: string) => console.log(label);
|
||||
|
||||
<ItemCard label="卡片 A" onPick={handlePick} />;
|
||||
```
|
||||
|
||||
需要双向绑定时,把事件声明为 `update:prop`,子组件发出新值,父组件用 `v-model:prop` 绑定,读值与写回写在同一个绑定里。适合输入框、开关这类「父组件给值、子组件改值」的场景。
|
||||
|
||||
## slots
|
||||
|
||||
slot 是父组件向子组件内部「插入 UI」的出口。子组件决定插槽放在哪个位置,父组件决定往里面放什么内容。它传的是结构,不是数据:数据仍然走 props,slot 只负责把一段 UI 放进子组件预留的位置。
|
||||
|
||||
在 TSX 里,slot 是函数。子组件用 `slots.default?.()` 调用默认 slot,用 `slots.title?.(...)` 调用具名 slot;调用时传的参数会进入父组件的 slot 函数。父组件用标签内容传默认 slot,用对象传具名 slot。
|
||||
|
||||
`?.` 不能省略:父组件可能没有传这个 slot,未传时值是 `undefined`,先判断再调用才不会出错。具名 slot 使用对象写法时,默认 slot 也要写在对象里的 `default` 键上,不要同时在标签之间混写普通子元素,否则两处内容会冲突。
|
||||
|
||||
如果希望父组件传入的 slot 也有类型检查,可以用 `SlotsType` 声明 slot 的形状,并把它放在 `defineComponent` 的第四个泛型位置。不声明时 slot 是宽松类型,先跑通再补类型也可以。
|
||||
|
||||
子组件这一侧先声明参数与选项:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
interface PanelProps extends DefaultProps {
|
||||
width: number;
|
||||
height: number;
|
||||
}
|
||||
|
||||
const panelProps = {
|
||||
props: ['width', 'height']
|
||||
} satisfies SetupComponentOptions<PanelProps>;
|
||||
```
|
||||
|
||||
然后在组件里调用两种 slot:
|
||||
|
||||
```tsx
|
||||
const Panel = defineComponent<PanelProps>((props, { slots }) => {
|
||||
// 组件内容
|
||||
return () => (
|
||||
<container loc={[0, 0, props.width, props.height]}>
|
||||
<g-rect
|
||||
loc={[0, 0, props.width, props.height]}
|
||||
fillStyle="#26364d"
|
||||
/>
|
||||
{slots.title?.('背包')}
|
||||
{slots.default?.()}
|
||||
</container>
|
||||
);
|
||||
}, panelProps);
|
||||
```
|
||||
|
||||
### 默认 slot
|
||||
|
||||
默认 slot 的内容直接写在组件标签之间。父组件放什么,子组件就在 `slots.default?.()` 的位置显示什么:
|
||||
|
||||
```tsx
|
||||
<Panel width={240} height={160}>
|
||||
<text loc={[12, 48]} text="面板内容" fillStyle="#ffffff" />
|
||||
</Panel>
|
||||
```
|
||||
|
||||
### 具名 slot
|
||||
|
||||
具名 slot 用一个对象传入,键名就是 slot 名。父组件可以在对象里同时写 `title` 与 `default`;`title` 对应的函数会收到子组件调用 `slots.title?.('背包')` 时传入的参数:
|
||||
|
||||
```tsx
|
||||
<Panel width={240} height={160}>
|
||||
{{
|
||||
title: (title: string) => (
|
||||
<text loc={[12, 12]} text={title} fillStyle="#f2b84b" />
|
||||
),
|
||||
default: () => (
|
||||
<text loc={[12, 48]} text="面板内容" fillStyle="#ffffff" />
|
||||
)
|
||||
}}
|
||||
</Panel>
|
||||
```
|
||||
|
||||
只要用了具名 slot 的对象写法,默认 slot 也写进同一个对象;不要一部分用对象、一部分用标签之间的普通子元素。
|
||||
|
||||
## attrs
|
||||
|
||||
attrs 是父组件写在标签上、但子组件既没有声明为 props、也没有被 emits 消费的属性。它们没有被组件当成参数,适合用来把底层元素的属性原样透传下去,例如文字的颜色、位置或图片的填充方式。
|
||||
|
||||
默认情况下,未声明的属性会自动落到组件的根元素上。如果子组件的根元素不是最终要接收这些属性的元素,就在选项里写 `inheritAttrs: false`,让自动透传停止,再在内部指定的元素上手动展开 `{...attrs}`。
|
||||
|
||||
透传时属性名保持 camelCase,和平时写元素属性一致,例如 `fillStyle` 而不是 `fill-style`。
|
||||
|
||||
下面把 `text` 与 `fillStyle` 透传给内部的 `text`:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
interface FieldProps extends DefaultProps {}
|
||||
|
||||
const fieldProps = {
|
||||
props: [],
|
||||
inheritAttrs: false
|
||||
} satisfies SetupComponentOptions<FieldProps>;
|
||||
|
||||
const Field = defineComponent<FieldProps>((_props, { attrs }) => {
|
||||
// 组件内容
|
||||
return () => <text {...attrs} />;
|
||||
}, fieldProps);
|
||||
```
|
||||
|
||||
父组件直接写内部元素要用的属性:
|
||||
|
||||
```tsx
|
||||
<Field loc={[40, 120]} text="属性透传" fillStyle="#7ee787" />
|
||||
```
|
||||
|
||||
`Field` 没有声明 `loc`、`text`、`fillStyle`,它们全部进入 `attrs`,再被展开到内部的 `text` 上。不要同时保留自动透传又手动展开:要么让默认行为把属性落到根元素,要么写 `inheritAttrs: false` 后自己决定落点。
|
||||
|
||||
## 组件的调用
|
||||
|
||||
下面的模板把「自定义组件 + props + 事件 + 默认 slot」放进一个标准 UI。`ItemCard` 负责卡片本身,内容由调用方的默认 slot 填入;`MyPanel` 用 `ref` 保存选中项,再把 `active` 与 `onPick` 传给卡片。最后用 `new GameUI` 注册成 UI 入口。
|
||||
|
||||
```tsx
|
||||
import { computed, 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';
|
||||
|
||||
// 自定义组件:显示一张可选的卡片,底部内容由默认 slot 决定
|
||||
interface ItemCardProps extends DefaultProps {
|
||||
label: string;
|
||||
active?: boolean;
|
||||
}
|
||||
|
||||
type ItemCardEmits = {
|
||||
pick: (label: string) => void;
|
||||
};
|
||||
|
||||
const itemCardProps = {
|
||||
props: ['label', 'active'],
|
||||
emits: ['pick']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemCardProps,
|
||||
ItemCardEmits,
|
||||
keyof ItemCardEmits
|
||||
>;
|
||||
|
||||
const ItemCard = defineComponent<
|
||||
ItemCardProps,
|
||||
ItemCardEmits,
|
||||
keyof ItemCardEmits
|
||||
>((props, { emit, slots }) => {
|
||||
const fill = computed(() => (props.active ? '#2f6fed' : '#26364d'));
|
||||
const handleClick = () => {
|
||||
emit('pick', props.label);
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 200, 96]} onClick={handleClick}>
|
||||
<g-rect loc={[0, 0, 200, 96]} fillStyle={fill.value} />
|
||||
<text loc={[12, 12]} text={props.label} fillStyle="#ffffff" />
|
||||
{slots.default?.()}
|
||||
</container>
|
||||
);
|
||||
}, itemCardProps);
|
||||
|
||||
// UI 组件:把卡片放进整屏容器,并管理选中项
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
const selected = ref('甲');
|
||||
const handlePick = (label: string) => {
|
||||
selected.value = label;
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
<ItemCard
|
||||
label="甲"
|
||||
active={selected.value === '甲'}
|
||||
onPick={handlePick}
|
||||
>
|
||||
<text loc={[12, 60]} text="点我选择" fillStyle="#cfe0ff" />
|
||||
</ItemCard>
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
把这个文件放到 `src/client/ui/` 下,在 `src/client/ui/index.ts` 导出 `MyPanelUI`,就可以用 `props.controller.open(MyPanelUI, {})` 打开。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面用两个 `ItemCard` 演示 props、事件与默认 slot:点击卡片会切换选中态,卡片底部的内容由默认 slot 传入。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="customComponentsLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const customComponentsLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/custom-components-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,400 @@
|
||||
# 事件与交互
|
||||
|
||||
元素画出来之后,下一步是接住用户的操作:点击、按下、抬起、移动、悬停、滚轮。事件在容器与子元素之间有两个传递方向:**冒泡**是里面先生效,**捕获**是外面先生效。
|
||||
|
||||
一般更符合直觉的是冒泡。点一个按钮,应该先轮到按钮自己处理,而不是父容器先把事件接住;所以 `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`。
|
||||
@@ -0,0 +1,255 @@
|
||||
# 按键与快捷键
|
||||
|
||||
UI 里经常需要「按 Esc 关闭」「按 Enter 确认」「按方向键切换选中项」。不需要自己监听键盘:按键系统负责按键匹配、作用域与优先级,也负责让玩家在设置界面里改键。
|
||||
|
||||
下面按「在哪里写」「组件里怎么接」「什么时候需要额外参数」展开。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [响应式](./reactivity.md)
|
||||
- [事件与交互](./events.md)
|
||||
|
||||
## 按键与元素事件
|
||||
|
||||
元素事件来自画布上的指针:先做命中测试,找到指针下的元素,再沿容器捕获与冒泡,关心的是「点在哪里」。
|
||||
|
||||
按键事件来自键盘:直接匹配指令,不经过画布命中,关心的是「按了什么」。
|
||||
|
||||
两条路径互相独立:按 Enter 不会触发按钮的 `onClick`,点按钮也不会触发绑定在 Enter 上的指令。两者可以同时存在,但没有统一的先后顺序;需要协同时,用一个共享的 `ref` 记录状态,让两边都读写同一份状态。
|
||||
|
||||
## 指令与分组
|
||||
|
||||
指令和分组都注册在 `src/client/misc/hotkey.ts` 的 `initializeHotkey` 里。UI 组件里出现 `system.addCommand(...)` 或 `hotkey.setGroup(...)` 都是错误写法。
|
||||
|
||||
`hotkey.setGroup(groupId, name, commands)` 的第三个参数是指令数组,直接在数组里调用 `system.addCommand(...)`:
|
||||
|
||||
```ts
|
||||
// src/client/misc/hotkey.ts
|
||||
import { HotkeyEmitMode, KeyCode } from '@motajs/system';
|
||||
import { IClientCore } from '@user/client-modules';
|
||||
|
||||
export function initializeHotkey(state: IClientCore) {
|
||||
const hotkey = state.hotkey;
|
||||
const system = hotkey.system;
|
||||
|
||||
hotkey.setGroup('@my-ui', '我的界面', [
|
||||
system.addCommand('@my-ui/refresh', '刷新面板', {
|
||||
defaults: [[KeyCode.KeyR]]
|
||||
}),
|
||||
system.addCommand('@my-ui/save', '保存', {
|
||||
defaults: [[KeyCode.Ctrl, KeyCode.KeyS]],
|
||||
mode: HotkeyEmitMode.Once
|
||||
})
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
`addCommand(command, name, init)` 的 `command` 是全局指令 id。已有指令用命名空间前缀区分,例如 `@common/exit`、`@ui/book`、`@game/undo`;新增时用类似 `@my-ui/refresh` 的前缀,避免和已有 id 冲突。
|
||||
|
||||
`defaults` 是默认按键组合。
|
||||
|
||||
分组只影响设置界面里的显示,不影响按键是否生效。不分组也能用,只是不会出现在设置界面里。重复注册同一个 id 不会创建第二条指令,只会返回已有指令并给出警告。
|
||||
|
||||
`props.state.hotkey` 是客户端按键门面(`IClientHotkey`),`system` 是底层 `IHotkeySystem`:`addCommand` / `deleteCommand` 在 `system` 上,`setGroup` 在门面上。
|
||||
|
||||
### 触发方式
|
||||
|
||||
| 取值 | 含义 | 默认 |
|
||||
| --------------------------- | ---------------- | ---- |
|
||||
| `HotkeyEmitMode.KeyUp` | 按键抬起时触发 | 是 |
|
||||
| `HotkeyEmitMode.Once` | 按下时只触发一次 | 否 |
|
||||
| `HotkeyEmitMode.Continuous` | 按住后持续触发 | 否 |
|
||||
|
||||
`mode` 不写时是抬起触发。菜单里的「按一下执行一次」用默认抬起;需要按住连发才用持续触发。持续触发可以用 `timeout`、`interval`、`dt` 控制首次延迟与后续间隔,单位都是毫秒;这些是最小间隔,实际间隔只会不小于设定值,不能当作精确计时器。
|
||||
|
||||
### 优先级与阻断
|
||||
|
||||
`priority` 越高越先执行,目前只对抬起触发的指令生效。`block` 为 `true` 时,会阻断优先级比它更低的指令;同优先级的指令会全部执行,不会互相阻断。这两个属性同样在 `hotkey.ts` 的 `addCommand` 里设置。
|
||||
|
||||
它们比较的是同一次按键匹配到的多条指令,不是两个界面之间的优先级。两个界面谁生效由作用域栈决定,见[按键与 UI 栈](#按键与-ui-栈)。
|
||||
|
||||
## 组件中的实现
|
||||
|
||||
组件只做一件事:把当前界面的作用域接到指令回调上。
|
||||
|
||||
`useKey` 从 `@user/client-base` 引入,必须在 `setup` 中同步调用,才能拿到当前组件实例与作用域。它返回 `IHotkeyUsing | null`,组件内必定有实例,直接用非空断言 `!`:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
import { useKey } from '@user/client-base';
|
||||
|
||||
const key = useKey(props.state.hotkey.system)!;
|
||||
|
||||
key.implement('@common/exit', () => {
|
||||
props.controller.close(props.instance);
|
||||
});
|
||||
|
||||
key.implement('@common/confirm', () => {
|
||||
props.controller.close(props.instance);
|
||||
});
|
||||
```
|
||||
|
||||
回调通常写成无参的 `() =>`:一般情况下只关心触发了哪个指令,不需要 `info`。只有确实需要触发元信息时才接收 `info`,不要用它判断语义,见[辅助按键与按键组合](#辅助按键与按键组合)。
|
||||
|
||||
`useKey` 返回的对象只有 `implement()`、`scope()`、`when()`,它不是按键系统,也不是 `system`。不要在它上面调用 `addCommand`、`setGroup`、`deleteCommand`;需要这些方法时,单独取 `props.state.hotkey.system` 或 `props.state.hotkey`。
|
||||
|
||||
`implement` 把指令接到当前作用域,可以连续调用。同一次挂载里对同一指令重复 `implement` 会覆盖前一个回调,并给出警告。指令 id 拼错、或指令还没注册就 `implement`,不会抛异常,只会记录一条警告;「按了没反应」时先核对 id,再确认当前界面是否在栈顶。
|
||||
|
||||
### 启用条件:when
|
||||
|
||||
`when(() => boolean)` 给当前 `useKey` 的作用域设置启用条件:返回 `false` 时,这个界面的指令不会触发。适合临时禁用当前界面的快捷键。
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const key = useKey(props.state.hotkey.system)!;
|
||||
const enabled = ref(true);
|
||||
|
||||
key.when(() => enabled.value);
|
||||
key.implement('@common/exit', () => { ... });
|
||||
```
|
||||
|
||||
条件在按键按下时判断一次;不要依赖「按下时 `false`、抬起时 `true` 就能触发」,按下时条件不成立,这次按键就不会生效。条件函数里直接读响应式值即可。
|
||||
|
||||
`when` 作用于当前 `useKey` 的作用域,不是全局系统。不要在其他作用域上调用它来改当前界面。
|
||||
|
||||
### 作用域与生命周期
|
||||
|
||||
`useKey` 在组件挂载时进入一个新作用域,组件卸载时自动离开,不需要手动清理。
|
||||
|
||||
第二个参数 `clearImpl` 默认是 `true`,新作用域不继承下层界面的实现。传 `false` 时,下层已经实现的指令会复制到新作用域里继续生效,适合「面板打开时全局快捷键仍然可用」的场景;当前面板重新实现的指令会覆盖下层版本。
|
||||
|
||||
### 子组件
|
||||
|
||||
普通子组件没有 `props.state`:把父级面板的 `props.state.hotkey.system` 作为普通 prop 传下来(类型 `IHotkeySystem` 从 `@motajs/system` 导入),在子组件 `setup` 里 `useKey(system)!`。也可以把按键处理留在能拿到 `props.state` 的父级面板,子组件只 emit。
|
||||
|
||||
## 辅助按键与按键组合
|
||||
|
||||
`defaults` 是二维数组:每一项是一组按键组合,组内最后一个键是主按键,前面的键是辅助键。`[[KeyCode.Ctrl, KeyCode.KeyS]]` 表示按住 Ctrl 再按 S;单按 S 不会匹配。
|
||||
|
||||
辅助键要先于主键按下。抬起触发时,只有在辅助键和主键都按下后松开主键才触发。同一条指令可以写多组组合;同时能匹配多组时,只会触发辅助键精确匹配的那一组。
|
||||
|
||||
一般不要判断具体按键,包括 `info.keys` 和 `info.context`。玩家可以在设置界面里改键,按键和组合会变,按当前键位分支会得到错误的语义。
|
||||
|
||||
同一语义、只是默认组合不同时,在一条指令里写多个 `defaults`,组件里只 `implement` 一次,不需要 `info`:
|
||||
|
||||
```ts
|
||||
// src/client/misc/hotkey.ts
|
||||
hotkey.setGroup('@my-ui', '我的界面', [
|
||||
system.addCommand('@my-ui/refresh', '刷新面板', {
|
||||
defaults: [
|
||||
[KeyCode.KeyR], // R
|
||||
[KeyCode.Shift, KeyCode.KeyR] // Shift + R
|
||||
]
|
||||
})
|
||||
]);
|
||||
```
|
||||
|
||||
不同语义就拆成不同指令,各自注册、各自 `implement`:
|
||||
|
||||
```ts
|
||||
// src/client/misc/hotkey.ts
|
||||
hotkey.setGroup('@my-ui', '我的界面', [
|
||||
system.addCommand('@my-ui/save', '保存', {
|
||||
defaults: [[KeyCode.Ctrl, KeyCode.KeyS]]
|
||||
}),
|
||||
system.addCommand('@my-ui/quick-save', '快速保存', {
|
||||
defaults: [[KeyCode.KeyS]]
|
||||
})
|
||||
]);
|
||||
```
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
import { useKey } from '@user/client-base';
|
||||
|
||||
const key = useKey(props.state.hotkey.system)!;
|
||||
|
||||
key.implement('@my-ui/save', save);
|
||||
key.implement('@my-ui/quick-save', quickSave);
|
||||
```
|
||||
|
||||
`info` 一般不需要;确实需要触发元信息时才接收,不要用它判断语义。
|
||||
|
||||
确实需要 `info` 时,通常是「一条指令有多个语义槽位」:槽位由 `defaults` 里的组合顺序稳定决定,组件只按 `info.index` 取槽位。
|
||||
|
||||
例如快速切换装备,`Alt+1` 到 `Alt+0` 依次对应槽位 0 到 9:
|
||||
|
||||
```ts
|
||||
// src/client/misc/hotkey.ts
|
||||
import { KeyCode } from '@motajs/system';
|
||||
|
||||
hotkey.setGroup('@my-ui', '我的界面', [
|
||||
system.addCommand('@my-ui/quick-equip', '快速切换装备', {
|
||||
defaults: [
|
||||
[KeyCode.Alt, KeyCode.Digit1], // 槽位 0
|
||||
[KeyCode.Alt, KeyCode.Digit2], // 槽位 1
|
||||
[KeyCode.Alt, KeyCode.Digit3], // 槽位 2
|
||||
[KeyCode.Alt, KeyCode.Digit4], // 槽位 3
|
||||
[KeyCode.Alt, KeyCode.Digit5], // 槽位 4
|
||||
[KeyCode.Alt, KeyCode.Digit6], // 槽位 5
|
||||
[KeyCode.Alt, KeyCode.Digit7], // 槽位 6
|
||||
[KeyCode.Alt, KeyCode.Digit8], // 槽位 7
|
||||
[KeyCode.Alt, KeyCode.Digit9], // 槽位 8
|
||||
[KeyCode.Alt, KeyCode.Digit0] // 槽位 9
|
||||
]
|
||||
})
|
||||
]);
|
||||
```
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
import { useKey } from '@user/client-base';
|
||||
import { IHotkeyEmitInfo } from '@motajs/system';
|
||||
|
||||
const key = useKey(props.state.hotkey.system)!;
|
||||
|
||||
// info.index 是触发组合在 defaults 里的下标,正好对应装备槽位
|
||||
const quickEquip = (info: IHotkeyEmitInfo) => {
|
||||
const slot = info.index;
|
||||
// 使用 slot 切换装备
|
||||
};
|
||||
key.implement('@my-ui/quick-equip', quickEquip);
|
||||
```
|
||||
|
||||
这里需要 `info`,是因为一条指令有多个语义槽位,槽位由组合顺序稳定决定。不要判断 `info.keys` 或具体的数字键:玩家改键后按键会变,但 `info.index` 仍对应槽位。
|
||||
|
||||
## 按键与 UI 栈
|
||||
|
||||
按键作用域是一条全局栈,不按控制器分开。最后挂载并调用 `useKey` 的面板在栈顶,只有栈顶作用域里的实现会执行:
|
||||
|
||||
- 面板 A 打开,A 在栈顶,A 的 Esc 生效。
|
||||
- 面板 B 打开,B 在栈顶,A 的 Esc 暂时不生效,背景界面也不会同时响应。
|
||||
- 面板 B 关闭并卸载,B 的作用域移除,A 重新成为栈顶,A 的 Esc 恢复。
|
||||
|
||||
这里的「关闭」指组件卸载。只是把面板 `hidden` 起来,组件还在,作用域也还在,它仍然占着栈里的位置。用 `showAll` 让多个面板同时显示时,按键仍然只落到最后挂载的那个面板,不会因为都可见就都响应。
|
||||
|
||||
## 默认按键
|
||||
|
||||
默认值只是起点,玩家可以在设置界面里改:
|
||||
|
||||
| 指令 | 默认按键 | 说明 |
|
||||
| ------------------- | ----------------- | ----------- |
|
||||
| `@common/confirm` | Enter / Space / C | 确认 |
|
||||
| `@common/exit` | Escape / X | 取消 / 返回 |
|
||||
| `@ui/menu` | Escape | 游戏菜单 |
|
||||
| `@ui/toolbox` | T | 道具界面 |
|
||||
| `@ui/command` | Q | 装备界面 |
|
||||
| `@ui/save` | S | 存档界面 |
|
||||
| `@ui/load` | D | 读档界面 |
|
||||
| `@ui/book` | X | 怪物手册 |
|
||||
| `@ui/input-confirm` | Enter | 输入框确认 |
|
||||
| `@ui/view-map` | PageDown / PageUp | 浏览地图 |
|
||||
|
||||
表中只列出常用的 UI 指令;游戏按键与系统按键在 `hotkey.ts` 里另有分组。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 按键与元素事件是两条独立路径。不要用元素事件去等按键,也不要用按键去模拟点击。
|
||||
- 指令和分组只在 `src/client/misc/hotkey.ts` 的 `initializeHotkey` 里注册,UI 组件里不调用 `addCommand` / `setGroup`。
|
||||
- `useKey` 必须在 `setup` 中同步调用,返回可能为 `null`;组件内用非空断言 `!`。
|
||||
- `useKey` 返回的对象只有 `implement()`、`scope()`、`when()`,不是 `system`,不要在它上面调用按键系统方法。
|
||||
- 不要按具体按键、`info.keys` 或 `info.context` 判断行为。玩家可以改键,按键和组合会变,按当前键位分支会得到错误的语义;语义不同就拆成不同指令。
|
||||
- 按键回调保持短小。不要在里面写长时间的异步任务,需要等待的操作另起流程。
|
||||
- 一条指令确定不再被任何界面使用时,才在 `hotkey.ts` 里用 `system.deleteCommand` 删除;作用域卸载只清理实现,不会删除指令。
|
||||
@@ -0,0 +1,207 @@
|
||||
# 示例(一)目标与骨架
|
||||
|
||||
前面五批讲的是零件:模板、元素、响应式、事件、组件、内置组件与 UI 栈。这一批把它们装成同一个能用的面板——一个背包 / 装备界面。六篇按「每一步只加一小段」推进,本篇先定目标、拆分与骨架。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [第一个静态界面](../basics/first-static-ui.md)
|
||||
- [容器与坐标](../basics/container-and-coordinates.md)
|
||||
|
||||
## 这一步要解决什么
|
||||
|
||||
最终面板是一块 720×480 的区域:
|
||||
|
||||
- 顶部是标题与关闭按钮。
|
||||
- 左侧是 5 列的道具网格,格子显示名称与数量。
|
||||
- 右侧是选中道具的详情,没有选中时显示提示。
|
||||
- 底部是装备 / 使用 / 关闭按钮。
|
||||
- 道具变多后,左侧网格可以滚动。
|
||||
|
||||
本篇只做外框、标题、关闭按钮与左右两个占位区。网格、详情、滚动、交互与动画留到后面五篇,每一步都在这份骨架上继续填,不另起一套实现。
|
||||
|
||||
先搭骨架、后填数据,是因为骨架决定了每个后续节点「挂在哪里」:左侧区域有多大,网格就知道自己的行列要按什么尺寸排;右侧区域在哪,详情就知道自己该占多少文字宽度;底部操作条从哪开始,滚动区才不会压到按钮上。如果先写数据再回头调坐标,读者每加一步都要重新算一遍布局,最后也很难说清某一行代码到底属于树上的哪一层。
|
||||
|
||||
## 骨架在渲染树里的位置
|
||||
|
||||
先把最终面板的节点定下来,后面每一步都往这棵树里加东西。根 `container` 下依次是画布底色、面板主体、标题、关闭按钮、左侧占位与右侧占位,它们都是兄弟节点;树形规则本身见[第 2 篇「容器与坐标」](../basics/container-and-coordinates.md#渲染树根容器与子元素)。
|
||||
|
||||
三个区域是根容器的子容器,彼此是兄弟关系。它们的坐标都相对根容器的左上角:
|
||||
|
||||
- 面板主体在 `[30, 30]`,尺寸 `660×420`,所以内容可用范围是 `x` 从 30 到 690、`y` 从 30 到 450。
|
||||
- 左侧区域 `[54, 100, 400, 280]`,右边界 454;右侧区域 `[470, 100, 196, 280]`,两者之间留 16 像素空隙。
|
||||
- 底部操作条在示例(五)加到 `[54, 392, 304, 32]`:左侧区域的下边界是 `100 + 280 = 380`,操作条从 392 开始,`380 < 392`,两者不重叠。
|
||||
|
||||
720×480 是 UI 的逻辑尺寸,不是浏览器窗口尺寸。UI 被缩放显示时会按逻辑坐标整体变换,所以坐标只需要按 720×480 算一次,不必为不同窗口大小写几套。
|
||||
|
||||
它和第 2 篇说的「画布设计尺寸」是同一件事的两层:`props.state.renderer.width` / `height` 是客户端配置的画布尺寸(示例站点是 480×320),面板根容器再在这个画布上按自己的 `loc` 定位。面板根占多大、是否铺满,由你写的 `loc` 决定;示例写 `[0, 0, 720, 480]`,所以它相对 UI 容器从左上角开始。画布比面板小时,超出的部分不会自动缩小或居中;需要适配不同窗口时,读 `renderer.width` / `height` 自己算位置。
|
||||
|
||||
分工可以记成一句:面板内部坐标一律相对面板根(示例按 720×480 设计),画布尺寸只决定面板根放在哪、最终如何缩放。先把面板当成固定设计稿写坐标,再在打开处按画布适配。
|
||||
|
||||
跑起来的方式不在本系列重复,见仓库根目录的 `dev.md`。示例站画布是 480×320,720×480 的面板超出画布的部分不会自动缩放,只会不可见;先按画布尺寸调面板根,或整体缩放。
|
||||
|
||||
第一次在示例站(480×320)验证时,不用重排内部坐标:给面板根加 `scale={[2 / 3, 2 / 3]}`(比例取 `min(480 / 720, 320 / 480)`),`loc` 仍写 `[0, 0, 720, 480]`,整棵树会按同一比例缩小并完整落在 480×320 里。确认画面之后,如果要正式适配不同窗口,再按 `renderer.width` / `height` 改根 `loc` 并重排内部区域;不要同时改内部坐标和加缩放,否则会缩两次。
|
||||
|
||||
同一父级下的遮挡按 `zIndex` 与加入顺序决定:关闭按钮画在面板主体之后,因此会盖在主体上,点击落在按钮矩形里就由它接收。完整层级规则见[第 7 篇「层级、变换与性能」](../basics/layer-transform-performance.md#渲染树层级与绘制顺序)。
|
||||
|
||||
## 组件与文件怎么分
|
||||
|
||||
组件拆分在骨架阶段就定下来,后面只往对应文件里填内容,不再改结构:
|
||||
|
||||
| 文件 | 导出 | 职责 | 主要 props |
|
||||
| --------------------- | ---------------- | ------------------------------------------ | -------------------------------------------------- |
|
||||
| `inventory-panel.tsx` | `InventoryPanel` | 根容器、标题、关闭按钮、左右分栏与共享状态 | `controller` / `instance` / `state` |
|
||||
| `item-grid.tsx` | `ItemGrid` | 按行列排出道具网格,把点击事件交回父组件 | `items` / `selectedId` / `equippedId` / `onSelect` |
|
||||
| `item-cell.tsx` | `ItemCell` | 单个道具格子:背景、名称、数量、选中态 | `item` / `selected` / `equipped` / `size` |
|
||||
| `item-detail.tsx` | `ItemDetail` | 右侧详情:名称、数量、描述与未选中提示 | `item` / `onClear` |
|
||||
| `action-bar.tsx` | `ActionBar` | 底部按钮:装备 / 使用 / 关闭 | `canEquip` / `canUse` / `equipped` / 三个回调 |
|
||||
|
||||
表里列的是最终 props;`equipped` / `equippedId` 在示例(五)加入,前面几篇的格子先只有 `selected`。`InventoryPanel` 是唯一被 `GameUI` 注册的组件;另外四个都是普通子组件,由它按需组合。这样拆分的好处是:每个文件的职责固定,读者可以按文件名找到对应代码,而不用在一个大文件里翻找。
|
||||
|
||||
表里的「三个回调」「`onSelect`」「`onClear`」是父级写给子组件的监听器名;子组件内部用 `emits: ['select']` 或 `emits: ['clear']` 声明,再 `emit('select', id)` 触发,父级仍写 `onSelect={...}`。所以照表里的 props 名写父级用法即可,子组件内部则按 `emits` 声明。
|
||||
|
||||
本篇只落地 `inventory-panel.tsx`。左侧与右侧先写成两个带背景的 `container` 占位,不 import 后四个文件——这样每一步都能单独编译,等示例(二)(三)再把占位换成真正的 `ItemGrid` 与 `ItemDetail`,替换时只改子树,不动坐标。
|
||||
|
||||
## 打开、状态与关闭归谁
|
||||
|
||||
面板由控制器打开,打开时创建实例;关闭时把实例交回同一个控制器:
|
||||
|
||||
```tsx
|
||||
import { GameUI } from '@motajs/system';
|
||||
|
||||
// 构造只是把名字与组件绑成一个对象
|
||||
export const InventoryUI = new GameUI('inventory-panel', InventoryPanel);
|
||||
|
||||
// 从游戏主 UI 栈打开,返回值就是这次打开的实例
|
||||
const instance = props.state.mainUIController.open(InventoryUI, {});
|
||||
|
||||
// 关闭时把同一个实例交回去
|
||||
props.state.mainUIController.close(instance);
|
||||
```
|
||||
|
||||
面板内部拿到的 `props.instance` 就是打开时创建的那个实例,`props.controller` 是打开它的控制器。所以面板自己关闭自己时,写的是 `props.controller.close(props.instance)`,不需要记住是哪个控制器打开的。
|
||||
|
||||
**关闭归 `InventoryPanel`**。标题栏的关闭按钮调用这个方法;后面加进来的 `ActionBar` 只发出 `close` 事件,由面板决定是否关闭。子组件不直接拿 `controller` 去关面板,否则同一件事会出现两个入口,按键关闭和按钮关闭的行为也会分叉。
|
||||
|
||||
**状态归 `InventoryPanel`**。`items` 与 `selectedId` 由面板持有,网格只负责显示与上报点击,详情只接收派生结果。本篇先把关闭按钮接通,`items` 与 `selectedId` 从示例(二)开始填。
|
||||
|
||||
## 骨架代码
|
||||
|
||||
`inventory-panel.tsx` 先给外框、标题、关闭按钮与两个占位区:
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { GameUI, SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
import { IGameUIPropsBase } from '@user/client-base';
|
||||
|
||||
// UI 的 Props 必须同时继承基础 Props 与默认 Props
|
||||
interface InventoryPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const inventoryPanelProps = {
|
||||
// 三个键少一个,组件里就拿不到对应的值
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<InventoryPanelProps>;
|
||||
|
||||
const InventoryPanel = defineComponent<InventoryPanelProps>(props => {
|
||||
// 关闭归面板:把当前实例交回打开它的控制器
|
||||
const close = () => {
|
||||
props.controller.close(props.instance);
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 720, 480]}>
|
||||
{/* 画布底色 */}
|
||||
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
|
||||
|
||||
{/* 面板主体 */}
|
||||
<g-rectr
|
||||
loc={[30, 30, 660, 420]}
|
||||
circle={[18]}
|
||||
fill
|
||||
fillStyle="#1d2b45"
|
||||
stroke
|
||||
strokeStyle="#2f6fed"
|
||||
/>
|
||||
|
||||
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
|
||||
|
||||
{/* 关闭按钮必须在骨架阶段就能用,否则后面每加一块内容都无法验证退出 */}
|
||||
<container loc={[626, 50, 56, 32]} onClick={close}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 56, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle="#7a3d3d"
|
||||
/>
|
||||
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
|
||||
</container>
|
||||
|
||||
{/* 左侧网格占位:示例(二)换成 ItemGrid */}
|
||||
<container loc={[54, 100, 400, 280]}>
|
||||
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="道具网格占位" fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
|
||||
{/* 右侧详情占位:示例(三)换成 ItemDetail */}
|
||||
<container loc={[470, 100, 196, 280]}>
|
||||
<g-rect loc={[0, 0, 196, 280]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="详情占位" fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
}, inventoryPanelProps);
|
||||
|
||||
export const InventoryUI = new GameUI('inventory-panel', InventoryPanel);
|
||||
```
|
||||
|
||||
这段代码只做三件事:画出 720×480 的面板、放好标题与关闭按钮、用两个占位容器标出后续网格与详情的位置。
|
||||
|
||||
在渲染树上,根 `container` 是这次 UI 的入口,面板主体、标题、关闭按钮与两个占位区都是它的直接子元素。关闭按钮自己又是一个小容器,内部只有底板与文字:点击命中按钮区域后,事件交给带 `onClick` 的容器,调用 `close`,再由控制器卸载实例。两个占位容器不是装饰,它们先把区域尺寸写进树里,后面换 `ItemGrid` 与 `ItemDetail` 时只需要替换子节点,坐标不用重算。
|
||||
|
||||
`props` 数组必须同时列出 `controller`、`instance`、`state`,少一个组件里就拿不到对应的值。`InventoryPanel` 被 `GameUI` 注册后,这三个值由 UI 栈在创建实例时注入,作者不需要手动传。
|
||||
|
||||
## 打开它
|
||||
|
||||
骨架写完后,从三个常见位置打开:
|
||||
|
||||
```tsx
|
||||
// 场景 UI:由客户端核心的场景控制器打开
|
||||
props.state.sceneController.open(InventoryUI, {});
|
||||
|
||||
// 在另一个 UI 内打开:沿用当前 UI 的控制器
|
||||
props.controller.open(InventoryUI, {});
|
||||
|
||||
// 游戏内的背包通常从主 UI 栈打开
|
||||
props.state.mainUIController.open(InventoryUI, {});
|
||||
```
|
||||
|
||||
三者的区别只在「由哪个控制器管理这次打开的实例」:`mainUIController` 管主界面栈,`sceneController` 管场景层,`props.controller` 是当前 UI 的控制器。具体差别见[「UI 系统」](./ui-system.md)。本篇先把打开入口跑通;从示例(六)开始统一用主 UI 栈打开,并在那里说明注册与栈的关系。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面是骨架的 live。它只包含面板本身;关闭按钮在 live 里只显示一行提示——文档站没有真实的 UI 栈,无法真的关闭面板。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="skeletonLoader" :width="720" :height="480" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const skeletonLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/inventory-1-skeleton.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 组件拆分在骨架阶段就定下来,后面只填内容。中途换结构会让读者无法把前几篇和后几篇对上。
|
||||
- 不用真实素材。图标一律用 `g-rect` / `g-rectr` 加 `text` 画出来,读者不需要准备图片。
|
||||
- 关闭按钮必须在骨架阶段就能用。否则后面每加一块内容,都无法验证「面板能不能正常退出」。
|
||||
- 不要把网格、详情、按钮全塞进 `InventoryPanel`。根组件只负责布局与共享状态,具体区域交给子组件。
|
||||
- Props 只能用 `IGameUIPropsBase` 配 `DefaultProps`,`props` 数组至少包含 `controller`、`instance`、`state`。
|
||||
- 两个占位区按最终布局给足尺寸:左侧 `[54, 100, 400, 280]`、右侧 `[470, 100, 196, 280]`。示例(五)的操作条从 `y = 392` 开始,和左侧区域的下边界 380 之间留了 12 像素,不会压住网格。
|
||||
@@ -0,0 +1,306 @@
|
||||
# 示例(二)道具网格
|
||||
|
||||
上一篇的左侧只有一块占位。本篇把道具数据、`ItemCell` 与 `ItemGrid` 填进去,让网格能显示、能选中。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [示例(一)目标与骨架](./inventory-example-1-skeleton.md)
|
||||
- [基础图形](../basics/basic-shapes.md)
|
||||
|
||||
## 从占位到网格
|
||||
|
||||
本步只替换左侧占位区,右侧详情与底部操作条仍然是占位:
|
||||
|
||||
```text
|
||||
container [54, 100, 400, 280] 左侧区域
|
||||
├─ g-rect 区背景
|
||||
└─ ItemGrid 本步新增的组件
|
||||
├─ ItemCell 第 1 个道具
|
||||
├─ ItemCell 第 2 个道具
|
||||
└─ ... 按行列排开
|
||||
```
|
||||
|
||||
网格挂在左侧区域里,坐标相对左侧容器,不再相对根容器。这样后面换滚动容器、调整左侧区域大小时,网格跟着区域走,不用改每个格子的绝对坐标。
|
||||
|
||||
## 数据模型:Item 只定义一次
|
||||
|
||||
背包里的道具用一个最小模型表示。这个 `Item` 只在示例(二)定义一次,示例(三)到(六)都直接引用它,不各自重写:
|
||||
|
||||
```tsx
|
||||
// 道具模型:id 用于选中与装备状态,其余字段用于显示
|
||||
interface Item {
|
||||
id: string;
|
||||
name: string;
|
||||
count: number;
|
||||
desc: string;
|
||||
}
|
||||
```
|
||||
|
||||
`id` 用来判断选中与装备状态,必须是稳定且唯一的值。不要用数组下标代替:下标会随着删除、排序变化,同一个道具换到另一个位置后就变成了另一个身份。
|
||||
|
||||
示例把这个 `interface Item` 与 `ItemGrid` 放在 `item-grid.tsx` 里并 `export`;使用它的文件写 `import type { Item } from './item-grid'`。类型导入编译后会被擦除,不会引入运行时循环依赖。
|
||||
|
||||
假数据只在写作示范里用,读者可以替换成自己的存档数据:
|
||||
|
||||
```tsx
|
||||
const items = ref<Item[]>([
|
||||
{ id: 'potion-red', name: '红药水', count: 3, desc: '恢复少量生命。' },
|
||||
{ id: 'potion-blue', name: '蓝药水', count: 1, desc: '恢复少量魔力。' },
|
||||
{ id: 'key-yellow', name: '黄钥匙', count: 5, desc: '打开黄色的门。' },
|
||||
{ id: 'key-blue', name: '蓝钥匙', count: 2, desc: '打开蓝色的门。' },
|
||||
{ id: 'sword-wood', name: '木剑', count: 1, desc: '最基础的武器。' },
|
||||
{ id: 'shield-wood', name: '木盾', count: 1, desc: '最基础的防具。' },
|
||||
{ id: 'gem-red', name: '红宝石', count: 4, desc: '镶嵌用的素材。' },
|
||||
{ id: 'gem-blue', name: '蓝宝石', count: 2, desc: '镶嵌用的素材。' },
|
||||
{ id: 'scroll', name: '回城卷轴', count: 1, desc: '回到起点。' },
|
||||
{ id: 'bread', name: '面包', count: 6, desc: '恢复少量生命。' }
|
||||
]);
|
||||
```
|
||||
|
||||
`items` 是 `ref<Item[]>`,由 `InventoryPanel` 持有。用 `ref` 而不是普通数组,是因为后面使用道具会改数量、面板关闭后可能重新打开,数组需要在多次渲染之间保持同一份响应式数据。子组件不在自己的闭包里引用 `items`,只通过 props 拿到解包后的数组。
|
||||
|
||||
## 网格的树结构
|
||||
|
||||
网格是两层:`ItemGrid` 是容器,负责算位置;`ItemCell` 是叶子,负责画一个格子。一个格子在外层包一个定位容器,把「第几行第几列」换算成坐标,`ItemCell` 自己的根元素仍然固定在 `[0, 0]`,内部只按尺寸画。
|
||||
|
||||
5 列示例的坐标来源:
|
||||
|
||||
- 列宽 `cellSize = 66`,间距 `gap = 8`,所以列与列之间隔 74。
|
||||
- 第 `index` 个道具的列是 `index % 5`,行是 `Math.floor(index / 5)`。
|
||||
- 横坐标 `x = col * (66 + 8)`,纵坐标 `y = row * (66 + 8)`。
|
||||
- 5 列总宽 `5 * 66 + 4 * 8 = 362`,放在 400 宽的左侧区域里还剩 38 像素。
|
||||
|
||||
格子是并列的兄弟节点,绘制与命中按同一父级下的顺序进行;每格的位置互不重叠,所以点击落在哪个矩形里就由哪个格子接收。
|
||||
|
||||
## ItemCell:一个格子
|
||||
|
||||
格子只需知道「显示哪个道具」「是否选中」「多大」,点击时把 id 交回父组件。写法沿用[自定义组件的 props](./custom-components.md#props):
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
|
||||
interface ItemCellProps extends DefaultProps {
|
||||
item: Item;
|
||||
selected?: boolean;
|
||||
size?: number;
|
||||
}
|
||||
|
||||
interface ItemCellEmits {
|
||||
select: (id: string) => void;
|
||||
}
|
||||
|
||||
const itemCellProps = {
|
||||
props: ['item', 'selected', 'size'],
|
||||
emits: ['select']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>;
|
||||
|
||||
const ItemCell = defineComponent<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>((props, { emit }) => {
|
||||
// 格子不保存状态,只根据 item 与 selected 渲染
|
||||
// 尺寸在面板生命周期内不变,读一次即可;若尺寸会随窗口变化,再改成 computed
|
||||
const size = props.size ?? 66;
|
||||
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, size, size]}
|
||||
onClick={() => emit('select', props.item.id)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, size, size]}
|
||||
circle={[10]}
|
||||
fill
|
||||
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
|
||||
/>
|
||||
{/* 选中时加一圈描边;未选中时用暗色边框保持尺寸一致 */}
|
||||
<g-rectr
|
||||
loc={[1, 1, size - 2, size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
|
||||
/>
|
||||
{/* 名称在左上角,数量固定在左下角 */}
|
||||
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[8, size - 24]}
|
||||
text={`× ${props.item.count}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, itemCellProps);
|
||||
|
||||
export { ItemCell };
|
||||
```
|
||||
|
||||
在渲染树上,`ItemCell` 的根是一个带尺寸的容器,背景、描边、名称、数量都是它的子元素。它没有内部状态,`selected` 由父级传入:父级改变 `selectedId` 后,每个格子重新计算自己该不该高亮,不会出现「一个格子还亮着」的残留。这也是为什么点击不自己改状态,而是 `emit('select', props.item.id)` 交回父级。
|
||||
|
||||
## ItemGrid:按行列排列
|
||||
|
||||
`ItemGrid` 不写死每个格子的坐标,而是用列数、格子尺寸与间距算出位置:
|
||||
|
||||
```tsx
|
||||
import { computed, defineComponent } from 'vue';
|
||||
import { SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
|
||||
interface ItemGridProps extends DefaultProps {
|
||||
items: Item[];
|
||||
selectedId: string | null;
|
||||
columns?: number;
|
||||
cellSize?: number;
|
||||
gap?: number;
|
||||
}
|
||||
|
||||
interface ItemGridEmits {
|
||||
select: (id: string) => void;
|
||||
}
|
||||
|
||||
const itemGridProps = {
|
||||
props: ['items', 'selectedId', 'columns', 'cellSize', 'gap'],
|
||||
emits: ['select']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemGridProps,
|
||||
ItemGridEmits,
|
||||
keyof ItemGridEmits
|
||||
>;
|
||||
|
||||
const ItemGrid = defineComponent<
|
||||
ItemGridProps,
|
||||
ItemGridEmits,
|
||||
keyof ItemGridEmits
|
||||
>((props, { emit }) => {
|
||||
// 列数、尺寸、间距都可能来自 props,用 computed 派生,变化时重算
|
||||
const columns = computed(() => props.columns ?? 5);
|
||||
const cellSize = computed(() => props.cellSize ?? 66);
|
||||
const gap = computed(() => props.gap ?? 8);
|
||||
|
||||
return () => (
|
||||
// 网格根容器与左侧区域同尺寸,只做分组与定位,不裁切内容
|
||||
<container loc={[0, 0, 400, 280]}>
|
||||
{props.items.map((item, index) => {
|
||||
// 每行放 columns 个,超出后换到下一行
|
||||
const col = index % columns.value;
|
||||
const row = Math.floor(index / columns.value);
|
||||
const x = col * (cellSize.value + gap.value);
|
||||
const y = row * (cellSize.value + gap.value);
|
||||
return (
|
||||
// 定位容器与格子同尺寸,避免默认尺寸盖住邻居
|
||||
<container
|
||||
key={item.id}
|
||||
loc={[x, y, cellSize.value, cellSize.value]}
|
||||
>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === props.selectedId}
|
||||
size={cellSize.value}
|
||||
onSelect={id => emit('select', id)}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
})}
|
||||
</container>
|
||||
);
|
||||
}, itemGridProps);
|
||||
|
||||
export { ItemGrid };
|
||||
```
|
||||
|
||||
这里用 `.map()` 把数组映射成一组元素,没有写循环指令。定位容器与格子同尺寸,不会出现「容器默认 200×200 盖住邻格」的问题;容器本身没有点击监听,点击命中的是格子,再沿父链交给 `ItemGrid`。
|
||||
|
||||
`key` 用 `item.id`:格子身份跟道具走,不跟位置走。现在列表顺序固定、看起来用下标也能跑,但示例(五)会减数量、以后可能删除道具,一旦增删,下标会把「第 3 个位置」错当成「同一个道具」。从一开始就按 id 绑定,后面不用返工。
|
||||
|
||||
## 数据如何进入网格
|
||||
|
||||
数据只有一条路:`InventoryPanel` 持有 `items`,把解包后的数组传给 `ItemGrid`;`ItemGrid` 把它映射成若干 `ItemCell`;`ItemCell` 只接收 `item` 与 `selected`,不直接读父级闭包。
|
||||
|
||||
```tsx
|
||||
import { computed, ref } from 'vue';
|
||||
|
||||
// 面板持有 items,子组件只接收解包后的数组
|
||||
const items = ref<Item[]>([
|
||||
/* 上面的假数据 */
|
||||
]);
|
||||
// 未选中用 null,不用 undefined 或空字符串
|
||||
const selectedId = ref<string | null>(null);
|
||||
|
||||
// 选中项由 items 与 selectedId 派生,详情与按钮共用同一份数据
|
||||
const selectedItem = computed(
|
||||
() => items.value.find(item => item.id === selectedId.value) ?? null
|
||||
);
|
||||
|
||||
<container loc={[54, 100, 400, 280]}>
|
||||
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
|
||||
{/* 网格只上报点击,选中值仍由父组件保存 */}
|
||||
<ItemGrid
|
||||
items={items.value}
|
||||
selectedId={selectedId.value}
|
||||
columns={5}
|
||||
cellSize={66}
|
||||
gap={8}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</container>;
|
||||
```
|
||||
|
||||
`items` 作为 prop 传的是 `items.value`,也就是数组本身;`ItemGrid` 内部收到的是普通数组,不需要再解包。派生数据 `selectedItem` 也放在面板:详情与操作按钮都要用它,放在父级只有一份,不会出现网格与详情各算一遍、结果不一致。
|
||||
|
||||
## 点击如何上报
|
||||
|
||||
一次点击经过三层,每层只做自己的事:
|
||||
|
||||
```text
|
||||
点击 ItemCell
|
||||
→ ItemCell 的 onClick 发出 emit('select', item.id)
|
||||
→ ItemGrid 的 onSelect 收到 id,再 emit('select', id)
|
||||
→ InventoryPanel 的 onSelect 把 selectedId 写成这个 id
|
||||
→ 重新渲染:选中格子高亮,selectedItem 重算
|
||||
```
|
||||
|
||||
- `ItemCell` 知道「自己被点了」,但不知道该选谁,所以只上报自己的 `item.id`。
|
||||
- `ItemGrid` 知道「网格里有一个 id 被选中」,但它不持有选中状态,继续上报。
|
||||
- `InventoryPanel` 是唯一持有 `selectedId` 的地方,写值后由响应式系统把新状态推回子树。
|
||||
|
||||
这条链也是后面示例(四)滚动、示例(五)操作条继续沿用的路径:子组件上报,面板决定。
|
||||
|
||||
## 这一步的边界
|
||||
|
||||
本步的网格是普通容器平铺,不滚动。道具多到超出一屏时,超出的格子仍然会被渲染,只是画在区域外;`Scroll` 要等到示例(四)才引入,它会把「平铺 + 只渲染视口附近」接在这棵子树上。
|
||||
|
||||
所以不要把本步的普通网格当成最终方案。示例(四)会明确替换关系:左侧换成 `Scroll`,`ItemGrid` 的 props 与事件链不变,只把根容器换成滚动容器;示例(五)(六)不会再回到普通网格或 `ListPage`。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面的 live 在骨架上加了网格与选中态。点击任意格子,右侧占位区会显示当前选中的道具。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="gridLoader" :width="720" :height="480" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const gridLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/inventory-2-grid.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 列宽与间距用常量算,不要手写每格坐标。格子数量变化时只改 `columns` 或 `cellSize`。
|
||||
- 选中态只由 `selectedId` 决定,不要在格子里各存一份。否则父组件切换选中时会出现不同步。
|
||||
- `.map()` 返回的每一项结构必须一致。定位容器与格子同尺寸,不要用默认尺寸的容器去套小格子。
|
||||
- `id` 用稳定且唯一的值,`key` 也用 `item.id`;不要用数组下标代替。
|
||||
- 网格区域尺寸变化时重新算列数,不要让最后一列溢出到详情区;本篇 5 列总宽 362,左侧区域宽 400。
|
||||
@@ -0,0 +1,202 @@
|
||||
# 示例(三)详情区
|
||||
|
||||
上一篇左侧已经能选道具,右侧还是占位。本篇把 `ItemDetail` 填上:名称、数量、描述,以及没有选中时的提示。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [示例(二)道具网格](./inventory-example-2-grid.md)
|
||||
- [文字](../basics/text.md)
|
||||
- [通用参数](../basics/common-props.md)
|
||||
|
||||
## 详情区接的是哪个状态
|
||||
|
||||
详情不自己保存状态,它只接收一个「选中项」。选中项在 `InventoryPanel` 里用 `computed` 从 `items` 与 `selectedId` 算出来:
|
||||
|
||||
```tsx
|
||||
import { computed, ref } from 'vue';
|
||||
|
||||
// 面板持有选中 id;未选中用 null,不用 undefined 或空字符串
|
||||
const selectedId = ref<string | null>(null);
|
||||
|
||||
// 选中项由 items 与 selectedId 派生;找不到时统一变成 null
|
||||
const selectedItem = computed(
|
||||
() => items.value.find(item => item.id === selectedId.value) ?? null
|
||||
);
|
||||
```
|
||||
|
||||
`selectedId` 的类型是 `ref<string | null>`,初始值 `null`,表示「什么都没选」。用 `null` 而不是 `undefined` 或空字符串,是因为三种「没有值」的写法会在不同地方产生不同行为:`undefined` 容易被当成「还没传」而被默认值替换,空字符串会被当成一个合法 id 去查列表。`null` 在类型上明确表示「有值,但值是空」。
|
||||
|
||||
`find` 找不到时返回 `undefined`,这里用 `?? null` 收口,让 `selectedItem` 的类型固定为 `Item | null`。这样详情组件只需要判断「有没有 item」,不用区分 `undefined` 与 `null` 两种空值。
|
||||
|
||||
## 详情区的树结构
|
||||
|
||||
详情区在面板右侧,最终布局是 `[470, 100, 196, 280]`。`ItemDetail` 的根容器与区域同尺寸,内部再分四块:
|
||||
|
||||
```text
|
||||
container [0, 0, 196, 280] 详情组件根
|
||||
├─ g-rect 区背景
|
||||
├─ text [16, 16] 小标题「详情」
|
||||
├─ container hidden={有选中} 未选中提示
|
||||
│ └─ text [16, 52] 「请选择道具」
|
||||
├─ container hidden={没选中} 详情内容
|
||||
│ ├─ text [16, 52] 名称
|
||||
│ ├─ text [16, 84] 数量
|
||||
│ └─ TextContent [16, 120] 描述,按宽度折行
|
||||
└─ container [16, 236, 164, 28] 取消选择按钮
|
||||
```
|
||||
|
||||
名称、数量、描述都是详情容器的子节点,位置相对详情根容器。描述没有用 `text` 元素硬排:`text` 只画一行,不会自动换行;`TextContent` 给了 `width` 才会按宽度折行,`autoHeight` 让高度跟着内容走。`width` 是必填项,不传时组件拿不到排版宽度。描述从 `y = 120` 开始,到取消选择按钮上方 `236` 为止,大约能放四到五行;更长的说明要么缩短文案,要么在详情内部再套一个 `Scroll`,不要让它盖住按钮。
|
||||
|
||||
`hidden` 的两块是兄弟节点,同一时刻只有一块参与绘制与命中:未选中时提示可见,选中时详情内容可见。`hidden` 不显示、不交互,但元素与状态仍在,不会因为频繁切换选中而反复创建、销毁子树。
|
||||
|
||||
## ItemDetail:右侧面板
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
import { TextContent } from '@user/client-base';
|
||||
|
||||
interface ItemDetailProps extends DefaultProps {
|
||||
// 没有选中时是 null,组件必须允许空值
|
||||
item: Item | null;
|
||||
}
|
||||
|
||||
interface ItemDetailEmits {
|
||||
clear: () => void;
|
||||
}
|
||||
|
||||
const itemDetailProps = {
|
||||
props: ['item'],
|
||||
emits: ['clear']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemDetailProps,
|
||||
ItemDetailEmits,
|
||||
keyof ItemDetailEmits
|
||||
>;
|
||||
|
||||
const ItemDetail = defineComponent<
|
||||
ItemDetailProps,
|
||||
ItemDetailEmits,
|
||||
keyof ItemDetailEmits
|
||||
>((props, { emit }) => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 196, 280]}>
|
||||
<g-rect loc={[0, 0, 196, 280]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
|
||||
|
||||
{/* 没有选中:显示提示 */}
|
||||
<container hidden={props.item !== null}>
|
||||
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
|
||||
</container>
|
||||
|
||||
{/* 有选中:显示名称、数量与描述。两块都渲染,用 hidden 切换 */}
|
||||
<container hidden={props.item === null}>
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={props.item?.name ?? ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 84]}
|
||||
text={`数量:${props.item?.count ?? 0}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
{/* 长描述用 TextContent;width 必填,autoHeight 让高度跟着内容走 */}
|
||||
<TextContent
|
||||
loc={[16, 120]}
|
||||
width={164}
|
||||
text={props.item?.desc ?? ''}
|
||||
autoHeight
|
||||
fill
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
{/* 回到未选中:详情只上报,不自己改父级状态 */}
|
||||
<container loc={[16, 236, 164, 28]} onClick={() => emit('clear')}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 164, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
}, itemDetailProps);
|
||||
|
||||
export { ItemDetail };
|
||||
```
|
||||
|
||||
在渲染树上,`ItemDetail` 的根是右侧区域的整块容器,背景是第一个子节点,保证后面所有文字都画在背景之上;取消选择按钮是最后一个子节点,因此盖在其他内容之上,不会被描述文字挡住。按钮只发出 `clear` 事件,不碰 `selectedId`——选中状态归面板,详情没有写权限。
|
||||
|
||||
这里用 `hidden` 而不是三元,是因为选中切换很频繁,两块内容都很轻,保留元素后不需要反复创建与销毁。等读者真的需要「每次切换都重置」时,再换成三元。
|
||||
|
||||
## 选中态如何流到详情
|
||||
|
||||
面板把派生的 `selectedItem` 直接传给详情,详情不再查一遍列表:
|
||||
|
||||
```tsx
|
||||
// 面板的右侧区域:坐标与最终布局一致
|
||||
<container loc={[470, 100, 196, 280]}>
|
||||
<ItemDetail
|
||||
item={selectedItem.value}
|
||||
onClear={() => (selectedId.value = null)}
|
||||
/>
|
||||
</container>
|
||||
```
|
||||
|
||||
这条链与上一篇的点击上报是同一个方向的两端:
|
||||
|
||||
```text
|
||||
点击 ItemCell → ItemGrid → 面板写 selectedId
|
||||
→ selectedItem 重算 → ItemDetail 收到新的 item
|
||||
点击「取消选择」→ ItemDetail 发 clear → 面板把 selectedId 写回 null
|
||||
→ selectedItem 变成 null → 详情显示「请选择道具」
|
||||
```
|
||||
|
||||
详情不要在组件内部再 `items.find(...)`:那会让列表出现两份查询逻辑,一份用 `selectedId`,一份用内部状态,两边一旦不同步,就会出现「左侧高亮 A、右侧显示 B」。派生只做一次,放在持有源状态的面板里。
|
||||
|
||||
## 空态与边界
|
||||
|
||||
三种情况都要给出显示与恢复方式:
|
||||
|
||||
| 情况 | 详情显示 | 如何恢复 |
|
||||
| ------------ | -------------------------------------- | ------------------------------ |
|
||||
| 未选中 | 「请选择道具」 | 点任意格子,或初始状态就是空 |
|
||||
| 选中项被删除 | `find` 返回 `undefined`,收口成 `null` | 点其他格子;不要留着旧 id 高亮 |
|
||||
| `items` 为空 | 与未选中相同 | 先获得道具,再打开面板 |
|
||||
|
||||
未选中不是错误状态,而是面板的初始状态。示例(二)里 `selectedId` 的初始值是 `null`,所以第一次打开面板时右侧就显示提示;点击格子后才第一次出现详情。
|
||||
|
||||
「选中项被删除」要在面板层处理:删除道具时同时检查 `selectedId.value === 被删的 id`,如果是就把 `selectedId` 写回 `null`。只在详情里判空、不清理面板的 id,会让 `selectedId` 指向一个不存在的道具,之后任何按 id 比较的逻辑都会失效。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面的 live 选中不同格子,右侧详情随之更新;点「取消选择」可以看到没有选中时的提示。live 用元素层的 `text` 等价展示多行说明,正文代码块才给出 `TextContent` 的真实写法——两者不是同一段代码。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="detailLoader" :width="720" :height="480" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const detailLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/inventory-3-detail.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `computed` 里不要写副作用。它只负责算值,需要「变化后做一件事」时用 `watch`。
|
||||
- `find` 找不到时返回 `undefined`,用 `?? null` 收口;详情组件的 `item` 要允许为 `null`。
|
||||
- `TextContent` 的 `width` 必填。不给宽度时文字不会按预期折行,`autoHeight` 也失去意义。
|
||||
- 两块都渲染时注意 `zIndex` 与遮挡。提示层不要盖住真正的详情,也不要在有选中时仍然拦截点击。
|
||||
- 选中态放在父组件,详情只接收结果。子组件不要自己再存一份 `selectedId`,也不要在详情里重复查列表。
|
||||
@@ -0,0 +1,213 @@
|
||||
# 示例(四)滚动与列表
|
||||
|
||||
道具少的时候,网格一次就能排下。道具变多后,左侧区域放不下,需要滚动。本篇把示例(二)的普通网格换成 `Scroll`,并说明这次替换在渲染树、事件与数据流上各自改了什么。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [示例(三)详情区](./inventory-example-3-detail.md)
|
||||
- [内置组件:布局](./builtin-layout.md)
|
||||
|
||||
## 为什么要换滚动
|
||||
|
||||
普通容器只是按坐标把子元素画出来:区域外的格子照样绘制,超出的部分被窗口裁掉,但节点仍然在树上。道具只有十件时感觉不到问题;四十件时,左侧区域外的格子会越画越多,滚轮也没有任何反应。
|
||||
|
||||
`Scroll` 负责的是「视口」这一层:
|
||||
|
||||
- 它给内容一个固定大小的窗口,窗口外的行被隐藏(逻辑裁剪),不会继续绘制。
|
||||
- 它自己处理滚轮、拖动与右侧滚动条,不需要作者再写 `onWheel`。
|
||||
- 它按子元素的包围盒计算可滚动总长度,末尾用 `padEnd` 补一段空白。
|
||||
|
||||
代价是限制:`Scroll` 只检查它的**直接子元素**,所以内容不能先包一个大容器再放进去。一个把全部格子包住的 `ItemGrid` 根容器会让虚拟滚动退化成「一整块内容」,只能整体显示或整体隐藏。
|
||||
|
||||
组件本身不是节点(第 13 篇):`ItemGrid` 返回的是行数组,这些行会平铺成父级 `Scroll` 的直接子元素,而不是躲在组件内部;所以行容器能被 `Scroll` 直接读到,虚拟滚动成立。
|
||||
|
||||
**本步明确替换示例(二)的普通网格**:左侧最终方案是 `Scroll`,示例(五)(六)不会再回到普通网格或 `ListPage`。
|
||||
|
||||
## Scroll 在渲染树里的位置
|
||||
|
||||
替换后,左侧区域的树是这样:
|
||||
|
||||
```text
|
||||
container [54, 100, 400, 280] 左侧区域(坐标与最终布局一致)
|
||||
├─ g-rect 区背景
|
||||
├─ Scroll [0, 0, 372, 244] 视口:宽 372、高 244
|
||||
│ ├─ 行容器 [0, 0, 362, 66] 第 1 行,Scroll 的直接子元素
|
||||
│ │ ├─ ItemCell 第 1 个格子
|
||||
│ │ └─ ... 同一行其余 4 个
|
||||
│ ├─ 行容器 [0, 74, 362, 66] 第 2 行
|
||||
│ └─ ... 按 74 的行距继续
|
||||
├─ 按钮 [0, 252, 90, 28] 「回到顶部」
|
||||
└─ 按钮 [100, 252, 90, 28] 「滚到底部」
|
||||
```
|
||||
|
||||
`Scroll` 的根是左侧区域里的一个子容器,`loc` 的第三、四项就是视口大小。视口宽 372,左侧区域宽 400,右边留出的 28 像素是滚动条与内边距的位置;高度 244,下面从 252 开始放两个按钮,`244 < 252`,按钮不会被内容盖住。
|
||||
|
||||
滚动条是 `Scroll` 内部的一个 `custom` 节点,固定画在视口右侧、层级高于内容。作者不需要手动创建它,只需要把可点击的元素避开右侧滚动条区域。
|
||||
|
||||
未滚动时,`Scroll` 的内容容器从 `[0, 0]` 开始;滚动后,内容整体向上平移,但每个行容器在树上的 `loc` 不变。这就是为什么行坐标可以按「从内容顶部往下累计」来算:`0, 74, 148, ...`,而不用关心当前滚到了哪里。
|
||||
|
||||
`Scroll` 通过 `ref` 暴露两个方法:`scrollTo(y, time?)` 滚到指定位置,`getScrollLength()` 返回还能滚多长。`ref<ScrollExpose>()` 拿到的就是这个接口,只有在需要「回到顶部 / 滚到底部 / 滚到某一行」时才用它。
|
||||
|
||||
## 数据与选中态如何穿过滚动层
|
||||
|
||||
`Scroll` 只负责视口,不持有道具数据,也不持有选中状态:
|
||||
|
||||
- `items` 仍然是 `InventoryPanel` 里的 `ref<Item[]>`,由面板传给 `ItemGrid`。
|
||||
- `selectedId` 仍然是面板的 `ref<string | null>`,由 `ItemGrid` 继续按 id 比较。
|
||||
- `ItemGrid` 的 props 链不变:`items` / `selectedId` / `onSelect`(示例(五)再加 `equippedId`)。
|
||||
|
||||
唯一要改的是 `ItemGrid` 的根节点:示例(二)里它返回一个 `container`,现在改成返回「行容器数组」,让每一行直接成为 `Scroll` 的直接子元素。组件本身仍然是一个组件,只是它的子树从「一个容器」变成了「一组并列容器」:
|
||||
|
||||
```tsx
|
||||
// item-grid.tsx:根节点从单个 container 改成行容器数组
|
||||
const ItemGrid = defineComponent<
|
||||
ItemGridProps,
|
||||
ItemGridEmits,
|
||||
keyof ItemGridEmits
|
||||
>((props, { emit }) => {
|
||||
const columns = computed(() => props.columns ?? 5);
|
||||
const cellSize = computed(() => props.cellSize ?? 66);
|
||||
const gap = computed(() => props.gap ?? 8);
|
||||
|
||||
return () => {
|
||||
const pitch = cellSize.value + gap.value;
|
||||
const rowCount = Math.ceil(props.items.length / columns.value);
|
||||
const rows = [];
|
||||
|
||||
for (let row = 0; row < rowCount; row++) {
|
||||
const start = row * columns.value;
|
||||
const cells = props.items.slice(start, start + columns.value);
|
||||
|
||||
rows.push(
|
||||
// 一行是 Scroll 的一个直接子元素,行距由 loc 的 y 决定
|
||||
<container
|
||||
key={row}
|
||||
loc={[0, row * pitch, 362, cellSize.value]}
|
||||
>
|
||||
{cells.map((item, col) => (
|
||||
<container
|
||||
key={item.id}
|
||||
loc={[
|
||||
col * pitch,
|
||||
0,
|
||||
cellSize.value,
|
||||
cellSize.value
|
||||
]}
|
||||
>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === props.selectedId}
|
||||
size={cellSize.value}
|
||||
onSelect={id => emit('select', id)}
|
||||
/>
|
||||
</container>
|
||||
))}
|
||||
</container>
|
||||
);
|
||||
}
|
||||
|
||||
return rows;
|
||||
};
|
||||
}, itemGridProps);
|
||||
```
|
||||
|
||||
行容器的 `key` 用行号,是因为行本身没有业务身份,只表示「第几行」;行内的格子 `key` 仍然用 `item.id`,身份跟道具走。滚动时 `Scroll` 按行容器的包围盒决定整行显示还是隐藏,所以一行的高度必须包住这一行的格子,不能只给格子高度却让行容器用默认 200×200。
|
||||
|
||||
## 面板里怎么接
|
||||
|
||||
面板把 `ItemGrid` 放进 `Scroll`,其余状态不变:
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
import { Scroll, ScrollExpose } from '@user/client-base';
|
||||
|
||||
// 面板里:滚动容器只包住网格,选中态仍由面板持有
|
||||
const scroll = ref<ScrollExpose>();
|
||||
|
||||
// 回到顶部:scrollTo(目标位置, 动画时长)
|
||||
const backToTop = () => {
|
||||
scroll.value?.scrollTo(0, 200);
|
||||
};
|
||||
|
||||
// 滚到底部:先取总长度,再滚过去
|
||||
const toBottom = () => {
|
||||
scroll.value?.scrollTo(scroll.value.getScrollLength(), 200);
|
||||
};
|
||||
|
||||
<container loc={[54, 100, 400, 280]}>
|
||||
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
|
||||
|
||||
<Scroll ref={scroll} loc={[0, 0, 372, 244]} padEnd={16}>
|
||||
<ItemGrid
|
||||
items={items.value}
|
||||
selectedId={selectedId.value}
|
||||
columns={5}
|
||||
cellSize={66}
|
||||
gap={8}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</Scroll>
|
||||
|
||||
<container loc={[0, 252, 90, 28]} onClick={backToTop}>
|
||||
<g-rectr loc={[0, 0, 90, 28]} circle={[6]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[10, 6]} text="回到顶部" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[100, 252, 90, 28]} onClick={toBottom}>
|
||||
<g-rectr loc={[0, 0, 90, 28]} circle={[6]} fill fillStyle="#33465f" />
|
||||
<text loc={[10, 6]} text="滚到底部" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>;
|
||||
```
|
||||
|
||||
`padEnd` 给内容末尾多留 16 像素,避免最后一行贴着视口底边时滚动条位置看起来不对。`getScrollLength()` 返回的是「内容总长减视口高度」,也就是最大可滚动距离;直接把它交给 `scrollTo` 就滚到底。
|
||||
|
||||
单位补在这里:`scrollTo(y, time)` 的 `time` 是毫秒,默认 `0` 表示立即跳转;`padEnd` 是像素,追加在内容总长度之后。
|
||||
|
||||
滚动位置保存在 `Scroll` 组件自己的状态里。面板被真正卸载(关闭)后,组件销毁,下次打开回到顶部;如果只是用 `hide` 暂时隐藏实例,位置会保留。两种行为都是合理的,取决于你要「每次都从头看」还是「回到上次的位置」。
|
||||
|
||||
## 滚动与事件
|
||||
|
||||
滚轮不需要作者处理:`Scroll` 在根容器上监听 `onWheel`,把滚动量换算成目标位置,再带动画滚过去。子元素上的点击仍然按渲染树命中:先落到格子,再沿父链交给 `ItemGrid` 与面板。
|
||||
|
||||
滚动容器在捕获阶段会给事件坐标补上当前滚动偏移,所以格子拿到的是自己在内容里的局部坐标,不会因为「已经滚了 300 像素」而算错点击位置。这一点对拖动与点击都成立。
|
||||
|
||||
拖动内容与点击格子共用同一套按下 / 移动 / 抬起事件。`Scroll` 在按下时记录内容位置,移动超过阈值才视为拖动;没有移动的按下与抬起仍然是一次点击,会正常上报选中。作者的注意事项只有两条:
|
||||
|
||||
- 不要在内容上再套一层自己的滚动手势,两套手势会互相抢事件。
|
||||
- 可点击元素避开通往滚动条的右侧区域,滚动条本身会先接住那里的按下事件。
|
||||
|
||||
`noevent` 与 `actionStroke` 在这里都不是必需的:`Scroll` 已经处理了手势,格子按自身矩形命中即可。
|
||||
|
||||
## 为什么不用 ListPage 作为最终方案
|
||||
|
||||
`ListPage` 适合「左边一列文本、右边详情」的内置页面,它把左侧列表、选中 key 与关闭按钮都封装好了。但本系列的左侧是 5 列带选中态的网格,`ListPage` 的单列文本列表装不下这个结构;用它就得放弃网格,或者把网格塞进它的一行里,反而更绕。
|
||||
|
||||
所以最终方案只保留 `Scroll`。`ListPage` 与本篇的关系是「知道它存在、知道它不适用」,不是让读者在两个方案之间二选一。示例(五)(六)都沿本篇的 `Scroll` 继续。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面的 live 用 40 个假道具演示滚动效果:滚轮、右侧滚动条与「回到顶部 / 滚到底部」按钮都能用。live 用元素层等价画面实现滚动,正文代码块给出 `Scroll` 的真实写法;两者不是同一段代码。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="scrollLoader" :width="720" :height="480" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const scrollLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/inventory-4-scroll.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `Scroll` 里再包一层容器会让虚拟滚动失效。每一行都必须是 `Scroll` 的直接子元素。
|
||||
- 行容器的高度要包住整行格子;用默认 200×200 会让相邻行互相遮挡。
|
||||
- `padEnd` 按行高调整。最后一行底部过紧或滚动条偏长时,先检查它。
|
||||
- 滚动条占右侧一段宽度,可点击元素不要压到 `x = 372` 附近。
|
||||
- 一维长列表用 `Scroll`;左右分栏的文本列表才考虑 `ListPage`,固定页数才用 `Page`。不要用几十个隐藏容器模拟分页。
|
||||
@@ -0,0 +1,370 @@
|
||||
# 示例(五)交互与状态
|
||||
|
||||
网格、详情与滚动都齐了,但面板还只能看不能动。本篇加 `ActionBar`:装备、使用、关闭,并把状态与副作用收口到 `InventoryPanel`。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [示例(四)滚动与列表](./inventory-example-4-scroll.md)
|
||||
- [响应式](./reactivity.md)
|
||||
- [事件与交互](./events.md)
|
||||
|
||||
## 这一步把交互接起来
|
||||
|
||||
三类操作各自改变一件事:
|
||||
|
||||
| 操作 | 改变什么 | 状态归谁 |
|
||||
| ---- | ---------------------------- | ------------------------ |
|
||||
| 装备 | 记录「当前选中的道具已装备」 | 面板的 `equippedId` |
|
||||
| 使用 | 减少道具数量,刷新提示 | 面板的 `items` 与 `hint` |
|
||||
| 关闭 | 卸载当前面板实例 | 面板调用控制器的 `close` |
|
||||
|
||||
面板持有 `items`、`selectedId`、`equippedId` 与 `hint`;`ItemGrid`、`ItemCell`、`ItemDetail`、`ActionBar` 都只接收结果、上报动作。子组件不保存业务状态,也不直接操作控制器——那是面板的职责。
|
||||
|
||||
## 操作条的树与事件流
|
||||
|
||||
`ActionBar` 是底部区域里的一个容器,内部三个按钮是它的子节点:
|
||||
|
||||
```text
|
||||
container [54, 392, 304, 32] 底部区域(与左侧区域不重叠)
|
||||
└─ ActionBar
|
||||
└─ container [0, 0, 304, 32]
|
||||
├─ 按钮 [0, 0, 96, 32] 装备 / 已装备
|
||||
├─ 按钮 [104, 0, 96, 32] 使用
|
||||
└─ 按钮 [208, 0, 96, 32] 关闭
|
||||
```
|
||||
|
||||
事件从按钮出发,只向上走一层:
|
||||
|
||||
```tsx
|
||||
import { defineComponent } from 'vue';
|
||||
import { SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
|
||||
interface ActionBarProps extends DefaultProps {
|
||||
canEquip: boolean;
|
||||
canUse: boolean;
|
||||
equipped: boolean;
|
||||
}
|
||||
|
||||
interface ActionBarEmits {
|
||||
equip: () => void;
|
||||
use: () => void;
|
||||
close: () => void;
|
||||
}
|
||||
|
||||
const actionBarProps = {
|
||||
props: ['canEquip', 'canUse', 'equipped'],
|
||||
emits: ['equip', 'use', 'close']
|
||||
} satisfies SetupComponentOptions<
|
||||
ActionBarProps,
|
||||
ActionBarEmits,
|
||||
keyof ActionBarEmits
|
||||
>;
|
||||
|
||||
const ActionBar = defineComponent<
|
||||
ActionBarProps,
|
||||
ActionBarEmits,
|
||||
keyof ActionBarEmits
|
||||
>((props, { emit }) => {
|
||||
// 按钮禁用时只做视觉弱化,并在点击回调里早返回
|
||||
// 三个按钮共用 makeButton,装备、使用、关闭各自发出事件
|
||||
const makeButton = (
|
||||
x: number,
|
||||
label: string,
|
||||
enabled: boolean,
|
||||
onClick: () => void
|
||||
) => (
|
||||
<container
|
||||
loc={[x, 0, 96, 32]}
|
||||
onClick={() => {
|
||||
if (!enabled) return;
|
||||
onClick();
|
||||
}}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 96, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle={enabled ? '#2f6fed' : '#26364d'}
|
||||
alpha={enabled ? 1 : 0.5}
|
||||
/>
|
||||
<text loc={[12, 8]} text={label} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
|
||||
return () => (
|
||||
// 三个事件都交回父组件处理,操作条本身不决定装备或关闭
|
||||
<container loc={[0, 0, 304, 32]}>
|
||||
{makeButton(
|
||||
0,
|
||||
props.equipped ? '已装备' : '装备',
|
||||
props.canEquip,
|
||||
() => emit('equip')
|
||||
)}
|
||||
{makeButton(104, '使用', props.canUse, () => emit('use'))}
|
||||
{makeButton(208, '关闭', true, () => emit('close'))}
|
||||
</container>
|
||||
);
|
||||
}, actionBarProps);
|
||||
|
||||
export { ActionBar };
|
||||
```
|
||||
|
||||
`alpha` 只是把按钮画淡,真正的「不能用」由 `if (!enabled) return` 保证。不要用 `hidden` 把按钮藏起来当禁用——那样读者会以为按钮不存在。按钮上的点击先命中最上层的按钮容器,再由 `emit` 交给面板;`ActionBar` 没有 `stopPropagation` 的需求,因为按钮之外没有另一个处理同一事件的父级。
|
||||
|
||||
`equipped` 的含义是「**当前选中的道具是否已经装备**」,不是「面板里有没有装备」。所以面板传的是派生值 `isEquipped`,不是 `!!equippedId`;否则选中一把没装备的武器时,按钮会错误显示「已装备」。
|
||||
|
||||
## 状态放在 InventoryPanel
|
||||
|
||||
```tsx
|
||||
import { computed, ref, watch } from 'vue';
|
||||
|
||||
const items = ref<Item[]>([
|
||||
{ id: 'potion-red', name: '红药水', count: 3, desc: '恢复少量生命。' },
|
||||
{ id: 'potion-blue', name: '蓝药水', count: 1, desc: '恢复少量魔力。' }
|
||||
// 其余道具...
|
||||
]);
|
||||
|
||||
const selectedId = ref<string | null>(null);
|
||||
const equippedId = ref<string | null>(null);
|
||||
const hint = ref('选择道具后可以装备或使用');
|
||||
|
||||
// 选中项、可装备、可使用、是否已装备都是派生值
|
||||
const selectedItem = computed(
|
||||
() => items.value.find(item => item.id === selectedId.value) ?? null
|
||||
);
|
||||
const canEquip = computed(() => selectedItem.value !== null);
|
||||
const canUse = computed(
|
||||
() => selectedItem.value !== null && selectedItem.value.count > 0
|
||||
);
|
||||
const isEquipped = computed(
|
||||
() => selectedId.value !== null && equippedId.value === selectedId.value
|
||||
);
|
||||
|
||||
const equip = () => {
|
||||
if (selectedItem.value === null) return;
|
||||
equippedId.value = selectedItem.value.id;
|
||||
hint.value = `已装备:${selectedItem.value.name}`;
|
||||
};
|
||||
|
||||
// 数量减到 0 时,按钮通过 canUse 自动失效
|
||||
const use = () => {
|
||||
const item = selectedItem.value;
|
||||
if (item === null || item.count <= 0) return;
|
||||
item.count -= 1;
|
||||
};
|
||||
|
||||
// 数量变化是副作用:更新一行提示;「能不能用」是派生值,交给 computed
|
||||
watch(
|
||||
() => selectedItem.value?.count ?? 0,
|
||||
(next, prev) => {
|
||||
hint.value = `数量:${prev} → ${next}`;
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
`computed` 只负责算值,`watch` 只在需要「变化后做一件事」时使用。这里「能不能装备 / 使用」「是否已装备」都是派生值,用 `computed`;「数量变化时更新提示」是副作用,用 `watch`。不要在 `watch` 里再改回被监听的状态,否则会形成循环。
|
||||
|
||||
`items` 是 `ref<Item[]>`,内部对象也是响应式的,所以 `item.count -= 1` 会触发重渲染。不要用 `shallowRef` 装这组数据——那样改对象字段不会通知视图。
|
||||
|
||||
## 状态变化如何反映到画面
|
||||
|
||||
三条路径各自对应树上的一处:
|
||||
|
||||
```text
|
||||
装备 → equippedId 变 → isEquipped 变 → ItemGrid 的 equippedId 变
|
||||
→ 对应的 ItemCell 收到 equipped=true → 描边变绿
|
||||
使用 → items 里的 count 变 → ItemCell 的数量文本变
|
||||
→ canUse 重算 → ActionBar 的使用按钮变淡或恢复
|
||||
提示 → hint 变 → 面板底部 text 的 text 属性变
|
||||
```
|
||||
|
||||
不要直接改子组件内部状态来「假装」更新:`ItemCell` 没有内部状态,`ActionBar` 也没有;它们收到的 props 变了,画面自然变。反过来,如果在格子里存一份「已装备」并在点击时自己改,父组件切换装备后那份副本不会跟着变,就会出现两个格子同时显示已装备。
|
||||
|
||||
`watch` 的来源是 `selectedItem.value?.count`:切换选中时 `selectedItem` 换了对象,count 也可能变化,提示会跟着刷新。这是预期行为,不需要额外判断「是不是同一个道具」。如果只想在同一个道具数量变化时提示,把来源改成 `selectedId` 加 `count` 的组合,再在回调里判断 id 是否相同。
|
||||
|
||||
## 关闭的完整路径
|
||||
|
||||
关闭有三个入口,最终都走同一条路径:
|
||||
|
||||
```text
|
||||
标题栏关闭按钮 → 面板 close() ─┐
|
||||
ActionBar 的「关闭」→ emit('close') → 面板 onClose ─┤
|
||||
Esc / X(@common/exit)→ 面板 close() ─────────────┘
|
||||
↓
|
||||
props.controller.close(props.instance)
|
||||
↓
|
||||
控制器卸载实例,子树销毁
|
||||
```
|
||||
|
||||
面板里的关闭方法就是骨架篇写的那个:
|
||||
|
||||
```tsx
|
||||
const close = () => {
|
||||
props.controller.close(props.instance);
|
||||
};
|
||||
```
|
||||
|
||||
操作条只发出 `close` 事件,面板在组装处把它接到 `close`:
|
||||
|
||||
```tsx
|
||||
<ActionBar
|
||||
canEquip={canEquip.value}
|
||||
canUse={canUse.value}
|
||||
equipped={isEquipped.value}
|
||||
onEquip={equip}
|
||||
onUse={use}
|
||||
onClose={close}
|
||||
/>
|
||||
```
|
||||
|
||||
**不要**把 `onClose` 写成只改一行提示。那样按钮看起来在,面板却不会退出,读者会以为关闭功能坏了。子组件也不直接调用 `controller.close`:它拿不到「自己是哪个实例」,硬写会把关闭逻辑复制到每个子组件。
|
||||
|
||||
如果以后要做「关闭前确认」,确认框走 UI 栈:面板先打开一个确认 UI,确认后再调用 `close`。不要在面板里手写一个遮罩 + 两个按钮的临时弹窗,那会绕开栈的顺序、背景与按键作用域。
|
||||
|
||||
## 已装备的格子:三处一起改
|
||||
|
||||
给格子加装备态时,接口、`props` 数组、渲染三处必须同时改。只加接口字段,`props.equipped` 会永远是 `undefined`:
|
||||
|
||||
```tsx
|
||||
interface ItemCellProps extends DefaultProps {
|
||||
item: Item;
|
||||
selected?: boolean;
|
||||
equipped?: boolean;
|
||||
size?: number;
|
||||
}
|
||||
|
||||
const itemCellProps = {
|
||||
// equipped 必须出现在 props 数组里,否则父级传了也收不到
|
||||
props: ['item', 'selected', 'equipped', 'size'],
|
||||
emits: ['select']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>;
|
||||
|
||||
// 描边优先级:已装备 > 选中 > 普通
|
||||
<g-rectr
|
||||
loc={[1, 1, size - 2, size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={
|
||||
props.equipped ? '#7ee787' : props.selected ? '#f2b84b' : '#33465f'
|
||||
}
|
||||
/>;
|
||||
```
|
||||
|
||||
`ItemGrid` 也要同步加一个 `equippedId`,并把它换算成每个格子的布尔值:
|
||||
|
||||
```tsx
|
||||
interface ItemGridProps extends DefaultProps {
|
||||
items: Item[];
|
||||
selectedId: string | null;
|
||||
equippedId: string | null;
|
||||
columns?: number;
|
||||
cellSize?: number;
|
||||
gap?: number;
|
||||
}
|
||||
|
||||
const itemGridProps = {
|
||||
props: ['items', 'selectedId', 'equippedId', 'columns', 'cellSize', 'gap'],
|
||||
emits: ['select']
|
||||
} satisfies SetupComponentOptions<
|
||||
ItemGridProps,
|
||||
ItemGridEmits,
|
||||
keyof ItemGridEmits
|
||||
>;
|
||||
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === props.selectedId}
|
||||
equipped={item.id === props.equippedId}
|
||||
size={cellSize.value}
|
||||
onSelect={id => emit('select', id)}
|
||||
/>;
|
||||
```
|
||||
|
||||
`equippedId` 是单个 id,不是每格一份布尔值;网格按 id 比较后把结果传给格子。这样装备切换时只有相关格子重渲染,也不需要维护第二份状态。
|
||||
|
||||
## 键盘收口
|
||||
|
||||
按键只在组件的 `setup` 里接一次,组件卸载时作用域自动离开:
|
||||
|
||||
```tsx
|
||||
// 按键只在 setup 里接一次,组件卸载时作用域自动离开
|
||||
import { useKey } from '@user/client-base';
|
||||
|
||||
const key = useKey(props.state.hotkey.system)!;
|
||||
|
||||
key.implement('@common/exit', () => {
|
||||
props.controller.close(props.instance);
|
||||
});
|
||||
```
|
||||
|
||||
`useKey` 必须在 `setup` 中调用,不能放进事件回调。`@common/exit` 默认对应 Esc / X,玩家可以在设置界面改键。按键与按钮走同一条关闭路径:都是面板调用 `props.controller.close(props.instance)`,不存在「按 Esc 只关一半」的分叉。
|
||||
|
||||
文档站没有游戏的按键系统,下面的 live 用关闭按钮代替,按键写法以代码块为准。
|
||||
|
||||
## 遮罩与 noevent
|
||||
|
||||
面板背后常常要压一层遮罩,让下面的画面变暗,但又不挡住点击。给遮罩加 `noevent`:
|
||||
|
||||
```tsx
|
||||
{
|
||||
/* 可见但不接收交互,事件会下穿到后面的元素 */
|
||||
}
|
||||
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#000000" alpha={0.35} noevent />;
|
||||
```
|
||||
|
||||
遮罩放在根容器的第一个子节点、面板主体之前:它在树上先绘制,所以面板会盖在它上面;`zIndex` 不需要额外设置。`noevent` 与 `hidden` 是两件事:`hidden` 连绘制一起跳过,元素不显示也不交互;`noevent` 仍然绘制,只是不参与命中。要压暗画面又不想拦截点击时用 `noevent`。
|
||||
|
||||
## 组装
|
||||
|
||||
把操作条放到底部,状态与回调从根组件传入:
|
||||
|
||||
```tsx
|
||||
// 状态与回调都从根组件传入,子组件不持有业务状态
|
||||
<container loc={[54, 392, 304, 32]}>
|
||||
<ActionBar
|
||||
canEquip={canEquip.value}
|
||||
canUse={canUse.value}
|
||||
equipped={isEquipped.value}
|
||||
onEquip={equip}
|
||||
onUse={use}
|
||||
onClose={close}
|
||||
/>
|
||||
</container>
|
||||
<text loc={[54, 432]} text={hint.value} fillStyle="#8fb6ff" />;
|
||||
```
|
||||
|
||||
操作条与提示都在左侧区域下边界 `380` 之下:操作条 `392` 到 `424`,提示在 `432`,不压住网格,也不超出面板底边 `450`。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面的 live 可以装备、使用与关闭:点格子选中道具,再点底部按钮。使用后数量会减一,数量为 0 时按钮变淡且点击不再生效。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="stateLoader" :width="720" :height="480" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const stateLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/inventory-5-state.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 不要在 `watch` 里改同一个状态造成循环。回调只更新提示这类外部结果。
|
||||
- 按钮禁用只是视觉弱化加早返回。不要用 `hidden` 把按钮藏起来当禁用。
|
||||
- `useKey` 只在 `setup` 里调用。组件卸载后作用域会自动离开,不需要手动清理。
|
||||
- 遮罩层注意 `zIndex`。遮罩要盖在画面之上、面板之下,并且用 `noevent` 放行点击。
|
||||
- 装备状态只保存 id,不要在每个格子里各存一份;接口、`props` 数组、渲染三处要一起改。
|
||||
- 操作条的 `equipped` 是「当前选中是否已装备」,不是「面板里有没有装备」。
|
||||
@@ -0,0 +1,278 @@
|
||||
# 示例(六)动画、拆分与注册
|
||||
|
||||
前面五步已经把网格、详情、滚动与交互拼起来了。最后一步补三件事:让选中态与提示动起来、把代码落回五个文件、把面板注册成 `GameUI` 并从打开处接入。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [示例(五)交互与状态](./inventory-example-5-state.md)
|
||||
- [自定义组件](./custom-components.md)
|
||||
- [UI 系统](./ui-system.md)
|
||||
|
||||
## 最后一步要收什么
|
||||
|
||||
收尾不是「再加一个功能」,而是把前面五步已经写下的东西固定下来:
|
||||
|
||||
```text
|
||||
src/client/ui/
|
||||
├─ inventory/
|
||||
│ ├─ inventory-panel.tsx InventoryPanel:根容器、标题、关闭、共享状态
|
||||
│ ├─ item-grid.tsx ItemGrid:行容器数组、行列计算、选中/装备比较
|
||||
│ ├─ item-cell.tsx ItemCell:单个格子的背景、名称、数量与描边
|
||||
│ ├─ item-detail.tsx ItemDetail:详情、描述与未选中提示
|
||||
│ └─ action-bar.tsx ActionBar:装备 / 使用 / 关闭按钮
|
||||
└─ index.ts 导出 InventoryUI,供打开处引用
|
||||
```
|
||||
|
||||
每个文件的职责在示例(一)就定好了,这里只是把它们落到真实路径。下面依次说明动画挂在哪、最终组装怎么核对、注册与打开怎么写、以及一份可以逐项验证的清单。
|
||||
|
||||
## 动画作用在树的哪一层
|
||||
|
||||
动画只驱动响应式值,不重建组件。本篇只做两处:
|
||||
|
||||
- **面板呼吸描边**:面板主体之后加一个同样大小的描边矩形,只改它的 `alpha`。
|
||||
- **提示淡出**:底部提示文字只改 `alpha`,文字内容仍由 `hint` 决定。
|
||||
|
||||
```tsx
|
||||
import { onMounted, onUnmounted, ref, watch } from 'vue';
|
||||
|
||||
const pulse = ref(0.4);
|
||||
const hintAlpha = ref(1);
|
||||
// 上一次提示变化的时间,用来算淡出进度
|
||||
let lastHintAt = 0;
|
||||
let raf = 0;
|
||||
|
||||
const tick = (now: number) => {
|
||||
// 0~1 之间来回变化,只驱动描边的 alpha
|
||||
const phase = (now % 1600) / 1600;
|
||||
pulse.value = 0.35 + Math.sin(phase * Math.PI * 2) * 0.3;
|
||||
|
||||
// 提示变化后 1.2 秒内淡到 0.4,之后保持
|
||||
const since = now - lastHintAt;
|
||||
hintAlpha.value = since < 1200 ? 1 - (since / 1200) * 0.6 : 0.4;
|
||||
|
||||
raf = requestAnimationFrame(tick);
|
||||
};
|
||||
|
||||
// 提示一变就重新计时,动画不参与提示内容的计算
|
||||
watch(hint, () => {
|
||||
lastHintAt = performance.now();
|
||||
hintAlpha.value = 1;
|
||||
});
|
||||
|
||||
onMounted(() => {
|
||||
raf = requestAnimationFrame(tick);
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
// 组件卸载后必须停掉,否则回调会继续访问已销毁的组件
|
||||
cancelAnimationFrame(raf);
|
||||
});
|
||||
```
|
||||
|
||||
两个动画节点都挂在面板根容器下:
|
||||
|
||||
```tsx
|
||||
{
|
||||
/* 呼吸描边:只改 alpha,不重建组件;noevent 不拦截点击 */
|
||||
}
|
||||
<g-rectr
|
||||
loc={[30, 30, 660, 420]}
|
||||
circle={[18]}
|
||||
stroke
|
||||
strokeStyle="#f2b84b"
|
||||
alpha={pulse.value * 0.6}
|
||||
noevent
|
||||
/>;
|
||||
|
||||
{
|
||||
/* 提示:内容来自 hint,只有透明度在动 */
|
||||
}
|
||||
<text
|
||||
loc={[54, 432]}
|
||||
text={hint.value}
|
||||
fillStyle="#8fb6ff"
|
||||
alpha={hintAlpha.value}
|
||||
/>;
|
||||
```
|
||||
|
||||
描边与提示都是面板的兄弟节点,不进入 `ItemGrid` 或 `ItemDetail` 的 props 链,所以动画不会改变数据流:`items` 仍由面板持有,`selectedId` 仍由点击驱动,格子的描边仍由 `selected` / `equipped` 决定。`noevent` 让描边只负责好看,不参与命中;不加它,整块面板的点击都会被这层描边接走。
|
||||
|
||||
`pulse` 每帧只写一个数字,元素属性跟着变;组件本身不会重新创建。停止动画放在 `onUnmounted`,否则页面切走后回调仍在跑。仓库里另有 `transitioned` / `transitionedColor` 渐变工具,返回值是 `ITransitionedController<...> | null`,使用前必须判空;本篇不依赖它,避免把可空值带进每一帧。
|
||||
|
||||
## 最终组装与契约核对
|
||||
|
||||
六篇共用的系列契约逐条对照最终代码:
|
||||
|
||||
| 契约 | 内容 | 最终写法 |
|
||||
| ---- | ------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| 1 | `items` 的形态 | `InventoryPanel` 里 `const items = ref<Item[]>(...)`;子组件收 `items.value`,派生用 `computed` |
|
||||
| 2 | `Item` 来源 | 只在示例(二)定义一次,后续文件 `import` 同一份类型 |
|
||||
| 3 | `selectedId` 空值 | `ref<string \| null>(null)`;未选中显示「请选择道具」;「取消选择」写回 `null` |
|
||||
| 4 | 关闭归属 | 面板调用 `props.controller.close(props.instance)`;子组件只 `emit('close')` |
|
||||
| 5 | 左侧最终方案 | `Scroll`;示例(二)的普通网格是阶段性实现,示例(四)已替换 |
|
||||
| 6 | 布局坐标(layout) | 左侧 `[54, 100, 400, 280]`、右侧 `[470, 100, 196, 280]`、操作条 `[54, 392, 304, 32]` |
|
||||
| 7 | 组件拆分与 props 链 | `InventoryPanel → ItemGrid → ItemCell`;`ItemDetail` 与 `ActionBar` 平级接收结果 |
|
||||
| 8 | key | 格子 `key={item.id}`;行容器 `key={row}`,因为行只表示位置 |
|
||||
| 9 | 事件流 | `ItemCell → ItemGrid → InventoryPanel`;操作条 `emit` 后由面板决定动作 |
|
||||
|
||||
最终组装的骨架(省略内部细节):
|
||||
|
||||
```tsx
|
||||
<container loc={[0, 0, 720, 480]}>
|
||||
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
|
||||
<g-rect
|
||||
loc={[0, 0, 720, 480]}
|
||||
fill
|
||||
fillStyle="#000000"
|
||||
alpha={0.35}
|
||||
noevent
|
||||
/>
|
||||
|
||||
<container loc={[0, 0, 720, 480]}>
|
||||
<g-rectr
|
||||
loc={[30, 30, 660, 420]}
|
||||
circle={[18]}
|
||||
fill
|
||||
fillStyle="#1d2b45"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[30, 30, 660, 420]}
|
||||
circle={[18]}
|
||||
stroke
|
||||
strokeStyle="#f2b84b"
|
||||
alpha={pulse.value * 0.6}
|
||||
noevent
|
||||
/>
|
||||
|
||||
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
|
||||
<container loc={[626, 50, 56, 32]} onClick={close}>
|
||||
…
|
||||
</container>
|
||||
|
||||
<container loc={[54, 100, 400, 280]}>
|
||||
<Scroll ref={scroll} loc={[0, 0, 372, 244]} padEnd={16}>
|
||||
<ItemGrid
|
||||
items={items.value}
|
||||
selectedId={selectedId.value}
|
||||
equippedId={equippedId.value}
|
||||
columns={5}
|
||||
cellSize={66}
|
||||
gap={8}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</Scroll>
|
||||
</container>
|
||||
|
||||
<container loc={[470, 100, 196, 280]}>
|
||||
<ItemDetail
|
||||
item={selectedItem.value}
|
||||
onClear={() => (selectedId.value = null)}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[54, 392, 304, 32]}>
|
||||
<ActionBar
|
||||
canEquip={canEquip.value}
|
||||
canUse={canUse.value}
|
||||
equipped={isEquipped.value}
|
||||
onEquip={equip}
|
||||
onUse={use}
|
||||
onClose={close}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[54, 432]}
|
||||
text={hint.value}
|
||||
fillStyle="#8fb6ff"
|
||||
alpha={hintAlpha.value}
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
```
|
||||
|
||||
如果前面某一页的写法与本表冲突,以本表为准:左侧只有 `Scroll` 一个方案,`selectedId` 只有 `null` 一种空值,关闭只有面板一个入口。前面页面已经写过的坐标若与这里不同,按这里替换;本篇不再给第二个方案。
|
||||
|
||||
本表与最终骨架里的坐标都相对 720×480 根容器:面板主体矩形自己画在 `[30, 30, 660, 420]`,标题 `[54, 52]` 直接相对根容器,不要再套一层 `[30, 30]` 的容器;否则标题会被再加一次偏移。
|
||||
|
||||
最终骨架里那层同尺寸的 `container [0, 0, 720, 480]` 是面板根:外层是画布根,里层是面板根(实际代码用 `hidden` 控制开合)。新内容加到面板根这一层,不要加到画布根上;两层的 `loc` 相同,所以坐标写法不变,但层级职责分开。
|
||||
|
||||
## 注册与打开
|
||||
|
||||
`InventoryPanel` 与 `GameUI` 在同一个文件里导出:
|
||||
|
||||
```tsx
|
||||
// inventory-panel.tsx:把名字与组件绑成一个对象
|
||||
import { GameUI } from '@motajs/system';
|
||||
|
||||
export const InventoryUI = new GameUI('inventory-panel', InventoryPanel);
|
||||
```
|
||||
|
||||
`src/client/ui/index.ts` 再统一导出,打开处只认这个对象:
|
||||
|
||||
```ts
|
||||
// src/client/ui/index.ts
|
||||
export { InventoryUI } from './inventory/inventory-panel';
|
||||
```
|
||||
|
||||
打开时把对象交给控制器,返回值就是这次打开的实例:
|
||||
|
||||
```tsx
|
||||
// 从主 UI 栈打开
|
||||
const instance = props.state.mainUIController.open(InventoryUI, {});
|
||||
|
||||
// 关闭时把同一个实例交回去(面板内部用 props.instance 拿到它)
|
||||
props.state.mainUIController.close(instance);
|
||||
```
|
||||
|
||||
打开时传的是 `GameUI` 对象本身,名字不参与查找;构造与命名的规则见[第 1 篇「UI 通用模板」](../basics/ui-template.md#gameui-是一个对象不是名字)。
|
||||
|
||||
关闭当前面板、马上打开另一个面板时,用 `props.controller.keep()` 包住切换,用完调用 `safelyUnload()`,避免背景闪一下;用法见[「UI 系统」的「keep」](./ui-system.md#keep)。
|
||||
|
||||
## 最终验证清单
|
||||
|
||||
按下面的顺序点一遍,每一项都对应一条事件路径或一处树位置:
|
||||
|
||||
| 验证项 | 操作 | 预期 | 对应路径 |
|
||||
| -------- | ----------------------- | ---------------------------------------- | ---------------------------------------------- |
|
||||
| 打开 | 从主 UI 栈 `open` | 720×480 面板出现,右侧显示「请选择道具」 | 控制器创建实例 → `props` 注入 → 根容器挂载 |
|
||||
| 选中 | 点一个格子 | 格子高亮,右侧显示名称、数量、描述 | `ItemCell → ItemGrid → InventoryPanel` |
|
||||
| 取消选择 | 点详情底部「取消选择」 | 高亮消失,右侧回到「请选择道具」 | `ItemDetail` 发 `clear` → 面板写 `null` |
|
||||
| 滚动 | 滚轮 / 滚动条 / 按钮 | 行整体上下移动,滚动条位置同步 | `Scroll` 内部处理,格子坐标不变 |
|
||||
| 装备 | 选中后点「装备」 | 按钮变「已装备」,该格子描边变绿 | `ActionBar` 发 `equip` → 面板写 `equippedId` |
|
||||
| 使用 | 点「使用」 | 数量减一,提示刷新,数量为 0 时按钮变淡 | `ActionBar` 发 `use` → 面板改 `items` / `hint` |
|
||||
| 关闭 | 点标题栏关闭 / 底部关闭 | 面板卸载,背景恢复 | 面板 `close()` → `controller.close(instance)` |
|
||||
| 再次打开 | 再 `open` 一次 | 回到初始状态:未选中、滚动在顶部 | 新实例 → 新状态 |
|
||||
|
||||
关闭后动画必须停:如果 `cancelAnimationFrame` 漏了,再次打开会看到两个循环同时在改 `pulse`,边框呼吸会变得忽快忽慢。这也是清单里「再次打开」要单独验证的原因。
|
||||
|
||||
清单里的「再次打开」按 `close` 写:`close` 会卸载实例,再 `open` 得到新实例,所以未选中、滚动在顶部。如果你改用 `hide` 隐藏面板,实例与滚动位置都会保留,这一行的预期要相应改成「回到隐藏前的位置」;两种语义的区别见[第 7 篇「显示开关」](../basics/layer-transform-performance.md)与[「UI 系统」的「隐藏与显示」](./ui-system.md#隐藏与显示)。
|
||||
|
||||
## 运行效果
|
||||
|
||||
下面是完整面板的 live:网格、详情、滚动、装备 / 使用、关闭与动画都在。关闭后可以用「重新打开」按钮回到面板。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="fullLoader" :width="720" :height="480" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const fullLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/inventory-6-full.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 动画在卸载后必须停。`onUnmounted` 里调用 `cancelAnimationFrame`,不要只停一次。
|
||||
- 动画节点不要进入子组件的 props 链。只改面板自己节点的 `alpha`,数据流保持单向。
|
||||
- 拆分后 Props 要逐层传。不要用全局变量绕过父子关系,否则读者无法从文件结构看出数据流。
|
||||
- 注册只是把名字和组件绑成一个对象,不写入名字查找表。不要按名字取 UI,也不要做全局注册表。
|
||||
- 最终 live 如果跑不起来,保留代码与说明,不要删内容;先确认真实客户端环境与依赖是否齐全。
|
||||
- 性能建议先测再改。`hidden`、`Scroll`、`key` 与组件粒度是四条固定口径,不要为了「看起来更快」额外加缓存。
|
||||
@@ -0,0 +1,303 @@
|
||||
# 响应式
|
||||
|
||||
前面几篇的元素都是静态的:写死坐标、写死颜色。真实界面要跟着数据变,比如点一下按钮让计数加一、输入内容后让文字更新。如果每次都手写「改完数据再手动重画」,迟早会漏掉某处更新。
|
||||
|
||||
Vue 的响应式解决的就是这件事:数据被读取时记下依赖,数据变化时自动重新执行用到它的渲染函数,渲染器再把变化 patch 到画布上的元素。本篇从零讲清 UI 作者需要的那部分,不假设你写过 Vue。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [UI 入门](../basics/ui-basics.md)
|
||||
- [第一个静态界面](../basics/first-static-ui.md)
|
||||
|
||||
## 数据到渲染
|
||||
|
||||
响应式值变化后,读取过它的组件会重新执行渲染函数,对应元素的属性或子组件随之更新;没有读取它的组件不会因为这次变化而更新。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[响应式值变化] --> B[读取过它的组件<br/>重新执行渲染函数]
|
||||
B --> C[元素属性 / 子组件更新]
|
||||
```
|
||||
|
||||
示例里的 `onClick` 是交互事件,后面[事件与交互](./events.md)会专门讲;这里只把它当作改变数据的方式。
|
||||
|
||||
```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 => {
|
||||
const count = ref(0);
|
||||
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
{/* 点击只改数据,界面由响应式自动更新 */}
|
||||
<g-rect
|
||||
loc={[40, 40, 160, 48]}
|
||||
fillStyle="#2f6fed"
|
||||
onClick={() => count.value++}
|
||||
/>
|
||||
{/* 渲染函数里读 count.value,Vue 才能记录这处依赖 */}
|
||||
<text
|
||||
loc={[40, 110]}
|
||||
text={`点击次数:${count.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="counterLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
点击按钮只改 `count.value`,下方文字会跟着更新。
|
||||
|
||||
## ref:带 value 的盒子
|
||||
|
||||
`ref` 把普通值包成一个响应式对象。读和写都要经过 `.value`:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const count = ref(0);
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect
|
||||
loc={[40, 40, 160, 48]}
|
||||
fillStyle="#2f6fed"
|
||||
onClick={() => count.value++}
|
||||
/>
|
||||
<text
|
||||
loc={[40, 110]}
|
||||
text={`点击次数:${count.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
</container>;
|
||||
```
|
||||
|
||||
在 TSX 的渲染函数里也要写 `count.value`。原因是 JSX 不是模板:模板里 Vue 会自动帮你解包 `ref`,TSX 里不会。`ref` 本质上是一个带 `value` 属性的盒子,Vue 通过「你读了哪个盒子的 `value`」来记录依赖。
|
||||
|
||||
只写 `count` 而不写 `.value`,读到的就是盒子本身,渲染出来的文字会变成 `[object Object]`,点击也不会触发更新。这是最常见的错误。
|
||||
|
||||
`ref` 也可以包对象。包对象时,`.value` 指向的还是响应式代理,改内部字段同样会触发更新:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const panel = ref({ open: true, title: '背包' });
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<text
|
||||
loc={[40, 40]}
|
||||
text={panel.value.title}
|
||||
fillStyle="#ffffff"
|
||||
onClick={() => {
|
||||
// 改的是响应式代理上的字段,依赖仍然有效
|
||||
panel.value.open = !panel.value.open;
|
||||
panel.value.title = panel.value.open ? '背包' : '道具';
|
||||
}}
|
||||
/>
|
||||
</container>;
|
||||
```
|
||||
|
||||
## reactive:一整块对象
|
||||
|
||||
`reactive` 适合把一组相关的字段放在一起:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const panel = reactive({
|
||||
open: true,
|
||||
title: '背包'
|
||||
});
|
||||
|
||||
// 组件内容
|
||||
<text text={panel.title} fillStyle="#ffffff" />;
|
||||
```
|
||||
|
||||
`reactive` 返回的是代理对象,读写字段时不需要 `.value`。但它有两条限制:
|
||||
|
||||
1. 不能整体替换。`panel = reactive({ ... })` 会让变量指向新对象,旧依赖还挂在旧对象上;应改为逐字段赋值,或改用 `ref` 保存整个对象。
|
||||
2. 解构会丢响应式。`const { open } = panel` 取到的是当时的普通值,后续 `panel.open` 变化不会同步过去;应直接写 `panel.open`,或改用 `toRefs`。
|
||||
|
||||
```tsx
|
||||
// 逐字段修改,原有依赖仍然挂在同一个代理对象上
|
||||
// 正确:逐字段修改
|
||||
panel.open = false;
|
||||
panel.title = '道具';
|
||||
|
||||
// 错误:整体替换,原依赖失联
|
||||
// panel = reactive({ open: false, title: '道具' });
|
||||
```
|
||||
|
||||
`reactive` 创建在哪里也很重要。创建在组件 `setup` 内,每个组件实例各有一份;创建在模块顶层,所有实例共用同一份。界面状态通常应放在 `setup` 内,只有确实要全局共享的数据才放到模块顶层。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="reactiveLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
点击切换后,`open` 与 `title` 两个字段会同时更新。
|
||||
|
||||
## computed:派生值
|
||||
|
||||
`computed` 从别的响应式数据算出一个新值:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const count = ref(0);
|
||||
const doubled = computed(() => count.value * 2);
|
||||
```
|
||||
|
||||
它有两个特点:
|
||||
|
||||
- 惰性求值:第一次被读取时才计算。
|
||||
- 会缓存:依赖没变时重复读取直接返回上次结果,不会重复计算。
|
||||
|
||||
在 TSX 里读 `computed` 同样要写 `.value`:
|
||||
|
||||
```tsx
|
||||
// 组件内容
|
||||
<text text={`两倍:${doubled.value}`} fillStyle="#f2b84b" />
|
||||
```
|
||||
|
||||
不要往 `computed` 里写副作用。它只负责算值;需要「变化时做一件事」时用 `watch`。也不要在 `computed` 里改别的响应式数据,那会让「读一个值」变成「改一个值」,依赖关系难以推理。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="computedLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
按钮只改 `count`,`doubled` 由它算出,不需要另外维护。
|
||||
|
||||
## 重渲染的触发条件
|
||||
|
||||
判断依据只有一条:**这个变化是否碰到渲染函数读过的响应式值**。
|
||||
|
||||
会触发重渲染的情况:
|
||||
|
||||
- 渲染函数里读了 `count.value`,事件回调里改 `count.value`。
|
||||
- 渲染函数里读了 `panel.title`,别处改了 `panel.title`。
|
||||
- 渲染函数里读了 `list.value`,对 `list.value` 做 `push` / `splice` / 整体替换。
|
||||
- 渲染函数里读了 `doubled.value`,而 `doubled` 依赖的 `count` 变了。
|
||||
|
||||
不会触发重渲染的情况:
|
||||
|
||||
- 改的是普通对象或普通数组,它们没有被 `ref` / `reactive` 包过。
|
||||
- 改了响应式对象的副本,比如先 `const copy = list.value` 再替换 `copy` 变量本身。
|
||||
- 只在事件回调里读、渲染函数里没读过的值变化了。
|
||||
- 用了 `shallowRef`,只改内部字段而没有替换 `.value`。
|
||||
|
||||
Vue 会把这些更新合并到微任务里排队执行。同一个事件回调里连续改三次,通常只重渲染一次;`await` 之后、或下一次用户操作时,才会进入下一轮。需要等画面更新后再做后续动作时,用 `nextTick`:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const count = ref(0);
|
||||
const message = ref('');
|
||||
|
||||
const addThree = async () => {
|
||||
count.value++;
|
||||
count.value++;
|
||||
count.value++;
|
||||
// 三次修改在同一轮里合并,nextTick 后渲染已经完成
|
||||
await nextTick();
|
||||
message.value = `现在是 ${count.value}`;
|
||||
};
|
||||
|
||||
// 组件内容
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={[40, 40, 160, 48]} fillStyle="#2f6fed" onClick={addThree} />
|
||||
<text loc={[40, 110]} text={message.value} fillStyle="#ffffff" />
|
||||
</container>;
|
||||
```
|
||||
|
||||
`nextTick` 只保证「这一轮更新已经处理完」,不保证画布已经绘制到屏幕上。需要等浏览器真正绘制时,再配合一帧的回调。
|
||||
|
||||
## watch:副作用
|
||||
|
||||
`watch` 监听一个响应式数据,在它变化后执行回调:
|
||||
|
||||
```tsx
|
||||
// setup
|
||||
const count = ref(0);
|
||||
const log = ref('还没有变化');
|
||||
|
||||
watch(count, (next, prev) => {
|
||||
log.value = `count:${prev} → ${next}`;
|
||||
});
|
||||
|
||||
// 组件内容
|
||||
<text text={log.value} fillStyle="#ffffff" />;
|
||||
```
|
||||
|
||||
回调拿到新值与旧值。适合用来打印日志、同步到外部、触发一次性的动作。
|
||||
|
||||
在组件 `setup` 里创建的 `watch` 会绑定到当前组件,组件卸载时自动停止,不需要手动保存停止函数。只有在组件外创建的 `watch` 才需要自己调用返回的停止函数。
|
||||
|
||||
选择原则很简单:只是「根据现有数据算出要显示的内容」,用 `computed`;需要在变化后「做一件事」,用 `watch`。能用 `computed` 表达时不要用 `watch` 再手动赋值,那样多了一份需要维护的状态。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="watchLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
按钮改变 `count` 后,`watch` 把新旧值写进 `log`。
|
||||
|
||||
## shallowRef 与 markRaw 的适用场景
|
||||
|
||||
这两个是优化手段,判断依据只有两条:
|
||||
|
||||
- 大对象、只需要整体替换、不需要深层字段响应式时,用 `shallowRef`。它只追踪 `.value` 的替换,不追踪内部字段。
|
||||
- 外部实例(例如第三方库创建的对象、画布对象、纹理对象)不需要被 Vue 代理时,用 `markRaw` 标记,避免深层代理带来的开销与意外行为。
|
||||
|
||||
纹理与外部对象尤其值得注意:把纹理放进普通 `ref` 会被深层代理,读它时多一层代理开销;用 `markRaw(texture)` 后再放进状态,Vue 就不会继续代理它。只想整体替换纹理时,`shallowRef` 更合适。
|
||||
|
||||
不确定是否需要时,先用 `ref` 与 `reactive`。等确认大对象带来性能问题,再换成 `shallowRef` 或 `markRaw`。
|
||||
|
||||
## props 与解构
|
||||
|
||||
组件收到的 `props` 本身是响应式的。把字段解构出来会得到普通值,父组件更新后子组件不会跟着变;直接读 `props.title`,或在 render 函数里现取局部变量。props 的基本写法见[自定义组件](./custom-components.md#props)。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const counterLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/reactivity-counter-demo.tsx');
|
||||
const reactiveLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/reactivity-reactive-demo.tsx');
|
||||
const computedLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/reactivity-computed-demo.tsx');
|
||||
const watchLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/reactivity-watch-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `reactive` 不能整体替换。要换整块数据时,用 `ref` 保存对象,或逐字段赋值。
|
||||
- 解构 `reactive` 对象或 `props` 会丢响应式。直接读字段,必要时用 `toRefs`。
|
||||
- `ref` 忘记写 `.value` 是最常见的错误:读不到值,也触发不了更新。
|
||||
- 不要在渲染函数里做副作用。渲染函数只负责根据当前状态算出画面;副作用放进事件回调或 `watch`。
|
||||
@@ -0,0 +1,142 @@
|
||||
# UI 性能
|
||||
|
||||
多数简单 UI 不需要特别的性能优化。渲染系统会按需更新,缓存也默认开在合适的元素上;按常规方式写,性能通常已经足够。下面是一组日常习惯,用来减少不必要的绘制与内存占用,按需采用即可。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [层级、变换与性能](../basics/layer-transform-performance.md)
|
||||
- [UI 系统](./ui-system.md)
|
||||
|
||||
## 元素平铺与分组
|
||||
|
||||
同一层里堆很多兄弟元素,会让一次更新牵动整层。更新会沿父链标脏,父容器需要重新遍历并绘制受影响的部分;兄弟越多,重复的工作越明显。按更新频率分组:把一起变化、且不常变的元素放进同一个 `container`,把频繁变化的元素单独放。不要为了分组嵌得太深,层级越深,布局、绘制与命中遍历的递归也越深。
|
||||
|
||||
不推荐把静态内容与频繁变化的内容全部平铺在同一层:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<text loc={[12, 12]} text="标题" />
|
||||
<g-rect loc={[12, 40, 160, 32]} fillStyle="#2f6fed" />
|
||||
<text loc={[12, 80]} text="说明" />
|
||||
<text loc={[12, 280]} text={score.value.toString()} />
|
||||
</container>
|
||||
```
|
||||
|
||||
推荐把不常变的内容收进一个容器,把变化的文字单独放:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<container loc={[0, 0, 240, 120]}>
|
||||
<text loc={[12, 12]} text="标题" />
|
||||
<g-rect loc={[12, 40, 160, 32]} fillStyle="#2f6fed" />
|
||||
<text loc={[12, 80]} text="说明" />
|
||||
</container>
|
||||
<container loc={[0, 260, 240, 32]}>
|
||||
<text loc={[12, 0]} text={score.value.toString()} />
|
||||
</container>
|
||||
</container>
|
||||
```
|
||||
|
||||
## 长列表:Scroll 与 Page
|
||||
|
||||
不得不平铺一长串元素时,用 `Scroll` 或 `Page`。`Scroll` 按**直接子元素**的包围盒计算总长度,并把视口外的直接子元素隐藏:不绘制、不命中,元素与状态仍保留。因此每一行都要直接挂在 `Scroll` 下,不要先用一个大容器把全部内容包起来,否则 `Scroll` 只能看到一整块内容。
|
||||
|
||||
`Scroll` 适合需要连续滚动、行高不固定的列表。`Page` 只渲染当前页,适合页数固定、单页内容复杂或总条目更多的情况;代价是翻页而不是滚动。简单列表先用 `Scroll`,更大或更复杂的列表再考虑 `Page`。
|
||||
|
||||
```tsx
|
||||
<Scroll loc={[40, 40, 280, 200]}>
|
||||
{rows.map(row => (
|
||||
<container key={row.id} loc={[0, row.y, 280, 32]}>
|
||||
<text loc={[8, 8]} text={row.label} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
))}
|
||||
</Scroll>
|
||||
```
|
||||
|
||||
```tsx
|
||||
<Page pages={pageCount} loc={[40, 40, 280, 220]}>
|
||||
{page => {
|
||||
return rowsOfPage(page).map(row => (
|
||||
<text
|
||||
key={row.id}
|
||||
loc={[8, 8 + row.y]}
|
||||
text={row.label}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
));
|
||||
}}
|
||||
</Page>
|
||||
```
|
||||
|
||||
`Scroll` 与 `Page` 的参数见[内置组件:布局](./builtin-layout.md)。
|
||||
|
||||
## 渲染函数中的自我更新
|
||||
|
||||
不要在元素的渲染函数里调用它自己的更新方法。渲染函数已经在绘制这个元素,再次触发更新会形成递归;开发环境会输出警告,指出元素类型与 `uid`。需要随时间变化的内容,改由响应式状态或外部的定时逻辑驱动,让渲染函数只读取当前值。
|
||||
|
||||
不推荐在渲染函数里更新自身:
|
||||
|
||||
```tsx
|
||||
const render = () => {
|
||||
element.value?.update();
|
||||
};
|
||||
|
||||
<custom ref={element} render={render} />;
|
||||
```
|
||||
|
||||
## cache 与 nocache
|
||||
|
||||
`container`、`container-custom` 与 `custom` 默认缓存;`text`、`image` 与全部 `g-*` 默认不缓存。缓存适合结构复杂、内容稳定、重复绘制成本高的子树;一行文字、一个矩形,或者每帧都在变的进度与动画,直接绘制通常更便宜。
|
||||
|
||||
默认缓存的容器如果只装一行简单文字,可以加 `nocache` 省掉离屏画布与贴回。默认不缓存的元素如果内容复杂且很少变化,可以加 `cache` 复用绘制结果。`nocache` 优先于 `cache`;两者都可以随 props 动态修改,切换时会按新状态启用或清理缓存。没有必要每帧反复切换,但不要把它们当成创建后不可改的固定值。
|
||||
|
||||
```tsx
|
||||
<container loc={[40, 40, 240, 80]} nocache>
|
||||
<text loc={[12, 12]} text="简单内容" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
```tsx
|
||||
<g-path path={badge} cache fillStyle="#7ee787" />
|
||||
```
|
||||
|
||||
缓存的默认值与开关语义见[层级、变换与性能](../basics/layer-transform-performance.md#缓存与脏更新)。
|
||||
|
||||
## 像素风:抗锯齿与高清
|
||||
|
||||
抗锯齿控制缩放时的插值。像素图的边缘本来就是硬边,插值会把边缘变成半透明过渡,放大后容易发虚;因此像素图应使用 `noanti`。`hd` 只对开启缓存的元素有效:缓存的本来就是 1x 像素数据时,按设备像素比放大不会增加信息,可以配 `hd={false}` 减少缓存开销。
|
||||
|
||||
```tsx
|
||||
<image image={texture} loc={[40, 40, 160, 160]} noanti />
|
||||
|
||||
<container loc={[40, 40, 160, 160]} cache hd={false}>
|
||||
<image image={texture} loc={[0, 0, 160, 160]} noanti />
|
||||
</container>
|
||||
```
|
||||
|
||||
`hd` 与 `anti` / `noanti` 的完整说明见[通用参数](../basics/common-props.md)。
|
||||
|
||||
## 显隐:hidden 与条件渲染
|
||||
|
||||
需要显示或隐藏一块内容时,优先用 `hidden`。它只跳过绘制与命中,元素、组件状态、事件监听与按键作用域都还在;再次显示时直接恢复,不需要重新创建。不要用条件表达式卸载元素,也不要把它移到画面外或把颜色调成透明:前两种会改变树结构或布局,后一种仍然参与绘制与命中。
|
||||
|
||||
不推荐用条件表达式切换显隐:
|
||||
|
||||
```tsx
|
||||
{
|
||||
open.value ? <Panel /> : null;
|
||||
}
|
||||
```
|
||||
|
||||
推荐用 `hidden`:
|
||||
|
||||
```tsx
|
||||
<container loc={[40, 40, 240, 160]} hidden={!open.value}>
|
||||
<g-rect loc={[0, 0, 240, 160]} fillStyle="#26364d" />
|
||||
<text loc={[16, 16]} text="面板内容" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
只有确认一块长期不用、体积又大的子树需要释放时,才用条件渲染卸载。更多条件与列表写法见[条件渲染与循环渲染](./conditional-and-list-rendering.md)。
|
||||
@@ -0,0 +1,146 @@
|
||||
# UI 系统
|
||||
|
||||
UI 系统由控制器、实例和栈组成。每次 `open` 都会在控制器上产生一个实例并压入栈,`close` 把实例从栈里移除;栈记录打开顺序,决定实例的叠放关系,也决定哪些实例可见。一个控制器同时管理一条栈、一个背景和一套显示策略。
|
||||
|
||||
写 UI 时主要接触控制器与 `GameUI`;实例由系统创建,作者通常只持有 `open` 返回的实例,用来关闭或隐藏它。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [事件与交互](./events.md)
|
||||
|
||||
## 打开与关闭
|
||||
|
||||
需要让一个界面出现在控制器管理的画面上时,用 `open(ui, vBind, alwaysShow?)`。`ui` 是声明的 `GameUI`,`vBind` 是传给组件的参数,`alwaysShow` 省略时为普通界面。每次调用都会新建一个实例、压入栈,并返回这个实例;后打开的实例默认叠在先打开的上面。
|
||||
|
||||
```tsx
|
||||
// 打开一个已声明的 UI,返回这次打开产生的实例
|
||||
const instance = props.controller.open(ShopUI, {});
|
||||
|
||||
// 关闭这个实例
|
||||
props.controller.close(instance);
|
||||
```
|
||||
|
||||
关闭时要传 `open` 返回的那个实例,而不是重新打开一个再关。需要一次清空时用 `closeAll()`;传入一个 `GameUI` 时只关闭这一类界面。一次性弹窗可以用第三个参数 `alwaysShow` 打开,让它保持可见并盖在普通面板上方。
|
||||
|
||||
```ts
|
||||
// 关闭控制器里的全部 UI
|
||||
props.controller.closeAll();
|
||||
|
||||
// 只关闭 ShopUI 这一类
|
||||
props.controller.closeAll(ShopUI);
|
||||
```
|
||||
|
||||
下面的示例用一个最小控制器演示打开、关闭、栈长度与激活状态。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="controllerLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## 隐藏与显示
|
||||
|
||||
面板短期内还要回来,并且希望保留滚动位置、输入内容或组件状态时,用 `hide(instance)` 隐藏;需要恢复时用 `show(instance)`。两者只改可见性,不改变栈顺序,也不会卸载组件,状态、监听与按键作用域都还在。确定不再需要这个界面、希望它下次打开时重新开始时,才用 `close` 卸载。
|
||||
|
||||
```ts
|
||||
// 暂时隐藏,稍后还能原样显示
|
||||
props.controller.hide(instance);
|
||||
props.controller.show(instance);
|
||||
```
|
||||
|
||||
隐藏的实例仍然留在栈里,策略计算「最后一个该显示谁」时仍会把它算进去;如果只是想让面板从画面上消失,不要用 `close` 再 `open` 重建。
|
||||
|
||||
## keep
|
||||
|
||||
`keep()` 用来处理「关一个、马上开一个」的间隙。比如从道具栏切换到详情面板时,旧面板关闭后背景会先熄灭;用 `keep()` 包住这次切换,背景就能保持到新面板打开。
|
||||
|
||||
它返回一个 `IKeepController` 对象,这个对象有两个方法:
|
||||
|
||||
- `safelyUnload()`:栈里还有 UI 时保留背景,栈为空时才关闭背景。
|
||||
- `unload()`:不管栈里还有没有 UI,立即关闭背景。
|
||||
|
||||
`keep()` 本身不改变栈,也不卸载 UI;用完要调用其中一个方法收尾。
|
||||
|
||||
```ts
|
||||
// 先保持背景,再关旧面板、开新面板
|
||||
const keep = props.controller.keep();
|
||||
props.controller.close(oldInstance);
|
||||
props.controller.open(NextUI, {});
|
||||
keep.safelyUnload();
|
||||
```
|
||||
|
||||
## 控制器状态
|
||||
|
||||
`active` 与 `showBack` 是控制器的状态引用,主要给主场景容器用,普通 UI 组件一般不需要读。
|
||||
|
||||
## 背景
|
||||
|
||||
背景是控制器单独管理的一层,垫在 UI 栈下面,不占栈位置。普通 `open` / `close` 不会把它压栈或移除,`hide(instance)` 也关不掉它;要控制背景,用下面这组接口。
|
||||
|
||||
`setBackground(ui, vBind)` 设置背景 UI:`ui` 是一个 `GameUI`,`vBind` 是传给背景组件的参数。设置后背景实例始终在最下面;传 `null` 可以清空背景。
|
||||
|
||||
`showBackground()` 打开背景开关,`hideBackground()` 关闭背景开关。两者只影响背景这一层,不改变栈里的 UI。
|
||||
|
||||
`showBack` 是一个只读的 `Ref<boolean>`,表示背景最终是否显示;`showingBack()` 是同一结果的函数形式,返回 `boolean`。需要判断背景现在是否可见时,读 `showBack.value` 或调用 `showingBack()`。
|
||||
|
||||
```ts
|
||||
// 设置背景 UI:不占栈位置,始终垫在最下面
|
||||
props.controller.setBackground(BackgroundUI, {});
|
||||
|
||||
// 打开或关闭背景开关
|
||||
props.controller.hideBackground();
|
||||
props.controller.showBackground();
|
||||
|
||||
// 读取背景当前是否显示
|
||||
const showing = props.controller.showingBack();
|
||||
```
|
||||
|
||||
## 显示策略
|
||||
|
||||
栈里同时有多个实例时,显示策略决定打开与关闭后每个实例该显示还是隐藏。默认是 `lastOnly()`:只显示最后一个非 `alwaysShow` 实例,适合一层层推进的面板。`showAll()` 让栈里的界面同时可见,适合并排或叠加的界面。需要特殊叠放规则时,用 `showCustom(strategy)` 传入自定义策略;`strategy` 是一个 `IUICustomStrategy` 对象,负责决定每个实例在打开、关闭、隐藏、显示时该显示还是隐藏,只有内置的 `lastOnly()` / `showAll()` 不够用时才需要自己实现。
|
||||
|
||||
`lastOnly` 与 `showAll` 都接受一个 `stack` 参数:`lastOnly()` 默认开启栈模式,`showAll()` 默认关闭。开启栈模式后,关闭一个实例会连带移除它之后打开的实例;关闭并排工具栏时则不要开启。`alwaysShow` 的实例参与压栈,但不会被 `hide` 隐藏,所以弹窗能盖在面板上而不把面板挤掉。
|
||||
|
||||
```ts
|
||||
// 一层层推进的面板
|
||||
props.controller.lastOnly();
|
||||
|
||||
// 同时显示栈里的界面
|
||||
props.controller.showAll();
|
||||
|
||||
// strategy 是一个由你实现的 IUICustomStrategy 对象
|
||||
props.controller.showCustom(strategy);
|
||||
```
|
||||
|
||||
切换策略会立刻按现有栈重算显示状态,不要假设「新打开的一定盖住旧的」而不看当前策略。
|
||||
|
||||
下面的示例并排对比「只显示最后一个」与「显示全部」两种策略的叠放效果。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="strategyLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 栈模式下 `close` 会连带关闭上层。只想去掉一层时,先确认当前策略是不是 `lastOnly`,或者改用 `showAll`。
|
||||
- `alwaysShow` 的实例不会被 `hide` 隐藏;一次性弹窗就是靠这一点盖在面板上。
|
||||
- 背景实例是 `alwaysShow` 的,`hide(instance)` 关不掉它;要隐藏背景用 `hideBackground`。
|
||||
- `showBack` 与 `showingBack()` 是同一个结果;判断背景可见性时读它们即可。
|
||||
- 频繁 `open` / `close` 会反复创建与销毁组件。能复用就复用,能 `hide` / `show` 就不要重建。
|
||||
- `hide` 不会移除按键作用域,也不会让已打开的输入框失焦;需要彻底停止交互时用 `close`。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const controllerLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/controller-demo.tsx');
|
||||
|
||||
const strategyLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/strategy-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,115 @@
|
||||
# 什么是组件
|
||||
|
||||
组件可以看成 UI 的函数:调用时接收 props,返回一棵 UI 树。同一个组件声明一次,就能在不同位置反复使用;每次传入不同的 props,得到不同的画面。
|
||||
|
||||
本篇只讲组件最基本的形态、props 的传法,以及组件与 GameUI 的关系。
|
||||
|
||||
## 前置知识
|
||||
|
||||
阅读本篇前,建议先读完:
|
||||
|
||||
- [UI 入门](../basics/ui-basics.md)
|
||||
|
||||
## 用 props 接收数据
|
||||
|
||||
组件通过 props 接收父组件给的数据。写法固定为三步:
|
||||
|
||||
1. 定义 Props 接口,普通组件继承 `DefaultProps`;
|
||||
2. 在 `SetupComponentOptions` 的 `props` 数组里列出组件用到的键;
|
||||
3. 用 `defineComponent<Props>(props => ...)` 声明组件。
|
||||
|
||||
只有列在 `props` 数组里的键,才能在子组件里通过 `props` 读到。父组件把值写在组件标签的属性上,子组件通过 `props.x` 读取;某个 props 可以不传时,默认值用 `computed` 派生,props 变化时会重新计算。
|
||||
|
||||
## 普通组件:ItemCard
|
||||
|
||||
`ItemCard` 接收 `position`、`label`、`color` 三个 props,返回容器、矩形和文字:
|
||||
|
||||
```tsx
|
||||
import { computed, defineComponent } from 'vue';
|
||||
import { SetupComponentOptions } from '@motajs/system';
|
||||
import { DefaultProps } from '@motajs/render-vue';
|
||||
|
||||
// 普通组件的 Props 只需要继承 DefaultProps
|
||||
interface ItemCardProps extends DefaultProps {
|
||||
// 卡片相对父容器的横纵坐标
|
||||
position: [number, number];
|
||||
label: string;
|
||||
color?: string;
|
||||
}
|
||||
|
||||
// props 数组列出用到的键,父组件传的值才会进入 props
|
||||
const itemCardProps = {
|
||||
props: ['position', 'label', 'color']
|
||||
} satisfies SetupComponentOptions<ItemCardProps>;
|
||||
|
||||
const ItemCard = defineComponent<ItemCardProps>(props => {
|
||||
// 没有传 color 时使用默认颜色
|
||||
const color = computed(() => props.color ?? '#f2b84b');
|
||||
|
||||
return () => (
|
||||
// 根容器放在 props.position 指定的位置,卡片尺寸由组件自己决定
|
||||
<container loc={props.position}>
|
||||
<g-rect loc={[0, 0, 220, 64]} fillStyle={color.value} />
|
||||
<text loc={[16, 22]} text={props.label} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
}, itemCardProps);
|
||||
|
||||
export { ItemCard };
|
||||
```
|
||||
|
||||
父组件写 `<ItemCard position={[40, 64]} label="卡片 A" color="#2f6fed" />` 时,`position` 决定卡片位置,`label` 决定文字,`color` 决定矩形颜色;不写 `color` 的卡片使用默认颜色。
|
||||
|
||||
## UI 组件:MyPanel
|
||||
|
||||
GameUI 也是先声明成一个组件,再用 `new GameUI('id', MyPanel)` 定义为 UI。它和普通组件的区别在参数来源:GameUI 是特殊组件,能接收 UI 参数 `controller`、`instance`、`state`(来自 `IGameUIPropsBase`),由 UI 系统 / 控制器打开。
|
||||
|
||||
普通组件更自由,不受 GameUI 约束:它不需要这些 UI 参数,可以嵌套在任意 UI 树里;它不是 UI 入口,只负责画自己那块内容。
|
||||
|
||||
下面是一份完整的标准 UI 模板,里面用了两次 `ItemCard`:
|
||||
|
||||
```tsx
|
||||
import { defineComponent } 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';
|
||||
import { ItemCard } from './item-card';
|
||||
|
||||
// UI 组件的 Props 同时继承 IGameUIPropsBase 与 DefaultProps
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
// controller、instance、state 来自 IGameUIPropsBase
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
{/* 同一个组件用两次,不同的 props 得到不同的卡片 */}
|
||||
<ItemCard position={[40, 64]} label="卡片 A" color="#2f6fed" />
|
||||
<ItemCard position={[40, 152]} label="卡片 B" />
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
// 声明成 UI:第一个参数是唯一 id,第二个参数是上面声明的组件
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
下面用父容器放三张 `ItemCard`,只改 `label` 与 `color`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="componentBasicLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const componentBasicLoader = () =>
|
||||
import('../../.vitepress/components/demos/ui/component-basic-demo.tsx');
|
||||
</script>
|
||||
Reference in new issue
Block a user