mirror of
https://github.com/motajs/template.git
synced 2026-11-20 19:54:36 +08:00
docs: complete advanced II custom UI documentation
This commit is contained in:
1 parent
e25ef39481
commit
5db2cefb39
127 files changed
+22831
-13
No files matched your search
@@ -0,0 +1,53 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<container loc={[8, 8, 228, 148]}>
|
||||
<g-rect
|
||||
loc={[110, 70, 100, 60, 0, 0]}
|
||||
fillStyle="#2f6fed"
|
||||
alpha={0.6}
|
||||
/>
|
||||
<g-circle circle={[110, 70, 6]} fillStyle="#e8f0ff" />
|
||||
<text loc={[8, 122]} text="锚点 0, 0" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
|
||||
<container loc={[244, 8, 228, 148]}>
|
||||
<g-rect
|
||||
loc={[110, 70, 100, 60, 0.5, 0.5]}
|
||||
fillStyle="#f2b84b"
|
||||
alpha={0.6}
|
||||
/>
|
||||
<g-circle circle={[110, 70, 6]} fillStyle="#ffe9b0" />
|
||||
<text loc={[8, 122]} text="锚点 0.5, 0.5" fillStyle="#ffe9b0" />
|
||||
</container>
|
||||
|
||||
<container loc={[8, 164, 228, 148]}>
|
||||
<g-rect
|
||||
loc={[110, 70, 100, 60, 1, 1]}
|
||||
fillStyle="#58c4dd"
|
||||
alpha={0.6}
|
||||
/>
|
||||
<g-circle circle={[110, 70, 6]} fillStyle="#e8f0ff" />
|
||||
<text loc={[8, 122]} text="锚点 1, 1" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
|
||||
<container loc={[244, 164, 228, 148]}>
|
||||
<g-rect
|
||||
loc={[110, 70, 160, 100, 0.5, 0.5]}
|
||||
fillStyle="#c58af9"
|
||||
alpha={0.5}
|
||||
/>
|
||||
<g-circle circle={[110, 70, 6]} fillStyle="#f3e8ff" />
|
||||
<text
|
||||
loc={[8, 122]}
|
||||
text="中心锚点,尺寸更大"
|
||||
fillStyle="#f3e8ff"
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,13 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// UI 入门演示:一个 480×320 的容器,里面放一行文字和一个矩形
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
{/* 一行文字 */}
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
{/* 一个矩形 */}
|
||||
<g-rect loc={[24, 64, 160, 80]} fill fillStyle="#2f6fed" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,20 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import { Arrow } from '../../../../../packages-user/client-base/src/components/misc';
|
||||
|
||||
// 箭头:三条箭头分别改 head 与 color
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<Arrow arrow={[48, 48, 300, 48]} head={8} color="#f2b84b" />
|
||||
<text loc={[48, 80]} text="head = 8" fillStyle="#cfe0ff" />
|
||||
|
||||
<Arrow arrow={[48, 136, 300, 136]} head={18} color="#7ee787" />
|
||||
<text loc={[48, 168]} text="head = 18" fillStyle="#cfe0ff" />
|
||||
|
||||
<Arrow arrow={[48, 224, 300, 224]} head={30} color="#7aa2ff" />
|
||||
<text loc={[48, 256]} text="head = 30" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,33 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import { Background } from '../../../../../packages-user/client-base/src/components/background';
|
||||
|
||||
// 背景:同一个组件换两组 color 与 border
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<container loc={[40, 48, 180, 150]}>
|
||||
<Background
|
||||
loc={[0, 0, 180, 150]}
|
||||
color="#1d2b45"
|
||||
border="#3a5a8c"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text="color + border"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[260, 48, 180, 150]}>
|
||||
<Background
|
||||
loc={[0, 0, 180, 150]}
|
||||
color="#2a2140"
|
||||
border="#c9a7ff"
|
||||
/>
|
||||
<text loc={[16, 16]} text="换一组颜色" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,52 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import {
|
||||
PlayIcon,
|
||||
PauseIcon,
|
||||
RollbackIcon,
|
||||
RetweetIcon,
|
||||
SoundVolume,
|
||||
Fullscreen,
|
||||
DoubleArrow,
|
||||
StepForward,
|
||||
ArrowLeftTailless
|
||||
} from '../../../../../packages-user/client-base/src/components/icons';
|
||||
|
||||
// 图标组件:每个图标都只接受 loc,按名字使用
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<PlayIcon loc={[56, 36, 32, 32]} />
|
||||
<text loc={[56, 80]} text="PlayIcon" fillStyle="#cfe0ff" />
|
||||
|
||||
<PauseIcon loc={[196, 36, 32, 32]} />
|
||||
<text loc={[196, 80]} text="PauseIcon" fillStyle="#cfe0ff" />
|
||||
|
||||
<RollbackIcon loc={[336, 36, 32, 32]} />
|
||||
<text loc={[336, 80]} text="RollbackIcon" fillStyle="#cfe0ff" />
|
||||
|
||||
<RetweetIcon loc={[56, 128, 32, 32]} />
|
||||
<text loc={[56, 172]} text="RetweetIcon" fillStyle="#cfe0ff" />
|
||||
|
||||
<SoundVolume loc={[196, 128, 32, 32]} />
|
||||
<text loc={[196, 172]} text="SoundVolume" fillStyle="#cfe0ff" />
|
||||
|
||||
<Fullscreen loc={[336, 128, 32, 32]} />
|
||||
<text loc={[336, 172]} text="Fullscreen" fillStyle="#cfe0ff" />
|
||||
|
||||
<DoubleArrow loc={[56, 220, 32, 32]} />
|
||||
<text loc={[56, 264]} text="DoubleArrow" fillStyle="#cfe0ff" />
|
||||
|
||||
<ArrowLeftTailless loc={[196, 220, 32, 32]} />
|
||||
<text
|
||||
loc={[196, 264]}
|
||||
text="ArrowLeftTailless"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<StepForward loc={[336, 220, 32, 32]} />
|
||||
<text loc={[336, 264]} text="StepForward" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,33 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import { Input } from '../../../../../packages-user/client-base/src/components/input';
|
||||
|
||||
// 输入框:单行占位、单行已填内容与多行输入
|
||||
export default defineComponent(() => {
|
||||
const name = ref('');
|
||||
const filled = ref('魔塔玩家');
|
||||
const note = ref('第一行备注\n第二行备注');
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[40, 24]} text="单行" fillStyle="#cfe0ff" />
|
||||
<Input
|
||||
loc={[40, 48, 280, 32]}
|
||||
v-model:value={name.value}
|
||||
placeholder="输入名字"
|
||||
/>
|
||||
|
||||
<text loc={[40, 96]} text="已填内容" fillStyle="#cfe0ff" />
|
||||
<Input loc={[40, 120, 280, 32]} v-model:value={filled.value} />
|
||||
|
||||
<text loc={[40, 168]} text="多行" fillStyle="#cfe0ff" />
|
||||
<Input
|
||||
loc={[40, 192, 320, 88]}
|
||||
v-model:value={note.value}
|
||||
multiline
|
||||
placeholder="多行备注"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,30 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import { List } from '../../../../../packages-user/client-base/src/components/list';
|
||||
|
||||
const ITEMS: [string, string][] = [
|
||||
['basic', '基础设置'],
|
||||
['sound', '声音'],
|
||||
['key', '按键'],
|
||||
['about', '关于']
|
||||
];
|
||||
|
||||
// 列表:四项由 list 渲染,选中项显示闪烁光标
|
||||
export default defineComponent(() => {
|
||||
const selected = ref(ITEMS[0][0]);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<List
|
||||
loc={[40, 40, 300, 160]}
|
||||
list={ITEMS}
|
||||
lineHeight={32}
|
||||
color="#2b4a6f"
|
||||
border="#6fa8ff"
|
||||
alphaRange={[0.6, 0.9]}
|
||||
v-model:selected={selected.value}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,38 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import { ListPage } from '../../../../../packages-user/client-base/src/components/list';
|
||||
|
||||
const ITEMS: [string, string][] = [
|
||||
['basic', '基础设置'],
|
||||
['sound', '声音'],
|
||||
['key', '按键']
|
||||
];
|
||||
const DETAIL: Record<string, string> = {
|
||||
basic: '这里放基础设置的说明。',
|
||||
sound: '这里放音量与音效的说明。',
|
||||
key: '这里放按键改绑的说明。'
|
||||
};
|
||||
|
||||
// 左列表、右详情:选中项高亮,右侧显示对应内容
|
||||
export default defineComponent(() => {
|
||||
const selected = ref(ITEMS[0][0]);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<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>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,25 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import { Page } from '../../../../../packages-user/client-base/src/components/page';
|
||||
|
||||
const PAGES = ['第一页:基础设置', '第二页:声音', '第三页:按键'];
|
||||
|
||||
// 分页:三页内容共用一个 loc,页码条在底部
|
||||
export default defineComponent(() => {
|
||||
const page = ref(0);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<Page pages={3} v-model:page={page.value} loc={[90, 48, 300, 200]}>
|
||||
{(index: number) => (
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text={PAGES[index] ?? ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
)}
|
||||
</Page>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,34 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import { Progress } from '../../../../../packages-user/client-base/src/components/misc';
|
||||
|
||||
// 进度条:progress 分别取 0.3、0.6 与 1
|
||||
const BARS = [
|
||||
{ label: 'progress = 0.3', y: 68, progress: 0.3 },
|
||||
{ label: 'progress = 0.6', y: 128, progress: 0.6 },
|
||||
{ label: 'progress = 1', y: 188, progress: 1 }
|
||||
];
|
||||
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
{BARS.map(bar => (
|
||||
<container key={bar.label} loc={[0, 0, 480, 320]}>
|
||||
<text
|
||||
loc={[48, bar.y - 24]}
|
||||
text={bar.label}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<Progress
|
||||
loc={[48, bar.y, 300, 10]}
|
||||
progress={bar.progress}
|
||||
success="#7ee787"
|
||||
background="#26364d"
|
||||
lineWidth={8}
|
||||
/>
|
||||
</container>
|
||||
))}
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,32 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import { Scroll } from '../../../../../packages-user/client-base/src/components/scroll';
|
||||
|
||||
const ROWS = Array.from({ length: 12 }, (_, index) => `第 ${index + 1} 行`);
|
||||
|
||||
// 滚动区域:直接子元素从上往下排,右侧是滚动条
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[40, 24]}
|
||||
text="直接子元素依次排列"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<g-rect loc={[40, 52, 300, 220]} fillStyle="#101820" />
|
||||
<Scroll loc={[40, 52, 300, 220]}>
|
||||
{ROWS.map((row, index) => (
|
||||
<container key={row} loc={[8, 6 + index * 30, 280, 28]}>
|
||||
<g-rect
|
||||
loc={[0, 0, 280, 28]}
|
||||
fillStyle={index % 2 === 0 ? '#26364d' : '#1d2b45'}
|
||||
/>
|
||||
<text loc={[10, 6]} text={row} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
))}
|
||||
</Scroll>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,51 @@
|
||||
import { defineComponent, onUnmounted, ref } from 'vue';
|
||||
import {
|
||||
ScrollText,
|
||||
ScrollTextExpose
|
||||
} from '../../../../../packages-user/client-base/src/components/misc';
|
||||
|
||||
const NOTICE = [
|
||||
'公告:今晚八点维护',
|
||||
'提示:记得保存进度',
|
||||
'活动:新地图开放',
|
||||
'注意:离开前先存档'
|
||||
]
|
||||
.join('\n')
|
||||
.repeat(3);
|
||||
|
||||
// 滚动文字:内容在固定视口里向上滚动,超出视口的部分不显示
|
||||
export default defineComponent(() => {
|
||||
const scroll = ref<ScrollTextExpose>();
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
|
||||
const restart = () => {
|
||||
// 组件触发 scrollEnd 后会立刻暂停,等一小段可见停顿后再恢复
|
||||
timer = setTimeout(() => {
|
||||
timer = undefined;
|
||||
scroll.value?.rescroll();
|
||||
scroll.value?.resume();
|
||||
}, 1000);
|
||||
};
|
||||
|
||||
onUnmounted(() => {
|
||||
if (timer !== undefined) clearTimeout(timer);
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[40, 32]} text="公告" fillStyle="#cfe0ff" />
|
||||
|
||||
<ScrollText
|
||||
ref={scroll}
|
||||
loc={[40, 60, 400, 160]}
|
||||
width={400}
|
||||
speed={80}
|
||||
text={NOTICE}
|
||||
fillStyle="#7ee787"
|
||||
onScrollEnd={restart}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,38 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import { Selection } from '../../../../../packages-user/client-base/src/components/misc';
|
||||
|
||||
// 选中框:两组 color 与 border,第二组调大 alphaRange
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<container loc={[40, 48, 240, 32]}>
|
||||
<Selection
|
||||
loc={[0, 0, 240, 32]}
|
||||
color="#2f6fed"
|
||||
border="#7aa2ff"
|
||||
/>
|
||||
<text loc={[12, 8]} text="被选中的项" fillStyle="#ffffff" />
|
||||
</container>
|
||||
|
||||
<container loc={[40, 96, 240, 32]}>
|
||||
<Selection
|
||||
loc={[0, 0, 240, 32]}
|
||||
color="#8a6a1f"
|
||||
border="#f2b84b"
|
||||
alphaRange={[0.4, 0.8]}
|
||||
/>
|
||||
<text
|
||||
loc={[12, 8]}
|
||||
text="alphaRange = [0.4, 0.8]"
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[40, 144, 240, 32]}>
|
||||
<text loc={[12, 8]} text="没有选中框的项" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,60 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import { Slider } from '../../../../../packages-user/client-base/src/components/slider';
|
||||
|
||||
// 滑动条:右侧显示当前值,旁边配两个按钮增减数值
|
||||
export default defineComponent(() => {
|
||||
const volume = ref(40);
|
||||
|
||||
const decrease = () => {
|
||||
volume.value = Math.max(0, volume.value - 5);
|
||||
};
|
||||
const increase = () => {
|
||||
volume.value = Math.min(100, volume.value + 5);
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[44, 48]} text="音量" fillStyle="#cfe0ff" />
|
||||
|
||||
<container loc={[44, 76, 196, 24]}>
|
||||
<Slider
|
||||
loc={[0, 0, 196, 24]}
|
||||
v-model:value={volume.value}
|
||||
min={0}
|
||||
max={100}
|
||||
step={5}
|
||||
showValue
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[44, 124, 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={[120, 124, 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>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,28 @@
|
||||
import { defineComponent } from 'vue';
|
||||
import { TextContent } from '../../../../../packages-user/client-base/src/components/textbox';
|
||||
|
||||
const TEXT =
|
||||
'[c=#f2b84b][s=20]标题字号[/s][/c]\n' +
|
||||
'[c=#7ee787]正文颜色,长句会按 width 折行,超出宽度的部分自动换到下一行[/c]\n' +
|
||||
'[c=#8aa0b8][s=13]小字注释:[[[[ 和 ]]]] 显示为方括号[/s][/c]';
|
||||
|
||||
// 文本标记:颜色、字号、手动换行与方括号字面量,长句按 width 折行
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[40, 24]} text="文本标记" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-rect loc={[40, 56, 400, 216]} fillStyle="#101820" />
|
||||
<TextContent
|
||||
loc={[60, 80]}
|
||||
width={360}
|
||||
autoHeight
|
||||
lineHeight={8}
|
||||
text={TEXT}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,45 @@
|
||||
import { computed, defineComponent } from 'vue';
|
||||
|
||||
interface ItemCardProps {
|
||||
position: [number, number];
|
||||
label: string;
|
||||
color?: string;
|
||||
}
|
||||
|
||||
interface ItemCardOptions {
|
||||
props: (keyof ItemCardProps)[];
|
||||
}
|
||||
|
||||
const itemCardOptions: ItemCardOptions = {
|
||||
props: ['position', 'label', 'color']
|
||||
};
|
||||
|
||||
// 子组件:只按 props 决定卡片的位置、文字与颜色
|
||||
const ItemCard = defineComponent<ItemCardProps>(props => {
|
||||
// 没有传 color 时使用默认颜色
|
||||
const color = computed(() => props.color ?? '#f2b84b');
|
||||
|
||||
return () => (
|
||||
<container loc={props.position}>
|
||||
<g-rect loc={[0, 0, 220, 64]} fillStyle={color.value} />
|
||||
<text loc={[16, 22]} text={props.label} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
}, itemCardOptions);
|
||||
|
||||
// 父组件:同一个 ItemCard 声明一次,用三次,只改传入的 props
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
<text
|
||||
loc={[40, 24]}
|
||||
text="同一个组件,不同的 props"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<ItemCard position={[40, 56]} label="卡片 A" color="#2f6fed" />
|
||||
<ItemCard position={[40, 144]} label="卡片 B" color="#7ee787" />
|
||||
<ItemCard position={[40, 232]} label="卡片 C" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,53 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
// hidden 只切换绘制与命中,面板实例和内部计数都保留
|
||||
export default defineComponent(() => {
|
||||
const open = ref(true);
|
||||
const count = ref(0);
|
||||
|
||||
const togglePanel = () => {
|
||||
open.value = !open.value;
|
||||
};
|
||||
|
||||
const increaseCount = () => {
|
||||
count.value++;
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<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, 92, 240, 160]}
|
||||
hidden={!open.value}
|
||||
onClick={increaseCount}
|
||||
>
|
||||
<g-rect loc={[0, 0, 240, 160]} fill fillStyle="#26364d" />
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text="点击面板内部 +1"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={`面板内点击:${count.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 96]}
|
||||
text="隐藏后再显示,状态仍在"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,96 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
interface Row {
|
||||
id: number;
|
||||
label: string;
|
||||
}
|
||||
|
||||
interface StatefulRowProps {
|
||||
label: string;
|
||||
offsetY: number;
|
||||
}
|
||||
|
||||
interface StatefulRowOptions {
|
||||
props: (keyof StatefulRowProps)[];
|
||||
}
|
||||
|
||||
const statefulRowOptions: StatefulRowOptions = {
|
||||
props: ['label', 'offsetY']
|
||||
};
|
||||
|
||||
// 每一行有自己的计数;重排后它跟着组件实例走
|
||||
const StatefulRow = defineComponent<StatefulRowProps, {}, string>(props => {
|
||||
const count = ref(0);
|
||||
|
||||
const increaseCount = () => {
|
||||
count.value++;
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, props.offsetY, 200, 36]} onClick={increaseCount}>
|
||||
<g-rect loc={[0, 0, 200, 36]} fill fillStyle="#26364d" />
|
||||
<text loc={[10, 10]} text={props.label} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[104, 10]}
|
||||
text={`点击 ${count.value}`}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, statefulRowOptions);
|
||||
|
||||
// key=id 的状态跟着项,key=index 的状态留在原位置
|
||||
export default defineComponent(() => {
|
||||
const rows = ref<Row[]>([
|
||||
{ id: 1, label: '甲' },
|
||||
{ id: 2, label: '乙' },
|
||||
{ id: 3, label: '丙' }
|
||||
]);
|
||||
|
||||
const rotateRows = () => {
|
||||
const first = rows.value.shift();
|
||||
if (first) {
|
||||
rows.value.push(first);
|
||||
}
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 16]}
|
||||
text="点行内 +1,再点「轮换顺序」"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<text loc={[24, 52]} text="key = id" fillStyle="#58c4dd" />
|
||||
<text loc={[256, 52]} text="key = index" fillStyle="#f2b84b" />
|
||||
|
||||
<container loc={[24, 84]}>
|
||||
{rows.value.map((row, index) => (
|
||||
<StatefulRow
|
||||
key={row.id}
|
||||
label={row.label}
|
||||
offsetY={index * 42}
|
||||
/>
|
||||
))}
|
||||
</container>
|
||||
|
||||
<container loc={[256, 84]}>
|
||||
{rows.value.map((row, index) => (
|
||||
<StatefulRow
|
||||
key={index}
|
||||
label={row.label}
|
||||
offsetY={index * 42}
|
||||
/>
|
||||
))}
|
||||
</container>
|
||||
|
||||
<container loc={[160, 260, 160, 36]} onClick={rotateRows}>
|
||||
<g-rect loc={[0, 0, 160, 36]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[52, 10]} text="轮换顺序" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,57 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
// 面板自己的计数:组件被卸载后实例消失,再挂载时从 0 开始
|
||||
const CounterPanel = defineComponent(() => {
|
||||
const count = ref(0);
|
||||
|
||||
const increaseCount = () => {
|
||||
count.value++;
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 240, 160]} onClick={increaseCount}>
|
||||
<g-rect loc={[0, 0, 240, 160]} fill fillStyle="#26364d" />
|
||||
<text loc={[16, 16]} text="点击面板内部 +1" fillStyle="#e8f0ff" />
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={`面板内点击:${count.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 96]}
|
||||
text="重新显示后,计数归零"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
|
||||
// 三元切换:面板被卸载与重建
|
||||
export default defineComponent(() => {
|
||||
const open = ref(true);
|
||||
|
||||
const togglePanel = () => {
|
||||
open.value = !open.value;
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<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, 92]}>
|
||||
<CounterPanel />
|
||||
</container>
|
||||
) : null}
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,70 @@
|
||||
import type { CustomContainerRenderFn } from '@motajs/render';
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 同一组 3 个子元素:左侧普通 container 原样绘制,右侧 container-custom 逐个设置递增模糊
|
||||
const rows = [
|
||||
{ fillStyle: '#2f6fed', textFillStyle: '#e8f0ff', label: '第一行' },
|
||||
{ fillStyle: '#7aa7ff', textFillStyle: '#141a22', label: '第二行' },
|
||||
{ fillStyle: '#f2b84b', textFillStyle: '#141a22', label: '第三行' }
|
||||
];
|
||||
|
||||
export default defineComponent(() => {
|
||||
// render 接管子元素绘制:按 index 给每个子元素设置递增的 blur,再逐个绘制
|
||||
const render: CustomContainerRenderFn = (canvas, children, transform) => {
|
||||
children.forEach((child, index) => {
|
||||
if (child.hidden) return;
|
||||
child.setFilter(`blur(${index * 2}px)`);
|
||||
child.renderContent(canvas, transform);
|
||||
});
|
||||
};
|
||||
|
||||
// 两侧使用相同结构的三行内容
|
||||
const renderRows = () =>
|
||||
rows.map((row, index) => (
|
||||
<container loc={[0, index * 52, 180, 44]}>
|
||||
<g-rect loc={[0, 0, 180, 44]} fillStyle={row.fillStyle} />
|
||||
<text
|
||||
loc={[14, 12]}
|
||||
text={row.label}
|
||||
fillStyle={row.textFillStyle}
|
||||
/>
|
||||
</container>
|
||||
));
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="<container-custom> 逐个设置递增 blur"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<g-rect loc={[40, 72, 180, 160]} fillStyle="#1d2430" />
|
||||
<g-rect loc={[260, 72, 180, 160]} fillStyle="#1d2430" />
|
||||
|
||||
<text
|
||||
loc={[40, 48]}
|
||||
text="container:原样绘制"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
<container loc={[40, 72, 180, 160]}>{renderRows()}</container>
|
||||
|
||||
<text
|
||||
loc={[260, 48]}
|
||||
text="custom:递增 blur"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
<container-custom loc={[260, 72, 180, 160]} render={render}>
|
||||
{renderRows()}
|
||||
</container-custom>
|
||||
|
||||
<text
|
||||
loc={[40, 272]}
|
||||
text="同一组子元素:右侧按顺序设置 blur(0 / 2 / 4px)"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,33 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<container loc={[60, 50, 360, 220]}>
|
||||
<g-rect
|
||||
loc={[0, 0, 360, 220]}
|
||||
fillStyle="#2f6fed"
|
||||
alpha={0.22}
|
||||
/>
|
||||
<g-circle circle={[0, 0, 6]} fillStyle="#e8f0ff" />
|
||||
<text loc={[16, 16]} text="父容器原点" fillStyle="#cfe0ff" />
|
||||
|
||||
<container loc={[80, 60, 200, 120]}>
|
||||
<g-rect
|
||||
loc={[0, 0, 200, 120]}
|
||||
fillStyle="#f2b84b"
|
||||
alpha={0.3}
|
||||
/>
|
||||
<g-circle circle={[0, 0, 6]} fillStyle="#ffe9b0" />
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text="子容器原点"
|
||||
fillStyle="#ffe9b0"
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,95 @@
|
||||
import { computed, defineComponent, onUnmounted } from 'vue';
|
||||
import {
|
||||
GameUI,
|
||||
IUIDefaultPropsBase,
|
||||
IUIInstance,
|
||||
UIController
|
||||
} from '@motajs/system';
|
||||
|
||||
// 最小控制器:只注入 instance 与 controller,不依赖游戏状态
|
||||
const controller = new UIController<IUIDefaultPropsBase>();
|
||||
controller.setPropsBaseCreator((instance, ctrl) => ({
|
||||
instance,
|
||||
controller: ctrl
|
||||
}));
|
||||
|
||||
// 被打开的 UI:固定在画布右侧,避免和按钮重叠
|
||||
const DemoPanel = defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[220, 120, 220, 150]}>
|
||||
<g-rect loc={[0, 0, 220, 150]} fill fillStyle="#1d2b45" />
|
||||
<g-rect loc={[0, 0, 220, 150]} stroke strokeStyle="#7aa2ff" />
|
||||
<text loc={[16, 24]} text="这是一个最小 UI" fillStyle="#e8f0ff" />
|
||||
<text
|
||||
loc={[16, 64]}
|
||||
text="由 UIController 打开"
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
|
||||
const demoUI = new GameUI('controller-demo-panel', DemoPanel);
|
||||
|
||||
// 把 controller.render() 挂进同一棵渲染树
|
||||
const UIRenderer = defineComponent(() => {
|
||||
return () => controller.render();
|
||||
});
|
||||
|
||||
export default defineComponent(() => {
|
||||
// 打开与关闭必须复用同一个实例
|
||||
let instance: IUIInstance | null = null;
|
||||
|
||||
const stackSize = computed(() => controller.stack.length);
|
||||
const activeText = computed(() =>
|
||||
controller.active.value ? '已打开' : '未打开'
|
||||
);
|
||||
|
||||
const openUI = () => {
|
||||
if (!instance) {
|
||||
instance = controller.open(demoUI, {});
|
||||
}
|
||||
};
|
||||
|
||||
const closeUI = () => {
|
||||
if (instance) {
|
||||
controller.close(instance);
|
||||
instance = null;
|
||||
}
|
||||
};
|
||||
|
||||
onUnmounted(() => {
|
||||
controller.closeAll();
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#141a22" />
|
||||
|
||||
<text loc={[20, 20]} text="打开 UI" fillStyle="#e8f0ff" />
|
||||
<container loc={[20, 44, 150, 44]} onClick={openUI}>
|
||||
<g-rect loc={[0, 0, 150, 44]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[16, 12]} text="打开" fillStyle="#ffffff" />
|
||||
</container>
|
||||
|
||||
<text loc={[20, 116]} text="关闭 UI" fillStyle="#e8f0ff" />
|
||||
<container loc={[20, 140, 150, 44]} onClick={closeUI}>
|
||||
<g-rect loc={[0, 0, 150, 44]} fill fillStyle="#3a2f5f" />
|
||||
<text loc={[16, 12]} text="关闭" fillStyle="#ffffff" />
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[20, 220]}
|
||||
text={`栈长度:${stackSize.value}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
<text
|
||||
loc={[20, 252]}
|
||||
text={`状态:${activeText.value}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
|
||||
<UIRenderer />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,74 @@
|
||||
import { computed, defineComponent, ref } from 'vue';
|
||||
|
||||
interface ItemCardProps {
|
||||
label: string;
|
||||
active?: boolean;
|
||||
}
|
||||
|
||||
type ItemCardEmits = {
|
||||
pick: (label: string) => void;
|
||||
};
|
||||
|
||||
interface ItemCardOptions {
|
||||
props: (keyof ItemCardProps)[];
|
||||
emits: (keyof ItemCardEmits)[];
|
||||
}
|
||||
|
||||
const itemCardOptions: ItemCardOptions = {
|
||||
props: ['label', 'active'],
|
||||
emits: ['pick']
|
||||
};
|
||||
|
||||
// 子组件:按 props 决定颜色,点击时发出 pick 事件,底部内容由默认 slot 填入
|
||||
const ItemCard = defineComponent<
|
||||
ItemCardProps,
|
||||
ItemCardEmits,
|
||||
keyof ItemCardEmits
|
||||
>((props, { emit, slots }) => {
|
||||
const fill = computed(() => (props.active ? '#2f6fed' : '#26364d'));
|
||||
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, 200, 96]}
|
||||
onClick={() => emit('pick', props.label)}
|
||||
>
|
||||
<g-rect loc={[0, 0, 200, 96]} fillStyle={fill.value} />
|
||||
<text loc={[12, 12]} text={props.label} fillStyle="#ffffff" />
|
||||
{slots.default?.()}
|
||||
</container>
|
||||
);
|
||||
}, itemCardOptions);
|
||||
|
||||
// 父组件:用 ref 保存选中项,把 props、事件与默认 slot 传给两个卡片
|
||||
export default defineComponent(() => {
|
||||
const selected = ref('甲');
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
<text
|
||||
loc={[24, 28]}
|
||||
text={`当前选择:${selected.value}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<container loc={[24, 72]}>
|
||||
<ItemCard
|
||||
label="甲"
|
||||
active={selected.value === '甲'}
|
||||
onPick={label => (selected.value = label)}
|
||||
>
|
||||
<text loc={[12, 60]} text="点我选择" fillStyle="#cfe0ff" />
|
||||
</ItemCard>
|
||||
</container>
|
||||
<container loc={[256, 72]}>
|
||||
<ItemCard
|
||||
label="乙"
|
||||
active={selected.value === '乙'}
|
||||
onPick={label => (selected.value = label)}
|
||||
>
|
||||
<text loc={[12, 60]} text="点我选择" fillStyle="#cfe0ff" />
|
||||
</ItemCard>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,88 @@
|
||||
import type { CustomRenderFunction } from '@motajs/render';
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
const ringColors = ['#2f6fed', '#7aa7ff', '#f2b84b'];
|
||||
|
||||
// 演示 custom 的局部坐标绘制:同心圆环、径向渐变与旋转指针
|
||||
export default defineComponent(() => {
|
||||
// 把 angle.value 放进 bindings;点击按钮改变角度时会触发重绘
|
||||
const angle = ref(0);
|
||||
|
||||
// 在元素局部坐标里直接绘制:同心圆环、径向渐变与旋转指针
|
||||
const render: CustomRenderFunction = canvas => {
|
||||
const ctx = canvas.ctx;
|
||||
const cx = 100;
|
||||
const cy = 100;
|
||||
|
||||
// 径向渐变与同心圆环直接走 Canvas 2D
|
||||
const gradient = ctx.createRadialGradient(cx, cy, 12, cx, cy, 88);
|
||||
gradient.addColorStop(0, '#2f6fed');
|
||||
gradient.addColorStop(1, '#141a22');
|
||||
ctx.beginPath();
|
||||
ctx.arc(cx, cy, 88, 0, Math.PI * 2);
|
||||
ctx.fillStyle = gradient;
|
||||
ctx.fill();
|
||||
|
||||
ringColors.forEach((color, index) => {
|
||||
ctx.beginPath();
|
||||
ctx.arc(cx, cy, 70 - index * 16, 0, Math.PI * 2);
|
||||
ctx.strokeStyle = color;
|
||||
ctx.lineWidth = 3;
|
||||
ctx.stroke();
|
||||
});
|
||||
|
||||
// 指针从圆心出发,按 angle 旋转;坐标都相对元素左上角
|
||||
ctx.translate(cx, cy);
|
||||
ctx.rotate(angle.value);
|
||||
ctx.beginPath();
|
||||
ctx.moveTo(0, 0);
|
||||
ctx.lineTo(0, -64);
|
||||
ctx.strokeStyle = '#e8f0ff';
|
||||
ctx.lineWidth = 4;
|
||||
ctx.stroke();
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="<custom> 在局部坐标里直接绘制"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<custom
|
||||
loc={[140, 44, 200, 200]}
|
||||
bindings={[angle.value]}
|
||||
render={render}
|
||||
/>
|
||||
|
||||
<container
|
||||
loc={[138, 256, 92, 36]}
|
||||
onClick={() => {
|
||||
angle.value -= Math.PI / 12;
|
||||
}}
|
||||
>
|
||||
<g-rect loc={[0, 0, 92, 36]} fillStyle="#2f6fed" />
|
||||
<text loc={[18, 9]} text="−15°" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
<container
|
||||
loc={[250, 256, 92, 36]}
|
||||
onClick={() => {
|
||||
angle.value += Math.PI / 12;
|
||||
}}
|
||||
>
|
||||
<g-rect loc={[0, 0, 92, 36]} fillStyle="#2f6fed" />
|
||||
<text loc={[18, 9]} text="+15°" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[24, 300]}
|
||||
text="angle.value 放进 bindings,点击按钮会重绘"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,73 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import type { IActionEvent, IWheelEvent } from '@motajs/render';
|
||||
|
||||
// 内置事件:按下、抬起、点击,以及进入、离开、移动、滚轮
|
||||
export default defineComponent(() => {
|
||||
const log = ref<string[]>([]);
|
||||
const move = ref('—');
|
||||
|
||||
const push = (text: string) => {
|
||||
log.value = [...log.value, text].slice(-4);
|
||||
};
|
||||
|
||||
const handleDown = () => push('按下');
|
||||
const handleUp = () => push('抬起');
|
||||
const handleClick = () => push('点击');
|
||||
const handleEnter = () => push('进入');
|
||||
const handleLeave = () => push('离开');
|
||||
const handleMove = (ev: IActionEvent) => {
|
||||
move.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
|
||||
};
|
||||
const handleWheel = (ev: IWheelEvent) => {
|
||||
push(`滚轮 ${Math.round(ev.wheelY)}`);
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="内置事件" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-rect
|
||||
loc={[24, 56, 160, 48]}
|
||||
fillStyle="#2f6fed"
|
||||
onDown={handleDown}
|
||||
onUp={handleUp}
|
||||
onClick={handleClick}
|
||||
/>
|
||||
<text loc={[64, 73]} text="点我" fillStyle="#e8f0ff" noevent />
|
||||
|
||||
<g-rect
|
||||
loc={[212, 56, 244, 112]}
|
||||
fillStyle="#26364d"
|
||||
onEnter={handleEnter}
|
||||
onLeave={handleLeave}
|
||||
onMove={handleMove}
|
||||
onWheel={handleWheel}
|
||||
/>
|
||||
<text
|
||||
loc={[228, 72]}
|
||||
text="悬停、移动、滚轮"
|
||||
fillStyle="#cfe0ff"
|
||||
noevent
|
||||
/>
|
||||
<text
|
||||
loc={[228, 100]}
|
||||
text={`局部坐标:${move.value}`}
|
||||
fillStyle="#8b98a8"
|
||||
noevent
|
||||
/>
|
||||
|
||||
<text
|
||||
loc={[24, 196]}
|
||||
text={`事件:${log.value.join(' → ')}`}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
<text
|
||||
loc={[24, 236]}
|
||||
text="移动只更新坐标,不写入事件日志"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,76 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import type { IActionEvent } from '@motajs/render';
|
||||
|
||||
// 同一个点击在内层、外层与画布坐标下的不同结果
|
||||
export default defineComponent(() => {
|
||||
const inner = ref('—');
|
||||
const outer = ref('—');
|
||||
const absolute = ref('—');
|
||||
|
||||
// 外层移动与点击都刷新同一组外层坐标
|
||||
const handleOuterPoint = (ev: IActionEvent) => {
|
||||
outer.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
|
||||
absolute.value = `${Math.round(ev.absoluteX)}, ${Math.round(
|
||||
ev.absoluteY
|
||||
)}`;
|
||||
};
|
||||
|
||||
// 内层移动与点击都刷新同一组内层坐标
|
||||
const handleInnerPoint = (ev: IActionEvent) => {
|
||||
inner.value = `${Math.round(ev.offsetX)}, ${Math.round(ev.offsetY)}`;
|
||||
};
|
||||
|
||||
const handleInnerLeave = () => {
|
||||
inner.value = '—';
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="事件坐标" fillStyle="#cfe0ff" />
|
||||
|
||||
<container
|
||||
loc={[24, 60, 216, 180]}
|
||||
onMove={handleOuterPoint}
|
||||
onClick={handleOuterPoint}
|
||||
>
|
||||
<g-rect loc={[0, 0, 216, 180]} fillStyle="#26364d" />
|
||||
<g-rect
|
||||
loc={[36, 40, 144, 88]}
|
||||
fillStyle="#2f6fed"
|
||||
onMove={handleInnerPoint}
|
||||
onClick={handleInnerPoint}
|
||||
onLeave={handleInnerLeave}
|
||||
/>
|
||||
<text
|
||||
loc={[72, 76]}
|
||||
text="点这里"
|
||||
fillStyle="#e8f0ff"
|
||||
noevent
|
||||
/>
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[264, 76]}
|
||||
text={`内层 offset:${inner.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[264, 108]}
|
||||
text={`外层 offset:${outer.value}`}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
<text
|
||||
loc={[264, 140]}
|
||||
text={`画布 absolute:${absolute.value}`}
|
||||
fillStyle="#7ee787"
|
||||
/>
|
||||
<text
|
||||
loc={[24, 264]}
|
||||
text="在内层与外层移动、点击,比较三组坐标"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,95 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import type { IWheelEvent } from '@motajs/render';
|
||||
|
||||
// enter / leave 由悬停集合做差集触发,滚轮与 cursor 跟随命中结果
|
||||
export default defineComponent(() => {
|
||||
const outerState = ref('未进入');
|
||||
const innerState = ref('未进入');
|
||||
const cursor = ref('pointer');
|
||||
const total = ref(0);
|
||||
|
||||
const handleOuterEnter = () => {
|
||||
outerState.value = '进入';
|
||||
cursor.value = 'pointer';
|
||||
};
|
||||
|
||||
const handleOuterLeave = () => {
|
||||
outerState.value = '离开';
|
||||
cursor.value = 'pointer';
|
||||
};
|
||||
|
||||
const handleOuterWheel = (ev: IWheelEvent) => {
|
||||
total.value += ev.wheelY;
|
||||
};
|
||||
|
||||
const handleInnerEnter = () => {
|
||||
innerState.value = '进入';
|
||||
cursor.value = 'text';
|
||||
};
|
||||
|
||||
const handleInnerLeave = () => {
|
||||
innerState.value = '离开';
|
||||
cursor.value = 'pointer';
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="悬停与滚轮" fillStyle="#cfe0ff" />
|
||||
|
||||
<container
|
||||
loc={[24, 64, 220, 176]}
|
||||
cursor="pointer"
|
||||
onEnter={handleOuterEnter}
|
||||
onLeave={handleOuterLeave}
|
||||
onWheel={handleOuterWheel}
|
||||
>
|
||||
<g-rect loc={[0, 0, 220, 176]} fillStyle="#26364d" />
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text="外层:cursor pointer"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<g-rect
|
||||
loc={[40, 64, 140, 80]}
|
||||
fillStyle="#2f6fed"
|
||||
cursor="text"
|
||||
onEnter={handleInnerEnter}
|
||||
onLeave={handleInnerLeave}
|
||||
/>
|
||||
<text
|
||||
loc={[40, 152]}
|
||||
text="内层:cursor text"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[264, 80]}
|
||||
text={`外层:${outerState.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[264, 112]}
|
||||
text={`内层:${innerState.value}`}
|
||||
fillStyle="#7ee787"
|
||||
/>
|
||||
<text
|
||||
loc={[264, 144]}
|
||||
text={`cursor:${cursor.value}`}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
<text
|
||||
loc={[264, 176]}
|
||||
text={`滚轮累计:${Math.round(total.value)}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[24, 264]}
|
||||
text="从内层移回外层时,外层不会重新 enter"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,94 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
import type { IActionEvent } from '@motajs/render';
|
||||
|
||||
// 嵌套容器中的捕获与冒泡,以及可切换的 stopPropagation
|
||||
export default defineComponent(() => {
|
||||
const log = ref<string[]>([]);
|
||||
const stop = ref(false);
|
||||
|
||||
// 每次点击只保留本次交互的日志,不做累积
|
||||
const push = (text: string) => {
|
||||
log.value = [...log.value, text];
|
||||
};
|
||||
|
||||
const handleToggleStop = () => {
|
||||
stop.value = !stop.value;
|
||||
};
|
||||
|
||||
// 外层捕获是一次点击的起点:先清空日志,再记录本次触发的后续事件
|
||||
const handleOuterCapture = () => {
|
||||
log.value = ['外层捕获'];
|
||||
};
|
||||
|
||||
const handleOuterBubble = () => push('外层冒泡');
|
||||
const handleInnerCapture = () => push('内层捕获');
|
||||
const handleInnerBubble = () => push('内层冒泡');
|
||||
const handleButtonCapture = () => push('按钮捕获');
|
||||
|
||||
const handleButtonBubble = (ev: IActionEvent) => {
|
||||
// 先记录按钮冒泡,再按开关决定是否截断向外传播
|
||||
push('按钮冒泡');
|
||||
if (stop.value) ev.stopPropagation();
|
||||
};
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="捕获与冒泡" fillStyle="#cfe0ff" />
|
||||
|
||||
{/* 切换 stop:只影响下方按钮冒泡是否继续向外层传递 */}
|
||||
<container loc={[24, 52, 156, 36]} onClick={handleToggleStop}>
|
||||
<g-rect
|
||||
loc={[0, 0, 156, 36]}
|
||||
fillStyle={stop.value ? '#f2b84b' : '#2f6fed'}
|
||||
/>
|
||||
<text
|
||||
loc={[18, 10]}
|
||||
text={stop.value ? 'stop:开启' : 'stop:关闭'}
|
||||
fillStyle="#141a22"
|
||||
/>
|
||||
</container>
|
||||
|
||||
{/* 外层捕获是一次点击的起点:先清空日志,再记录本次触发的后续事件 */}
|
||||
<container
|
||||
loc={[24, 108, 264, 172]}
|
||||
onClickCapture={handleOuterCapture}
|
||||
onClick={handleOuterBubble}
|
||||
>
|
||||
<g-rect loc={[0, 0, 264, 172]} fillStyle="#26364d" />
|
||||
<container
|
||||
loc={[32, 32, 200, 108]}
|
||||
onClickCapture={handleInnerCapture}
|
||||
onClick={handleInnerBubble}
|
||||
>
|
||||
<g-rect loc={[0, 0, 200, 108]} fillStyle="#1d2a3a" />
|
||||
<g-rect
|
||||
loc={[40, 28, 120, 52]}
|
||||
fillStyle="#2f6fed"
|
||||
onClickCapture={handleButtonCapture}
|
||||
onClick={handleButtonBubble}
|
||||
/>
|
||||
<text loc={[40, 90]} text="点按钮" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
|
||||
<text loc={[308, 80]} text="只显示本次点击" fillStyle="#8b98a8" />
|
||||
|
||||
{[0, 1, 2, 3, 4, 5].map(index => (
|
||||
<text
|
||||
key={index}
|
||||
loc={[308, 112 + index * 24]}
|
||||
text={log.value[index] ?? ''}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
))}
|
||||
|
||||
<text
|
||||
loc={[24, 292]}
|
||||
text="stop 开启后,按钮冒泡不再传给外层"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,47 @@
|
||||
import { Texture } from '@motajs/render';
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 演示用纹理:只在 demo 内部生成,正文不展示生成方式
|
||||
function createDemoTexture() {
|
||||
const canvas = document.createElement('canvas');
|
||||
canvas.width = 64;
|
||||
canvas.height = 64;
|
||||
|
||||
const ctx = canvas.getContext('2d')!;
|
||||
ctx.fillStyle = '#1d2733';
|
||||
ctx.fillRect(0, 0, 64, 64);
|
||||
ctx.strokeStyle = '#7aa7ff';
|
||||
ctx.lineWidth = 4;
|
||||
ctx.strokeRect(8, 8, 48, 48);
|
||||
ctx.fillStyle = '#f2b84b';
|
||||
ctx.beginPath();
|
||||
ctx.arc(32, 32, 14, 0, Math.PI * 2);
|
||||
ctx.fill();
|
||||
|
||||
return new Texture(canvas);
|
||||
}
|
||||
|
||||
const demoTexture = createDemoTexture();
|
||||
|
||||
// 单张图片:loc 固定为 [40, 64, 128, 128]
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="<image> 按 loc 显示纹理的效果"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<image image={demoTexture} loc={[40, 64, 128, 128]} />
|
||||
|
||||
<text
|
||||
loc={[40, 208]}
|
||||
text="loc = [40, 64, 128, 128]"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,48 @@
|
||||
import { Texture } from '@motajs/render';
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 演示用纹理:只在 demo 内部生成,正文不展示生成方式
|
||||
function createDemoTexture() {
|
||||
const canvas = document.createElement('canvas');
|
||||
canvas.width = 64;
|
||||
canvas.height = 64;
|
||||
|
||||
const ctx = canvas.getContext('2d')!;
|
||||
ctx.fillStyle = '#1d2733';
|
||||
ctx.fillRect(0, 0, 64, 64);
|
||||
ctx.strokeStyle = '#7aa7ff';
|
||||
ctx.lineWidth = 4;
|
||||
ctx.strokeRect(8, 8, 48, 48);
|
||||
ctx.fillStyle = '#f2b84b';
|
||||
ctx.beginPath();
|
||||
ctx.arc(32, 32, 14, 0, Math.PI * 2);
|
||||
ctx.fill();
|
||||
|
||||
return new Texture(canvas);
|
||||
}
|
||||
|
||||
const demoTexture = createDemoTexture();
|
||||
|
||||
// 同一张纹理放进三种尺寸的矩形
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="同一张图,三种显示尺寸"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<image image={demoTexture} loc={[48, 96, 64, 64]} />
|
||||
<text loc={[48, 172]} text="64×64" fillStyle="#8b98a8" />
|
||||
|
||||
<image image={demoTexture} loc={[192, 80, 96, 96]} />
|
||||
<text loc={[192, 188]} text="96×96" fillStyle="#8b98a8" />
|
||||
|
||||
<image image={demoTexture} loc={[336, 64, 128, 128]} />
|
||||
<text loc={[336, 204]} text="128×128" fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,50 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
// 示例(一)的 live:720×480 骨架、标题、关闭按钮与左右占位
|
||||
export default defineComponent(() => {
|
||||
const hint = ref('骨架阶段:先确认面板能显示、关闭按钮能用');
|
||||
|
||||
const close = () => {
|
||||
// 文档站没有真实 UI 栈,用一行提示代替 controller.close
|
||||
hint.value = '已请求关闭(真实面板会调用 controller.close)';
|
||||
};
|
||||
|
||||
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>
|
||||
|
||||
<container loc={[54, 110, 400, 330]}>
|
||||
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="道具网格占位" fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
|
||||
<container loc={[470, 110, 196, 330]}>
|
||||
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="详情占位" fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
|
||||
<text loc={[54, 420]} text={hint.value} fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,192 @@
|
||||
import { computed, defineComponent, ref } from 'vue';
|
||||
|
||||
interface Item {
|
||||
id: string;
|
||||
name: string;
|
||||
count: number;
|
||||
desc: string;
|
||||
}
|
||||
|
||||
interface ItemCellProps {
|
||||
item: Item;
|
||||
selected: boolean;
|
||||
size: number;
|
||||
}
|
||||
|
||||
type ItemCellEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemCellOptions {
|
||||
props: (keyof ItemCellProps)[];
|
||||
emits: (keyof ItemCellEmits)[];
|
||||
}
|
||||
|
||||
const itemCellOptions: ItemCellOptions = {
|
||||
props: ['item', 'selected', 'size'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
// 单个格子:只负责画名称、数量与选中态,点击后把 id 交给父组件
|
||||
// 格子只接收结果,选中状态由父组件持有
|
||||
const ItemCell = defineComponent<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>((props, { emit }) => {
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
onClick={() => emit('select', props.item.id)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
circle={[10]}
|
||||
fill
|
||||
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[1, 1, props.size - 2, props.size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
|
||||
/>
|
||||
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[8, props.size - 24]}
|
||||
text={`× ${props.item.count}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, itemCellOptions);
|
||||
|
||||
interface ItemGridProps {
|
||||
items: Item[];
|
||||
selectedId: string;
|
||||
columns: number;
|
||||
cellSize: number;
|
||||
gap: number;
|
||||
}
|
||||
|
||||
type ItemGridEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemGridOptions {
|
||||
props: (keyof ItemGridProps)[];
|
||||
emits: (keyof ItemGridEmits)[];
|
||||
}
|
||||
|
||||
const itemGridOptions: ItemGridOptions = {
|
||||
props: ['items', 'selectedId', 'columns', 'cellSize', 'gap'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
// 网格:用列数、格子尺寸与间距算出位置,不写死每格坐标
|
||||
const ItemGrid = defineComponent<
|
||||
ItemGridProps,
|
||||
ItemGridEmits,
|
||||
keyof ItemGridEmits
|
||||
>((props, { emit }) => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 0, 0]}>
|
||||
{props.items.map((item, index) => {
|
||||
const col = index % props.columns;
|
||||
const row = Math.floor(index / props.columns);
|
||||
const x = col * (props.cellSize + props.gap);
|
||||
const y = row * (props.cellSize + props.gap);
|
||||
return (
|
||||
<container loc={[x, y]}>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === props.selectedId}
|
||||
size={props.cellSize}
|
||||
onSelect={id => emit('select', id)}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
})}
|
||||
</container>
|
||||
);
|
||||
}, itemGridOptions);
|
||||
|
||||
const items: 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: '恢复少量生命。' }
|
||||
];
|
||||
|
||||
// 示例(二)的 live:骨架 + 网格 + 选中态
|
||||
export default defineComponent(() => {
|
||||
const selectedId = ref('potion-red');
|
||||
const selectedItem = computed(() =>
|
||||
items.find(item => item.id === selectedId.value)
|
||||
);
|
||||
|
||||
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]}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 56, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle="#7a3d3d"
|
||||
/>
|
||||
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
|
||||
</container>
|
||||
|
||||
<container loc={[54, 110, 400, 330]}>
|
||||
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
|
||||
<ItemGrid
|
||||
items={items}
|
||||
selectedId={selectedId.value}
|
||||
columns={5}
|
||||
cellSize={66}
|
||||
gap={8}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[470, 110, 196, 330]}>
|
||||
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
|
||||
<text
|
||||
loc={[16, 16]}
|
||||
text={
|
||||
selectedItem.value ? selectedItem.value.name : '未选择'
|
||||
}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 48]}
|
||||
text={
|
||||
selectedItem.value
|
||||
? `数量 × ${selectedItem.value.count}`
|
||||
: '点击左侧格子'
|
||||
}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,251 @@
|
||||
import { computed, defineComponent, ref } from 'vue';
|
||||
|
||||
interface Item {
|
||||
id: string;
|
||||
name: string;
|
||||
count: number;
|
||||
desc: string;
|
||||
}
|
||||
|
||||
interface ItemCellProps {
|
||||
item: Item;
|
||||
selected: boolean;
|
||||
size: number;
|
||||
}
|
||||
|
||||
type ItemCellEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemCellOptions {
|
||||
props: (keyof ItemCellProps)[];
|
||||
emits: (keyof ItemCellEmits)[];
|
||||
}
|
||||
|
||||
const itemCellOptions: ItemCellOptions = {
|
||||
props: ['item', 'selected', 'size'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
// 网格、详情与父组件共享同一份道具数据
|
||||
const ItemCell = defineComponent<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>((props, { emit }) => {
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
onClick={() => emit('select', props.item.id)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
circle={[10]}
|
||||
fill
|
||||
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[1, 1, props.size - 2, props.size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
|
||||
/>
|
||||
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[8, props.size - 24]}
|
||||
text={`× ${props.item.count}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, itemCellOptions);
|
||||
|
||||
interface ItemGridProps {
|
||||
items: Item[];
|
||||
selectedId: string;
|
||||
columns: number;
|
||||
cellSize: number;
|
||||
gap: number;
|
||||
}
|
||||
|
||||
type ItemGridEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemGridOptions {
|
||||
props: (keyof ItemGridProps)[];
|
||||
emits: (keyof ItemGridEmits)[];
|
||||
}
|
||||
|
||||
const itemGridOptions: ItemGridOptions = {
|
||||
props: ['items', 'selectedId', 'columns', 'cellSize', 'gap'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
const ItemGrid = defineComponent<
|
||||
ItemGridProps,
|
||||
ItemGridEmits,
|
||||
keyof ItemGridEmits
|
||||
>((props, { emit }) => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 0, 0]}>
|
||||
{props.items.map((item, index) => {
|
||||
const col = index % props.columns;
|
||||
const row = Math.floor(index / props.columns);
|
||||
const x = col * (props.cellSize + props.gap);
|
||||
const y = row * (props.cellSize + props.gap);
|
||||
return (
|
||||
<container loc={[x, y]}>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === props.selectedId}
|
||||
size={props.cellSize}
|
||||
onSelect={id => emit('select', id)}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
})}
|
||||
</container>
|
||||
);
|
||||
}, itemGridOptions);
|
||||
|
||||
interface ItemDetailProps {
|
||||
item?: Item;
|
||||
}
|
||||
|
||||
type ItemDetailEmits = {
|
||||
clear: () => void;
|
||||
};
|
||||
|
||||
interface ItemDetailOptions {
|
||||
props: (keyof ItemDetailProps)[];
|
||||
emits: (keyof ItemDetailEmits)[];
|
||||
}
|
||||
|
||||
const itemDetailOptions: ItemDetailOptions = {
|
||||
props: ['item'],
|
||||
emits: ['clear']
|
||||
};
|
||||
|
||||
// 右侧详情:没有选中时显示提示,有选中时显示名称、数量与描述
|
||||
// 详情只接收选中的道具,没有选中时显示提示
|
||||
const ItemDetail = defineComponent<
|
||||
ItemDetailProps,
|
||||
ItemDetailEmits,
|
||||
keyof ItemDetailEmits
|
||||
>((props, { emit }) => {
|
||||
const clear = () => emit('clear');
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 196, 330]}>
|
||||
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
|
||||
|
||||
{/* 两块都渲染,用 hidden 切换 */}
|
||||
<container hidden={!!props.item}>
|
||||
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
|
||||
</container>
|
||||
|
||||
<container hidden={!props.item}>
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={props.item ? props.item.name : ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 84]}
|
||||
text={props.item ? `数量:${props.item.count}` : ''}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 120]}
|
||||
text={props.item ? props.item.desc : ''}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 156]}
|
||||
text="live 用 text 等价展示说明"
|
||||
fillStyle="#4f6d94"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[16, 286, 164, 28]} onClick={clear}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 164, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
}, itemDetailOptions);
|
||||
|
||||
// 假数据只用于演示,可替换成存档数据
|
||||
const items: 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: '恢复少量生命。' }
|
||||
];
|
||||
|
||||
// 示例(三)的 live:骨架 + 网格 + 选中态 + 详情区
|
||||
export default defineComponent(() => {
|
||||
const selectedId = ref('potion-red');
|
||||
const selectedItem = computed(() =>
|
||||
items.find(item => item.id === selectedId.value)
|
||||
);
|
||||
|
||||
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]}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 56, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle="#7a3d3d"
|
||||
/>
|
||||
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
|
||||
</container>
|
||||
|
||||
<container loc={[54, 110, 400, 330]}>
|
||||
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
|
||||
<ItemGrid
|
||||
items={items}
|
||||
selectedId={selectedId.value}
|
||||
columns={5}
|
||||
cellSize={66}
|
||||
gap={8}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[470, 110, 196, 330]}>
|
||||
<ItemDetail
|
||||
item={selectedItem.value}
|
||||
onClear={() => (selectedId.value = '')}
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,301 @@
|
||||
import { computed, defineComponent, ref } from 'vue';
|
||||
|
||||
interface Item {
|
||||
id: string;
|
||||
name: string;
|
||||
count: number;
|
||||
desc: string;
|
||||
}
|
||||
|
||||
interface ItemCellProps {
|
||||
item: Item;
|
||||
selected: boolean;
|
||||
size: number;
|
||||
}
|
||||
|
||||
type ItemCellEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemCellOptions {
|
||||
props: (keyof ItemCellProps)[];
|
||||
emits: (keyof ItemCellEmits)[];
|
||||
}
|
||||
|
||||
const itemCellOptions: ItemCellOptions = {
|
||||
props: ['item', 'selected', 'size'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
// 滚动演示沿用网格与详情的组件结构
|
||||
const ItemCell = defineComponent<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>((props, { emit }) => {
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
onClick={() => emit('select', props.item.id)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
circle={[10]}
|
||||
fill
|
||||
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[1, 1, props.size - 2, props.size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
|
||||
/>
|
||||
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[8, props.size - 24]}
|
||||
text={`× ${props.item.count}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, itemCellOptions);
|
||||
|
||||
interface ItemDetailProps {
|
||||
item?: Item;
|
||||
}
|
||||
|
||||
type ItemDetailEmits = {
|
||||
clear: () => void;
|
||||
};
|
||||
|
||||
interface ItemDetailOptions {
|
||||
props: (keyof ItemDetailProps)[];
|
||||
emits: (keyof ItemDetailEmits)[];
|
||||
}
|
||||
|
||||
const itemDetailOptions: ItemDetailOptions = {
|
||||
props: ['item'],
|
||||
emits: ['clear']
|
||||
};
|
||||
|
||||
const ItemDetail = defineComponent<
|
||||
ItemDetailProps,
|
||||
ItemDetailEmits,
|
||||
keyof ItemDetailEmits
|
||||
>((props, { emit }) => {
|
||||
const clear = () => emit('clear');
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 196, 330]}>
|
||||
<g-rect loc={[0, 0, 196, 330]} fill fillStyle="#101820" />
|
||||
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
|
||||
|
||||
<container hidden={!!props.item}>
|
||||
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
|
||||
</container>
|
||||
|
||||
<container hidden={!props.item}>
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={props.item ? props.item.name : ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 84]}
|
||||
text={props.item ? `数量:${props.item.count}` : ''}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 120]}
|
||||
text={props.item ? props.item.desc : ''}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[16, 286, 164, 28]} onClick={clear}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 164, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
}, itemDetailOptions);
|
||||
|
||||
const NAMES = [
|
||||
'红药水',
|
||||
'蓝药水',
|
||||
'黄钥匙',
|
||||
'蓝钥匙',
|
||||
'木剑',
|
||||
'木盾',
|
||||
'红宝石',
|
||||
'蓝宝石',
|
||||
'回城卷轴',
|
||||
'面包'
|
||||
];
|
||||
|
||||
// 40 个假道具用来撑出可滚动的内容
|
||||
const items: Item[] = Array.from({ length: 40 }, (_, index) => ({
|
||||
id: `item-${index + 1}`,
|
||||
name: NAMES[index % NAMES.length],
|
||||
count: (index % 6) + 1,
|
||||
desc: `第 ${index + 1} 个道具。`
|
||||
}));
|
||||
|
||||
const COLUMNS = 5;
|
||||
const CELL_SIZE = 66;
|
||||
const GAP = 8;
|
||||
const ROW_PITCH = CELL_SIZE + GAP;
|
||||
const VIEW_WIDTH = 372;
|
||||
const VIEW_HEIGHT = 294;
|
||||
const ROWS = Math.ceil(items.length / COLUMNS);
|
||||
const CONTENT_HEIGHT = ROWS * ROW_PITCH;
|
||||
const MAX_START_ROW = Math.max(0, ROWS - Math.floor(VIEW_HEIGHT / ROW_PITCH));
|
||||
const MAX_SCROLL = MAX_START_ROW * ROW_PITCH;
|
||||
|
||||
// 示例(四)的 live:用元素层等价实现 Scroll 的滚动窗口与滚动条
|
||||
// 滚动位置只保存在本地 ref,滚动条由计算出的位置绘制
|
||||
export default defineComponent(() => {
|
||||
const selectedId = ref('item-1');
|
||||
const scrollTop = ref(0);
|
||||
const selectedItem = computed(() =>
|
||||
items.find(item => item.id === selectedId.value)
|
||||
);
|
||||
const startRow = computed(() => Math.round(scrollTop.value / ROW_PITCH));
|
||||
|
||||
// 滚轮与按钮都只调整 scrollTop
|
||||
const scrollRows = (delta: number) => {
|
||||
const current = Math.round(scrollTop.value / ROW_PITCH);
|
||||
const next = Math.max(0, Math.min(MAX_START_ROW, current + delta));
|
||||
scrollTop.value = next * ROW_PITCH;
|
||||
};
|
||||
|
||||
const onWheel = (ev: { wheelY: number }) => {
|
||||
scrollRows(ev.wheelY > 0 ? 1 : -1);
|
||||
};
|
||||
|
||||
const backToTop = () => {
|
||||
scrollTop.value = 0;
|
||||
};
|
||||
|
||||
const toBottom = () => {
|
||||
scrollTop.value = MAX_SCROLL;
|
||||
};
|
||||
|
||||
const thumbHeight = Math.max(
|
||||
28,
|
||||
(VIEW_HEIGHT / CONTENT_HEIGHT) * VIEW_HEIGHT
|
||||
);
|
||||
const thumbY =
|
||||
MAX_SCROLL === 0
|
||||
? 0
|
||||
: (scrollTop.value / MAX_SCROLL) * (VIEW_HEIGHT - thumbHeight);
|
||||
|
||||
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]}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 56, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle="#7a3d3d"
|
||||
/>
|
||||
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
|
||||
</container>
|
||||
|
||||
<container loc={[54, 110, 400, 330]}>
|
||||
<g-rect loc={[0, 0, 400, 330]} fill fillStyle="#101820" />
|
||||
|
||||
<container
|
||||
loc={[0, 0, VIEW_WIDTH, VIEW_HEIGHT]}
|
||||
onWheel={onWheel}
|
||||
>
|
||||
{items.map((item, index) => {
|
||||
const row = Math.floor(index / COLUMNS);
|
||||
// 只渲染视口附近的行,等价于 Scroll 的虚拟滚动
|
||||
if (row < startRow.value || row >= startRow.value + 5) {
|
||||
return null;
|
||||
}
|
||||
const col = index % COLUMNS;
|
||||
return (
|
||||
<container
|
||||
key={item.id}
|
||||
loc={[
|
||||
col * ROW_PITCH,
|
||||
(row - startRow.value) * ROW_PITCH
|
||||
]}
|
||||
>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === selectedId.value}
|
||||
size={CELL_SIZE}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
})}
|
||||
</container>
|
||||
|
||||
<g-rect
|
||||
loc={[378, 0, 6, VIEW_HEIGHT]}
|
||||
fill
|
||||
fillStyle="#1b2634"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[378, thumbY, 6, thumbHeight]}
|
||||
circle={[3]}
|
||||
fill
|
||||
fillStyle="#3f6fa8"
|
||||
/>
|
||||
|
||||
<container loc={[0, 302, 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, 302, 90, 28]} onClick={toBottom}>
|
||||
<g-rectr
|
||||
loc={[0, 0, 90, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[10, 6]} text="滚到底部" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
<text
|
||||
loc={[204, 308]}
|
||||
text={`已滚动 ${scrollTop.value} / ${MAX_SCROLL}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[470, 110, 196, 330]}>
|
||||
<ItemDetail
|
||||
item={selectedItem.value}
|
||||
onClear={() => (selectedId.value = '')}
|
||||
/>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,402 @@
|
||||
import { computed, defineComponent, ref, watch } from 'vue';
|
||||
|
||||
interface Item {
|
||||
id: string;
|
||||
name: string;
|
||||
count: number;
|
||||
desc: string;
|
||||
}
|
||||
|
||||
interface ItemCellProps {
|
||||
item: Item;
|
||||
selected: boolean;
|
||||
equipped: boolean;
|
||||
size: number;
|
||||
}
|
||||
|
||||
type ItemCellEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemCellOptions {
|
||||
props: (keyof ItemCellProps)[];
|
||||
emits: (keyof ItemCellEmits)[];
|
||||
}
|
||||
|
||||
const itemCellOptions: ItemCellOptions = {
|
||||
props: ['item', 'selected', 'equipped', 'size'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
// 装备、使用与关闭的状态全部集中在根组件
|
||||
const ItemCell = defineComponent<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>((props, { emit }) => {
|
||||
const strokeStyle = computed(() => {
|
||||
if (props.equipped) return '#7ee787';
|
||||
if (props.selected) return '#f2b84b';
|
||||
return '#33465f';
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
onClick={() => emit('select', props.item.id)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
circle={[10]}
|
||||
fill
|
||||
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[1, 1, props.size - 2, props.size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={strokeStyle.value}
|
||||
/>
|
||||
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[8, props.size - 24]}
|
||||
text={`× ${props.item.count}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, itemCellOptions);
|
||||
|
||||
interface ItemDetailProps {
|
||||
item?: Item;
|
||||
}
|
||||
|
||||
type ItemDetailEmits = {
|
||||
clear: () => void;
|
||||
};
|
||||
|
||||
interface ItemDetailOptions {
|
||||
props: (keyof ItemDetailProps)[];
|
||||
emits: (keyof ItemDetailEmits)[];
|
||||
}
|
||||
|
||||
const itemDetailOptions: ItemDetailOptions = {
|
||||
props: ['item'],
|
||||
emits: ['clear']
|
||||
};
|
||||
|
||||
// 详情只负责显示父组件算好的结果
|
||||
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}>
|
||||
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
|
||||
</container>
|
||||
|
||||
<container hidden={!props.item}>
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={props.item ? props.item.name : ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 84]}
|
||||
text={props.item ? `数量:${props.item.count}` : ''}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 120]}
|
||||
text={props.item ? props.item.desc : ''}
|
||||
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>
|
||||
);
|
||||
}, itemDetailOptions);
|
||||
|
||||
interface ActionBarProps {
|
||||
canEquip: boolean;
|
||||
canUse: boolean;
|
||||
equipped: boolean;
|
||||
}
|
||||
|
||||
type ActionBarEmits = {
|
||||
equip: () => void;
|
||||
use: () => void;
|
||||
close: () => void;
|
||||
};
|
||||
|
||||
interface ActionBarOptions {
|
||||
props: (keyof ActionBarProps)[];
|
||||
emits: (keyof ActionBarEmits)[];
|
||||
}
|
||||
|
||||
const actionBarOptions: ActionBarOptions = {
|
||||
props: ['canEquip', 'canUse', 'equipped'],
|
||||
emits: ['equip', 'use', 'close']
|
||||
};
|
||||
|
||||
// 按钮的可用性由父组件传入,自己不做业务判断
|
||||
const ActionBar = defineComponent<
|
||||
ActionBarProps,
|
||||
ActionBarEmits,
|
||||
keyof ActionBarEmits
|
||||
>((props, { emit }) => {
|
||||
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>
|
||||
);
|
||||
}, actionBarOptions);
|
||||
|
||||
const NAMES = [
|
||||
'红药水',
|
||||
'蓝药水',
|
||||
'黄钥匙',
|
||||
'蓝钥匙',
|
||||
'木剑',
|
||||
'木盾',
|
||||
'红宝石',
|
||||
'蓝宝石',
|
||||
'回城卷轴',
|
||||
'面包'
|
||||
];
|
||||
|
||||
// 40 个假道具同时用于测试滚动与使用次数
|
||||
const sourceItems: Item[] = Array.from({ length: 40 }, (_, index) => ({
|
||||
id: `item-${index + 1}`,
|
||||
name: NAMES[index % NAMES.length],
|
||||
count: (index % 6) + 1,
|
||||
desc: `第 ${index + 1} 个道具。`
|
||||
}));
|
||||
|
||||
const COLUMNS = 5;
|
||||
const CELL_SIZE = 66;
|
||||
const GAP = 8;
|
||||
const ROW_PITCH = CELL_SIZE + GAP;
|
||||
const VIEW_WIDTH = 372;
|
||||
const VIEW_HEIGHT = 244;
|
||||
const ROWS = Math.ceil(sourceItems.length / COLUMNS);
|
||||
const MAX_START_ROW = Math.max(0, ROWS - Math.floor(VIEW_HEIGHT / ROW_PITCH));
|
||||
const MAX_SCROLL = MAX_START_ROW * ROW_PITCH;
|
||||
|
||||
// 示例(五)的 live:滚动网格 + 详情 + 装备 / 使用 / 关闭
|
||||
// items 复制一份,使用道具时只改本地副本
|
||||
export default defineComponent(() => {
|
||||
const items = ref<Item[]>(sourceItems.map(item => ({ ...item })));
|
||||
const selectedId = ref('item-1');
|
||||
const equippedId = ref('');
|
||||
const hint = ref('选择道具后可以装备或使用');
|
||||
const scrollTop = ref(0);
|
||||
|
||||
const selectedItem = computed(() =>
|
||||
items.value.find(item => item.id === selectedId.value)
|
||||
);
|
||||
const canEquip = computed(() => !!selectedItem.value);
|
||||
const canUse = computed(
|
||||
() => !!selectedItem.value && selectedItem.value.count > 0
|
||||
);
|
||||
const isEquipped = computed(
|
||||
() => !!selectedId.value && equippedId.value === selectedId.value
|
||||
);
|
||||
const startRow = computed(() => Math.round(scrollTop.value / ROW_PITCH));
|
||||
|
||||
const equip = () => {
|
||||
if (!selectedItem.value) return;
|
||||
equippedId.value = selectedItem.value.id;
|
||||
hint.value = `已装备:${selectedItem.value.name}`;
|
||||
};
|
||||
|
||||
const use = () => {
|
||||
const item = selectedItem.value;
|
||||
if (!item || item.count <= 0) return;
|
||||
item.count -= 1;
|
||||
};
|
||||
|
||||
watch(
|
||||
() => selectedItem.value?.count ?? 0,
|
||||
(next, prev) => {
|
||||
hint.value = `数量:${prev} → ${next}`;
|
||||
}
|
||||
);
|
||||
|
||||
const scrollRows = (delta: number) => {
|
||||
const current = Math.round(scrollTop.value / ROW_PITCH);
|
||||
const next = Math.max(0, Math.min(MAX_START_ROW, current + delta));
|
||||
scrollTop.value = next * ROW_PITCH;
|
||||
};
|
||||
|
||||
const onWheel = (ev: { wheelY: number }) => {
|
||||
scrollRows(ev.wheelY > 0 ? 1 : -1);
|
||||
};
|
||||
|
||||
const thumbHeight = Math.max(
|
||||
28,
|
||||
(VIEW_HEIGHT / (ROWS * ROW_PITCH)) * VIEW_HEIGHT
|
||||
);
|
||||
const thumbY =
|
||||
MAX_SCROLL === 0
|
||||
? 0
|
||||
: (scrollTop.value / MAX_SCROLL) * (VIEW_HEIGHT - thumbHeight);
|
||||
|
||||
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={[54, 100, 400, 280]}>
|
||||
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
|
||||
|
||||
<container
|
||||
loc={[0, 0, VIEW_WIDTH, VIEW_HEIGHT]}
|
||||
onWheel={onWheel}
|
||||
>
|
||||
{items.value.map((item, index) => {
|
||||
const row = Math.floor(index / COLUMNS);
|
||||
if (row < startRow.value || row >= startRow.value + 4) {
|
||||
return null;
|
||||
}
|
||||
const col = index % COLUMNS;
|
||||
return (
|
||||
<container
|
||||
key={item.id}
|
||||
loc={[
|
||||
col * ROW_PITCH,
|
||||
(row - startRow.value) * ROW_PITCH
|
||||
]}
|
||||
>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === selectedId.value}
|
||||
equipped={item.id === equippedId.value}
|
||||
size={CELL_SIZE}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
})}
|
||||
</container>
|
||||
|
||||
<g-rect
|
||||
loc={[378, 0, 6, VIEW_HEIGHT]}
|
||||
fill
|
||||
fillStyle="#1b2634"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[378, thumbY, 6, thumbHeight]}
|
||||
circle={[3]}
|
||||
fill
|
||||
fillStyle="#3f6fa8"
|
||||
/>
|
||||
|
||||
<container
|
||||
loc={[0, 252, 90, 28]}
|
||||
onClick={() => scrollRows(-1)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 90, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[10, 6]} text="上一行" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
<container
|
||||
loc={[100, 252, 90, 28]}
|
||||
onClick={() => scrollRows(1)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 90, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[10, 6]} text="下一行" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
<text
|
||||
loc={[204, 258]}
|
||||
text={`已滚动 ${scrollTop.value} / ${MAX_SCROLL}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[470, 100, 196, 280]}>
|
||||
<ItemDetail
|
||||
item={selectedItem.value}
|
||||
onClear={() => (selectedId.value = '')}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[54, 392, 304, 32]}>
|
||||
<ActionBar
|
||||
canEquip={canEquip.value}
|
||||
canUse={canUse.value}
|
||||
equipped={isEquipped.value}
|
||||
onEquip={equip}
|
||||
onUse={use}
|
||||
onClose={() => (hint.value = '已请求关闭')}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<text loc={[54, 432]} text={hint.value} fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,482 @@
|
||||
import {
|
||||
computed,
|
||||
defineComponent,
|
||||
onMounted,
|
||||
onUnmounted,
|
||||
ref,
|
||||
watch
|
||||
} from 'vue';
|
||||
|
||||
interface Item {
|
||||
id: string;
|
||||
name: string;
|
||||
count: number;
|
||||
desc: string;
|
||||
}
|
||||
|
||||
interface ItemCellProps {
|
||||
item: Item;
|
||||
selected: boolean;
|
||||
equipped: boolean;
|
||||
size: number;
|
||||
pulse: number;
|
||||
}
|
||||
|
||||
type ItemCellEmits = {
|
||||
select: (id: string) => void;
|
||||
};
|
||||
|
||||
interface ItemCellOptions {
|
||||
props: (keyof ItemCellProps)[];
|
||||
emits: (keyof ItemCellEmits)[];
|
||||
}
|
||||
|
||||
const itemCellOptions: ItemCellOptions = {
|
||||
props: ['item', 'selected', 'equipped', 'size', 'pulse'],
|
||||
emits: ['select']
|
||||
};
|
||||
|
||||
// 完整示例把网格、详情、滚动、装备与动画放在一个文件里
|
||||
const ItemCell = defineComponent<
|
||||
ItemCellProps,
|
||||
ItemCellEmits,
|
||||
keyof ItemCellEmits
|
||||
>((props, { emit }) => {
|
||||
const strokeStyle = computed(() => {
|
||||
if (props.equipped) return '#7ee787';
|
||||
if (props.selected) return '#f2b84b';
|
||||
return '#33465f';
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
onClick={() => emit('select', props.item.id)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, props.size, props.size]}
|
||||
circle={[10]}
|
||||
fill
|
||||
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[1, 1, props.size - 2, props.size - 2]}
|
||||
circle={[9]}
|
||||
stroke
|
||||
strokeStyle={strokeStyle.value}
|
||||
alpha={props.selected ? props.pulse : 1}
|
||||
/>
|
||||
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
|
||||
<text
|
||||
loc={[8, props.size - 24]}
|
||||
text={`× ${props.item.count}`}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
}, itemCellOptions);
|
||||
|
||||
interface ItemDetailProps {
|
||||
item?: Item;
|
||||
pulse: number;
|
||||
}
|
||||
|
||||
type ItemDetailEmits = {
|
||||
clear: () => void;
|
||||
};
|
||||
|
||||
interface ItemDetailOptions {
|
||||
props: (keyof ItemDetailProps)[];
|
||||
emits: (keyof ItemDetailEmits)[];
|
||||
}
|
||||
|
||||
const itemDetailOptions: ItemDetailOptions = {
|
||||
props: ['item', 'pulse'],
|
||||
emits: ['clear']
|
||||
};
|
||||
|
||||
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" />
|
||||
{/* 顶部亮条只改 alpha 与 scale,不重建组件 */}
|
||||
<g-rect
|
||||
loc={[0, 0, 196, 4]}
|
||||
fill
|
||||
fillStyle="#f2b84b"
|
||||
alpha={props.pulse}
|
||||
scale={[1, 0.5 + props.pulse]}
|
||||
/>
|
||||
<text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />
|
||||
|
||||
<container hidden={!!props.item}>
|
||||
<text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
|
||||
</container>
|
||||
|
||||
<container hidden={!props.item}>
|
||||
<text
|
||||
loc={[16, 52]}
|
||||
text={props.item ? props.item.name : ''}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 84]}
|
||||
text={props.item ? `数量:${props.item.count}` : ''}
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[16, 120]}
|
||||
text={props.item ? props.item.desc : ''}
|
||||
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>
|
||||
);
|
||||
}, itemDetailOptions);
|
||||
|
||||
interface ActionBarProps {
|
||||
canEquip: boolean;
|
||||
canUse: boolean;
|
||||
equipped: boolean;
|
||||
}
|
||||
|
||||
type ActionBarEmits = {
|
||||
equip: () => void;
|
||||
use: () => void;
|
||||
close: () => void;
|
||||
};
|
||||
|
||||
interface ActionBarOptions {
|
||||
props: (keyof ActionBarProps)[];
|
||||
emits: (keyof ActionBarEmits)[];
|
||||
}
|
||||
|
||||
const actionBarOptions: ActionBarOptions = {
|
||||
props: ['canEquip', 'canUse', 'equipped'],
|
||||
emits: ['equip', 'use', 'close']
|
||||
};
|
||||
|
||||
const ActionBar = defineComponent<
|
||||
ActionBarProps,
|
||||
ActionBarEmits,
|
||||
keyof ActionBarEmits
|
||||
>((props, { emit }) => {
|
||||
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>
|
||||
);
|
||||
}, actionBarOptions);
|
||||
|
||||
const NAMES = [
|
||||
'红药水',
|
||||
'蓝药水',
|
||||
'黄钥匙',
|
||||
'蓝钥匙',
|
||||
'木剑',
|
||||
'木盾',
|
||||
'红宝石',
|
||||
'蓝宝石',
|
||||
'回城卷轴',
|
||||
'面包'
|
||||
];
|
||||
|
||||
const sourceItems: Item[] = Array.from({ length: 40 }, (_, index) => ({
|
||||
id: `item-${index + 1}`,
|
||||
name: NAMES[index % NAMES.length],
|
||||
count: (index % 6) + 1,
|
||||
desc: `第 ${index + 1} 个道具。`
|
||||
}));
|
||||
|
||||
const COLUMNS = 5;
|
||||
const CELL_SIZE = 66;
|
||||
const GAP = 8;
|
||||
const ROW_PITCH = CELL_SIZE + GAP;
|
||||
const VIEW_WIDTH = 372;
|
||||
const VIEW_HEIGHT = 244;
|
||||
const ROWS = Math.ceil(sourceItems.length / COLUMNS);
|
||||
const MAX_START_ROW = Math.max(0, ROWS - Math.floor(VIEW_HEIGHT / ROW_PITCH));
|
||||
const MAX_SCROLL = MAX_START_ROW * ROW_PITCH;
|
||||
|
||||
// 示例(六)的 live:完整背包面板,含动画与关闭 / 重新打开
|
||||
// InventoryPanel 是唯一注册为 GameUI 的根组件
|
||||
const InventoryPanel = defineComponent(() => {
|
||||
const items = ref<Item[]>(sourceItems.map(item => ({ ...item })));
|
||||
const selectedId = ref('item-1');
|
||||
const equippedId = ref('');
|
||||
const hint = ref('选择道具后可以装备或使用');
|
||||
const scrollTop = ref(0);
|
||||
const closed = ref(false);
|
||||
const pulse = ref(0.4);
|
||||
let raf = 0;
|
||||
|
||||
const tick = (now: number) => {
|
||||
const phase = (now % 1600) / 1600;
|
||||
pulse.value = 0.35 + Math.sin(phase * Math.PI * 2) * 0.3;
|
||||
raf = requestAnimationFrame(tick);
|
||||
};
|
||||
|
||||
onMounted(() => {
|
||||
raf = requestAnimationFrame(tick);
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
// 卸载后必须停掉,否则回调会继续访问已销毁的组件
|
||||
cancelAnimationFrame(raf);
|
||||
});
|
||||
|
||||
const selectedItem = computed(() =>
|
||||
items.value.find(item => item.id === selectedId.value)
|
||||
);
|
||||
const canEquip = computed(() => !!selectedItem.value);
|
||||
const canUse = computed(
|
||||
() => !!selectedItem.value && selectedItem.value.count > 0
|
||||
);
|
||||
const isEquipped = computed(
|
||||
() => !!selectedId.value && equippedId.value === selectedId.value
|
||||
);
|
||||
const startRow = computed(() => Math.round(scrollTop.value / ROW_PITCH));
|
||||
|
||||
const equip = () => {
|
||||
if (!selectedItem.value) return;
|
||||
equippedId.value = selectedItem.value.id;
|
||||
hint.value = `已装备:${selectedItem.value.name}`;
|
||||
};
|
||||
|
||||
const use = () => {
|
||||
const item = selectedItem.value;
|
||||
if (!item || item.count <= 0) return;
|
||||
item.count -= 1;
|
||||
};
|
||||
|
||||
watch(
|
||||
() => selectedItem.value?.count ?? 0,
|
||||
(next, prev) => {
|
||||
hint.value = `数量:${prev} → ${next}`;
|
||||
}
|
||||
);
|
||||
|
||||
const scrollRows = (delta: number) => {
|
||||
const current = Math.round(scrollTop.value / ROW_PITCH);
|
||||
const next = Math.max(0, Math.min(MAX_START_ROW, current + delta));
|
||||
scrollTop.value = next * ROW_PITCH;
|
||||
};
|
||||
|
||||
const onWheel = (ev: { wheelY: number }) => {
|
||||
scrollRows(ev.wheelY > 0 ? 1 : -1);
|
||||
};
|
||||
|
||||
const thumbHeight = Math.max(
|
||||
28,
|
||||
(VIEW_HEIGHT / (ROWS * ROW_PITCH)) * VIEW_HEIGHT
|
||||
);
|
||||
const thumbY =
|
||||
MAX_SCROLL === 0
|
||||
? 0
|
||||
: (scrollTop.value / MAX_SCROLL) * (VIEW_HEIGHT - thumbHeight);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 720, 480]}>
|
||||
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
|
||||
|
||||
<container loc={[0, 0, 720, 480]} hidden={closed.value}>
|
||||
<g-rectr
|
||||
loc={[30, 30, 660, 420]}
|
||||
circle={[18]}
|
||||
fill
|
||||
fillStyle="#1d2b45"
|
||||
stroke
|
||||
strokeStyle="#2f6fed"
|
||||
/>
|
||||
|
||||
{/* 呼吸边框只改 alpha,不每帧重建 */}
|
||||
<g-rectr
|
||||
loc={[30, 30, 660, 420]}
|
||||
circle={[18]}
|
||||
stroke
|
||||
strokeStyle="#f2b84b"
|
||||
alpha={pulse.value * 0.6}
|
||||
/>
|
||||
|
||||
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
|
||||
|
||||
<container
|
||||
loc={[626, 50, 56, 32]}
|
||||
onClick={() => (closed.value = true)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 56, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle="#7a3d3d"
|
||||
/>
|
||||
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
|
||||
</container>
|
||||
|
||||
<container loc={[54, 100, 400, 280]}>
|
||||
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
|
||||
|
||||
<container
|
||||
loc={[0, 0, VIEW_WIDTH, VIEW_HEIGHT]}
|
||||
onWheel={onWheel}
|
||||
>
|
||||
{items.value.map((item, index) => {
|
||||
const row = Math.floor(index / COLUMNS);
|
||||
if (
|
||||
row < startRow.value ||
|
||||
row >= startRow.value + 4
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
const col = index % COLUMNS;
|
||||
return (
|
||||
<container
|
||||
key={item.id}
|
||||
loc={[
|
||||
col * ROW_PITCH,
|
||||
(row - startRow.value) * ROW_PITCH
|
||||
]}
|
||||
>
|
||||
<ItemCell
|
||||
item={item}
|
||||
selected={item.id === selectedId.value}
|
||||
equipped={item.id === equippedId.value}
|
||||
size={CELL_SIZE}
|
||||
pulse={pulse.value}
|
||||
onSelect={id => (selectedId.value = id)}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
})}
|
||||
</container>
|
||||
|
||||
<g-rect
|
||||
loc={[378, 0, 6, VIEW_HEIGHT]}
|
||||
fill
|
||||
fillStyle="#1b2634"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[378, thumbY, 6, thumbHeight]}
|
||||
circle={[3]}
|
||||
fill
|
||||
fillStyle="#3f6fa8"
|
||||
/>
|
||||
|
||||
<container
|
||||
loc={[0, 252, 90, 28]}
|
||||
onClick={() => scrollRows(-1)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 90, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[10, 6]} text="上一行" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
<container
|
||||
loc={[100, 252, 90, 28]}
|
||||
onClick={() => scrollRows(1)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 90, 28]}
|
||||
circle={[6]}
|
||||
fill
|
||||
fillStyle="#33465f"
|
||||
/>
|
||||
<text loc={[10, 6]} text="下一行" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
<text
|
||||
loc={[204, 258]}
|
||||
text={`已滚动 ${scrollTop.value} / ${MAX_SCROLL}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[470, 100, 196, 280]}>
|
||||
<ItemDetail
|
||||
item={selectedItem.value}
|
||||
pulse={pulse.value}
|
||||
onClear={() => (selectedId.value = '')}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[54, 392, 304, 32]}>
|
||||
<ActionBar
|
||||
canEquip={canEquip.value}
|
||||
canUse={canUse.value}
|
||||
equipped={isEquipped.value}
|
||||
onEquip={equip}
|
||||
onUse={use}
|
||||
onClose={() => (closed.value = true)}
|
||||
/>
|
||||
</container>
|
||||
|
||||
<text loc={[54, 432]} text={hint.value} fillStyle="#8fb6ff" />
|
||||
</container>
|
||||
|
||||
<container loc={[0, 0, 720, 480]} hidden={!closed.value}>
|
||||
<text loc={[300, 220]} text="面板已关闭" fillStyle="#e8f0ff" />
|
||||
<container
|
||||
loc={[300, 260, 120, 32]}
|
||||
onClick={() => (closed.value = false)}
|
||||
>
|
||||
<g-rectr
|
||||
loc={[0, 0, 120, 32]}
|
||||
circle={[8]}
|
||||
fill
|
||||
fillStyle="#2f6fed"
|
||||
/>
|
||||
<text loc={[18, 8]} text="重新打开" fillStyle="#ffffff" />
|
||||
</container>
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
|
||||
export default InventoryPanel;
|
||||
@@ -0,0 +1,56 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 同一组重叠图形分别使用 source-over、multiply 与 screen
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="composite 对照" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[24, 48]}
|
||||
text="默认 source-over,可换成 multiply / screen"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
|
||||
<container loc={[25, 76, 140, 150]}>
|
||||
<g-rect loc={[0, 0, 140, 150]} fillStyle="#1b2430" />
|
||||
<g-circle circle={[50, 50, 50]} fillStyle="#2f6fed" />
|
||||
<g-rect
|
||||
loc={[40, 60, 100, 90]}
|
||||
fillStyle="#f2b84b"
|
||||
composite="source-over"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[170, 76, 140, 150]}>
|
||||
<g-rect loc={[0, 0, 140, 150]} fillStyle="#1b2430" />
|
||||
<g-circle circle={[50, 50, 50]} fillStyle="#2f6fed" />
|
||||
<g-rect
|
||||
loc={[40, 60, 100, 90]}
|
||||
fillStyle="#f2b84b"
|
||||
composite="multiply"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<container loc={[315, 76, 140, 150]}>
|
||||
<g-rect loc={[0, 0, 140, 150]} fillStyle="#1b2430" />
|
||||
<g-circle circle={[50, 50, 50]} fillStyle="#2f6fed" />
|
||||
<g-rect
|
||||
loc={[40, 60, 100, 90]}
|
||||
fillStyle="#f2b84b"
|
||||
composite="screen"
|
||||
/>
|
||||
</container>
|
||||
|
||||
<text loc={[25, 244]} text="source-over" fillStyle="#8b98a8" />
|
||||
<text loc={[170, 244]} text="multiply" fillStyle="#8b98a8" />
|
||||
<text loc={[315, 244]} text="screen" fillStyle="#8b98a8" />
|
||||
<text
|
||||
loc={[24, 286]}
|
||||
text="composite 只影响绘制结果,不改变布局与命中"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,38 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 父级缩放,子元素仍按局部坐标描述内容
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="变换沿树传递" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[24, 48]}
|
||||
text="父级 scale 后,子元素的 loc 不变"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
|
||||
{/* 父级放大 1.5 倍,子元素仍写 [0, 0, 140, 100];加 nocache 避免缓存图被重采样 */}
|
||||
<container loc={[40, 88, 140, 100]} scale={[1.5, 1.5]} nocache>
|
||||
<g-rect loc={[0, 0, 140, 100]} fill fillStyle="#2f6fed" />
|
||||
<g-circle circle={[18, 18, 10]} fillStyle="#f2b84b" />
|
||||
<text loc={[12, 44]} text="子元素" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
{/* 同一棵子树未缩放的参考 */}
|
||||
<container loc={[290, 88, 140, 100]}>
|
||||
<g-rect loc={[0, 0, 140, 100]} fill fillStyle="#2f6fed" />
|
||||
<g-circle circle={[18, 18, 10]} fillStyle="#f2b84b" />
|
||||
<text loc={[12, 44]} text="子元素" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[40, 252]}
|
||||
text="父级 scale [1.5, 1.5]"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
<text loc={[290, 252]} text="未缩放参考" fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,101 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 同一变换在左上角锚点与中心锚点下的对比;白点 = 锚点
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 14]}
|
||||
text="同一变换,不同锚点"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[24, 34]}
|
||||
text="白点 = 锚点:分别对比绕左上角与绕中心"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
|
||||
{/* scale:左上角锚点 */}
|
||||
<container loc={[12, 52, 224, 124]}>
|
||||
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
|
||||
<text
|
||||
loc={[10, 8]}
|
||||
text="scale · anc [0, 0]"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<container
|
||||
loc={[84, 58, 76, 42]}
|
||||
anc={[0, 0]}
|
||||
scale={[1.35, 0.7]}
|
||||
nocache
|
||||
>
|
||||
<g-rect loc={[0, 0, 76, 42]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
|
||||
</container>
|
||||
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
{/* scale:中心锚点 */}
|
||||
<container loc={[244, 52, 224, 124]}>
|
||||
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
|
||||
<text
|
||||
loc={[10, 8]}
|
||||
text="scale · anc [0.5, 0.5]"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<container
|
||||
loc={[84, 58, 76, 42]}
|
||||
anc={[0.5, 0.5]}
|
||||
scale={[1.35, 0.7]}
|
||||
nocache
|
||||
>
|
||||
<g-rect loc={[0, 0, 76, 42]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
|
||||
</container>
|
||||
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
{/* rotate:左上角锚点 */}
|
||||
<container loc={[12, 180, 224, 124]}>
|
||||
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
|
||||
<text
|
||||
loc={[10, 8]}
|
||||
text="rotate · anc [0, 0]"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<container
|
||||
loc={[84, 58, 76, 42]}
|
||||
anc={[0, 0]}
|
||||
rotate={Math.PI / 12}
|
||||
nocache
|
||||
>
|
||||
<g-rect loc={[0, 0, 76, 42]} fillStyle="#c58af9" />
|
||||
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
|
||||
</container>
|
||||
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
{/* rotate:中心锚点 */}
|
||||
<container loc={[244, 180, 224, 124]}>
|
||||
<g-rect loc={[0, 0, 224, 124]} fillStyle="#1a2330" />
|
||||
<text
|
||||
loc={[10, 8]}
|
||||
text="rotate · anc [0.5, 0.5]"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<container
|
||||
loc={[84, 58, 76, 42]}
|
||||
anc={[0.5, 0.5]}
|
||||
rotate={Math.PI / 12}
|
||||
nocache
|
||||
>
|
||||
<g-rect loc={[0, 0, 76, 42]} fillStyle="#c58af9" />
|
||||
<g-circle circle={[14, 12, 7]} fillStyle="#f2b84b" />
|
||||
</container>
|
||||
<g-circle circle={[84, 58, 5]} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,102 @@
|
||||
import { computed, defineComponent, onUnmounted, ref } from 'vue';
|
||||
import { GameUI, IUIDefaultPropsBase, UIController } from '@motajs/system';
|
||||
|
||||
// 切换 hidden / cache 的小面板,并显示 active / showBack 状态
|
||||
export default defineComponent(() => {
|
||||
// 控制器与状态 UI 都在 setup 里创建,卸载时释放
|
||||
const controller = new UIController<IUIDefaultPropsBase>();
|
||||
controller.setPropsBaseCreator((instance, ctrl) => ({
|
||||
instance,
|
||||
controller: ctrl
|
||||
}));
|
||||
|
||||
// 状态 UI 只负责显示控制器的两个引用值
|
||||
const StateUI = defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[330, 200, 130, 96]}>
|
||||
<g-rect loc={[0, 0, 130, 96]} fill fillStyle="#1d2b45" />
|
||||
<g-rect loc={[0, 0, 130, 96]} stroke strokeStyle="#7aa2ff" />
|
||||
<text loc={[10, 10]} text="控制器状态" fillStyle="#e8f0ff" />
|
||||
<text
|
||||
loc={[10, 40]}
|
||||
text={`active:${controller.active.value}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
<text
|
||||
loc={[10, 64]}
|
||||
text={`showBack:${controller.showBack.value}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
|
||||
const stateUI = new GameUI('perf-state', StateUI);
|
||||
controller.open(stateUI, {});
|
||||
|
||||
const Renderer = defineComponent(() => {
|
||||
return () => controller.render();
|
||||
});
|
||||
|
||||
const visible = ref(true);
|
||||
const cached = ref(false);
|
||||
const cacheText = computed(() => (cached.value ? '已开缓存' : '未开缓存'));
|
||||
|
||||
onUnmounted(() => {
|
||||
controller.closeAll();
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#141a22" />
|
||||
|
||||
<container
|
||||
loc={[20, 20, 120, 32]}
|
||||
onClick={() => (visible.value = !visible.value)}
|
||||
>
|
||||
<g-rect loc={[0, 0, 120, 32]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 8]} text="显示 / 隐藏" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container
|
||||
loc={[150, 20, 120, 32]}
|
||||
onClick={() => (cached.value = !cached.value)}
|
||||
>
|
||||
<g-rect loc={[0, 0, 120, 32]} fill fillStyle="#3a2f5f" />
|
||||
<text loc={[12, 8]} text="切换缓存" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<text loc={[20, 64]} text={cacheText.value} fillStyle="#8fb6ff" />
|
||||
|
||||
{/* hidden 控制显示,cache / nocache 控制是否复用离屏画布 */}
|
||||
<container
|
||||
loc={[20, 96, 260, 200]}
|
||||
hidden={!visible.value}
|
||||
cache={cached.value}
|
||||
nocache={!cached.value}
|
||||
>
|
||||
<g-rect loc={[0, 0, 260, 200]} fill fillStyle="#101820" />
|
||||
{Array.from({ length: 8 }, (_, index) => (
|
||||
<container key={index} loc={[12, 12 + index * 22, 236, 18]}>
|
||||
<g-rect
|
||||
loc={[0, 0, 236, 18]}
|
||||
fill
|
||||
fillStyle={index % 2 === 0 ? '#26364d' : '#1d2b45'}
|
||||
/>
|
||||
<text
|
||||
loc={[8, 2]}
|
||||
text={`静态内容 ${index + 1}`}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
))}
|
||||
</container>
|
||||
|
||||
<text
|
||||
loc={[20, 300]}
|
||||
text="hidden 保留状态;cache 只在内容稳定时才有收益。"
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
|
||||
<Renderer />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,25 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 三个同尺寸矩形对比不同的 alpha
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="alpha 对照" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-rect loc={[40, 88, 120, 120]} fillStyle="#4f8cff" alpha={1} />
|
||||
<text loc={[40, 226]} text="alpha 1" fillStyle="#8b98a8" />
|
||||
|
||||
<g-rect loc={[180, 88, 120, 120]} fillStyle="#4f8cff" alpha={0.6} />
|
||||
<text loc={[180, 226]} text="alpha 0.6" fillStyle="#8b98a8" />
|
||||
|
||||
<g-rect
|
||||
loc={[320, 88, 120, 120]}
|
||||
fillStyle="#4f8cff"
|
||||
alpha={0.25}
|
||||
/>
|
||||
<text loc={[320, 226]} text="alpha 0.25" fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,42 @@
|
||||
import { Texture } from '@motajs/render';
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 演示用纹理:16×16 的棋盘格,放大后更容易看出抗锯齿差异
|
||||
function createPixelTexture() {
|
||||
const canvas = document.createElement('canvas');
|
||||
canvas.width = 16;
|
||||
canvas.height = 16;
|
||||
|
||||
const ctx = canvas.getContext('2d')!;
|
||||
for (let y = 0; y < 16; y++) {
|
||||
for (let x = 0; x < 16; x++) {
|
||||
ctx.fillStyle = (x + y) % 2 === 0 ? '#f2b84b' : '#2f6fed';
|
||||
ctx.fillRect(x, y, 1, 1);
|
||||
}
|
||||
}
|
||||
|
||||
return new Texture(canvas);
|
||||
}
|
||||
|
||||
const demoTexture = createPixelTexture();
|
||||
|
||||
// 同一张纹理放大显示,对照默认抗锯齿与 noanti
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="同一张纹理放大到 160×160"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<image image={demoTexture} loc={[56, 76, 160, 160]} />
|
||||
<text loc={[56, 250]} text="默认" fillStyle="#8b98a8" />
|
||||
|
||||
<image image={demoTexture} noanti loc={[264, 76, 160, 160]} />
|
||||
<text loc={[264, 250]} text="noanti" fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,24 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 带 cursor 的区域:鼠标移入后光标变成手型
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="cursor 属性" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[24, 56]}
|
||||
text="把鼠标移到下面的区域上"
|
||||
fillStyle="#8b98a8"
|
||||
/>
|
||||
|
||||
<g-rect
|
||||
loc={[40, 100, 400, 140]}
|
||||
fillStyle="#2f6fed"
|
||||
cursor="pointer"
|
||||
/>
|
||||
<text loc={[40, 258]} text='cursor="pointer"' fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
import { Texture } from '@motajs/render';
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 演示用纹理:带几种颜色,便于看出灰度与亮度变化
|
||||
function createDemoTexture() {
|
||||
const canvas = document.createElement('canvas');
|
||||
canvas.width = 64;
|
||||
canvas.height = 64;
|
||||
|
||||
const ctx = canvas.getContext('2d')!;
|
||||
ctx.fillStyle = '#2a3550';
|
||||
ctx.fillRect(0, 0, 64, 64);
|
||||
ctx.fillStyle = '#2f6fed';
|
||||
ctx.fillRect(0, 0, 64, 24);
|
||||
ctx.fillStyle = '#f2b84b';
|
||||
ctx.beginPath();
|
||||
ctx.arc(32, 42, 14, 0, Math.PI * 2);
|
||||
ctx.fill();
|
||||
ctx.fillStyle = '#7ee787';
|
||||
ctx.fillRect(44, 44, 20, 20);
|
||||
ctx.fillStyle = '#ffffff';
|
||||
ctx.fillRect(6, 40, 10, 10);
|
||||
|
||||
return new Texture(canvas);
|
||||
}
|
||||
|
||||
const demoTexture = createDemoTexture();
|
||||
|
||||
// 同一张图分别使用正常、模糊与灰度滤镜
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="filter 对照" fillStyle="#cfe0ff" />
|
||||
|
||||
<image image={demoTexture} loc={[48, 84, 120, 120]} />
|
||||
<text loc={[48, 218]} text="正常" fillStyle="#8b98a8" />
|
||||
|
||||
<image
|
||||
image={demoTexture}
|
||||
loc={[180, 84, 120, 120]}
|
||||
filter="blur(3px)"
|
||||
/>
|
||||
<text loc={[180, 218]} text="blur(3px)" fillStyle="#8b98a8" />
|
||||
|
||||
<image
|
||||
image={demoTexture}
|
||||
loc={[312, 84, 120, 120]}
|
||||
filter="grayscale(1) brightness(0.7)"
|
||||
/>
|
||||
<text loc={[312, 218]} text="灰度 + 亮度" fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,18 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 两个重叠矩形:先写的蓝色 zIndex 更高,盖在黄色上面
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="zIndex 对照" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-rect loc={[80, 88, 200, 140]} fillStyle="#2f6fed" zIndex={2} />
|
||||
<g-rect loc={[180, 148, 200, 140]} fillStyle="#f2b84b" />
|
||||
|
||||
<text loc={[24, 296]} text="蓝色 zIndex 2" fillStyle="#8b98a8" />
|
||||
<text loc={[300, 296]} text="黄色 zIndex 0" fillStyle="#8b98a8" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,37 @@
|
||||
import { computed, defineComponent, ref } from 'vue';
|
||||
|
||||
// computed 从 count 派生 doubled,不需要另外维护一份状态
|
||||
export default defineComponent(() => {
|
||||
const count = ref(0);
|
||||
const doubled = computed(() => count.value * 2);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[40, 36]}
|
||||
text="count 变化后 doubled 自动重算"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<g-rect
|
||||
loc={[40, 96, 180, 56]}
|
||||
fillStyle="#2f6fed"
|
||||
onClick={() => count.value++}
|
||||
/>
|
||||
<text loc={[64, 114]} text="点我 +1" fillStyle="#e8f0ff" noevent />
|
||||
|
||||
<text
|
||||
loc={[260, 104]}
|
||||
text={`count = ${count.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[260, 140]}
|
||||
text={`doubled = ${doubled.value}`}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,31 @@
|
||||
import { defineComponent, ref } from 'vue';
|
||||
|
||||
// 计数器:点击按钮只改 count,文字由响应式自动更新
|
||||
export default defineComponent(() => {
|
||||
const count = ref(0);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[40, 36]}
|
||||
text="点击按钮改变 count"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<g-rect
|
||||
loc={[40, 96, 180, 56]}
|
||||
fillStyle="#2f6fed"
|
||||
onClick={() => count.value++}
|
||||
/>
|
||||
<text loc={[64, 114]} text="点我 +1" fillStyle="#e8f0ff" noevent />
|
||||
|
||||
<text
|
||||
loc={[260, 112]}
|
||||
text={`count = ${count.value}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,42 @@
|
||||
import { defineComponent, reactive } from 'vue';
|
||||
|
||||
// reactive 代理对象:逐字段修改,标题与开关一起更新
|
||||
export default defineComponent(() => {
|
||||
const panel = reactive({
|
||||
open: true,
|
||||
title: '背包'
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[40, 36]}
|
||||
text="点击切换 open 与 title"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<g-rect
|
||||
loc={[40, 96, 180, 56]}
|
||||
fillStyle="#2f6fed"
|
||||
onClick={() => {
|
||||
panel.open = !panel.open;
|
||||
panel.title = panel.open ? '背包' : '道具';
|
||||
}}
|
||||
/>
|
||||
<text loc={[64, 114]} text="切换" fillStyle="#e8f0ff" noevent />
|
||||
|
||||
<text
|
||||
loc={[260, 104]}
|
||||
text={`open = ${panel.open}`}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[260, 140]}
|
||||
text={`title = ${panel.title}`}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,36 @@
|
||||
import { defineComponent, ref, watch } from 'vue';
|
||||
|
||||
// watch 监听 count,变化后把新旧值写进 log
|
||||
export default defineComponent(() => {
|
||||
const count = ref(0);
|
||||
const log = ref('还没有变化');
|
||||
|
||||
watch(count, (next, prev) => {
|
||||
log.value = `count:${prev} → ${next}`;
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[40, 36]}
|
||||
text="count 变化后 watch 写日志"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
|
||||
<g-rect
|
||||
loc={[40, 96, 180, 56]}
|
||||
fillStyle="#2f6fed"
|
||||
onClick={() => count.value++}
|
||||
/>
|
||||
<text loc={[64, 114]} text="点我 +1" fillStyle="#e8f0ff" noevent />
|
||||
|
||||
<text
|
||||
loc={[260, 112]}
|
||||
text={`log = ${log.value}`}
|
||||
fillStyle="#7ee787"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 八种图形放在一起:矩形、圆、椭圆、直线、三次贝塞尔、二次贝塞尔、路径、圆角矩形
|
||||
export default defineComponent(() => {
|
||||
const badge = new Path2D();
|
||||
badge.moveTo(300, 205);
|
||||
badge.lineTo(345, 230);
|
||||
badge.lineTo(333, 280);
|
||||
badge.lineTo(267, 280);
|
||||
badge.lineTo(255, 230);
|
||||
badge.closePath();
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
<text loc={[24, 14]} text="八种图形" fillStyle="#e8f0ff" />
|
||||
|
||||
<g-rect loc={[20, 72, 80, 62]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[180, 103, 34]} fillStyle="#58c4dd" />
|
||||
<g-ellipse ellipse={[300, 103, 50, 32]} fillStyle="#c58af9" />
|
||||
<g-line
|
||||
line={[370, 133, 460, 75]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
<g-bezier
|
||||
curve={[20, 275, 45, 205, 80, 280, 105, 212]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-quad
|
||||
curve={[140, 270, 180, 205, 220, 270]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-path path={badge} fillStyle="#7ee787" />
|
||||
<g-rectr
|
||||
loc={[370, 215, 80, 62]}
|
||||
circle={[24]}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
|
||||
<text loc={[44, 146]} text="矩形" fillStyle="#cfe0ff" />
|
||||
<text loc={[170, 146]} text="圆" fillStyle="#cfe0ff" />
|
||||
<text loc={[285, 146]} text="椭圆" fillStyle="#cfe0ff" />
|
||||
<text loc={[405, 146]} text="直线" fillStyle="#cfe0ff" />
|
||||
|
||||
<text loc={[20, 292]} text="三次贝塞尔" fillStyle="#cfe0ff" />
|
||||
<text loc={[140, 292]} text="二次贝塞尔" fillStyle="#cfe0ff" />
|
||||
<text loc={[290, 292]} text="路径" fillStyle="#cfe0ff" />
|
||||
<text loc={[380, 292]} text="圆角矩形" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,129 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 三次贝塞尔:curve 依次是起点、两个控制点、终点
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="三次贝塞尔:白点 = 控制点,虚线 = 控制多边形"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
{/* 控制多边形:起点 → cp1 → cp2 → 终点 */}
|
||||
<g-line
|
||||
line={[30, 110, 70, 85]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[70, 85, 135, 90]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[135, 90, 205, 120]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[255, 110, 300, 60]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[300, 60, 395, 65]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[395, 65, 450, 120]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[30, 235, 125, 215]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[125, 215, 110, 255]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[110, 255, 205, 235]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[255, 235, 330, 205]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[330, 205, 380, 265]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[380, 265, 450, 235]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-bezier
|
||||
curve={[30, 110, 70, 85, 135, 90, 205, 120]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-bezier
|
||||
curve={[255, 110, 300, 60, 395, 65, 450, 120]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-bezier
|
||||
curve={[30, 235, 125, 215, 110, 255, 205, 235]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-bezier
|
||||
curve={[255, 235, 330, 205, 380, 265, 450, 235]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
{/* 每个控制点用白色小圆点标出 */}
|
||||
<g-circle circle={[70, 85, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[135, 90, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[300, 60, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[395, 65, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[125, 215, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[110, 255, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[330, 205, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[380, 265, 4]} fillStyle="#ffffff" />
|
||||
|
||||
<text loc={[30, 145]} text="控制点靠近" fillStyle="#cfe0ff" />
|
||||
<text loc={[270, 145]} text="控制点拉远" fillStyle="#cfe0ff" />
|
||||
<text loc={[30, 292]} text="控制点交叉" fillStyle="#cfe0ff" />
|
||||
<text loc={[270, 292]} text="S 形" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,48 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 圆:用 circle 简写给出圆心与半径
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="圆:半径、圆心与 start / end"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
<g-circle circle={[80, 100, 30]} fillStyle="#58c4dd" />
|
||||
<g-circle circle={[210, 100, 55]} fillStyle="#58c4dd" />
|
||||
<g-circle circle={[350, 100, 80]} fillStyle="#58c4dd" />
|
||||
|
||||
<text loc={[65, 190]} text="r=30" fillStyle="#cfe0ff" />
|
||||
<text loc={[188, 190]} text="r=55" fillStyle="#cfe0ff" />
|
||||
<text loc={[323, 190]} text="r=80" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-circle circle={[90, 255, 35, 0, Math.PI]} fillStyle="#58c4dd" />
|
||||
<g-circle
|
||||
circle={[240, 255, 35, Math.PI / 2, Math.PI * 1.5]}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-circle
|
||||
circle={[390, 255, 35, 0, Math.PI * 1.5]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#58c4dd"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={3}
|
||||
/>
|
||||
|
||||
<text loc={[15, 298]} text="fill 0°→180°" fillStyle="#cfe0ff" />
|
||||
<text loc={[155, 298]} text="stroke 90°→270°" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[310, 298]}
|
||||
text="fill+stroke 0°→270°"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,55 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 椭圆:用 ellipse 简写给出圆心、横向半径与纵向半径
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="椭圆:rx / ry 与 start / end"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
<g-ellipse ellipse={[100, 95, 70, 30]} fillStyle="#c58af9" />
|
||||
<g-ellipse ellipse={[250, 95, 90, 42]} fillStyle="#c58af9" />
|
||||
<g-ellipse ellipse={[400, 95, 55, 25]} fillStyle="#c58af9" />
|
||||
|
||||
<text loc={[55, 150]} text="rx=70 ry=30" fillStyle="#cfe0ff" />
|
||||
<text loc={[200, 150]} text="rx=90 ry=42" fillStyle="#cfe0ff" />
|
||||
<text loc={[355, 150]} text="rx=55 ry=25" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-ellipse
|
||||
ellipse={[90, 230, 60, 35, 0, Math.PI]}
|
||||
fillStyle="#c58af9"
|
||||
/>
|
||||
<g-ellipse
|
||||
ellipse={[240, 230, 60, 35, Math.PI, Math.PI * 2]}
|
||||
stroke
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-ellipse
|
||||
ellipse={[390, 230, 60, 35, 0, Math.PI]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#c58af9"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={3}
|
||||
/>
|
||||
|
||||
<text loc={[30, 298]} text="fill 0°→180°" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[172, 298]}
|
||||
text="stroke 180°→360°"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text
|
||||
loc={[320, 298]}
|
||||
text="fill+stroke 0°→180°"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,43 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 直线:用 line 简写给出两个端点,默认描边
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="直线:端点、线宽、虚线与颜色"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[40, 80, 210, 80]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={2}
|
||||
/>
|
||||
<g-line
|
||||
line={[260, 80, 440, 80]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={14}
|
||||
/>
|
||||
<g-line
|
||||
line={[40, 185, 210, 185]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
lineDash={[18, 12]}
|
||||
/>
|
||||
<g-line
|
||||
line={[260, 240, 440, 170]}
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={6}
|
||||
/>
|
||||
|
||||
<text loc={[40, 96]} text="细 lineWidth=2" fillStyle="#cfe0ff" />
|
||||
<text loc={[260, 110]} text="粗 lineWidth=14" fillStyle="#cfe0ff" />
|
||||
<text loc={[40, 203]} text="虚线 lineDash" fillStyle="#cfe0ff" />
|
||||
<text loc={[260, 254]} text="斜线,改端点" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,40 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 绘制模式:同一个矩形分别用 fill、stroke、fill + stroke 与 strokeAndFill
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 16]} text="四种绘制模式" fillStyle="#e8f0ff" />
|
||||
|
||||
<text loc={[40, 48]} text="fill" fillStyle="#cfe0ff" />
|
||||
<text loc={[260, 48]} text="stroke" fillStyle="#cfe0ff" />
|
||||
<text loc={[40, 180]} text="fill + stroke" fillStyle="#cfe0ff" />
|
||||
<text loc={[260, 180]} text="strokeAndFill" fillStyle="#cfe0ff" />
|
||||
|
||||
<g-rect loc={[40, 84, 180, 80]} fillStyle="#2f6fed" />
|
||||
<g-rect
|
||||
loc={[260, 84, 180, 80]}
|
||||
stroke
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={10}
|
||||
/>
|
||||
<g-rect
|
||||
loc={[40, 218, 180, 80]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#2f6fed"
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={14}
|
||||
/>
|
||||
<g-rect
|
||||
loc={[260, 218, 180, 80]}
|
||||
strokeAndFill
|
||||
fillStyle="#2f6fed"
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={14}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,45 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 路径:path 接收一个 Path2D,默认填充
|
||||
export default defineComponent(() => {
|
||||
const polyline = new Path2D();
|
||||
polyline.moveTo(40, 230);
|
||||
polyline.lineTo(85, 140);
|
||||
polyline.lineTo(125, 215);
|
||||
polyline.lineTo(160, 150);
|
||||
|
||||
const polygon = new Path2D();
|
||||
polygon.moveTo(195, 230);
|
||||
polygon.lineTo(285, 230);
|
||||
polygon.lineTo(240, 135);
|
||||
polygon.closePath();
|
||||
|
||||
const arc = new Path2D();
|
||||
arc.moveTo(455, 180);
|
||||
arc.arc(390, 180, 65, 0, Math.PI * 1.5);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="路径:折线、闭合填充与圆弧"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
<g-path
|
||||
path={polyline}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={3}
|
||||
/>
|
||||
<g-path path={polygon} fillStyle="#7ee787" />
|
||||
<g-path path={arc} stroke strokeStyle="#f2b84b" lineWidth={3} />
|
||||
|
||||
<text loc={[50, 285]} text="折线" fillStyle="#cfe0ff" />
|
||||
<text loc={[205, 285]} text="闭合填充" fillStyle="#cfe0ff" />
|
||||
<text loc={[374, 285]} text="圆弧" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,101 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 二次贝塞尔:curve 依次是起点、控制点、终点
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="二次贝塞尔:白点 = 控制点,虚线 = 控制多边形"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
{/* 控制多边形:起点 → 控制点 → 终点 */}
|
||||
<g-line
|
||||
line={[30, 110, 120, 65]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[120, 65, 210, 110]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[255, 110, 345, 155]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[345, 155, 450, 110]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[100, 270, 85, 250]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[85, 250, 210, 270]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-line
|
||||
line={[260, 270, 395, 250]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
<g-line
|
||||
line={[395, 250, 370, 270]}
|
||||
strokeStyle="#8a94a6"
|
||||
lineWidth={1}
|
||||
lineDash={[4, 4]}
|
||||
/>
|
||||
|
||||
<g-quad
|
||||
curve={[30, 110, 120, 65, 210, 110]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-quad
|
||||
curve={[255, 110, 345, 155, 450, 110]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-quad
|
||||
curve={[100, 270, 85, 250, 210, 270]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-quad
|
||||
curve={[260, 270, 395, 250, 370, 270]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
{/* 每个控制点用白色小圆点标出 */}
|
||||
<g-circle circle={[120, 65, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[345, 155, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[85, 250, 4]} fillStyle="#ffffff" />
|
||||
<g-circle circle={[395, 250, 4]} fillStyle="#ffffff" />
|
||||
|
||||
<text loc={[30, 145]} text="控制点在上" fillStyle="#cfe0ff" />
|
||||
<text loc={[270, 145]} text="控制点在下" fillStyle="#cfe0ff" />
|
||||
<text loc={[30, 292]} text="控制点在左" fillStyle="#cfe0ff" />
|
||||
<text loc={[270, 292]} text="控制点在右" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,26 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 矩形:用 loc 简写给出左上角与宽高
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="矩形:改 loc 对比位置与宽高"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
<g-rect loc={[50, 70, 70, 55]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[250, 70, 170, 55]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[50, 170, 70, 95]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[250, 170, 170, 95]} fillStyle="#2f6fed" />
|
||||
|
||||
<text loc={[50, 135]} text="小 70×55" fillStyle="#cfe0ff" />
|
||||
<text loc={[250, 135]} text="宽 170×55" fillStyle="#cfe0ff" />
|
||||
<text loc={[50, 275]} text="高 70×95" fillStyle="#cfe0ff" />
|
||||
<text loc={[250, 275]} text="大 170×95" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,50 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 圆角矩形:circle 给圆形圆角,ellipse 给椭圆圆角
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 20]}
|
||||
text="圆角矩形:不同圆角写法对比"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
<g-rectr
|
||||
loc={[60, 60, 130, 90]}
|
||||
circle={[24]}
|
||||
fillStyle="#2f6fed"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[290, 60, 130, 90]}
|
||||
circle={[36, 0, 36, 0]}
|
||||
fillStyle="#58c4dd"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[60, 192, 130, 90]}
|
||||
ellipse={[50, 24]}
|
||||
fillStyle="#c58af9"
|
||||
/>
|
||||
<g-rectr
|
||||
loc={[290, 192, 130, 90]}
|
||||
circle={[90]}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
|
||||
<text loc={[60, 163]} text="1 项 circle=[24]" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[270, 163]}
|
||||
text="4 项 [36,0,36,0]"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
<text loc={[60, 294]} text="ellipse=[50,24]" fillStyle="#cfe0ff" />
|
||||
<text
|
||||
loc={[290, 294]}
|
||||
text="大半径 circle=[90]"
|
||||
fillStyle="#cfe0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,127 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 描边:线宽、虚线、端点与拐角四组对比
|
||||
export default defineComponent(() => {
|
||||
const joinMiter = new Path2D();
|
||||
joinMiter.moveTo(275, 210);
|
||||
joinMiter.lineTo(300, 268);
|
||||
joinMiter.lineTo(325, 210);
|
||||
|
||||
const joinRound = new Path2D();
|
||||
joinRound.moveTo(345, 210);
|
||||
joinRound.lineTo(370, 268);
|
||||
joinRound.lineTo(395, 210);
|
||||
|
||||
const joinBevel = new Path2D();
|
||||
joinBevel.moveTo(415, 210);
|
||||
joinBevel.lineTo(440, 268);
|
||||
joinBevel.lineTo(465, 210);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[24, 16]}
|
||||
text="描边:线宽、虚线、端点与拐角"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
|
||||
{/* 线宽 */}
|
||||
<text loc={[30, 48]} text="线宽 lineWidth" fillStyle="#cfe0ff" />
|
||||
<g-line
|
||||
line={[30, 80, 200, 80]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={2}
|
||||
/>
|
||||
<g-line
|
||||
line={[30, 110, 200, 110]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={6}
|
||||
/>
|
||||
<g-line
|
||||
line={[30, 140, 200, 140]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={12}
|
||||
/>
|
||||
<text loc={[214, 72]} text="2" fillStyle="#cfe0ff" />
|
||||
<text loc={[214, 102]} text="6" fillStyle="#cfe0ff" />
|
||||
<text loc={[214, 132]} text="12" fillStyle="#cfe0ff" />
|
||||
|
||||
{/* 虚线 */}
|
||||
<text loc={[240, 48]} text="虚线 lineDash" fillStyle="#cfe0ff" />
|
||||
<g-line
|
||||
line={[340, 80, 456, 80]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={3}
|
||||
lineDash={[8, 6]}
|
||||
/>
|
||||
<g-line
|
||||
line={[340, 110, 456, 110]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={3}
|
||||
lineDash={[2, 6]}
|
||||
/>
|
||||
<g-line
|
||||
line={[340, 140, 456, 140]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={3}
|
||||
lineDash={[16, 6, 2, 6]}
|
||||
/>
|
||||
<text loc={[240, 72]} text="8,6" fillStyle="#cfe0ff" />
|
||||
<text loc={[240, 102]} text="2,6" fillStyle="#cfe0ff" />
|
||||
<text loc={[240, 132]} text="16,6,2,6" fillStyle="#cfe0ff" />
|
||||
|
||||
{/* 端点 */}
|
||||
<text loc={[30, 168]} text="端点 lineCap" fillStyle="#cfe0ff" />
|
||||
<g-line
|
||||
line={[105, 210, 210, 210]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={16}
|
||||
lineCap="butt"
|
||||
/>
|
||||
<g-line
|
||||
line={[105, 245, 210, 245]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={16}
|
||||
lineCap="round"
|
||||
/>
|
||||
<g-line
|
||||
line={[105, 280, 210, 280]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={16}
|
||||
lineCap="square"
|
||||
/>
|
||||
<text loc={[30, 202]} text="butt" fillStyle="#cfe0ff" />
|
||||
<text loc={[30, 237]} text="round" fillStyle="#cfe0ff" />
|
||||
<text loc={[30, 272]} text="square" fillStyle="#cfe0ff" />
|
||||
|
||||
{/* 拐角 */}
|
||||
<text loc={[260, 168]} text="拐角 lineJoin" fillStyle="#cfe0ff" />
|
||||
<g-path
|
||||
path={joinMiter}
|
||||
stroke
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={14}
|
||||
lineJoin="miter"
|
||||
/>
|
||||
<g-path
|
||||
path={joinRound}
|
||||
stroke
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={14}
|
||||
lineJoin="round"
|
||||
/>
|
||||
<g-path
|
||||
path={joinBevel}
|
||||
stroke
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={14}
|
||||
lineJoin="bevel"
|
||||
/>
|
||||
<text loc={[277, 296]} text="miter" fillStyle="#cfe0ff" />
|
||||
<text loc={[347, 296]} text="round" fillStyle="#cfe0ff" />
|
||||
<text loc={[417, 296]} text="bevel" fillStyle="#cfe0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,25 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 静态界面演示:容器、背景、标题、矩形、圆、分隔线与层级
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
{/* 深色底:用一块和容器等大的矩形铺出来 */}
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
{/* 标题 */}
|
||||
<text loc={[24, 24]} text="背包" fillStyle="#e8f0ff" />
|
||||
|
||||
{/* 矩形与圆 */}
|
||||
<g-rect loc={[24, 64, 160, 64]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[280, 96, 32]} fillStyle="#58c4dd" />
|
||||
|
||||
{/* 分隔线 */}
|
||||
<g-line line={[24, 168, 456, 168]} strokeStyle="#7aa7ff" />
|
||||
|
||||
{/* 层级:第一个 zIndex 更大,重叠处在上面 */}
|
||||
<g-rect loc={[320, 120, 120, 72]} fillStyle="#f2b84b" zIndex={2} />
|
||||
<g-rect loc={[368, 152, 120, 72]} fillStyle="#58c4dd" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,208 @@
|
||||
import { computed, defineComponent, onUnmounted } from 'vue';
|
||||
import {
|
||||
GameUI,
|
||||
IUIDefaultPropsBase,
|
||||
IUIInstance,
|
||||
UIController
|
||||
} from '@motajs/system';
|
||||
|
||||
// 策略演示:四个面板分别放在左右两个控制器里
|
||||
interface PanelLoc {
|
||||
x: number;
|
||||
y: number;
|
||||
width: number;
|
||||
height: number;
|
||||
color: string;
|
||||
label: string;
|
||||
}
|
||||
|
||||
// 生成一个固定位置的演示面板,两个策略各用两份
|
||||
const makePanel = (options: PanelLoc) => {
|
||||
const { x, y, width, height, color, label } = options;
|
||||
return defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[x, y, width, height]}>
|
||||
<g-rect loc={[0, 0, width, height]} fill fillStyle={color} />
|
||||
<g-rect
|
||||
loc={[0, 0, width, height]}
|
||||
stroke
|
||||
strokeStyle="#ffffff"
|
||||
/>
|
||||
<text loc={[12, 12]} text={label} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
};
|
||||
|
||||
// 每个面板都是一个独立 GameUI,打开时按策略压栈
|
||||
const leftBottomUI = new GameUI(
|
||||
'strategy-left-bottom',
|
||||
makePanel({
|
||||
x: 20,
|
||||
y: 110,
|
||||
width: 200,
|
||||
height: 130,
|
||||
color: '#2f6fed',
|
||||
label: '底层 A'
|
||||
})
|
||||
);
|
||||
const leftTopUI = new GameUI(
|
||||
'strategy-left-top',
|
||||
makePanel({
|
||||
x: 70,
|
||||
y: 160,
|
||||
width: 200,
|
||||
height: 130,
|
||||
color: '#3a2f5f',
|
||||
label: '上层 B'
|
||||
})
|
||||
);
|
||||
const rightBottomUI = new GameUI(
|
||||
'strategy-right-bottom',
|
||||
makePanel({
|
||||
x: 260,
|
||||
y: 110,
|
||||
width: 200,
|
||||
height: 130,
|
||||
color: '#2f6fed',
|
||||
label: '底层 A'
|
||||
})
|
||||
);
|
||||
const rightTopUI = new GameUI(
|
||||
'strategy-right-top',
|
||||
makePanel({
|
||||
x: 310,
|
||||
y: 160,
|
||||
width: 200,
|
||||
height: 130,
|
||||
color: '#3a2f5f',
|
||||
label: '上层 B'
|
||||
})
|
||||
);
|
||||
|
||||
const leftController = new UIController<IUIDefaultPropsBase>();
|
||||
leftController.setPropsBaseCreator((instance, ctrl) => ({
|
||||
instance,
|
||||
controller: ctrl
|
||||
}));
|
||||
// 左边:只显示最后一个
|
||||
leftController.lastOnly();
|
||||
|
||||
const rightController = new UIController<IUIDefaultPropsBase>();
|
||||
rightController.setPropsBaseCreator((instance, ctrl) => ({
|
||||
instance,
|
||||
controller: ctrl
|
||||
}));
|
||||
// 右边:显示全部
|
||||
rightController.showAll();
|
||||
|
||||
const LeftRenderer = defineComponent(() => {
|
||||
return () => leftController.render();
|
||||
});
|
||||
|
||||
const RightRenderer = defineComponent(() => {
|
||||
return () => rightController.render();
|
||||
});
|
||||
|
||||
export default defineComponent(() => {
|
||||
let leftBottom: IUIInstance | null = null;
|
||||
let leftTop: IUIInstance | null = null;
|
||||
let rightBottom: IUIInstance | null = null;
|
||||
let rightTop: IUIInstance | null = null;
|
||||
|
||||
const leftCount = computed(() => leftController.stack.length);
|
||||
const rightCount = computed(() => rightController.stack.length);
|
||||
|
||||
// 打开与关闭都直接调用对应控制器
|
||||
const openLeftBottom = () => {
|
||||
if (!leftBottom) {
|
||||
leftBottom = leftController.open(leftBottomUI, {});
|
||||
}
|
||||
};
|
||||
const openLeftTop = () => {
|
||||
if (!leftTop) {
|
||||
leftTop = leftController.open(leftTopUI, {});
|
||||
}
|
||||
};
|
||||
const openRightBottom = () => {
|
||||
if (!rightBottom) {
|
||||
rightBottom = rightController.open(rightBottomUI, {});
|
||||
}
|
||||
};
|
||||
const openRightTop = () => {
|
||||
if (!rightTop) {
|
||||
rightTop = rightController.open(rightTopUI, {});
|
||||
}
|
||||
};
|
||||
|
||||
const closeLeft = () => {
|
||||
leftController.closeAll();
|
||||
leftBottom = null;
|
||||
leftTop = null;
|
||||
};
|
||||
const closeRight = () => {
|
||||
rightController.closeAll();
|
||||
rightBottom = null;
|
||||
rightTop = null;
|
||||
};
|
||||
|
||||
onUnmounted(() => {
|
||||
leftController.closeAll();
|
||||
rightController.closeAll();
|
||||
});
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[20, 16]}
|
||||
text="只显示最后一个(lastOnly)"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<container loc={[20, 44, 80, 32]} onClick={openLeftBottom}>
|
||||
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 8]} text="打开 A" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[110, 44, 80, 32]} onClick={openLeftTop}>
|
||||
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#3a2f5f" />
|
||||
<text loc={[12, 8]} text="打开 B" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[200, 44, 80, 32]} onClick={closeLeft}>
|
||||
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#7a3d3d" />
|
||||
<text loc={[12, 8]} text="清空" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<text
|
||||
loc={[20, 84]}
|
||||
text={`栈长度:${leftCount.value}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
|
||||
<text
|
||||
loc={[260, 16]}
|
||||
text="显示全部(showAll)"
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
<container loc={[260, 44, 80, 32]} onClick={openRightBottom}>
|
||||
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 8]} text="打开 A" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[350, 44, 80, 32]} onClick={openRightTop}>
|
||||
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#3a2f5f" />
|
||||
<text loc={[12, 8]} text="打开 B" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<container loc={[260, 76, 80, 32]} onClick={closeRight}>
|
||||
<g-rect loc={[0, 0, 80, 32]} fill fillStyle="#7a3d3d" />
|
||||
<text loc={[12, 8]} text="清空" fillStyle="#ffffff" />
|
||||
</container>
|
||||
<text
|
||||
loc={[360, 84]}
|
||||
text={`栈长度:${rightCount.value}`}
|
||||
fillStyle="#8fb6ff"
|
||||
/>
|
||||
|
||||
<LeftRenderer />
|
||||
<RightRenderer />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,12 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 最小 UI 模板的 live 版本:一个背景矩形加一行文字
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
{/* 背景矩形先铺满整块画布,避免文字落在透明区域 */}
|
||||
<g-rect loc={[0, 0, 480, 320]} fill fillStyle="#1d2b45" />
|
||||
<text loc={[24, 24]} text="我的第一个 UI" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,42 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 三行文字分别用不同锚点,白点标出 loc 的位置
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[24, 20]} text="白点 = loc 的位置" fillStyle="#cfe0ff" />
|
||||
|
||||
{/* anc=[0, 0]:loc 是文字左上角 */}
|
||||
<text loc={[40, 56]} text="anc=[0, 0]" fillStyle="#8b98a8" />
|
||||
<text
|
||||
loc={[160, 60]}
|
||||
anc={[0, 0]}
|
||||
text="左对齐"
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<g-circle circle={[160, 60, 5]} fillStyle="#ffffff" />
|
||||
|
||||
{/* anc=[0.5, 0.5]:loc 是文字中心 */}
|
||||
<text loc={[40, 146]} text="anc=[0.5, 0.5]" fillStyle="#8b98a8" />
|
||||
<text
|
||||
loc={[280, 150]}
|
||||
anc={[0.5, 0.5]}
|
||||
text="居中"
|
||||
fillStyle="#58c4dd"
|
||||
/>
|
||||
<g-circle circle={[280, 150, 5]} fillStyle="#ffffff" />
|
||||
|
||||
{/* anc=[1, 0]:loc 是文字右边缘 */}
|
||||
<text loc={[40, 246]} text="anc=[1, 0]" fillStyle="#8b98a8" />
|
||||
<text
|
||||
loc={[420, 250]}
|
||||
anc={[1, 0]}
|
||||
text="右对齐"
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
<g-circle circle={[420, 250, 5]} fillStyle="#ffffff" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,13 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 最基本的一行文字:内容写在 text,位置由 loc 决定
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[40, 60]} text="一行文字" fillStyle="#ffffff" />
|
||||
<text loc={[40, 110]} text="第二行文字" fillStyle="#58c4dd" />
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,41 @@
|
||||
import { Font, FontWeight } from '@motajs/render';
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 同内容不同字号、字重与斜体的对照
|
||||
export default defineComponent(() => {
|
||||
const small = new Font('Verdana', 14, 'px', FontWeight.Normal);
|
||||
const bold = new Font('Verdana', 20, 'px', FontWeight.Bold);
|
||||
const italic = new Font('Verdana', 24, 'px', FontWeight.Normal, true);
|
||||
const title = new Font('Verdana', 32, 'px', FontWeight.Bold);
|
||||
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text
|
||||
loc={[32, 40]}
|
||||
text="14px 常规文字"
|
||||
font={small}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
<text
|
||||
loc={[32, 80]}
|
||||
text="20px 粗体文字"
|
||||
font={bold}
|
||||
fillStyle="#58c4dd"
|
||||
/>
|
||||
<text
|
||||
loc={[32, 124]}
|
||||
text="24px 斜体文字"
|
||||
font={italic}
|
||||
fillStyle="#f2b84b"
|
||||
/>
|
||||
<text
|
||||
loc={[32, 176]}
|
||||
text="32px 粗体标题"
|
||||
font={title}
|
||||
fillStyle="#e8f0ff"
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -0,0 +1,27 @@
|
||||
import { defineComponent } from 'vue';
|
||||
|
||||
// 填充、描边颜色与描边宽度的对照
|
||||
export default defineComponent(() => {
|
||||
return () => (
|
||||
<container loc={[0, 0, 480, 320]}>
|
||||
<g-rect loc={[0, 0, 480, 320]} fillStyle="#141a22" />
|
||||
|
||||
<text loc={[32, 50]} text="白色填充" fillStyle="#ffffff" />
|
||||
<text loc={[32, 104]} text="蓝色填充" fillStyle="#58c4dd" />
|
||||
<text
|
||||
loc={[32, 158]}
|
||||
text="填充 + 描边 2"
|
||||
fillStyle="#ffffff"
|
||||
strokeStyle="#f2b84b"
|
||||
strokeWidth={2}
|
||||
/>
|
||||
<text
|
||||
loc={[32, 222]}
|
||||
text="填充 + 描边 6"
|
||||
fillStyle="#ffffff"
|
||||
strokeStyle="#c58af9"
|
||||
strokeWidth={6}
|
||||
/>
|
||||
</container>
|
||||
);
|
||||
});
|
||||
@@ -1,6 +1,16 @@
|
||||
<template>
|
||||
<div :style="{ background: props.background, overflow: 'hidden' }">
|
||||
<canvas ref="canvasRef"></canvas>
|
||||
<div
|
||||
:style="{
|
||||
background: props.background,
|
||||
overflow: 'hidden',
|
||||
display: 'flex',
|
||||
justifyContent: 'center'
|
||||
}"
|
||||
>
|
||||
<canvas
|
||||
ref="canvasRef"
|
||||
:style="{ display: 'block', flex: 'none' }"
|
||||
></canvas>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
@@ -82,3 +92,14 @@ onUnmounted(() => {
|
||||
dispose = null;
|
||||
});
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.motajs-input-element {
|
||||
left: 0;
|
||||
top: 0;
|
||||
position: fixed;
|
||||
border: none;
|
||||
z-index: 1000;
|
||||
background-color: transparent;
|
||||
}
|
||||
</style>
|
||||
@@ -12,6 +12,7 @@ const custom = [
|
||||
'shader',
|
||||
'comment',
|
||||
'custom-container',
|
||||
'container-custom',
|
||||
'map-render',
|
||||
'animate',
|
||||
'damage',
|
||||
@@ -252,6 +253,162 @@ export default defineConfig({
|
||||
{
|
||||
text: '怪物上下文与战斗深入',
|
||||
link: '/advanced/ii/enemy-context-and-combat'
|
||||
},
|
||||
{
|
||||
text: '自定义 UI 与渲染',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
text: '起步',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: 'UI 通用模板(TSX)',
|
||||
link: '/advanced/ii/ui/ui-template'
|
||||
},
|
||||
{
|
||||
text: 'UI 入门',
|
||||
link: '/advanced/ii/ui/ui-basics'
|
||||
},
|
||||
{
|
||||
text: '第一个静态界面',
|
||||
link: '/advanced/ii/ui/first-static-ui'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '元素与布局',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: '容器与坐标',
|
||||
link: '/advanced/ii/ui/container-and-coordinates'
|
||||
},
|
||||
{
|
||||
text: '基础图形',
|
||||
link: '/advanced/ii/ui/basic-shapes'
|
||||
},
|
||||
{
|
||||
text: '文字',
|
||||
link: '/advanced/ii/ui/text'
|
||||
},
|
||||
{
|
||||
text: '图片与纹理',
|
||||
link: '/advanced/ii/ui/image-and-texture'
|
||||
},
|
||||
{
|
||||
text: '自绘元素与自定义容器',
|
||||
link: '/advanced/ii/ui/custom-and-container-custom'
|
||||
},
|
||||
{
|
||||
text: '通用参数',
|
||||
link: '/advanced/ii/ui/common-props'
|
||||
},
|
||||
{
|
||||
text: '层级、变换与性能',
|
||||
link: '/advanced/ii/ui/layer-transform-performance'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '交互与数据',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: '响应式',
|
||||
link: '/advanced/ii/ui/reactivity'
|
||||
},
|
||||
{
|
||||
text: '事件与交互',
|
||||
link: '/advanced/ii/ui/events'
|
||||
},
|
||||
{
|
||||
text: '条件渲染与循环渲染',
|
||||
link: '/advanced/ii/ui/conditional-and-list-rendering'
|
||||
},
|
||||
{
|
||||
text: '按键与快捷键',
|
||||
link: '/advanced/ii/ui/hotkey-in-ui'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '组件化',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: '什么是组件',
|
||||
link: '/advanced/ii/ui/what-is-component'
|
||||
},
|
||||
{
|
||||
text: '内置组件:基础',
|
||||
link: '/advanced/ii/ui/builtin-basic'
|
||||
},
|
||||
{
|
||||
text: '内置组件:布局',
|
||||
link: '/advanced/ii/ui/builtin-layout'
|
||||
},
|
||||
{
|
||||
text: '内置组件:文本',
|
||||
link: '/advanced/ii/ui/builtin-text'
|
||||
},
|
||||
{
|
||||
text: '自定义组件',
|
||||
link: '/advanced/ii/ui/custom-components'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'UI 系统',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: 'UI 系统',
|
||||
link: '/advanced/ii/ui/ui-system'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '性能',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: 'UI 性能',
|
||||
link: '/advanced/ii/ui/ui-performance'
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: '完整示例',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: '示例(一)目标与骨架',
|
||||
link: '/advanced/ii/ui/inventory-example-1-skeleton'
|
||||
},
|
||||
{
|
||||
text: '示例(二)道具网格',
|
||||
link: '/advanced/ii/ui/inventory-example-2-grid'
|
||||
},
|
||||
{
|
||||
text: '示例(三)详情区',
|
||||
link: '/advanced/ii/ui/inventory-example-3-detail'
|
||||
},
|
||||
{
|
||||
text: '示例(四)滚动与列表',
|
||||
link: '/advanced/ii/ui/inventory-example-4-scroll'
|
||||
},
|
||||
{
|
||||
text: '示例(五)交互与状态',
|
||||
link: '/advanced/ii/ui/inventory-example-5-state'
|
||||
},
|
||||
{
|
||||
text: '示例(六)动画、拆分与注册',
|
||||
link: '/advanced/ii/ui/inventory-example-6-animation-and-register'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
- 认真阅读样板后,能把一部分简单系统和中等复杂度的系统读明白;
|
||||
- 想把某个具体系统改成自己的规则,而不只是调用现成接口。
|
||||
|
||||
这一层不预设你是资深引擎开发者,也不要求通读引擎源码。它要求的是能跟着样板找到改动点,并判断改动会不会影响存档与录像。这里仍然只写数据端;引擎编写者的内容属于高级 III。
|
||||
这一层不预设你是资深引擎开发者,也不要求通读引擎源码。它要求的是能跟着样板找到改动点,并判断改动会不会影响存档与录像。这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。
|
||||
|
||||
## 难度层定位
|
||||
|
||||
@@ -49,7 +49,9 @@
|
||||
|
||||
## 本层包含什么
|
||||
|
||||
本层一共十篇:这一页导览,加上九篇正文。
|
||||
本层一共十篇(这一页导览 + 九篇数据端正文),另有「自定义 UI 与渲染」子分组 27 篇(见侧边栏)。
|
||||
|
||||
「自定义 UI 与渲染」子分组的入口从 [UI 通用模板](./ui/ui-template.md) 开始;先看 [UI 入门](./ui/ui-basics.md) 了解打开方式、TSX 写法与渲染树,再看 [第一个静态界面](./ui/first-static-ui.md) 把容器、文字、图片与图形拼成一块面板,之后回到模板动手写。Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端;上文的数据端前置只对数据端篇目成立。
|
||||
|
||||
| 序 | 篇目 | 它能让你做什么 | 前置 |
|
||||
| --- | ----------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------- |
|
||||
@@ -76,7 +78,8 @@
|
||||
|
||||
## 本层不覆盖什么
|
||||
|
||||
- **渲染端与编辑器**:渲染端表现、编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内,相关篇目只用占位说明归属。
|
||||
- **编辑器与状态栏**:编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内,相关篇目只用占位说明归属;界面绘制与 UI 系统见子分组「自定义 UI 与渲染」。
|
||||
- **引擎级性能**:高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。
|
||||
- **高级 III 的原理与架构**:双端分离约束、数据端分层、编辑器识别协议、录像深层原理与性能调优留给高级 III。
|
||||
- **API 全量参考**:本层只讲改动链路与关键接口,不做签名清单。
|
||||
|
||||
|
||||
@@ -0,0 +1,518 @@
|
||||
# 基础图形
|
||||
|
||||
上一篇[《容器与坐标》](./container-and-coordinates.md)讲的是怎么把元素摆到位置上:坐标从哪里来、`loc` 与锚点怎么配合、容器嵌套后子元素怎么算。位置有了,这一篇开始画东西。界面里的图形元素一共八种:矩形 `g-rect`、圆 `g-circle`、椭圆 `g-ellipse`、直线 `g-line`、三次贝塞尔 `g-bezier`、二次贝塞尔 `g-quad`、路径 `g-path` 和圆角矩形 `g-rectr`。
|
||||
|
||||
在逐个看图形之前,先弄清所有图形共用的填充、描边与颜色规则,后面每种图形的用法都建立在这套规则上。每种图形都有一个用数组传参的简写,日常写 UI 用简写最省事;逐个属性写的普通写法只在需要拆分或复用单个值时再用,下面每节只提一句。每种图形配一个 live,最后再把八种放在一起。
|
||||
|
||||
## 通用规则:填充、描边与颜色
|
||||
|
||||
图形有两种绘制模式:填充和描边。`fill`、`stroke`、`strokeAndFill` 是模式开关,值都是布尔值,不是颜色;颜色分别写在 `fillStyle` 与 `strokeStyle` 里。写 `fill="#f00"` 不会把图形变成红色,要写 `fill fillStyle="#f00"`;默认填充的图形本来就不用写 `fill`。
|
||||
|
||||
每种图形有自己的默认模式:
|
||||
|
||||
| 图形 | 默认模式 |
|
||||
| ---------------------------------------------------------- | -------- |
|
||||
| `g-rect` / `g-circle` / `g-ellipse` / `g-rectr` / `g-path` | 填充 |
|
||||
| `g-line` / `g-bezier` / `g-quad` | 描边 |
|
||||
|
||||
默认填充的图形只写 `fillStyle`;默认描边的图形只写 `strokeStyle`。需要同时填充和描边时,写 `fill` 与 `stroke`:渲染时先填充、后描边,所以**描边会覆盖 fill**,边框完整地画在填充之上。`strokeAndFill` 是另一套顺序——先描边、后填充,**fill 会覆盖描边**,描边的内半边被填充盖住,边框看起来更细;`strokeAndFill` 优先级最高,写它会忽略 `fill` 与 `stroke`。
|
||||
|
||||
这里有个容易踩的地方:默认填充的图形只要写了 `stroke`、又没写过 `fill`,模式就会切换成只描边,原来的填充不再生效。也就是说,默认填充只在「没写 `stroke`、也没写 `strokeAndFill`」时成立。想同时填充和描边,必须显式写 `fill` + `stroke`,或者直接用 `strokeAndFill`。
|
||||
|
||||
```tsx
|
||||
// 默认填充的矩形只写 stroke:只画边框,不填充
|
||||
<g-rect loc={[40, 40, 160, 100]} stroke strokeStyle="#58c4dd" lineWidth={4} />
|
||||
|
||||
// 想同时填充和描边:必须显式写 fill + stroke
|
||||
<g-rect
|
||||
loc={[240, 40, 160, 100]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#2f6fed"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={4}
|
||||
/>
|
||||
```
|
||||
|
||||
这四种模式放在一起对照:
|
||||
|
||||
```tsx
|
||||
// 默认填充:颜色用 fillStyle
|
||||
<g-rect loc={[40, 40, 120, 80]} fillStyle="#2f6fed" />
|
||||
|
||||
// 默认描边:颜色用 strokeStyle
|
||||
<g-line line={[40, 160, 200, 160]} strokeStyle="#7ee787" />
|
||||
|
||||
// 同时填充与描边:先填充后描边,描边盖住 fill
|
||||
<g-circle
|
||||
circle={[300, 100, 50]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#58c4dd"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
// 先描边后填充:fill 盖住描边,strokeAndFill 优先级最高
|
||||
<g-rect
|
||||
loc={[260, 180, 120, 80]}
|
||||
strokeAndFill
|
||||
fillStyle="#f2b84b"
|
||||
strokeStyle="#141a22"
|
||||
lineWidth={6}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="modesLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一个矩形分别用四种模式,对照看边框和填充;重点对照 `fill` + `stroke` 与 `strokeAndFill` 的覆盖关系。
|
||||
|
||||
`fillRule` 只在填充路径时起作用,可选 `nonzero` 与 `evenodd`,具体在后面的路径一节展开。所有图形的默认颜色都是浅灰 `#ddd`;示例里通常显式写 `fillStyle` 或 `strokeStyle`。
|
||||
|
||||
### 描边细节
|
||||
|
||||
默认描边的图形,以及任何写了 `stroke` 的图形,都可以用下面这些属性控制描边:
|
||||
|
||||
| 属性 | 作用 | 常见值 |
|
||||
| ---------------- | ------------------------------------------ | --------------------------- |
|
||||
| `lineWidth` | 线宽,默认 `2` | `2` / `6` / `12` |
|
||||
| `lineDash` | 虚线样式,数组按「实线长度、空白长度」交替 | `[18, 10]` |
|
||||
| `lineDashOffset` | 虚线起始偏移,改变虚线从哪里开始 | `0` / `12` |
|
||||
| `lineCap` | 端点样式,只影响线段两端 | `butt` / `round` / `square` |
|
||||
| `lineJoin` | 拐角样式,只影响线段连接处 | `miter` / `round` / `bevel` |
|
||||
| `miterLimit` | 尖角限制,`miter` 拐角过长时会被截断 | 默认 `10` |
|
||||
|
||||
`lineDash` 的数组会按「画一段、空一段」交替;写 `[18, 10]` 就是画 18、空 10。超过两项时继续交替,例如 `[16, 6, 2, 6]` 是长线、空白、短线、空白,常用来画点划线。`lineDashOffset` 把整个虚线图案向后平移,可以做流动的虚线。
|
||||
|
||||
`lineCap` 只改变两个端点,`lineJoin` 只改变拐角,两者互不影响。`miterLimit` 只在 `lineJoin="miter"` 时有意义,尖角被拉得太长时会被切成斜角。
|
||||
|
||||
```tsx
|
||||
<g-line
|
||||
line={[80, 80, 400, 80]}
|
||||
strokeStyle="#7ee787"
|
||||
lineWidth={6}
|
||||
lineDash={[18, 10]}
|
||||
lineDashOffset={4}
|
||||
lineCap="round"
|
||||
/>
|
||||
|
||||
<g-path
|
||||
path={arrow}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={6}
|
||||
lineJoin="miter"
|
||||
miterLimit={8}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="strokeLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 分四组对比:线宽、虚线、端点与拐角。
|
||||
|
||||
这些属性对所有描边图形通用:默认描边的直线、贝塞尔曲线能直接用,矩形、圆、椭圆、路径写了 `stroke` 之后也能用。例如给矩形加虚线描边:
|
||||
|
||||
```tsx
|
||||
<g-rect
|
||||
loc={[40, 40, 180, 100]}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={6}
|
||||
lineDash={[12, 8]}
|
||||
/>
|
||||
```
|
||||
|
||||
## 矩形 g-rect
|
||||
|
||||
矩形用 `loc` 简写,四个值依次是左上角 `x`、左上角 `y`、宽度、高度。矩形默认填充,颜色用 `fillStyle`。也可以把四个值拆成 `x`、`y`、`width`、`height` 分别写,效果一样。
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[80, 80, 240, 140]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="rectLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组参数,分别对比 `loc` 不同时的位置与宽高。
|
||||
|
||||
矩形默认锚点在左上角,所以前两个值是左上角的位置。想改锚点时,可以把 `loc` 写成六个值,最后两项是 `anchorX`、`anchorY`;也可以单独写 `anchorX` / `anchorY`。例如把锚点改成 `0.5` 后,前两个值就变成矩形中心。
|
||||
|
||||
```tsx
|
||||
// 锚点在中心:前两个值是矩形中心坐标
|
||||
<g-rect loc={[240, 160, 120, 80, 0.5, 0.5]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
`g-rect` 本身没有圆角参数,需要圆角时用后面的 `g-rectr`。
|
||||
|
||||
## 圆 g-circle
|
||||
|
||||
圆用 `circle` 简写,三个值依次是圆心 `x`、圆心 `y`、半径。圆默认填充,颜色用 `fillStyle`。也可以写 `x`、`y`、`radius`,效果一样。
|
||||
|
||||
```tsx
|
||||
<g-circle circle={[240, 170, 80]} fillStyle="#58c4dd" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="circleLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 上排放三个整圆对比半径,下排三个圆弧分别用 fill、stroke、fill+stroke 三种模式,`start` / `end` 只控制角度;标签上写的是度数,代码里按弧度写。
|
||||
|
||||
`circle` 还能写五个值:`[圆心 x, 圆心 y, 半径, 起始角度, 终止角度]`,这时画的是从起始角到终止角的圆弧。`start` / `end` 的单位是**弧度**,不是度数;`0` 指向右侧,角度增大沿顺时针方向。live 标签用度数只是为了好读,代码里仍要换算成弧度:
|
||||
|
||||
| 度数 | 弧度 |
|
||||
| ------ | ------- |
|
||||
| `0°` | `0` |
|
||||
| `90°` | `π / 2` |
|
||||
| `180°` | `π` |
|
||||
| `270°` | `1.5π` |
|
||||
| `360°` | `2π` |
|
||||
|
||||
圆弧也按填充 / 描边两种模式画:默认填充,`start` 与 `end` 之间的圆弧和两端连线围成的区域会被填满,颜色用 `fillStyle`;只想看弧线时写 `stroke`,颜色改用 `strokeStyle`;两者都要就同时写 `fill` 和 `stroke`,`fillStyle` 与 `strokeStyle` 分别给色。
|
||||
|
||||
```tsx
|
||||
// 完整圆
|
||||
<g-circle circle={[120, 100, 60]} fillStyle="#58c4dd" />
|
||||
|
||||
// 圆弧 0° → 180°:默认填充,弧与两端连线围成的区域被填满
|
||||
<g-circle circle={[320, 100, 60, 0, Math.PI]} fillStyle="#58c4dd" />
|
||||
|
||||
// 同一个圆弧只描边:写 stroke,颜色改用 strokeStyle
|
||||
<g-circle
|
||||
circle={[320, 100, 60, 0, Math.PI]}
|
||||
stroke
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
// 填充与描边都要:同时写 fill 和 stroke,两种颜色分别给
|
||||
<g-circle
|
||||
circle={[320, 100, 60, 0, Math.PI]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#58c4dd"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={3}
|
||||
/>
|
||||
```
|
||||
|
||||
## 椭圆 g-ellipse
|
||||
|
||||
椭圆用 `ellipse` 简写,四个值依次是圆心 `x`、圆心 `y`、横向半径 `rx`、纵向半径 `ry`。椭圆默认填充。也可以写 `x`、`y`、`radiusX`、`radiusY`。
|
||||
|
||||
```tsx
|
||||
<g-ellipse ellipse={[240, 170, 130, 70]} fillStyle="#c58af9" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="ellipseLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 上排放三个整椭圆对比 `rx` / `ry`,下排三个部分椭圆分别用 fill、stroke、fill+stroke 三种模式,`start` / `end` 只控制角度;标签上写的是度数,代码里按弧度写。
|
||||
|
||||
`ellipse` 还能写六个值:`[圆心 x, 圆心 y, 横向半径, 纵向半径, 起始角度, 终止角度]`,用来画部分椭圆。角度规则与圆相同:`start` / `end` 用弧度,不是度数,`0` 指向右侧,角度增大沿顺时针方向;换算见上面的度数对照表。部分椭圆也按填充 / 描边两种模式画:默认填充,圆弧与两端连线围成的区域会被填满,颜色用 `fillStyle`;只想看弧线时写 `stroke`,颜色改用 `strokeStyle`;两者都要就同时写 `fill` 和 `stroke`,`fillStyle` 与 `strokeStyle` 分别给色。
|
||||
|
||||
```tsx
|
||||
// 完整椭圆
|
||||
<g-ellipse ellipse={[120, 100, 70, 40]} fillStyle="#c58af9" />
|
||||
|
||||
// 部分椭圆 180° → 360°:默认填充
|
||||
<g-ellipse
|
||||
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
|
||||
fillStyle="#c58af9"
|
||||
/>
|
||||
|
||||
// 同一个部分椭圆只描边:写 stroke,颜色改用 strokeStyle
|
||||
<g-ellipse
|
||||
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
|
||||
stroke
|
||||
strokeStyle="#c58af9"
|
||||
lineWidth={4}
|
||||
/>
|
||||
|
||||
// 填充与描边都要:同时写 fill 和 stroke,两种颜色分别给
|
||||
<g-ellipse
|
||||
ellipse={[330, 100, 80, 45, Math.PI, Math.PI * 2]}
|
||||
fill
|
||||
stroke
|
||||
fillStyle="#c58af9"
|
||||
strokeStyle="#e8f0ff"
|
||||
lineWidth={3}
|
||||
/>
|
||||
```
|
||||
|
||||
## 直线 g-line
|
||||
|
||||
直线用 `line` 简写,四个值依次是两个端点 `x1`、`y1`、`x2`、`y2`。直线默认描边,`strokeStyle` 给颜色,`lineWidth` 给线宽。也可以逐个写 `x1`、`y1`、`x2`、`y2`。
|
||||
|
||||
```tsx
|
||||
<g-line line={[80, 240, 400, 100]} strokeStyle="#7ee787" lineWidth={6} />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="lineLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组参数,分别对比端点、`lineWidth`、`lineDash` 与颜色。
|
||||
|
||||
直线是最简单的描边图形,描边细节一节讲的 `lineDash`、`lineDashOffset`、`lineCap` 都能直接写在 `g-line` 上。`lineCap` 只改变两个端点,虚线则从起点开始按 `lineDash` 交替。
|
||||
|
||||
```tsx
|
||||
<g-line
|
||||
line={[80, 200, 400, 200]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={10}
|
||||
lineDash={[18, 10]}
|
||||
lineCap="round"
|
||||
/>
|
||||
```
|
||||
|
||||
## 三次贝塞尔 g-bezier
|
||||
|
||||
三次贝塞尔用 `curve` 简写,八个值依次是起点 `sx`、`sy`,第一个控制点 `cp1x`、`cp1y`,第二个控制点 `cp2x`、`cp2y`,终点 `ex`、`ey`。曲线默认描边,`strokeStyle` 与 `lineWidth` 控制颜色和粗细。也可以逐个写这八个属性。
|
||||
|
||||
```tsx
|
||||
<g-bezier
|
||||
curve={[80, 240, 140, 70, 340, 250, 400, 100]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="bezierLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组曲线,分别对比控制点靠近、拉远、交叉与 S 形;白点是控制点,虚线是起点 → `cp1` → `cp2` → 终点的控制多边形。
|
||||
|
||||
起点与终点决定曲线两端,两个控制点决定中间的弯曲:第一个控制点主要拉住起点附近的走向,第二个控制点主要拉住终点附近的走向。控制点离端点越远,曲线被拉得越开;两个控制点分居曲线两侧时会出现 S 形。
|
||||
|
||||
## 二次贝塞尔 g-quad
|
||||
|
||||
二次贝塞尔用 `curve` 简写,六个值依次是起点 `sx`、`sy`,控制点 `cpx`、`cpy`,终点 `ex`、`ey`。曲线默认描边。也可以逐个写这六个属性。
|
||||
|
||||
```tsx
|
||||
<g-quad
|
||||
curve={[90, 230, 240, 80, 390, 230]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="quadLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组曲线,分别对比控制点在上、下、左、右;白点是控制点,虚线是起点 → 控制点 → 终点的控制多边形。
|
||||
|
||||
二次曲线只有一个控制点,它同时影响起点与终点两侧的走向,曲线在控制点方向达到最大弯曲。控制点离两个端点越远,弧线越鼓;做简单的弧线或装饰够用。
|
||||
|
||||
## 路径 g-path
|
||||
|
||||
路径用 `path` 属性,值是一个 `Path2D`。`Path2D` 是浏览器自带的全局构造器,直接 `new Path2D()` 即可,不需要 import。路径默认填充;只想画线时写 `stroke`。路径坐标相对元素自身,元素默认在父容器的原点,所以不写 `x` / `y` 时,坐标看起来就是从父容器原点开始。
|
||||
|
||||
```tsx
|
||||
// Path2D 是浏览器全局对象,直接 new
|
||||
const badge = new Path2D();
|
||||
badge.moveTo(240, 80);
|
||||
badge.lineTo(340, 140);
|
||||
badge.lineTo(315, 255);
|
||||
badge.lineTo(165, 255);
|
||||
badge.lineTo(140, 140);
|
||||
badge.closePath();
|
||||
|
||||
// 默认填充:给颜色即可
|
||||
<g-path path={badge} fillStyle="#7ee787" />;
|
||||
|
||||
// 只想画轮廓:写 stroke
|
||||
<g-path path={badge} stroke strokeStyle="#7ee787" lineWidth={3} />;
|
||||
|
||||
// 自交或多段重叠时,用 fillRule 指定填充规则
|
||||
<g-path path={badge} fillStyle="#7ee787" fillRule="evenodd" />;
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="pathLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了三个路径,分别对比折线、闭合填充与圆弧。
|
||||
|
||||
`moveTo` 决定从哪里开始,`lineTo` 连到下一个点,`closePath` 把最后一点连回起点。路径可以有多段;`arc` 画圆弧,`bezierCurveTo` 画三次贝塞尔。开放路径通常写 `stroke`,闭合路径适合填充;有自交或多段重叠时,用 `fillRule` 决定哪些区域算内部:`nonzero` 按环绕方向,`evenodd` 按奇偶,默认是 `nonzero`。
|
||||
|
||||
同一个 `Path2D` 可以交给多个 `g-path` 复用;但 `Path2D` 不能序列化,不能直接放进存档。需要保存路径时,保存构造它用到的点或参数,读档后重新构造。
|
||||
|
||||
## 圆角矩形 g-rectr
|
||||
|
||||
圆角矩形用 `g-rectr`。`g-rect` 没有圆角参数,需要圆角时换用 `g-rectr`。圆角用 `circle` 或 `ellipse` 简写:`circle` 给圆形圆角,`ellipse` 给椭圆圆角。
|
||||
|
||||
`circle` 可以写 1 到 4 项,按项数决定每个角用哪个半径:
|
||||
|
||||
- 1 项 `[r1]`:四个角都用 `r1`。
|
||||
- 2 项 `[r1, r2]`:左上、右下用 `r1`,右上、左下用 `r2`。
|
||||
- 3 项 `[r1, r2, r3]`:左上用 `r1`,右上和左下用 `r2`,右下用 `r3`。
|
||||
- 4 项 `[r1, r2, r3, r4]`:依次对应左上、右上、右下、左下。
|
||||
|
||||
`ellipse` 每两个值为一组(横向半径、纵向半径),按组数决定每个角用哪一组:
|
||||
|
||||
- 2 项 `[rx1, ry1]`:四个角都用这一组。
|
||||
- 4 项 `[rx1, ry1, rx2, ry2]`:左上、右下用第 1 组,右上、左下用第 2 组。
|
||||
- 6 项 `[rx1, ry1, rx2, ry2, rx3, ry3]`:左上用第 1 组,右上和左下用第 2 组,右下用第 3 组。
|
||||
- 8 项 `[rx1, ry1, rx2, ry2, rx3, ry3, rx4, ry4]`:依次对应左上、右上、右下、左下,每组两个值。
|
||||
|
||||
只想让某几个角是圆角时,把不需要的角写成 0。
|
||||
|
||||
```tsx
|
||||
// 四个角同样圆
|
||||
<g-rectr loc={[30, 70, 120, 90]} circle={[24]} fillStyle="#2f6fed" />
|
||||
|
||||
// 依次左上、右上、右下、左下
|
||||
<g-rectr
|
||||
loc={[180, 70, 120, 90]}
|
||||
circle={[36, 0, 36, 0]}
|
||||
fillStyle="#58c4dd"
|
||||
/>
|
||||
|
||||
// 椭圆圆角:横向与纵向半径不同
|
||||
<g-rectr
|
||||
loc={[330, 70, 120, 90]}
|
||||
ellipse={[48, 24]}
|
||||
fillStyle="#c58af9"
|
||||
/>
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="rectrLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这个 live 里放了四组圆角参数,分别对比一项半径、四项半径、椭圆圆角与大半径。
|
||||
|
||||
圆角矩形默认填充;圆角半径超过宽高一半时会被限制在宽高的一半以内,不会画到矩形外面。
|
||||
|
||||
## 所有图形的组合
|
||||
|
||||
把八种图形放进同一个标准 `container`,用 `FULL_LOC` 铺满整块 UI。下面是一段完整 TSX;路径先构造一次 `Path2D`,再交给 `g-path`。
|
||||
|
||||
```tsx
|
||||
const badge = new Path2D();
|
||||
badge.moveTo(300, 205);
|
||||
badge.lineTo(345, 230);
|
||||
badge.lineTo(333, 280);
|
||||
badge.lineTo(267, 280);
|
||||
badge.lineTo(255, 230);
|
||||
badge.closePath();
|
||||
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
|
||||
<text loc={[24, 14]} text="八种图形" fillStyle="#e8f0ff" />
|
||||
|
||||
{/* 上排:矩形、圆、椭圆、直线 */}
|
||||
<g-rect loc={[20, 72, 80, 62]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[180, 103, 34]} fillStyle="#58c4dd" />
|
||||
<g-ellipse ellipse={[300, 103, 50, 32]} fillStyle="#c58af9" />
|
||||
<g-line line={[370, 133, 460, 75]} strokeStyle="#7ee787" lineWidth={4} />
|
||||
|
||||
{/* 下排:三次贝塞尔、二次贝塞尔、路径、圆角矩形 */}
|
||||
<g-bezier
|
||||
curve={[20, 275, 45, 205, 80, 280, 105, 212]}
|
||||
strokeStyle="#f2b84b"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-quad
|
||||
curve={[140, 270, 180, 205, 220, 270]}
|
||||
strokeStyle="#58c4dd"
|
||||
lineWidth={4}
|
||||
/>
|
||||
<g-path path={badge} fillStyle="#7ee787" />
|
||||
<g-rectr loc={[370, 215, 80, 62]} circle={[24]} fillStyle="#f2b84b" />
|
||||
|
||||
{/* 每个图形的短标签 */}
|
||||
<text loc={[44, 146]} text="矩形" fillStyle="#cfe0ff" />
|
||||
<text loc={[170, 146]} text="圆" fillStyle="#cfe0ff" />
|
||||
<text loc={[285, 146]} text="椭圆" fillStyle="#cfe0ff" />
|
||||
<text loc={[405, 146]} text="直线" fillStyle="#cfe0ff" />
|
||||
<text loc={[20, 292]} text="三次贝塞尔" fillStyle="#cfe0ff" />
|
||||
<text loc={[140, 292]} text="二次贝塞尔" fillStyle="#cfe0ff" />
|
||||
<text loc={[290, 292]} text="路径" fillStyle="#cfe0ff" />
|
||||
<text loc={[380, 292]} text="圆角矩形" fillStyle="#cfe0ff" />
|
||||
</container>;
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="allLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
这段代码里每种图形只出现一次,位置按 4×2 排开;换成自己的布局时,改各自的 `loc`、圆心或端点即可。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const modesLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-modes.tsx');
|
||||
const strokeLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-stroke.tsx');
|
||||
const rectLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-rect.tsx');
|
||||
const circleLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-circle.tsx');
|
||||
const ellipseLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-ellipse.tsx');
|
||||
const lineLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-line.tsx');
|
||||
const bezierLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-bezier.tsx');
|
||||
const quadLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-quad.tsx');
|
||||
const pathLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-path.tsx');
|
||||
const rectrLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-rectr.tsx');
|
||||
const allLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/shapes-all.tsx');
|
||||
</script>
|
||||
|
||||
## 默认值与注意
|
||||
|
||||
- 圆与椭圆的默认锚点是 `0.5`,`x` / `y` 指圆心;矩形与容器的默认锚点是 `0`,`x` / `y` 指左上角。
|
||||
- `curve` 数组长度写错不会报错,只会画出错误形状:三次贝塞尔要 8 个值,二次贝塞尔要 6 个值。
|
||||
- `lineDash` 建议写偶数项;写奇数项时浏览器会自动复制一份再交替,容易看不出规律。
|
||||
- 默认填充只在没写 `stroke` 时生效:给默认填充的图形加 `stroke` 会变成只描边,要同时填充和描边就显式写 `fill` + `stroke`。
|
||||
|
||||
下一篇[《文字》](./text.md)讲怎么在图形旁边写字:内容、字体、颜色与简单排版。
|
||||
@@ -0,0 +1,396 @@
|
||||
# 内置组件:基础
|
||||
|
||||
`@user/client-base` 里已经有一批常用的基础组件。它们和普通组件一样,在 TSX 里按名字使用,属性名写成 camelCase。下面每个组件都先说它解决什么问题,再给最小写法,常用参数跟着讲,最后接一个 live。
|
||||
|
||||
## 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,293 @@
|
||||
# 内置组件:布局
|
||||
|
||||
这一篇讲四个负责区域与列表的组件:`Scroll`、`Page`、`List`、`ListPage`。它们都先说要解决什么,再给最小写法,常用参数跟着讲,最后接一个 live。
|
||||
|
||||
## 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,216 @@
|
||||
# 内置组件:文本
|
||||
|
||||
文字元素只画一行。要让长文字按宽度折行、逐字显示或自动向上滚动时,用内置的文本组件。这一篇讲 `TextContent` 和 `ScrollText`,每个都先说它解决什么问题,再给最小写法,最后接一个 live。
|
||||
|
||||
## 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,150 @@
|
||||
# 通用参数
|
||||
|
||||
这些属性大多数元素都能写。它们有的只在特定条件下有意义:`hd` 只对开启缓存的元素有效;`anti` / `noanti` 影响绘制内容在缩放时的插值;`cursor`、`hidden` 要鼠标经过或隐藏时才能看出差别。下面会说明每个参数在什么条件下有意义;场景只是由属性语义推出的适用条件,不是限定用途。
|
||||
|
||||
## hd
|
||||
|
||||
`hd` 默认 `true`。它控制元素的缓存画布是否按设备像素比(DPR)使用高清分辨率:为 `true` 时缓存画布按 DPR 放大,为 `false` 时按 1x 绘制。它只对开启缓存的元素有效;没有缓存的元素写 `hd` 看不到可见变化。
|
||||
|
||||
是否要高清缓存由缓存内容决定。缓存的是文字、矢量图形这类需要清晰边缘的内容时,在高 DPR 屏幕上按 DPR 绘制,放大后边缘才不会糊,默认的 `true` 适合这类内容。反过来,如果缓存内容本身就是 1x 的像素数据,按 DPR 放大并不会多出信息;或者更在意缓存的显存与内存开销而不是 DPR 下的清晰度,就可以写 `hd={false}`。
|
||||
|
||||
```tsx
|
||||
// hd 只对开启缓存的元素有效;container 默认开启缓存,这里让它按 1x 绘制缓存
|
||||
<container loc={[40, 40, 240, 160]} hd={false}>
|
||||
<text loc={[8, 8]} text="缓存内容" fillStyle="#ffffff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
## anti / noanti
|
||||
|
||||
`anti` 默认 `true`,`noanti` 默认 `false`。两者控制同一个抗锯齿开关:`anti` 为 `false` 关闭抗锯齿,`noanti` 为 `true` 也关闭抗锯齿。`noanti` 的优先级更高,`noanti` 为 `true` 等价于关闭 `anti`;不要同时依赖两个开关。
|
||||
|
||||
抗锯齿影响的是图片等绘制内容在缩放时的插值方式。连续色调的图片与渐变在缩放时,平滑插值能减少锯齿和色块,默认的 `anti` 适合这类内容。像素图相反:它的边缘本来就是硬边,抗锯齿会把硬边插值成半透明过渡,放大后像素边缘会发虚。因此像素图放大时应写 `noanti`,并尽量按整数倍放大,减少额外的重采样。这个结论是从「像素图需要硬边」推出来的适用条件,不是对 `noanti` 用途的限定。
|
||||
|
||||
```tsx
|
||||
// noanti 关闭图片缩放时的插值,让像素边缘保持硬边
|
||||
<image image={texture} noanti loc={[40, 40, 160, 160]} />
|
||||
```
|
||||
|
||||
下面把同一张 16×16 纹理放大到 160×160:左边用默认绘制,右边写了 `noanti`,对照边缘是平滑还是方块。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsAntiLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## hidden
|
||||
|
||||
`hidden` 默认 `false`。为 `true` 时元素不绘制,也不参与交互。它不改变元素的尺寸与坐标,改回 `false` 后原样恢复。需要保留元素实例、只是临时不绘制或不交互时用它;改回 `false` 就能恢复,不需要反复创建和销毁元素。
|
||||
|
||||
```tsx
|
||||
// hidden 为 true 时不绘制,也不参与交互
|
||||
<g-rect loc={[40, 40, 120, 80]} hidden fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
## id
|
||||
|
||||
`id` 默认空字符串,一般情况下不会用到。只有需要从渲染器按 id 直接查找元素时才写,例如调试、测试或命令式访问;日常写 UI 不需要给元素命名。
|
||||
|
||||
空 id 不会被登记;同一个渲染器内 id 应当唯一,重复会告警。给元素写 `id` 后,可以用渲染器的 `getElementById(id)` 查找它。它不是 DOM id,不影响显示与布局。
|
||||
|
||||
```tsx
|
||||
// 需要按 id 查找时才写,之后可以用渲染器的 getElementById 取回
|
||||
<g-rect id="target" loc={FULL_LOC} fillStyle="#141a22" />
|
||||
```
|
||||
|
||||
## alpha
|
||||
|
||||
`alpha` 默认 `1`,范围 `0`–`1`。它不是继承属性,不会自动写到每个子元素各自的绘制上。子元素是否一起变透明,取决于当前元素有没有开启缓存:开启缓存的父级会把子元素先画进缓存图,再对整张缓存结果应用 `alpha`,子元素会一起变透明;未开启缓存时,`alpha` 只影响当前元素自身的绘制,子元素按自己的 `alpha` 绘制。单个元素需要淡入淡出时,改自己的 `alpha` 即可。
|
||||
|
||||
```tsx
|
||||
// 只影响这个矩形自身的透明度
|
||||
<g-rect loc={[40, 40, 120, 80]} fillStyle="#4f8cff" alpha={0.5} />
|
||||
```
|
||||
|
||||
下面三个同尺寸矩形分别使用 `alpha` 为 `1`、`0.6` 与 `0.25`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsAlphaLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## cursor
|
||||
|
||||
`cursor` 默认 `inherit`。值是一个 CSS cursor 字符串,例如 `pointer`、`text`、`default`,按 CSS 中这些值的语义选择需要的形状。它只改变鼠标悬停时的光标,不负责点击:点击由元素的事件处理,光标只是提示。鼠标悬停在元素上时才生效,所以元素本身要参与交互;不参与交互的元素不会改变光标。
|
||||
|
||||
```tsx
|
||||
// 悬停在这个矩形上时,光标变成手型
|
||||
<g-rect loc={[40, 40, 200, 80]} fillStyle="#2f6fed" cursor="pointer" />
|
||||
```
|
||||
|
||||
下面这块区域写了 `cursor="pointer"`,鼠标移上去后光标会变成手型。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsCursorLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## filter
|
||||
|
||||
`filter` 默认 `none`。值可以是任何合法的 CSS filter 字符串,例如 `blur(3px)`、`grayscale(1) brightness(0.7)`、`drop-shadow(0 4px 6px #000)`;完整的函数列表见 [MDN 的 filter 文档](https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter)。可以组合多个函数,用空格分隔,按书写顺序依次应用。
|
||||
|
||||
`filter` 不是继承属性,不会自动套到每个子元素各自的绘制上。子元素是否被过滤,取决于当前元素有没有开启缓存:开启缓存时,子元素先画进当前元素的缓存图,`filter` 作用在整张缓存结果上,子元素会一起被过滤;未开启缓存时,子元素按自己的 `filter` 绘制,当前元素的 `filter` 只影响自身绘制。如果当前元素没有自己的绘制(例如未开启缓存的容器),`filter` 就不会作用到子元素。它也不影响布局。
|
||||
|
||||
```tsx
|
||||
// 多个 filter 函数按书写顺序依次应用
|
||||
<g-rect
|
||||
loc={[40, 40, 160, 100]}
|
||||
fillStyle="#4f8cff"
|
||||
filter="blur(3px) brightness(0.8)"
|
||||
/>
|
||||
```
|
||||
|
||||
下面三张相同的图分别是正常、模糊与灰度加亮度。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsFilterLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## zIndex
|
||||
|
||||
`zIndex` 默认 `0`。它只在同一父元素下的兄弟之间比较:值越大越后画、越靠上。不同父级的元素不直接比较,它们跟随各自父级在树中的叠放关系绘制。`zIndex` 可以是负数,值越小越先画、越靠下。相同值不要依赖先后顺序。
|
||||
|
||||
```tsx
|
||||
// 只影响同一父元素下的兄弟:zIndex 较大的后画,盖住默认的 0
|
||||
<g-rect loc={[40, 40, 160, 110]} fillStyle="#f0b428" zIndex={1} />
|
||||
<g-rect loc={[100, 80, 160, 110]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
需要强制决定同一父级下兄弟的叠放顺序时,用 `zIndex`。下面两个矩形互相重叠,蓝色写了更高的 `zIndex`,即使先写也盖在黄色上面。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="propsZIndexLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const propsAntiLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/props-anti.tsx');
|
||||
const propsAlphaLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/props-alpha.tsx');
|
||||
const propsCursorLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/props-cursor.tsx');
|
||||
const propsFilterLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/props-filter.tsx');
|
||||
const propsZIndexLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/props-zindex.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,354 @@
|
||||
# 条件渲染与循环渲染
|
||||
|
||||
TSX 里没有模板指令。要不要显示一块内容、要不要重复一组元素,都是普通表达式:条件用 `hidden` 或三元,循环用 `.map()`。
|
||||
|
||||
绝大多数情况用 `hidden` 更划算:它只跳过绘制与命中,元素、状态和事件监听都还在。虽然会多占一点内存,但一般影响很小;TSX 也更平整,不需要为条件分支多套一层缩进。
|
||||
|
||||
## 条件渲染与 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,107 @@
|
||||
# 容器与坐标
|
||||
|
||||
上一篇[《第一个静态界面》](./first-static-ui.md)已经用容器、文字和几个简单图形拼出了一块静态界面:`container` 圈出范围,文字和图形按 `loc` 摆进去。这一篇只讲怎么把元素放到想要的位置:坐标从哪里算起、`loc` 与锚点怎么配合、容器嵌套后子元素的坐标怎么变。事件、变换、缓存和层级都留到后面的篇章。
|
||||
|
||||
## 坐标来源
|
||||
|
||||
根容器的左上角是原点,向右是正 `x`,向下是正 `y`。子元素的坐标相对父容器的左上角,不是相对整块画布;容器嵌套时,每一层都把坐标系重新平移一次。
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<text loc={[24, 24]} text="左上角是原点" fillStyle="#e8f0ff" />
|
||||
<g-rect loc={[24, 64, 120, 60]} fillStyle="#2f6fed" />
|
||||
</container>
|
||||
```
|
||||
|
||||
这段代码里,文字和矩形的 `x` / `y` 都从根容器的左上角量起。
|
||||
|
||||
## loc 与锚点
|
||||
|
||||
`loc` 是一个六元组,顺序固定:`x`、`y`、`width`、`height`、`anchorX`、`anchorY`。
|
||||
|
||||
```tsx
|
||||
// x、y、width、height、anchorX、anchorY
|
||||
<g-rect loc={[40, 40, 120, 80, 0, 0]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
六个值也可以拆成同名属性分别写:
|
||||
|
||||
```tsx
|
||||
<g-rect
|
||||
x={40}
|
||||
y={40}
|
||||
width={120}
|
||||
height={80}
|
||||
anchorX={0}
|
||||
anchorY={0}
|
||||
fillStyle="#2f6fed"
|
||||
/>
|
||||
```
|
||||
|
||||
`anchorX` 与 `anchorY` 还可以合并成 `anc`:
|
||||
|
||||
```tsx
|
||||
<container loc={[240, 160, 160, 120]} anc={[0.5, 0.5]} />
|
||||
```
|
||||
|
||||
`loc` 里每一对(`x` / `y`、`width` / `height`、`anchorX` / `anchorY`)要么都写,要么整对省略。只写 `[x, y]` 是合法的;宽高省略时沿用默认的 200×200。
|
||||
|
||||
锚点回答的是「元素自己的哪一个点落在 `x` / `y` 上」。矩形与容器的默认锚点是 `0`,也就是左上角;圆与椭圆的默认锚点是 `0.5`,也就是中心。锚点不是把元素整体平移,而是换一个点去对齐坐标:同一个 `x` / `y` 配不同锚点,元素落下的位置会明显不同。
|
||||
|
||||
矩形代表容器,圆点标出 `(x, y)` 所在的位置。下面四个例子用的是同一个局部坐标 `(110, 70)`,只是锚点和尺寸不同:
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="anchorLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
四个例子的坐标点相同:锚点为 `0, 0` 时矩形从圆点向右下展开,锚点为 `0.5, 0.5` 时圆点是矩形中心,锚点为 `1, 1` 时矩形从圆点向左上展开。最后一个仍是中心锚点,只是宽高更大,所以向四周展开得更多。
|
||||
|
||||
## 嵌套:局部坐标系
|
||||
|
||||
把一组元素放进子容器后,子元素的坐标就相对这个子容器,而不是相对根容器。移动父容器时,里面的子容器和元素跟着移动,子元素自己的 `x` / `y` 不需要改。
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
{/* 父容器:在根容器里的 (80, 60),尺寸 240×160 */}
|
||||
<container loc={[80, 60, 240, 160]}>
|
||||
{/* 子容器:在父容器里的 (20, 20),尺寸 160×100 */}
|
||||
<container loc={[20, 20, 160, 100]}>
|
||||
{/* 圆点在子容器的 (0, 0),也就是子容器的左上角 */}
|
||||
<g-circle circle={[0, 0, 6]} fillStyle="#58c4dd" />
|
||||
</container>
|
||||
</container>
|
||||
</container>
|
||||
```
|
||||
|
||||
子容器不需要知道自己在屏幕上的绝对位置,只需要知道自己在父容器里的位置。下面的 live 用两种颜色区分父容器和子容器,两个圆点分别是它们的左上角:
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="containerLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
子容器的 `(0, 0)` 是它在父容器内的位置,不是画布原点;父容器移动时,子容器和里面的元素一起移动。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const anchorLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/anchor-demo.tsx');
|
||||
const containerLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/container-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 不写宽高时,元素的默认尺寸是 200×200。
|
||||
- 锚点改变的是「元素自己的哪一个点」落在 `x` / `y` 上,不是把元素整体平移。
|
||||
- 子元素的坐标相对父容器,不是相对画布;移动父容器时,子元素跟着移动。
|
||||
- 容器外的内容默认不可见;需要显示的内容要放在容器矩形内。
|
||||
- `nocache` 可能让超出容器的内容显示,但这是渲染实现的特性,后续可能变动,不要依赖。
|
||||
|
||||
下一篇[《基础图形》](./basic-shapes.md)开始讲矩形、圆、线这些元素本身:它们的几何参数、填充与描边怎么用。
|
||||
@@ -0,0 +1,140 @@
|
||||
# 自绘元素与自定义容器
|
||||
|
||||
`<custom>` 与 `<container-custom>` 用来处理现成元素无法直接表达的绘制与子元素控制:前者在元素内部直接用 Canvas 2D 画内容,后者接管子元素的绘制与事件传递。普通布局仍然优先用 `<container>` 与现成元素;只有确实需要直接操作画布或控制子元素时才用这两个标签。
|
||||
|
||||
## custom
|
||||
|
||||
`<custom>` 是叶子元素,没有子元素。它的尺寸与位置由 `loc` 决定,`loc` 之外不参与布局。
|
||||
|
||||
`render` 接收 `MotaOffscreenCanvas2D`,在元素局部坐标里直接用 `canvas.ctx` 绘制。局部坐标的原点在元素左上角,宽高就是 `loc` 的宽高。
|
||||
|
||||
系统在调用 `render` 前后已经保存并恢复了画布状态,函数里不需要在开头和结尾习惯性地写 `save` / `restore`。只有在函数内部临时改变状态、之后还要恢复并继续绘制时,才需要自己保存和恢复。
|
||||
|
||||
`bindings` 接收依赖值数组。把 `render` 读取的响应式值放进数组,例如 `bindings={[angle.value]}`,不需要传 `ref` 对象。读取 `.value` 发生在父组件 render 中,和 `loc={[x.value, ...]}` 一样会被 Vue 追踪;值变化后父组件重渲染,`bindings` prop 更新,`<custom>` 重绘。`render` 函数本身不需要认识 Vue、`Ref` 或 `watch`,它只读取普通值。`Ref` 等响应式基础见[《响应式》](./reactivity.md)。
|
||||
|
||||
::: warning
|
||||
不要在 `render` 里修改用于 `bindings` 的响应式值(例如渲染时递增 `angle.value`),这会让渲染与状态更新互相触发。一般不会遇到这种情况,确实需要时会在高级 III 中进一步讲解。
|
||||
:::
|
||||
|
||||
`<custom>` 默认开启缓存。内容频繁变化、缓存没有收益时,可以加 `nocache`。
|
||||
|
||||
需要直接使用 Canvas 2D 的路径、渐变、裁剪等能力,而现成元素组合不出来时,用 `<custom>` 自绘。能用 `g-*` 图形、`image` 与 `text` 拼出来的内容,继续用现成元素。
|
||||
|
||||
```tsx
|
||||
import { ref } from 'vue';
|
||||
|
||||
// 把 angle.value 放进 bindings;角度变化时 <custom> 会重绘
|
||||
const angle = ref(0);
|
||||
const ringColors = ['#2f6fed', '#7aa7ff', '#f2b84b'];
|
||||
|
||||
// render 在元素局部坐标里绘制内容
|
||||
const render = canvas => {
|
||||
const ctx = canvas.ctx;
|
||||
const cx = 100;
|
||||
const cy = 100;
|
||||
|
||||
// 径向渐变与同心圆环直接走 Canvas 2D
|
||||
const gradient = ctx.createRadialGradient(cx, cy, 12, cx, cy, 88);
|
||||
gradient.addColorStop(0, '#2f6fed');
|
||||
gradient.addColorStop(1, '#141a22');
|
||||
ctx.beginPath();
|
||||
ctx.arc(cx, cy, 88, 0, Math.PI * 2);
|
||||
ctx.fillStyle = gradient;
|
||||
ctx.fill();
|
||||
|
||||
ringColors.forEach((color, index) => {
|
||||
ctx.beginPath();
|
||||
ctx.arc(cx, cy, 70 - index * 16, 0, Math.PI * 2);
|
||||
ctx.strokeStyle = color;
|
||||
ctx.lineWidth = 3;
|
||||
ctx.stroke();
|
||||
});
|
||||
|
||||
// 指针从圆心出发,按 angle 旋转;坐标都相对元素左上角
|
||||
ctx.translate(cx, cy);
|
||||
ctx.rotate(angle.value);
|
||||
ctx.beginPath();
|
||||
ctx.moveTo(0, 0);
|
||||
ctx.lineTo(0, -64);
|
||||
ctx.strokeStyle = '#e8f0ff';
|
||||
ctx.lineWidth = 4;
|
||||
ctx.stroke();
|
||||
};
|
||||
|
||||
<custom loc={[40, 40, 200, 200]} bindings={[angle.value]} render={render} />;
|
||||
```
|
||||
|
||||
下面的 live 用 `<custom>` 绘制同心圆环、径向渐变与旋转指针,角度值通过 `bindings` 触发重绘。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="customDemoLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## container-custom
|
||||
|
||||
`<container-custom>` 是带子元素的容器,区别只在绘制方式:`render` 接管子元素的绘制。
|
||||
|
||||
`render(canvas, children, transform)` 拿到画布、排好序的子元素列表与当前变换。子元素不会自动出现,必须自己遍历 `children`,对每个子元素调用 `renderContent`;不调用就不会绘制。`children` 已经按 `zIndex` 排好序,遍历顺序就是绘制顺序;`hidden` 的子元素应当跳过。
|
||||
|
||||
因为绘制的是子元素本身,`render` 里可以先逐个修改子元素的属性,再调用 `renderContent`。下面的例子给每个子元素设置依次递增的模糊:
|
||||
|
||||
```tsx
|
||||
// render 接管子元素绘制:按顺序给每个子元素设置递增的模糊,再逐个绘制
|
||||
const render = (canvas, children, transform) => {
|
||||
children.forEach((child, index) => {
|
||||
if (child.hidden) return;
|
||||
child.setFilter(`blur(${index * 2}px)`);
|
||||
child.renderContent(canvas, transform);
|
||||
});
|
||||
};
|
||||
|
||||
<container-custom loc={[40, 40, 240, 160]} render={render}>
|
||||
<g-rect loc={[16, 16, 208, 40]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[16, 64, 208, 40]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[16, 112, 208, 40]} fillStyle="#2f6fed" />
|
||||
</container-custom>;
|
||||
```
|
||||
|
||||
和 `custom` 一样,系统在调用 `render` 前后已经保存并恢复了画布状态,这个例子不需要写 `save` / `restore`。
|
||||
|
||||
`propagate` 接管事件传递,参数依次是事件类型、当前进度、事件对象、当前容器和「按默认规则继续传递」的回调。不写 `propagate` 就沿用默认。只有需要修改事件坐标或改变传递路径时才写,日常自定义绘制不需要它。
|
||||
|
||||
`<container-custom>` 常用于内置组件内部;需要自己控制子元素绘制或事件传递时也可以使用。普通布局继续用 `<container>`。
|
||||
|
||||
它默认开启缓存。内容频繁变化、缓存没有收益时,可以加 `nocache`。
|
||||
|
||||
普通 `<container>` 默认也会开启缓存:子元素先画到容器的缓存画布上,超出缓存画布的内容会被裁掉。给容器加 `nocache` 后子元素直接画到上层画布,超出容器的内容才不再被裁。不过这是缓存实现带来的特性,后续可能变化,不要依赖它来做布局或裁剪。
|
||||
|
||||
下面的 live 用同一组子元素对比:左侧普通 `<container>` 原样绘制,右侧 `<container-custom>` 在 `render` 里给子元素依次设置递增的模糊。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="containerCustomDemoLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 选择方式
|
||||
|
||||
| 需求 | 用法 |
|
||||
| -------------------- | ----------------------------------- |
|
||||
| 只画内容、没有子元素 | `<custom>` |
|
||||
| 要控制子元素怎么画 | `<container-custom>` 的 `render` |
|
||||
| 要控制事件怎么传递 | `<container-custom>` 的 `propagate` |
|
||||
| 普通布局 | `<container>` 与现成元素 |
|
||||
|
||||
能用现成元素组合出来的内容,优先用现成元素;`<custom>` 与 `<container-custom>` 留给 Canvas 2D 直接绘制或子元素控制。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `<custom>` 没有子元素,尺寸与位置由 `loc` 决定。
|
||||
- `<container-custom>` 的 `render` 必须遍历并调用子元素的 `renderContent`,否则子元素不会绘制。
|
||||
- `propagate` 不写就沿用默认;不需要改变事件传递时不要写。
|
||||
- `<custom>` 与 `<container-custom>` 默认缓存;内容频繁变化时再加 `nocache`。
|
||||
- 普通布局与能用现成元素表达的内容,继续用 `<container>` 与现成元素。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const customDemoLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/custom-demo.tsx');
|
||||
const containerCustomDemoLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/container-custom-demo.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,309 @@
|
||||
# 自定义组件
|
||||
|
||||
前面的页面已经能用容器、文字、图形与内置组件拼出整块 UI。当同一段 UI 要在多处出现时,把这块 UI 拆成一个自定义组件,声明一次,在各处调用。
|
||||
|
||||
这一篇只讲怎么用:怎么接收参数、怎么发事件、怎么留出内容位置,以及怎么把属性透传给内部元素。
|
||||
|
||||
## 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,393 @@
|
||||
# 事件与交互
|
||||
|
||||
元素画出来之后,下一步是接住用户的操作:点击、按下、抬起、移动、悬停、滚轮。事件在容器与子元素之间有两个传递方向:**冒泡**是里面先生效,**捕获**是外面先生效。
|
||||
|
||||
一般更符合直觉的是冒泡。点一个按钮,应该先轮到按钮自己处理,而不是父容器先把事件接住;所以 `onClick`、`onDown` 这些默认事件都走冒泡。只有确实需要外层先处理时,才用 `onClickCapture`、`onDownCapture` 这类捕获写法。
|
||||
|
||||
## 内置事件及用法
|
||||
|
||||
TSX 里用 `onXxx` 绑定事件。常用事件如下:
|
||||
|
||||
| 冒泡阶段 | 捕获阶段 | 触发时机 |
|
||||
| --------- | ---------------- | ---------------- |
|
||||
| `onClick` | `onClickCapture` | 点击 |
|
||||
| `onDown` | `onDownCapture` | 按下 |
|
||||
| `onUp` | `onUpCapture` | 抬起 |
|
||||
| `onMove` | `onMoveCapture` | 指针在元素上移动 |
|
||||
| `onEnter` | — | 指针进入元素 |
|
||||
| `onLeave` | — | 指针离开元素 |
|
||||
| `onWheel` | `onWheelCapture` | 在元素上滚动滚轮 |
|
||||
|
||||
这些是元素属性,直接写在元素上即可。属性名写错不会报错,也不会触发。
|
||||
|
||||
事件回调建议先单独声明成函数,再把函数名传给属性,例如 `const handleClick = (ev) => { ... }`,然后 `onClick={handleClick}`。只有需要额外参数时才内联包一层,例如 `onClick={() => handleClick(param)}`;只用到事件对象时直接传函数,不必再写成 `onClick={ev => handleClick(ev)}`。需要标注类型时,可以从 `@motajs/render` 引入 `IActionEvent` / `IWheelEvent`。
|
||||
|
||||
`onClick` 不是单独的按下:按下与抬起都发生在同一个元素上,才会产生点击。按下后把指针移出元素、在元素外抬起,只会触发**另一个元素**的 `onUp`,当前元素不会触发 `onClick`。同一次抬起里,`onUp` 先处理完,然后才处理 `onClick`。
|
||||
|
||||
下面是一段完整的 UI 模板,按钮上同时挂了按下、抬起与点击:
|
||||
|
||||
```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` 走,没有额外的最小热区。基础图形的命中细节见[基础图形](./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,169 @@
|
||||
# 第一个静态界面
|
||||
|
||||
这一篇从头拼一个静态界面:深色底、标题、一个图标、一个矩形、一个圆、一条分隔线,最后用两块重叠的矩形看层级。整屏 UI 用引擎给出的 `FULL_LOC`。每一步只加一种东西,最后得到一份可以直接运行的静态界面。
|
||||
|
||||
## 容器
|
||||
|
||||
界面从容器开始。容器决定这块 UI 占多大,也决定子元素的坐标从哪里算:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
|
||||
</container>
|
||||
```
|
||||
|
||||
- `FULL_LOC` 是引擎给出的整屏位置;
|
||||
- 子元素的坐标相对这个容器的左上角,而不是相对整块画布;
|
||||
- `container` 本身不画颜色,深色底用一块和它一样大的 `g-rect` 铺出来;
|
||||
- 图形默认填充,`fillStyle` 是填充颜色。
|
||||
|
||||
现在得到一块铺满整屏的深色区域,后面的元素都放进这个 `container`。
|
||||
|
||||
## 文字
|
||||
|
||||
在容器里加标题:
|
||||
|
||||
```tsx
|
||||
<text loc={[24, 24]} text="背包" fillStyle="#e8f0ff" />
|
||||
```
|
||||
|
||||
- `text` 是文字内容,写在属性里,不要写成标签之间的裸文字;
|
||||
- `loc` 只写两个数:文字左上角相对容器左上角的位置;
|
||||
- `fillStyle` 是文字颜色。
|
||||
|
||||
## 矩形与圆
|
||||
|
||||
矩形用 `g-rect`,位置和大小都由 `loc` 给出:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[24, 64, 160, 64]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
前两个数是左上角,后两个数是宽和高。
|
||||
|
||||
圆用 `g-circle`,写成 `circle={[圆心x, 圆心y, 半径]}`:
|
||||
|
||||
```tsx
|
||||
<g-circle circle={[280, 96, 32]} fillStyle="#58c4dd" />
|
||||
```
|
||||
|
||||
圆默认填充,`fillStyle` 给颜色。
|
||||
|
||||
## 直线
|
||||
|
||||
分隔线用 `g-line`,给出两个端点即可:
|
||||
|
||||
```tsx
|
||||
<g-line line={[24, 168, 456, 168]} strokeStyle="#7aa7ff" />
|
||||
```
|
||||
|
||||
- `line` 的四个数是起点 `x` / `y` 和终点 `x` / `y`;
|
||||
- 线默认描边,`strokeStyle` 是颜色。
|
||||
|
||||
这条线从 `(24, 168)` 画到 `(456, 168)`,横在面板中间。
|
||||
|
||||
## 素材管理器中的图片
|
||||
|
||||
图片从素材管理器按别名取:
|
||||
|
||||
```tsx
|
||||
const icon = props.state.materials.getImageByAlias('bg.jpg');
|
||||
|
||||
<image image={icon} loc={[24, 184, 64, 64]} />;
|
||||
```
|
||||
|
||||
- `props.state.materials` 是 ClientCore 提供的素材管理器,素材和别名由它统一维护;
|
||||
- `getImageByAlias('bg.jpg')` 按别名取一张已经登记好的图,返回纹理或 `null`;
|
||||
- 取到的纹理直接交给 `image` 的 `image` 属性,`loc` 决定画在哪里、画多大。
|
||||
|
||||
## 相对坐标与层级
|
||||
|
||||
前面所有元素的坐标都相对根容器。把一组元素放进子容器时,坐标改成相对这个子容器:
|
||||
|
||||
```tsx
|
||||
<container loc={[240, 200, 216, 88]}>
|
||||
<g-rect loc={[0, 0, 216, 88]} fillStyle="#1d2733" />
|
||||
<text loc={[12, 12]} text="状态" fillStyle="#9fb6d1" />
|
||||
</container>
|
||||
```
|
||||
|
||||
子容器的 `loc` 是它在根容器里的位置;里面 `g-rect` 的 `[0, 0]` 是子容器的左上角,不是面板的左上角。移动子容器时,里面的元素整体跟着走。
|
||||
|
||||
同一父级里的兄弟按 `zIndex` 决定谁在上面:值大的画在上面。第二个矩形后写,但给第一个写 `zIndex={2}`,重叠处就是第一个在上面:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[320, 120, 120, 72]} fillStyle="#f2b84b" zIndex={2} />
|
||||
<g-rect loc={[368, 152, 120, 72]} fillStyle="#58c4dd" />
|
||||
```
|
||||
|
||||
`zIndex` 只在同一个父级的兄弟之间比较;不写时按书写顺序叠放。缓存与命中的细节不在本篇展开。
|
||||
|
||||
## 完整模板
|
||||
|
||||
把上面的内容按顺序放进标准模板:
|
||||
|
||||
```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';
|
||||
|
||||
// 这里填写自定义的 UI 参数
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
// 图片从素材管理器按别名取
|
||||
const icon = props.state.materials.getImageByAlias('bg.jpg');
|
||||
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
<g-rect loc={FULL_LOC} fillStyle="#141a22" />
|
||||
<text loc={[24, 24]} text="背包" fillStyle="#e8f0ff" />
|
||||
<g-rect loc={[24, 64, 160, 64]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[280, 96, 32]} fillStyle="#58c4dd" />
|
||||
<g-line line={[24, 168, 456, 168]} strokeStyle="#7aa7ff" />
|
||||
<image image={icon} loc={[24, 184, 64, 64]} />
|
||||
<container loc={[240, 200, 216, 88]}>
|
||||
<g-rect loc={[0, 0, 216, 88]} fillStyle="#1d2733" />
|
||||
<text loc={[12, 12]} text="状态" fillStyle="#9fb6d1" />
|
||||
</container>
|
||||
<g-rect loc={[320, 120, 120, 72]} fillStyle="#f2b84b" zIndex={2} />
|
||||
<g-rect loc={[368, 152, 120, 72]} fillStyle="#58c4dd" />
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
`FULL_LOC` 是整块画布的位置;在已有 UI 中使用 `props.controller.open(MyPanelUI, {})` 打开后,看到的就是这块面板。
|
||||
|
||||
## 运行效果
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="staticUiLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const staticUiLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/static-ui-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 后续
|
||||
|
||||
- 坐标、锚点与嵌套:[容器与坐标](./container-and-coordinates.md)
|
||||
- 更多图形:[基础图形](./basic-shapes.md)
|
||||
- 文字样式:[文字](./text.md)
|
||||
- 纹理与素材:[图片与纹理](./image-and-texture.md)
|
||||
- 层级、变换与缓存:[层级、变换与性能](./layer-transform-performance.md)
|
||||
- 让界面响应点击:[事件与交互](./events.md)
|
||||
@@ -0,0 +1,248 @@
|
||||
# 按键与快捷键
|
||||
|
||||
UI 里经常需要「按 Esc 关闭」「按 Enter 确认」「按方向键切换选中项」。不需要自己监听键盘:按键系统负责按键匹配、作用域与优先级,也负责让玩家在设置界面里改键。
|
||||
|
||||
下面按「在哪里写」「组件里怎么接」「什么时候需要额外参数」展开。
|
||||
|
||||
## 按键与元素事件
|
||||
|
||||
元素事件来自画布上的指针:先做命中测试,找到指针下的元素,再沿容器捕获与冒泡,关心的是「点在哪里」。
|
||||
|
||||
按键事件来自键盘:直接匹配指令,不经过画布命中,关心的是「按了什么」。
|
||||
|
||||
两条路径互相独立:按 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,64 @@
|
||||
# 图片与纹理
|
||||
|
||||
`<image>` 用来显示一张纹理。它只负责把纹理按元素矩形铺开,本身不产生像素,也不负责加载。界面里用到的纹理都已经由客户端登记在贴图管理器里,写 UI 时从那里取,不在页面里现场生成。
|
||||
|
||||
## 贴图管理器中的纹理
|
||||
|
||||
`props.state.materials` 是 `ITextureManager`,客户端启动时把素材登记进去。取图片有两种方法:
|
||||
|
||||
- `getImageByAlias(alias)`:按别名取图片,返回 `ITexture | null`。别名来自素材配置,可能带后缀(如 `bg.jpg`),不是文件路径。
|
||||
- `getImage(index)`:按数字索引取图片,同样返回 `ITexture | null`。索引也来自素材配置。
|
||||
|
||||
```tsx
|
||||
// 按别名取一张已经登记好的图片
|
||||
const texture = props.state.materials.getImageByAlias('bg.jpg');
|
||||
|
||||
<image image={texture} loc={[40, 48, 96, 96]} />;
|
||||
```
|
||||
|
||||
取到后直接交给 `<image>` 的 `image` 属性,不需要额外判断或占位。
|
||||
|
||||
下面是 `<image>` 按 `loc` 显示纹理的效果。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="imageBasicLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## 图片尺寸
|
||||
|
||||
`<image>` 的显示矩形由 `loc` 决定:`[x, y, 宽, 高]`。纹理会被拉伸铺满这个矩形,所以同一张纹理放到不同大小会显示成不同尺寸。宽高比和纹理不一致时会变形,按纹理的原始宽高比给尺寸:
|
||||
|
||||
```tsx
|
||||
// 同一张纹理,显示成 64×64
|
||||
<image image={texture} loc={[40, 40, 64, 64]} />
|
||||
```
|
||||
|
||||
不写 `loc` 时元素默认 200×200。
|
||||
|
||||
下面把同一张纹理放进 64×64、96×96 与 128×128 三个矩形,对照显示尺寸的变化。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="imageSizesLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- 别名来自素材配置,可能带后缀(如 `bg.jpg`),不是文件路径;数字索引也来自同一份配置。
|
||||
- 同一张纹理取一次就够,不要把取图放进频繁执行的渲染逻辑里重复取。
|
||||
- 不要在 UI 里现场造纹理;界面只使用贴图管理器里已经登记的素材。
|
||||
- `<image>` 会把纹理拉伸到 `loc` 的宽高,比例不一致会变形;按原图比例给尺寸。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const imageBasicLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/image-basic.tsx');
|
||||
const imageSizesLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/image-sizes.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,200 @@
|
||||
# 示例(一)目标与骨架
|
||||
|
||||
前面五批讲的是零件:模板、元素、响应式、事件、组件、内置组件与 UI 栈。这一批把它们装成同一个能用的面板——一个背包 / 装备界面。六篇按「每一步只加一小段」推进,本篇先定目标、拆分与骨架。
|
||||
|
||||
## 这一步要解决什么
|
||||
|
||||
最终面板是一块 720×480 的区域:
|
||||
|
||||
- 顶部是标题与关闭按钮。
|
||||
- 左侧是 5 列的道具网格,格子显示名称与数量。
|
||||
- 右侧是选中道具的详情,没有选中时显示提示。
|
||||
- 底部是装备 / 使用 / 关闭按钮。
|
||||
- 道具变多后,左侧网格可以滚动。
|
||||
|
||||
本篇只做外框、标题、关闭按钮与左右两个占位区。网格、详情、滚动、交互与动画留到后面五篇,每一步都在这份骨架上继续填,不另起一套实现。
|
||||
|
||||
先搭骨架、后填数据,是因为骨架决定了每个后续节点「挂在哪里」:左侧区域有多大,网格就知道自己的行列要按什么尺寸排;右侧区域在哪,详情就知道自己该占多少文字宽度;底部操作条从哪开始,滚动区才不会压到按钮上。如果先写数据再回头调坐标,读者每加一步都要重新算一遍布局,最后也很难说清某一行代码到底属于树上的哪一层。
|
||||
|
||||
## 骨架在渲染树里的位置
|
||||
|
||||
先把最终面板的节点定下来,后面每一步都往这棵树里加东西。根 `container` 下依次是画布底色、面板主体、标题、关闭按钮、左侧占位与右侧占位,它们都是兄弟节点;树形规则本身见[第 2 篇「容器与坐标」](./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 篇「层级、变换与性能」](./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,299 @@
|
||||
# 示例(二)道具网格
|
||||
|
||||
上一篇的左侧只有一块占位。本篇把道具数据、`ItemCell` 与 `ItemGrid` 填进去,让网格能显示、能选中。
|
||||
|
||||
## 从占位到网格
|
||||
|
||||
本步只替换左侧占位区,右侧详情与底部操作条仍然是占位:
|
||||
|
||||
```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,194 @@
|
||||
# 示例(三)详情区
|
||||
|
||||
上一篇左侧已经能选道具,右侧还是占位。本篇把 `ItemDetail` 填上:名称、数量、描述,以及没有选中时的提示。
|
||||
|
||||
## 详情区接的是哪个状态
|
||||
|
||||
详情不自己保存状态,它只接收一个「选中项」。选中项在 `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,206 @@
|
||||
# 示例(四)滚动与列表
|
||||
|
||||
道具少的时候,网格一次就能排下。道具变多后,左侧区域放不下,需要滚动。本篇把示例(二)的普通网格换成 `Scroll`,并说明这次替换在渲染树、事件与数据流上各自改了什么。
|
||||
|
||||
## 为什么要换滚动
|
||||
|
||||
普通容器只是按坐标把子元素画出来:区域外的格子照样绘制,超出的部分被窗口裁掉,但节点仍然在树上。道具只有十件时感觉不到问题;四十件时,左侧区域外的格子会越画越多,滚轮也没有任何反应。
|
||||
|
||||
`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,362 @@
|
||||
# 示例(五)交互与状态
|
||||
|
||||
网格、详情与滚动都齐了,但面板还只能看不能动。本篇加 `ActionBar`:装备、使用、关闭,并把状态与副作用收口到 `InventoryPanel`。
|
||||
|
||||
## 这一步把交互接起来
|
||||
|
||||
三类操作各自改变一件事:
|
||||
|
||||
| 操作 | 改变什么 | 状态归谁 |
|
||||
| ---- | ---------------------------- | ------------------------ |
|
||||
| 装备 | 记录「当前选中的道具已装备」 | 面板的 `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,270 @@
|
||||
# 示例(六)动画、拆分与注册
|
||||
|
||||
前面五步已经把网格、详情、滚动与交互拼起来了。最后一步补三件事:让选中态与提示动起来、把代码落回五个文件、把面板注册成 `GameUI` 并从打开处接入。
|
||||
|
||||
## 最后一步要收什么
|
||||
|
||||
收尾不是「再加一个功能」,而是把前面五步已经写下的东西固定下来:
|
||||
|
||||
```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 通用模板」](./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 篇「显示开关」](./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,133 @@
|
||||
# 层级、变换与性能
|
||||
|
||||
元素摆好位置之后,还会遇到三类问题:层级怎么沿树生效、怎么缩放旋转与混合、什么时候该缓存。这三件事都写在元素属性上,不需要额外的图层对象。理解它们的前提是渲染树:层级、变换与缓存都沿着父子关系生效,不是全局开关。
|
||||
|
||||
<div id="渲染树层级与绘制顺序"></div>
|
||||
|
||||
## 渲染树、层级与绘制顺序
|
||||
|
||||
元素组成一棵渲染树:子元素相对父元素定位,绘制顺序、变换与缓存都沿父子关系生效。同一父级下的兄弟按 `zIndex` 从小到大绘制,命中顺序相反;`zIndex` 只在兄弟之间比较,父级的 `zIndex` 带着整棵子树参与父级兄弟的排序。`zIndex` 与 `hidden` 的完整语义见[通用参数页](./common-props.md#zindex)。
|
||||
|
||||
UI 栈也遵循同一套规则。控制器把每个打开的面板当作 UI 容器下的兄弟,按栈顺序分配递增的 `zIndex`;面板之间的遮挡由打开顺序与显示策略决定,面板内部的 `zIndex` 只影响这棵子树内部。先看面板在哪个栈、哪个位置,再看面板内部的兄弟顺序。
|
||||
|
||||
## 变换:scale、rotate 与 transform
|
||||
|
||||
`scale` 是 `[x, y]` 数组,分别表示横向与纵向缩放比例;`rotate` 的单位是弧度,不是角度。两者都作用在元素自己的坐标系里,锚点就是变换中心:缩放与旋转都绕锚点进行。默认锚点在左上角;改成 `[0.5, 0.5]` 后,同一个缩放或旋转会绕中心进行,元素的视觉位置与扩展方向都会跟着改变。
|
||||
|
||||
`scale` 与 `rotate` 是底层 `transform` 的简写:`transform` 属性可以直接接收一个 `Transform` 对象,用来表达更一般的矩阵与平移。日常写界面用 `scale` / `rotate` 就够了;需要直接替换整个变换矩阵时再传 `transform`,本篇不展开构造方式。
|
||||
|
||||
```tsx
|
||||
// scale 写 [x, y];rotate 写弧度。两者都是 transform 的简写属性
|
||||
<g-rect loc={[40, 40, 120, 80]} fillStyle="#2f6fed" scale={[1.2, 0.8]} />
|
||||
<g-rect loc={[220, 40, 120, 80]} fillStyle="#f2b84b" rotate={Math.PI / 12} />
|
||||
|
||||
// 同一个变换换锚点:anc 决定绕哪个点缩放 / 旋转
|
||||
<g-rect
|
||||
loc={[40, 180, 120, 80]}
|
||||
fillStyle="#2f6fed"
|
||||
scale={[1.2, 0.8]}
|
||||
anc={[0.5, 0.5]}
|
||||
/>
|
||||
<g-rect
|
||||
loc={[220, 180, 120, 80]}
|
||||
fillStyle="#f2b84b"
|
||||
rotate={Math.PI / 12}
|
||||
anc={[0.5, 0.5]}
|
||||
/>
|
||||
```
|
||||
|
||||
`scale` 只写一个数字不会生效。需要等比缩放时写 `scale={[1.2, 1.2]}`,需要压扁时分别给两个值。`rotate` 想转 30 度要写 `Math.PI / 6`;写成 `30` 会转很多圈。
|
||||
|
||||
`container` 默认开启缓存。对默认缓存的容器做 `scale` 或 `rotate` 时,引擎会先画出缓存图,再对这张图做变换;缓存图被缩放或旋转后会重新采样,边缘可能发糊。需要清晰变换时,给做变换的容器加 `nocache`,让子元素按变换直接绘制。
|
||||
|
||||
下面四组对比同一个 `scale` 或 `rotate` 在 `anc={[0, 0]}` 与 `anc={[0.5, 0.5]}` 下的差异。每组锚点位置的白点就是变换中心:`anc={[0, 0]}` 以左上角为基准,缩放向右下方展开、旋转绕左上角扫过;`anc={[0.5, 0.5]}` 以中心为基准,缩放向四周展开、旋转绕中心转动,两者的视觉位置也不同。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="layerTransformLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 变换沿树传递
|
||||
|
||||
父级的平移、缩放、旋转会复合到子级。父级移动,子级跟着移动;父级放大,子级的坐标与尺寸都按放大后的比例理解;父级旋转,子级的局部坐标轴也跟着旋转。子元素不需要知道父级做了哪些变换,它只按自己的局部坐标描述内容。
|
||||
|
||||
```tsx
|
||||
// 父容器放大 1.5 倍;加 nocache 让子元素按变换直接绘制,避免缓存图被重采样
|
||||
<container loc={[80, 40, 140, 100]} scale={[1.5, 1.5]} nocache>
|
||||
<g-rect loc={[0, 0, 140, 100]} fill fillStyle="#2f6fed" />
|
||||
<text loc={[12, 12]} text="局部坐标 140×100" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
子矩形的 `loc` 仍是 `[0, 0, 140, 100]`,但父级放大后,它在画布上占 210×150。文字也一起放大,包括字形。要反过来「让子元素不跟着放大」,不能靠给子元素写一个 0.667 的 `scale` 去抵消——父级变换已经作用在整棵子树上;正确做法是把需要独立缩放的内容移出这个父级,放到另一个不被缩放的容器里。
|
||||
|
||||
嵌套变换不要用「把每层坐标累加成屏幕坐标」的心算。按树逐层理解:先看元素在父容器里的局部坐标,再看父容器在它自己父级里的位置与变换。需要跨元素比较位置时,用事件里的 `absoluteX` / `absoluteY`(画布坐标),不要自己把若干层的 `x` / `y` 相加。
|
||||
|
||||
下面左侧的父容器放大了 1.5 倍,子元素仍按局部坐标写;右侧是同一棵子树未缩放的参考。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="layerTransformTreeLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 缓存:cache 与 nocache {#缓存与脏更新}
|
||||
|
||||
默认值只作判断起点:`container` 默认缓存;`text`、`image` 与全部 `g-*` 图形默认不缓存。
|
||||
|
||||
- 什么时候开:结构复杂、内容稳定、重复绘制成本高的子树。
|
||||
- 什么时候不开:内容频繁变化、子树很小,或者缓存的维护成本超过收益。
|
||||
|
||||
`cache` 用于打开缓存,`nocache` 用于关闭缓存。两者都在元素创建时决定,`nocache` 优先级更高;不要把它当成运行时反复切换的开关,需要改变缓存策略时应当重新创建元素。
|
||||
|
||||
```tsx
|
||||
// 静态复杂子树:内容不变、绘制成本高,开缓存
|
||||
<container loc={[40, 40, 240, 160]} cache>
|
||||
<g-rect loc={[0, 0, 240, 160]} fillStyle="#1b2433" />
|
||||
<g-rect loc={[16, 16, 208, 40]} fillStyle="#2f6fed" />
|
||||
<g-circle circle={[48, 96, 24]} fillStyle="#f2b84b" />
|
||||
<text loc={[96, 84]} text="静态标题" fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
|
||||
// 频繁变化的子树:文字随时会被改写,不开缓存
|
||||
<container loc={[40, 40, 240, 160]} nocache>
|
||||
<text loc={[0, 0]} text={String(clock.value)} fillStyle="#e8f0ff" />
|
||||
</container>
|
||||
```
|
||||
|
||||
## composite
|
||||
|
||||
`composite` 默认 `source-over`。值取 `GlobalCompositeOperation`(见 [MDN 的 composite 文档](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation)),例如 `multiply`、`screen`、`overlay`、`lighter`。它影响当前绘制结果与已绘制内容的混合方式,不改变布局与命中区域。
|
||||
|
||||
```tsx
|
||||
// composite 默认 source-over;这里用 multiply 让上层与已绘制内容混合
|
||||
<g-rect loc={[40, 40, 120, 120]} fillStyle="#2f6fed" />
|
||||
<g-rect loc={[100, 80, 120, 120]} fillStyle="#f2b84b" composite="multiply" />
|
||||
```
|
||||
|
||||
下面三组是相同的重叠图形,分别使用 `source-over`、`multiply` 与 `screen`。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="layerCompositeLoader" :width="480" :height="320" />
|
||||
</ClientOnly>
|
||||
|
||||
## 性能:缓存的代价
|
||||
|
||||
缓存用离屏画布换绘制次数:每帧少画一遍子树,代价是多占一份画布内存,内容变化时还要重画整块缓存。嵌套缓存会叠加内存占用,只在绘制成本确实高的地方开。没有确认有性能问题之前,先不开缓存。
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `scale` 必须是 `[x, y]` 数组。写成数字不会生效,也不会报错。
|
||||
- `rotate` 的单位是弧度。想转 30 度要写 `Math.PI / 6`,不是 `30`。
|
||||
- 锚点是变换中心:缩放与旋转都绕锚点进行,改锚点会连同变换一起改变视觉位置。
|
||||
- 父级变换会作用在整棵子树上;子元素不能用自己的 `scale` 抵消父级缩放,需要独立缩放时把内容移出该父级。
|
||||
- `cache` / `nocache` 在元素创建时决定,`nocache` 优先级更高;不要把它当成运行时反复切换的开关。
|
||||
- `composite` 影响绘制结果的混合方式,不改变布局与命中区域。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const layerTransformLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/layer-transform.tsx');
|
||||
const layerTransformTreeLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/layer-transform-tree.tsx');
|
||||
const layerCompositeLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/layer-composite.tsx');
|
||||
</script>
|
||||
@@ -0,0 +1,296 @@
|
||||
# 响应式
|
||||
|
||||
前面几篇的元素都是静态的:写死坐标、写死颜色。真实界面要跟着数据变,比如点一下按钮让计数加一、输入内容后让文字更新。如果每次都手写「改完数据再手动重画」,迟早会漏掉某处更新。
|
||||
|
||||
Vue 的响应式解决的就是这件事:数据被读取时记下依赖,数据变化时自动重新执行用到它的渲染函数,渲染器再把变化 patch 到画布上的元素。本篇从零讲清 UI 作者需要的那部分,不假设你写过 Vue。
|
||||
|
||||
## 数据到渲染
|
||||
|
||||
响应式值变化后,读取过它的组件会重新执行渲染函数,对应元素的属性或子组件随之更新;没有读取它的组件不会因为这次变化而更新。
|
||||
|
||||
```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,162 @@
|
||||
# 文字
|
||||
|
||||
文字元素只画一行。它的宽高由字体测量结果决定,不能自动换行,也没有行高与对齐属性;字号、字重、斜体这些信息由 `Font` 描述,`<text>` 负责把内容画出来。这一篇先讲 `Font`,再讲文字元素怎么用、尺寸与锚点怎么定。
|
||||
|
||||
## 字体:Font
|
||||
|
||||
`Font` 是描述字体的值对象,不负责绘制。它只有五项配置:
|
||||
|
||||
| 属性 | 默认值 | 说明 |
|
||||
| ---------- | ----------- | ---------------------------------------------- |
|
||||
| `family` | `'Verdana'` | 字体族名称 |
|
||||
| `size` | `16` | 字号数值 |
|
||||
| `sizeUnit` | `'px'` | 字号单位,通常用 `px` |
|
||||
| `weight` | `400` | 字重,`0`–`1000`,可写数字或 `FontWeight` 枚举 |
|
||||
| `italic` | `false` | 是否斜体 |
|
||||
|
||||
`weight` 除了直接写数字,也可以用 `FontWeight` 枚举。`FontWeight` 从 `@motajs/render` 导入,提供三个常用档位:`FontWeight.Light = 300`、`FontWeight.Normal = 400`、`FontWeight.Bold = 700`。枚举值本身就是数字,两种写法等价。
|
||||
|
||||
构造函数按位置传参:`Font(family, size, sizeUnit, weight, italic)`。省略的项用上面的默认值。例如在 TSX 里直接内联:
|
||||
|
||||
```tsx
|
||||
// 24px 粗体:字重可以用 FontWeight 枚举,也可以直接写数字
|
||||
<text
|
||||
text="标题"
|
||||
font={new Font('Verdana', 24, 'px', FontWeight.Bold)}
|
||||
fillStyle="#ffffff"
|
||||
/>
|
||||
```
|
||||
|
||||
`Font` 与 `FontWeight` 都从 `@motajs/render` 导入。`font` 只接受 `Font` 实例,不接收 CSS 字符串;不写 `font` 时使用默认 `Font`,也就是 Verdana、16px、400、非斜体。
|
||||
|
||||
五项配置在构造后是只读的:要换字号或字重,就再构造一个 `Font`。修改 `Font.defaultFamily` 这类默认值只影响之后创建的实例,已经创建的 `Font` 保留构造时的值。
|
||||
|
||||
需要基于默认值或已有字体做局部修改时,用静态方法:
|
||||
|
||||
- `Font.defaults()` 返回一个默认 `Font`;也可以传配置对象,例如 `Font.defaults({ size: 20 })`,没传的项仍用默认值。
|
||||
- `Font.clone(base, patch)` 复制一份字体,用 `patch` 覆盖部分字段,例如 `Font.clone(font, { weight: FontWeight.Bold })`。
|
||||
- `Font.setDefaults(font)` 一次性写入五项默认值;之后的 `new Font()` 都从它开始。
|
||||
- `addFallback(...fonts)` 给字体加后备字体;主字体不可用时按添加顺序尝试。后备字体也可以再加后备,但不要形成循环。
|
||||
|
||||
`Font` 没有行高、字距、下划线、对齐这些属性;它们不属于字体,文字元素也不提供行高或对齐属性。斜体只有 `italic` 一个开关。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="fontTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
同一个字符串换成不同字号、字重与斜体后的效果。
|
||||
|
||||
## 文字元素用法
|
||||
|
||||
`container` 里不能直接写裸文字:空白文字会变成注释节点,非空白文字会创建文字元素并告警。文字内容一律放在 `text` 属性里:
|
||||
|
||||
```tsx
|
||||
// 一行文字:内容只写在 text 属性
|
||||
<text loc={[40, 40]} text="一行文字" fillStyle="#ffffff" />
|
||||
```
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="basicTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
最基本的一行文字:内容写在 `text`,位置由 `loc` 决定。
|
||||
|
||||
`text` 只支持单行;字符串里的换行符不会产生第二行。需要多行、折行或输入时,用内置的文本组件。
|
||||
|
||||
### 文字属性
|
||||
|
||||
文字元素自己的属性不多,全部列在下面:
|
||||
|
||||
| 属性 | 默认值 | 作用 |
|
||||
| ------------- | ----------- | ------------------------ |
|
||||
| `text` | `''` | 要显示的内容,只支持单行 |
|
||||
| `font` | 默认 `Font` | 字体,必须是 `Font` 实例 |
|
||||
| `fillStyle` | `'#fff'` | 填充颜色 |
|
||||
| `strokeStyle` | 无 | 描边颜色,设置后才描边 |
|
||||
| `strokeWidth` | `1` | 描边宽度,参与尺寸测量 |
|
||||
|
||||
- `fillStyle` 默认白色,且不从父容器继承:父容器设了 `fillStyle`,文字也不会跟着变色。需要统一颜色时,在每个文字上显式写,或把同一个颜色变量传给每个文字。
|
||||
- `strokeStyle` 没有默认值。不写就不描边;写了之后才按这个颜色描边。
|
||||
- `strokeWidth` 默认 `1`,只在有描边时看得出效果。描边宽度会参与尺寸测量,改大之后文字占用的矩形也会变大。
|
||||
- 绘制时先画描边、再画填充,填充会盖住描边靠内的一半,所以描边看起来是沿字形外沿的一条边。
|
||||
- `text` 只支持单行,换行符不会生效。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="styleTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
填充、描边颜色与描边宽度的对照。
|
||||
|
||||
### 尺寸、锚点与对齐
|
||||
|
||||
文字没有固定宽度。宽高由字体测量结果决定:内容、字号、字重、斜体、描边宽度一变,尺寸就重新计算。给 `<text>` 写 `width` / `height` 不会裁剪文字,只会暂时改变元素的定位框;下一次测量会把它覆盖回去。需要固定占位或裁剪时,在外面包一个容器。
|
||||
|
||||
默认锚点是 `anc={[0, 0]}`,`loc` 的 x / y 是测量矩形的左上角。锚点用 `anc={[ax, ay]}` 表示,两个值分别是横向、纵向的锚点比例:`anc={[0.5, 0.5]}` 同时把横纵锚点设成中心,`anc={[1, 0]}` 让 x 落在右边缘、y 仍落在顶边,`anc={[1, 1]}` 则是右下角。
|
||||
|
||||
```tsx
|
||||
// 锚点居中:loc 的 x / y 落在文字中心
|
||||
<text loc={[240, 160]} anc={[0.5, 0.5]} text="居中文字" fillStyle="#ffffff" />
|
||||
```
|
||||
|
||||
本篇统一用 `loc` + `anc` 写位置和锚点。`loc` 只写 `[x, y]`,锚点统一用 `anc`。`loc` 的完整形式还能在坐标后写宽高与锚点(`[x, y, width, height, ax, ay]`),但文字尺寸由测量决定,宽高会被覆盖,所以文字页不采用;锚点也不塞进 `loc`。`anchorX` / `anchorY` 是 `anc` 的等价独立属性写法,例如 `anc={[0.5, 0.5]}` 等价于 `anchorX={0.5} anchorY={0.5}`;同一处只选一种写法,不要混用。
|
||||
|
||||
右对齐数值时用 `anc={[1, 0]}`,让文字的右边缘落在 x 上,y 仍是顶边:
|
||||
|
||||
```tsx
|
||||
// 锚点 [1, 0]:x 是文字右边缘,适合数量、金币这类右对齐数字
|
||||
<text loc={[440, 24]} anc={[1, 0]} text="128" fillStyle="#f2b84b" />
|
||||
```
|
||||
|
||||
这段文字无论内容多长,右边缘都固定在 `(440, 24)`,左侧按测量宽度向左延伸。做数值列时,把这一列都设成同一个 x 与 `anc={[1, 0]}`,数字就会沿右边缘对齐。
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="anchorTextLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
三行文字分别用不同的锚点,白点标出 `loc` 的位置。
|
||||
|
||||
文字没有 `textAlign`、`textBaseline`、`lineHeight` 这些属性。对齐只能靠锚点;单行文字基线固定,垂直居中按实际字形的上下沿算,不按行高;也不会自动换行。
|
||||
|
||||
## 文字在界面里的常见用法
|
||||
|
||||
- 标题:用较大字号与较粗字重,与正文拉开层级。
|
||||
- 标签:小字号、浅色,做说明,不抢主内容的视觉重心。
|
||||
- 按钮文字:放在按钮底容器里,点击由按钮底统一处理。
|
||||
- 数值显示:用 `anc={[1, 0]}` 右对齐;不要用 `width` 裁剪,长度变化靠锚点对齐。
|
||||
|
||||
## 换行、打字机与输入
|
||||
|
||||
文字元素只画一行,`text` 里的换行符不会生效,长文本也不会按宽度折行。多行说明、按宽度折行与打字机效果不要用多个 `<text>` 硬拼;用[内置组件:文本](./builtin-text.md)里的 `TextContent`。
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const basicTextLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/text-basic.tsx');
|
||||
const fontTextLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/text-font.tsx');
|
||||
const styleTextLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/text-style.tsx');
|
||||
const anchorTextLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/text-anchor.tsx');
|
||||
</script>
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- `fillStyle` 默认是白色。浅色背景上直接写字要显式改色。
|
||||
- `strokeWidth` 默认是 `1`,描边会计入尺寸;给 `strokeStyle` 时记得一起考虑宽度,靠边摆放要留出空间。
|
||||
- 给文字设 `width` / `height` 不会截断内容,下一次测量还会覆盖它们。需要固定占位或裁剪时,用外层容器。
|
||||
- 长文本不要用文字元素硬排。它只适合标题、标签、数值这类单行内容。
|
||||
- 本篇统一用 `loc` + `anc`;`anchorX` / `anchorY` 是等价写法,同一处只写一种。
|
||||
@@ -0,0 +1,179 @@
|
||||
# UI 入门
|
||||
|
||||
这篇讲三件事:怎样打开一个 UI、TSX 里的标签和组件怎么写、渲染树是什么样。看完你能在模板里写出文字和矩形。
|
||||
|
||||
## UI 的打开
|
||||
|
||||
每个 UI 是一个 `GameUI` 对象。在已有 UI 里,可以用 `props.controller` 打开另一个 UI,返回值是这次打开的实例:
|
||||
|
||||
```tsx
|
||||
// 打开 MyPanelUI,空对象是传给它的参数
|
||||
const instance = props.controller.open(MyPanelUI, {});
|
||||
|
||||
// 关闭这次打开的实例
|
||||
props.controller.close(instance);
|
||||
```
|
||||
|
||||
每次 `open` 都会得到独立实例,同一个 `GameUI` 也可以被打开多次。参数、栈顺序与 `alwaysShow` 的细节见 [UI 系统](./ui-system.md)。
|
||||
|
||||
## TSX 里的标签和组件
|
||||
|
||||
这里的 TSX 不是 DOM 的 JSX。它看起来像 HTML,但会被渲染系统解释成画布元素。记住下面几条就能开始写。
|
||||
|
||||
### 标签
|
||||
|
||||
`container`、`g-rect`、`text` 都是渲染元素,不是 HTML 标签。元素名一律小写,没有子元素时用自闭合写法:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[0, 0, 120, 80]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
有子元素时成对写,例如 `<container>...</container>`。
|
||||
|
||||
### 属性
|
||||
|
||||
属性写在标签上,名字用 camelCase:
|
||||
|
||||
```tsx
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
```
|
||||
|
||||
`loc` 的值是数组,所以写成 `loc={[...]}`;`text` 的值是字符串,直接写引号即可。
|
||||
|
||||
### 表达式与注释
|
||||
|
||||
`{}` 里可以写 JavaScript 表达式,表达式的结果会作为属性值,例如:
|
||||
|
||||
```tsx
|
||||
<text text={'分数:' + score} />
|
||||
```
|
||||
|
||||
`{/* ... */}` 是 TSX 注释,不会显示出来。
|
||||
|
||||
### 嵌套
|
||||
|
||||
标签里可以放子标签,子标签就是它的内容。下面容器里有一个文字和一个矩形:
|
||||
|
||||
```tsx
|
||||
<container loc={[0, 0, 240, 120]}>
|
||||
<text loc={[12, 12]} text="标题" fillStyle="#ffffff" />
|
||||
<g-rect loc={[12, 44, 120, 48]} fillStyle="#2f6fed" />
|
||||
</container>
|
||||
```
|
||||
|
||||
### 组件
|
||||
|
||||
大写开头的名字(如 `MyPanel`)是组件,可以像标签一样使用:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>
|
||||
<MyPanel />
|
||||
</container>
|
||||
```
|
||||
|
||||
`FULL_LOC` 来自标准模板的 import。
|
||||
|
||||
组件本身不额外产生节点,它的根元素挂在使用位置。组件内部写什么,由组件自己决定。
|
||||
|
||||
条件与循环这里先不展开,用到时再看[条件渲染与循环渲染](./conditional-and-list-rendering.md)。
|
||||
|
||||
## 渲染树的基本模型
|
||||
|
||||
模板里的 UI 都是这样一个容器:
|
||||
|
||||
```tsx
|
||||
<container loc={FULL_LOC}>{/* UI 内容 */}</container>
|
||||
```
|
||||
|
||||
- `container` 是整块 UI 的容器,负责位置和大小;
|
||||
- 里面的 `text`、`g-rect` 等元素负责具体内容;
|
||||
- 元素放在哪个容器里,就跟着哪个容器移动;子元素的位置相对它所在的容器;
|
||||
- `MyPanel` 组件本身不额外产生节点,它的根 `container` 就是整块 UI 的根。
|
||||
|
||||
所以写 UI 时,先把模板里的 `container` 当成画布,再往里面按顺序放元素。
|
||||
|
||||
## 一行文字
|
||||
|
||||
在模板的 `container` 里加一行:
|
||||
|
||||
```tsx
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
```
|
||||
|
||||
- `text` 是元素名,表示一行文字;
|
||||
- `loc` 的前两个数 `24, 24` 是文字左上角相对容器的位置;
|
||||
- `text="你好,UI"` 是要显示的文字;
|
||||
- `fillStyle="#e8f0ff"` 是文字颜色。
|
||||
|
||||
坐标以容器左上角为原点:第一个数是向右的距离,第二个数是向下的距离。文字的大小由字号决定,所以 `loc` 只写两个数就够了。
|
||||
|
||||
## 一个矩形
|
||||
|
||||
再加一个矩形:
|
||||
|
||||
```tsx
|
||||
<g-rect loc={[24, 64, 160, 80]} fillStyle="#2f6fed" />
|
||||
```
|
||||
|
||||
- `g-rect` 是绘制矩形用的标签;
|
||||
- `loc` 的前两个数 `24, 64` 是矩形左上角的位置,后两个数 `160, 80` 是宽和高;
|
||||
- 矩形默认填充,`fillStyle="#2f6fed"` 是填充颜色。
|
||||
|
||||
和文字不同,矩形必须给出宽高,所以 `loc` 写了四个数。
|
||||
|
||||
## 组合
|
||||
|
||||
两段放进同一个 `container`,就是完整的 UI:
|
||||
|
||||
```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';
|
||||
|
||||
// 这里填写自定义的 UI 参数
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>
|
||||
<text loc={[24, 24]} text="你好,UI" fillStyle="#e8f0ff" />
|
||||
<g-rect loc={[24, 64, 160, 80]} fillStyle="#2f6fed" />
|
||||
</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
在已有 UI 中使用 `props.controller.open(MyPanelUI, {})` 打开后,效果就是下面这样。同一个容器里的元素按书写先后顺序叠放,后写的画在上面。
|
||||
|
||||
## 运行效果
|
||||
|
||||
<ClientOnly>
|
||||
<RenderDemo :loader="basicsLoader" :width="480" :height="320" />
|
||||
<template #fallback>
|
||||
渲染示例需要浏览器环境。
|
||||
</template>
|
||||
</ClientOnly>
|
||||
|
||||
<script setup>
|
||||
import RenderDemo from '../../../.vitepress/components/renderDemo.vue';
|
||||
|
||||
const basicsLoader = () =>
|
||||
import('../../../.vitepress/components/demos/ui/basics-demo.tsx');
|
||||
</script>
|
||||
|
||||
## 后续
|
||||
|
||||
- 摆位置:[容器与坐标](./container-and-coordinates.md)
|
||||
- 画更多图形:[基础图形](./basic-shapes.md)
|
||||
- 写字:[文字](./text.md)
|
||||
- 处理交互:[事件与交互](./events.md)
|
||||
- 拆组件:[自定义组件](./custom-components.md)
|
||||
- 接 UI 系统:[UI 系统](./ui-system.md)
|
||||
@@ -0,0 +1,135 @@
|
||||
# UI 性能
|
||||
|
||||
多数简单 UI 不需要特别的性能优化。渲染系统会按需更新,缓存也默认开在合适的元素上;按常规方式写,性能通常已经足够。下面是一组日常习惯,用来减少不必要的绘制与内存占用,按需采用即可。
|
||||
|
||||
## 元素平铺与分组
|
||||
|
||||
同一层里堆很多兄弟元素,会让一次更新牵动整层。更新会沿父链标脏,父容器需要重新遍历并绘制受影响的部分;兄弟越多,重复的工作越明显。按更新频率分组:把一起变化、且不常变的元素放进同一个 `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" />
|
||||
```
|
||||
|
||||
缓存的默认值与开关语义见[层级、变换与性能](./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` 的完整说明见[通用参数](./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,140 @@
|
||||
# UI 系统
|
||||
|
||||
UI 系统由控制器、实例和栈组成。每次 `open` 都会在控制器上产生一个实例并压入栈,`close` 把实例从栈里移除;栈记录打开顺序,决定实例的叠放关系,也决定哪些实例可见。一个控制器同时管理一条栈、一个背景和一套显示策略。
|
||||
|
||||
写 UI 时主要接触控制器与 `GameUI`;实例由系统创建,作者通常只持有 `open` 返回的实例,用来关闭或隐藏它。
|
||||
|
||||
## 打开与关闭
|
||||
|
||||
需要让一个界面出现在控制器管理的画面上时,用 `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,44 @@
|
||||
# UI 通用模板
|
||||
|
||||
写 UI 时从这段模板开始。
|
||||
|
||||
```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';
|
||||
|
||||
// 这里填写自定义的 UI 参数
|
||||
interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}
|
||||
|
||||
const myPanelProps = {
|
||||
props: ['controller', 'instance', 'state']
|
||||
} satisfies SetupComponentOptions<MyPanelProps>;
|
||||
|
||||
const MyPanel = defineComponent<MyPanelProps>(props => {
|
||||
return () => (
|
||||
<container loc={FULL_LOC}>{/* 在这里编写自己的 UI 内容 */}</container>
|
||||
);
|
||||
}, myPanelProps);
|
||||
|
||||
export const MyPanelUI = new GameUI('my-panel', MyPanel);
|
||||
```
|
||||
|
||||
## 模板用法
|
||||
|
||||
1. 复制到 `src/client/ui/` 下新建的 `.tsx` 文件(例如 `my-panel.tsx`)。
|
||||
2. 把 `MyPanel`、`myPanelProps`、`MyPanelUI` 换成自己的名字。
|
||||
3. 在 `<container>` 里写 UI 内容。
|
||||
4. 在 `src/client/ui/index.ts` 中导出 `MyPanelUI`。
|
||||
|
||||
## 后续阅读
|
||||
|
||||
- 先读 [UI 入门](./ui-basics.md)
|
||||
- 摆放元素:[容器与坐标](./container-and-coordinates.md)
|
||||
- 画图形:[基础图形](./basic-shapes.md)
|
||||
- 写字与图片:[文字](./text.md)、[图片与纹理](./image-and-texture.md)
|
||||
- 让 UI 动起来:[响应式](./reactivity.md)、[事件与交互](./events.md)
|
||||
- 拆组件:[自定义组件](./custom-components.md)
|
||||
- 接 UI 系统:[UI 系统](./ui-system.md)
|
||||
- 完整示例:[示例(一)目标与骨架](./inventory-example-1-skeleton.md)
|
||||
@@ -0,0 +1,109 @@
|
||||
# 什么是组件
|
||||
|
||||
组件可以看成 UI 的函数:调用时接收 props,返回一棵 UI 树。同一个组件声明一次,就能在不同位置反复使用;每次传入不同的 props,得到不同的画面。
|
||||
|
||||
本篇只讲组件最基本的形态、props 的传法,以及组件与 GameUI 的关系。
|
||||
|
||||
## 用 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>
|
||||
@@ -35,7 +35,8 @@
|
||||
|
||||
## 边界与注意
|
||||
|
||||
- <strong>渲染端内容</strong>:渲染端尚未完工,本层当前只收录数据端内容;渲染端专题只用占位标记指出归属,待完工后补上。
|
||||
- <strong>渲染端内容</strong>:高级 II 已收录「自定义 UI 与渲染」子分组,本层其它篇目仍以数据端为主;编辑器与内容配置部分只用占位标记指出归属。
|
||||
- <strong>性能边界</strong>:高级 II 的《UI 性能》讲缓存与显示策略的取舍,引擎级性能仍属高级 III。
|
||||
- <strong>编辑器内容</strong>:涉及编辑器与内容配置的部分只保留占位,不在本层展开。
|
||||
- <strong>不重复中级已讲内容</strong>:接口的日常用法、参数清单与常见改法属于中级教程;本层只在需要说明扩展点时引用,不整段重写。
|
||||
- <strong>高级 III 入口</strong>:该层已可阅读,入口见[高级 III 导览](./iii/)。
|
||||
@@ -11,6 +11,7 @@
|
||||
"include": [
|
||||
"./.vitepress/**/*.ts",
|
||||
"./.vitepress/**/*.vue",
|
||||
"./.vitepress/**/*.tsx",
|
||||
"../src/types/vite-env.d.ts"
|
||||
]
|
||||
}
|
||||
Reference in new issue
Block a user