# 自定义组件 前面的页面已经能用容器、文字、图形与内置组件拼出整块 UI。当同一段 UI 要在多处出现时,把这块 UI 拆成一个自定义组件,声明一次,在各处调用。 这一篇只讲怎么用:怎么接收参数、怎么发事件、怎么留出内容位置,以及怎么把属性透传给内部元素。 ## 前置知识 阅读本篇前,建议先读完: - [什么是组件](./what-is-component.md) - [内置组件:基础](./builtin-basic.md) ## props 组件的外部参数叫 props。父组件把值写在组件标签的属性上,子组件通过 `props.x` 读取。声明分三步: 1. 定义 Props 接口,普通组件继承 `DefaultProps`; 2. 在 `SetupComponentOptions` 的 `props` 数组里列出用到的键; 3. 用 `defineComponent(setup, options)` 声明组件。 ```tsx import { computed, defineComponent } from 'vue'; // setup interface ItemCardProps extends DefaultProps { label: string; color?: string; } const itemCardProps = { props: ['label', 'color'] } satisfies SetupComponentOptions; const ItemCard = defineComponent(props => { // 组件内容 const color = computed(() => props.color ?? '#f2b84b'); return () => ( ); }, itemCardProps); ``` 父组件把值写在标签上;不传 `color` 时使用默认颜色: ```tsx ``` ## 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 () => ( ); }, itemCardProps); ``` 父组件在标签上写 `on事件名`,事件的参数会传进处理函数: ```tsx const handlePick = (label: string) => console.log(label); ; ``` 需要双向绑定时,把事件声明为 `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; ``` 然后在组件里调用两种 slot: ```tsx const Panel = defineComponent((props, { slots }) => { // 组件内容 return () => ( {slots.title?.('背包')} {slots.default?.()} ); }, panelProps); ``` ### 默认 slot 默认 slot 的内容直接写在组件标签之间。父组件放什么,子组件就在 `slots.default?.()` 的位置显示什么: ```tsx ``` ### 具名 slot 具名 slot 用一个对象传入,键名就是 slot 名。父组件可以在对象里同时写 `title` 与 `default`;`title` 对应的函数会收到子组件调用 `slots.title?.('背包')` 时传入的参数: ```tsx {{ title: (title: string) => ( ), default: () => ( ) }} ``` 只要用了具名 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; const Field = defineComponent((_props, { attrs }) => { // 组件内容 return () => ; }, fieldProps); ``` 父组件直接写内部元素要用的属性: ```tsx ``` `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 () => ( {slots.default?.()} ); }, itemCardProps); // UI 组件:把卡片放进整屏容器,并管理选中项 interface MyPanelProps extends IGameUIPropsBase, DefaultProps {} const myPanelProps = { props: ['controller', 'instance', 'state'] } satisfies SetupComponentOptions; const MyPanel = defineComponent(props => { const selected = ref('甲'); const handlePick = (label: string) => { selected.value = label; }; return () => ( ); }, 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 传入。