4.5 KiB
什么是组件
组件可以看成 UI 的函数:调用时接收 props,返回一棵 UI 树。同一个组件声明一次,就能在不同位置反复使用;每次传入不同的 props,得到不同的画面。
本篇只讲组件最基本的形态、props 的传法,以及组件与 GameUI 的关系。
前置知识
阅读本篇前,建议先读完:
用 props 接收数据
组件通过 props 接收父组件给的数据。写法固定为三步:
- 定义 Props 接口,普通组件继承
DefaultProps; - 在
SetupComponentOptions的props数组里列出组件用到的键; - 用
defineComponent<Props>(props => ...)声明组件。
只有列在 props 数组里的键,才能在子组件里通过 props 读到。父组件把值写在组件标签的属性上,子组件通过 props.x 读取;某个 props 可以不传时,默认值用 computed 派生,props 变化时会重新计算。
普通组件:ItemCard
ItemCard 接收 position、label、color 三个 props,返回容器、矩形和文字:
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:
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。