---
lang: zh-CN
---
# UI 编写
本文将介绍如何在 2.B 样板中编写 UI，以及如何优化 UI 性能。
## 创建 UI 文件
首先，我们打开 `packages-user/client-modules/render` 文件夹，这里是目前样板的 UI 目录（之后可能会修改），我们可以看到 `components` `legacy` `ui` 三个文件夹，其中 `component` 是组件文件夹，也就是所有 UI 都可能用到的组件，例如滚动条、分页、图标等，这些东西不会单独组成一个 UI，但是可以方便 UI 开发。`legacy` 文件夹是将要删除或重构的内容，不建议使用里面的内容。`ui` 就是 UI 文件夹，这里面存放了所有的 UI，我们在这里创建一个文件 `myUI.tsx`。
## 编写 UI 模板
下面，我们需要编写 UI 模板，以怪物手册为例，模板如下，直接复制粘贴即可：
```tsx
import { defineComponent } from 'vue';
import { GameUI, UIComponentProps } from '@motajs/system-ui';
import { SetupComponentOptions } from '../components';
export interface MyBookProps extends UIComponentProps {}
const myBookProps = {
props: ['controller', 'instance']
} satisfies SetupComponentOptions<MyBookProps>;
export const MyBook = defineComponent<MyBookProps>(props => {
return () => <container></container>;
}, myBookProps);
export const MyBookUI = new GameUI('my-book', MyBook);
```
然后打开 `index.ts`，增加如下代码：
```ts
export * from './myUI';
```
## 添加一些内容
新的 UI 使用 tsx 编写，即 `TypeScript JSX`，可以直接在 ts 文件中编写 XML，非常适合编写 UI。例如，我们想要把 UI 的位置设为水平竖直居中，位置在 240, 240，长宽为 480, 480，并显示一个文字，可以这么写：
```tsx
// ... 其他内容
// loc 参数表示这个元素的位置，六个数分别表示：
// 横纵坐标；长宽；水平竖直锚点，0.5 表示居中，1 表示靠右或靠下对齐，可以填不在 0-1 范围的数
// 每两项组成一组，这两项要么都填，要么都不填，例如长宽可以都不填，横纵坐标可以都不填
// 不填时会使用默认值，或是组件内部计算出的值
return () => (
<container loc={[240, 240, 480, 480, 0.5, 0.5]}>
{/* 文字元素会自动计算长宽，因此不能手动指定 */}
<text text="这是一段文字" loc={[240, 240, void 0, void 0, 0.5, 0.5]} />
</container>
);
```
## 显示 UI
我们编写完 UI 之后，这个 UI 并不会自己显示，需要手动打开。我们找到 `ui/main.tsx`，在 `MainScene` 这个根组件中添加一句话：
```ts
// 在这添加引入
import { MyBookUI } from './ui';
// ... 其他内容
const MainScene = defineComponent(() => {
// ... 其他内容
// 在这添加一句话，打开 UI，第二个参数为传入 UI 的参数，后面会有讲解
// 纵深设为 100 以保证可以显示出来，纵深越大，元素越靠上，会覆盖纵深低的元素
mainUIController.open(MyBookUI, { zIndex: 100 });
return () => (
// ... 其他内容
);
});
```
这样的话，我们就会在页面上显示一个新的 UI 了！不过这个 UI 会是常亮的 UI，没办法关闭，我们需要更精细的控制。我们可以在内部使用 `props.controller` 来获取到 UI 控制器实例，使用 `props.instance` 获取到当前 UI 实例，从而控制当前 UI 的状态：
```tsx
export const MyBook = defineComponent<MyBookProps>(props => {
// 例如，我们可以让它在打开 10 秒钟后关闭：
setTimeout(() => props.controller.close(props.instance), 10000);
return () => (
// ... UI 内容
);
}, myBookProps);
```
除此之外，我们还可以在任意渲染端模块中引入 `ui/controller` 来获取到根组件的 UI 控制器，注意跨文件夹引入时需要引入 `@user/client-modules`。例如，我们可以在其他文件中控制这个 UI 的开启与关闭：
```ts
import { mainUIController, MyBookUI } from './ui';
import { IUIInstance } from '@motajs/system-ui';
let myBookInstance: IUIInstance;
export function openMyBook() {
// 使用一个变量来记录打开的 UI 实例
myBookInstance = mainUIController.open(MyBookUI, {});
}
export function closeMyBook() {
// 传入 UI 实例，将会关闭此 UI 及其之后的 UI
mainUIController.close(myBookInstance);
}
```
也可以使用 `Mota.require` 引入：
```ts
const { mainUIController } = Mota.require('@user/client-modules');
```
也可以通过 `UIController` 的接口获取其实例：
```ts
import { UIController } from '@motajs/system-ui';
const mainUIController = UIController.getController('main-ui');
```
更多的 UI 控制功能可以参考后续文档以及相关的 [UI 系统指南](./ui-system.md) 或 [API 文档](../api/motajs-system-ui/UIController)。
## 添加更多内容
既然我们要编写一个简易怪物手册，那么仅靠上面这些内容当然不够，我们需要更多的元素和组件才行，下面我们来介绍一些常用的元素及组件。
### 图标
既然是怪物手册，那么图标必然不能少，图标是 `<icon>` 元素，需要传入 `icon` 参数，例如：
```tsx
return () => (
<container>
{/* 显示绿史莱姆图标，位置在 (32, 32)，循环播放动画 */}
<icon icon="greenSlime" loc={[32, 32]} animate />
</container>
);
```
### 字体
我们很多时候也会想要自定义字体，可以通过 `Font` 类来实现这个功能：
```tsx
import { Font, FontWeight } from '@motajs/render';
// 创建一个字体，包含五个参数，第一个是字体名称，第二个是字体大小，第三个是字体大小的单位，一般是 'px'
// 第四个是字体粗细，默认是 400，可以填 FontWeight.Bold，FontWeight.Light 或是数字，范围在 1-1000 之间
// 第五个是是否斜体。每个参数都是可选，不填则使用默认字体的样式。
const font = new Font('myFont', 24, 'px', FontWeight.Bold, false);
// 可以将这个字体设置为默认字体，之后的所有没有指定的都会使用此字体
Font.setDefaults(font);
// 如果需要使用默认字体，有两种写法
const font = new Font();
const font = Font.defaults();
return () => (
<container>
<icon icon="greenSlime" loc={[32, 32]} animate />
<text
text="绿史莱姆"
// 使用上面定义的字体
font={font}
// 靠左对齐，上下居中对齐
loc={[64, 48, void 0, void 0, 0, 0.5]}
/>
</container>
);
```
更多的字体使用方法可以参考 [API 文档](../api/motajs-render-style/Font)
### 圆角矩形
我们可以为怪物手册的一栏添加圆角矩形，写法如下：
```tsx
return () => (
<container>
<g-rectr
// 圆角矩形的位置
loc={[16, 16, 480 - 32, 480 - 32]}
// 圆角矩形为仅描边
stroke
// 圆角半径，可以设置四个，具体参考圆角矩形的文档
circle={[8]}
// 描边样式，这里设为了金色
strokeStyle="gold"
/>
</container>
);
```
### 线段
我们也可以添加线段，作为怪物列表之间的分割线：
```tsx
return () => (
<container>
<g-line
// 线段的起始位置和终止位置，不需要指定 loc 属性
line={[16, 80, 480 - 16, 80]}
// 线的端点为圆形
lineCap="round"
// 线宽为 1
lineWidth={1}
// 虚线样式，5 个像素为实，5 个像素为虚
lineDash={[5, 5]}
/>
</container>
);
```
### winskin 背景
我们可以为手册添加一个 winskin 背景，可以使用 `Background` 组件：
```tsx
// 从 components 文件夹中引入这个组件
import { Background } from '../components';
return () => (
<container loc={[240, 240, 480, 480, 0.5, 0.5]}>
<Background
// 位置是相对于父元素的，因此从 (0, 0) 开始
loc={[0, 0, 480, 480]}
// 设置 winskin 的图片名称
winskin="winskin.png"
/>
</container>
);
```
### 滚动条
怪物多的话一页肯定显示不完，因此我们可以添加一个滚动条 `Scroll` 组件，用法如下：
```tsx
// 从 components 文件夹中引入这个组件
import { Scroll } from '../components';
return () => (
// 使用滚动条组件替换 container 元素
<Scroll loc={[240, 240, 480, 480, 0.5, 0.5]}> // [!code ++]
<Background
// 位置是相对于父元素的，因此从 (0, 0) 开始
loc={[0, 0, 480, 480]}
// 设置 winskin 的图片名称
winskin="winskin.png"
/>
{/* 其他内容 */}
</Srcoll> // [!code ++]
);
```
在使用滚动条时，建议使用平铺式布局，将每个独立的内容平铺显示，而不是整体包裹为一个 `container`，这有助于提高性能表现。
### 循环
编写怪物手册的话，我们就必须用到循环，因为我们需要遍历当前怪物列表，然后每个怪物生成一个 `container`，在这个 `container` 里面显示内容。tsx 为我们提供了嵌入表达式的功能，因此我们可以通过 `map` 方法来遍历怪物列表，然后返回一个元素，组成元素数组，实现循环遍历的功能。示例如下：
```tsx
export const MyBook = defineComponent<MyBookProps>(props => {
// 获取怪物列表，enemys 为 CurrenEnemy 数组，可以查看 package-user/data-fallback/src/battle.ts
const enemys = core.getCurrentEnemys();
// 工具函数，居中，靠右，靠左对齐文字
const central = (x: number, y: number) => [x, y, void 0, void 0, 0.5, 0.5];
const right = (x: number, y: number) => [x, y, void 0, void 0, 1, 0.5];
const left = (x: number, y: number) => [x, y, void 0, void 0, 0, 0.5];
return () => (
<Scroll>
{/* 写一个 map 循环，将一个容器元素返回，就可以显示了 */}
{enemys.map((v, i) => {
return (
<container loc={[0, 80 * i, 480, 80]}>
{/* 怪物图标与怪物名称 */}
<icon icon={v.enemy.id} loc={[32, 16, 32, 32]} />
<text text={v.enemy.enemy.name} loc={central(48, 64)} />
{/* 显示怪物的属性 */}
<text text="生命" loc={right(96, 20)} />
<text text={v.enemy.info.hp} loc={left(108, 20)} />
{/* 其他的属性，例如攻击，防御等 */}
</container>
);
})}
</Scroll>
);
}, myBookProps);
```
### 条件判断
可以在表达式中使用三元表达式或者立即执行函数来实现条件判断：
```tsx
return () => (
<Scroll>
{enemys.length === 0 ? (
// 无怪物时，显示没有剩余怪物
<text text="没有剩余怪物" loc={central(240. 240)} font={new Font('Verdana', 48)} /> // [!code ++]
) : (
enemys.map(v => {
// 有怪物时
})
)}
</Scroll>
);
```
## 响应式
使用新的 UI 系统时，最大的优势就是响应式了，它可以让 UI 在数据发生变动时自动更改显示内容，而不需要手动重绘。本 UI 系统完全兼容 `vue` 的响应式系统，非常方便。
### 基础用法
例如，我想要给我的怪物手册添加一个楼层 id 的参数，首先我们先定义这个参数：
```tsx
import { computed } from 'vue';
export interface MyBookProps extends UIComponentProps {
// 定义 floorId 参数
floorId: FloorIds;
}
const myBookProps = {
// 这里也要修改
props: ['controller', 'instance', 'floorId']
} satisfies SetupComponentOptions<MyBookProps>;
```
然后我们需要在这个参数发生变动时修改怪物列表，可以这么写：
```tsx
export const MyBook = defineComponent<MyBookProps>(props => {
// 使用 computed，这样的话就会自动追踪到 props.floorId 参数，更新怪物列表，并更新显示内容
const enemys = computed(() => core.getCurrentEnemys(props.floorId)); // [!code ++]
return () => (
<Scroll>
{/* 需要使用 enemys.value 属性，不能直接使用 enemys.length */}
{enemys.value.length === 0 ? ( // [!code ++]
<text text="没有剩余怪物" loc={central(240. 240)} font={new Font('Verdana', 48)} />
) : (
// 同上，需要 value 属性
enemys.value.map(v => {}) // [!code ++]
)}
</Scroll>
);
}, myBookProps);
```
### 什么样的变量能使用响应式
其实，我们用一般的方式编写的变量或常量都是不能使用响应式的，例如这些都不行：
```ts
let num = 10;
let str = '123';
const num2 = computed(() => num * 2);
const str2 = computed(() => parseInt(str));
```
这么写的话，是没有响应式效果的，这是因为 `num` 和 `str` 并不是响应式变量，不能追踪到。对于 `string` `number` `boolean` 这些字面量类型的变量，我们需要使用 `ref` 函数包裹才可以：
```tsx
import { ref } from 'vue';
// 使用 ref 函数包裹
const num = ref(10);
// 使用 num.value 属性调用
const num2 = computed(() => num.value * 2);
// 使用 num.value 修改值
num.value = 20;
// 这样的话就有响应式效果了
<text text={num2.value.toString()} />;
```
对于对象类型来说，需要使用 `reactive` 函数包裹，这个函数会把对象变成深层响应式，任何一级发生更改都会触发响应式更新，例如：
```tsx
const obj = reactive({ obj1: { num: 10 } });
// 这个就不需要使用 value 属性了，只有 ref 函数包裹的需要
obj.obj1.num = 20;
// 直接调用即可，当值更改时内容也会自动更新
<text text={obj.obj1.num.toString()} />;
```
数组也可以使用 `reactive` 方法来实现响应式：
```tsx
// 传入一个泛型来指定这个变量的类型，这里使用数字数组作为示例
const array = reactive<number[]>([]);
// 可以使用数组自身的方法添加或修改元素
array.push(100);
<container>
{/* 直接对数组遍历，数组修改后这段内容也会自动更新 */}
{array.map(v => (
<text text={v.toString()} />
))}
</container>;
```
如果对象比较大，只想让第一层变为响应式，深层的不变，可以使用 `shallowReactive` 或 `shallowRef`，或使用 `markRaw` 手动标记不需要响应式的部分：
```ts
// 这样的话，当 obj1.obj1.num 修改时，就不会触发响应式，而 obj1.obj1 修改时会触发
const obj1 = shallowReactive({ obj1: { num: 10 } });
// 使用 shallowRef，也可以变成浅层响应式
const obj2 = shallowRef({ obj1: { num: 10 } });
// 或者手动标记为不需要响应式
const obj3 = reactive({ obj1: markRaw({ num: 10 }) });
```
响应式不仅可以用在 `computed` 或者是渲染元素中，还可以使用 `watch` 监听。不过该方法有一定的限制，那就是尽量不要在组件顶层之外使用。下面是一些例子：
::: code-group
```ts [ref]
const num1 = ref(10);
const num2 = ref(20);
watch(num1, (newValue, oldValue) => {
// 当 num1 的值发生变化时，在控制台输出新值和旧值
console.log(newValue, oldValue);
// 这里就不是组件顶层，不要使用 watch。如果需要条件判断的话，可以在监听函数内部判断，而不是外部
watch(num2, () => {});
});
```
```ts [reactive]
const obj = reactive({
num: 10,
obj1: {
num2: 20
}
});
// 监听 obj.num
watch(
() => obj.num,
(newValue, oldValue) => {
console.log(newValue, oldValue);
}
);
// 监听 obj 整体
watch(obj, () => {
console.log(obj.num);
});
```
:::
::: info
传入组件的 `props` 参数也是响应式的，可以通过 `watch` 监听，或使用 `computed` 追踪。
:::
关于更多 `vue` 响应式的知识，可以查看 [Vue 官方文档](https://cn.vuejs.org/)
## 鼠标与触摸交互事件
### 监听鼠标或触摸
通过上面这些内容，我们已经可以搭出来一个完整的怪物手册页面了，不过现在这个页面是死的，还没办法交互，我们需要让它有办法交互，允许用户点击和按键操作。UI 系统提供了丰富方便的接口来实现交互动作的监听，例如监听点击可以使用 `onClick`：
```tsx
const click = () => {
console.log('clicked!');
};
// 直接将函数传入 onClick 属性即可
<container onClick={click}>{/* 渲染内容 */}</container>;
```
可以使用 `cursor` 属性来指定鼠标移动到该元素上时的指针样式，如下例所示，鼠标移动到这个容器上时就会变成小手的形状：
```tsx
<container cursor="pointer" />
```
鼠标与触摸事件的触发包括两个阶段，从根节点捕获，然后一路传递到最下层，然后从最下层冒泡，然后一路再传递回根节点，一般情况下我们使用冒泡阶段的监听即可，也就是 `onXxx`，例如 `onClick` 等，不过如果我们需要监听捕获阶段的事件，也可以使用 `onXxxCapture` 的方法来监听：
```tsx
const clickCapture = () => {
console.log('click capture.');
};
const click = () => {
console.log('click bubble.');
};
<container onClick={click} onClickCapture={clickCapture} />;
```
当点击这个容器时，就会先触发 `clickCapture` 事件，再触发 `click` 事件。
### 监听事件的类型
鼠标和触摸交互包含如下类型：
- `click`: 当按下与抬起都发生在这个元素上时触发，冒泡阶段
- `clickCapture`: 同上，捕获阶段
- `down`: 当在这个元素上按下时触发，冒泡阶段
- `downCapture`: 同上，捕获阶段
- `up`: 当在这个元素上抬起时触发，冒泡阶段
- `upCapture`: 同上，捕获阶段
- `move`: 当在这个元素上移动时触发，冒泡阶段
- `moveCapture`: 同上，捕获阶段
- `enter`: 当进入这个元素时触发，顺序不固定，没有捕获阶段与冒泡阶段的分类
- `leave`: 当离开这个元素时触发，顺序不固定，没有捕获阶段与冒泡阶段的分类
- `wheel`: 当在这个元素上滚轮时触发，冒泡阶段
- `wheelCapture`: 同上，捕获阶段
触发顺序如下，滚轮单独列出，不在下述顺序中：
1. `downCapture`，按下捕获
2. `down`: 按下冒泡
3. `moveCapture`: 移动捕获
4. `move`: 移动冒泡
5. `leave`: 离开元素
6. `enter`: 进入元素
7. `upCapture`: 抬起捕获
8. `up`: 抬起冒泡
9. `clickCapture`: 点击捕获
10. `click`: 点击冒泡
### 阻止事件传播
有时候我们需要阻止交互事件的继续传播，例如按钮套按钮时，我们不希望点击内部按钮时也触发外部按钮，这时候我们需要在内部按钮中阻止冒泡的继续传播。每个交互事件都可以接受一个参数，调用这个参数的 `stopPropagation` 方法即可阻止冒泡或捕获的继续传播：
```tsx
import { IActionEvent } from '@motajs/render';
const click1 = (e: IActionEvent) => {
// 调用以阻止冒泡的继续传播
e.stopPropagation();
console.log('click1');
};
const click2 = () => {
console.log('click2');
};
<container onClick={click2}>
<container onClick={click1}></container>
</container>;
```
在上面这个例子中，当我们点击内层的容器时，只会触发 `click1`，而不会触发 `click2`，只有当我们点击外层容器时，才会触发 `click2`，这样就成功避免了内外两个按钮同时触发的场景。
### 事件对象的属性
事件包含很多属性，它们定义如下，其中 `IActionEventBase` 是 `enter` `leave` 的事件对象，`IActionEvent` 是按下、抬起、移动、点击的事件对象，`IWheelEvent` 是滚轮的事件对象。
::: code-group
```ts [IActionEventBase]
interface IActionEventBase {
/** 当前事件是监听的哪个元素 */
target: RenderItem;
/** 是触摸操作还是鼠标操作 */
touch: boolean;
/**
* 触发的按键种类，会出现在点击、按下、抬起三个事件中，而其他的如移动等该值只会是 {@link MouseType.None}，
* 电脑端可以有左键、中键、右键等，手机只会触发左键，每一项的值参考 {@link MouseType}
*/
type: MouseType;
/**
* 当前按下了哪些按键。该值是一个数字，可以通过位运算判断是否按下了某个按键。
* 例如通过 `buttons & MouseType.Left` 来判断是否按下了左键。
* 注意在鼠标抬起或鼠标点击事件中，并不会包含触发的那个按键
*/
buttons: number;
/** 触发时是否按下了 alt 键 */
altKey: boolean;
/** 触发时是否按下了 shift 键 */
shiftKey: boolean;
/** 触发时是否按下了 ctrl 键 */
ctrlKey: boolean;
/** 触发时是否按下了 Windows(Windows) / Command(Mac) 键 */
metaKey: boolean;
}
```
```ts [IActionEvent]
export interface IActionEvent extends IActionEventBase {
/** 这次操作的标识符，在按下、移动、抬起阶段中保持不变 */
identifier: number;
/** 相对于触发元素左上角的横坐标 */
offsetX: number;
/** 相对于触发元素左上角的纵坐标 */
offsetY: number;
/** 相对于整个画布左上角的横坐标 */
absoluteX: number;
/** 相对于整个画布左上角的纵坐标 */
absoluteY: number;
/**
* 调用后将停止事件的继续传播。
* 在捕获阶段，将会阻止捕获的进一步进行，在冒泡阶段，将会阻止冒泡的进一步进行。
* 如果当前元素有很多监听器，该方法并不会阻止其他监听器的执行。
*/
stopPropagation(): void;
}
```
```ts [IWheelEvent]
export interface IWheelEvent extends IActionEvent {
/** 滚轮事件的鼠标横向滚动量 */
wheelX: number;
/** 滚轮事件的鼠标纵向滚动量 */
wheelY: number;
/** 滚轮事件的鼠标垂直屏幕的滚动量 */
wheelZ: number;
/** 滚轮事件的滚轮类型，表示了对应值的单位 */
wheelType: WheelType;
}
```
:::
需要特别说明的是 `identifier` 属性，这个属性在移动端的表现没有异议，但是在电脑端，我们完全可以按下鼠标左键后，再按下鼠标右键，再按下鼠标侧键，抬起鼠标右键，抬起鼠标左键，再抬起鼠标侧键，这种情况下，我们必须单独定义 `identifier` 应该指代的是哪个。它遵循如下原则：
1. 按下、抬起、点击**永远**保持为同一个 `identifier`
2. 移动过程中，使用最后一个按下的按键的 `identifier` 作为移动事件的 `identifier`
3. 如果移动过程中，最后一个按下的按键抬起，那么依然会维持**原先的** `identifer`，**不会**回退至上一个按下的按键
除此之外，滚轮事件中的 `identifier` 永远为 -1。
## 监听按键操作
### 注册按键命令
首先，我们应该注册一个按键命令，我们从 `@motajs/system-action` 中引入 `gameKey` 常量，在模块顶层注册一个按键命令：
```ts
import { gameKey } from '@motajs/system-action';
import { KeyCode } from '@motajs/client-base';
gameKey
// 将后面注册的内容形成一个组，在修改快捷键时比较直观
// 命名建议为 @ui_[UI 名称]
.group('@ui_mybook', '示例怪物手册')
.register({
// 命名时，建议使用 @ui_[UI 名称]_[按键名称] 的格式
id: '@ui_mybook_moveUp',
// 在自定义快捷键界面显示的名称
name: '上移一个怪物',
// 默认按键
defaults: KeyCode.ArrowUp
})
// 可以继续注册其他的，这里不再演示
.register({});
```
### 实现按键操作
然后，我们需要从 `@motajs/render` 中引入 `useKey` 函数，然后在组件顶层这么使用：
```tsx
import { useKey } from '@motajs/render';
export const MyBook = defineComponent<MyBookProps>(props => {
// 第一个参数是按键实例，第二个参数是按键作用域，一般用不到
const [key, scope] = useKey();
return () => <container />;
});
```
最后，实现按键操作，使用 `key.realize` 方法：
```tsx
import { clamp } from 'lodash-es';
export const MyBook = defineComponent<MyBookProps>(props => {
const selected = ref(0); // [!code ++]
const [key, scope] = useKey();
// 实现按键操作，让选中的怪物索引减一 // [!code ++]
key.realize('@ui_mybook_moveUp', () => {
// clamp 函数是 lodash 库中的函数，可以将值限定在指定范围内 // [!code ++]
selected.value = clamp(0, enemys.value.length - 1, selected.value - 1); // [!code ++]
});
return () => <container />;
});
```
## 绘制选择框与动画
### 定义选择框动画
下面我们来把选择框加上，当按下方向键时，选择框会移动，当按下确定键时，会打开这个怪物的详细信息。首先，我们使用一个描边格式的 `g-rectr` 圆角矩形元素作为选择框：
```tsx
<Scroll>
<g-rectr loc={[16, 16, 480 - 32, 480 - 32]} stroke strokeStyle="gold" />
</Scroll>
```
接下来，我们需要让它能够移动，当用户按下按键时，选择框会平滑移动到目标位置。这时候，我们可以使用动画接口 `transitioned` 来实现平滑移动。我们需要先用它定义一个动画对象：
```ts
// 这个函数在用户代码里面，直接引入
import { transitioned } from '../use';
// 从高级动画库中引入双曲速率曲线，该曲线视角效果相对较好
import { hyper } from 'mutate-animate';
// 创建一个纵坐标动画对象，初始值为 0（第一个参数），动画时长 150ms（第二个参数）
// 曲线为 慢-快-慢 的双曲正弦曲线（第三个参数）
const rectY = transitioned(0, 150, hyper('sin', 'in-out'));
```
然后，我们需要通过 `computed` 方法来动态生成圆角矩形的位置：
```ts
const rectLoc = computed(() => [
16,
// 使用 rectY.ref.value 获取到动画对象的响应式变量
rectY.ref.value,
480 - 32,
480 - 32
]);
```
最后，我们把圆角矩形的 `loc` 属性设为 `computed` 值：
```tsx
<Scroll>
<g-rectr loc={rectLoc.value} stroke strokeStyle="gold" />
</Scroll>
```
### 执行动画
接下来，我们需要监听当前选中怪物，然后根据当前怪物来设置元素位置，使用 `watch` 监听 `selected` 变量：
```ts
watch(selected, value => {
// 使用 set 方法来动画至目标值
rectY.set(16 + value * 80);
});
```
除此之外，我们还可以添加当鼠标移动至怪物元素上时，选择框也移动至目标，我们需要监听 `onEnter` 事件：
```tsx
const onEnter = (index: number) => {
// 前面已经监听过 selected 了，这里直接设置即可，不需要再调用 rectY.set
// 不过调用了也不会有什么影响，动画会智能处理这种情况
selected.value = index;
};
<Scroll>
{/* 把圆角矩形的纵深调大，防止被怪物容器遮挡 */}
<g-rectr loc={rectLoc.value} stroke strokeStyle="gold" zIndex={10} />
{enemys.map((v, i) => {
// 元素内容不再展示。监听时，需要传入一个函数，因此需要使用匿名箭头函数包裹，
// 添加 void 关键字是为了防止返回值泄漏，不过在这里并不是必要，因为 onEnter 没有返回值
return <container onEnter={() => void onEnter(i)}></container>;
})}
</Scroll>;
```
### 处理重叠
如果你去尝试着使用上面这个方法来实现动画，并给每个怪物添加了一个点击事件，你会发现你可能无法触发选中怪物的点击事件，这是因为 `g-rectr` 的纵深 `zIndex` 较高，交互事件会传播至此元素，而不会传播至下层元素，于是就不会触发点击事件。样板自然也考虑到了这种情况，我们只需要给圆角矩形添加一个 `noevent` 标识，即可让交互事件不会受到此元素的影响，不过相应地，这个元素上的交互事件也将会无法触发。示例如下：
```tsx
<Scroll>
<g-rectr
loc={rectLoc.value}
stroke
strokeStyle="gold"
zIndex={10}
// 添加 noevent 标识，事件就不会传播至此元素
noevent // [!code ++]
/>
{enemys.map((v, i) => {
return <container onEnter={() => void onEnter(i)}></container>;
})}
</Scroll>
```
## 调用 Scroll 组件接口
我们现在已经实现了按键操作，但是移动时并不能同时修改滚动条的位置，这会导致当前选中的怪物跑到画面之外，这时候我们需要自动滚动到目标位置，可以使用 `Scroll` 组件暴露出的接口来实现。我们使用 `ref` 属性来获取其接口：
```tsx
import { ScrollExpose } from './components';
const scrollExpose = ref<ScrollExpose>();
<Scroll ref={scrollExpose}></Scroll>;
```
然后，我们可以调用其 `scrollTo` 方法来滚动至目标位置：
```tsx
import { ScrollExpose } from './components';
const scrollExpose = ref<ScrollExpose>();
watch(selected, () => {
// 滚动到选中怪物上下居中的位置，组件内部会自动处理滚动条边缘，因此不需要担心为负值
scrollExpose.value.scrollTo(selected.value * 80 - 240);
});
<Scroll ref={scrollExpose}></Scroll>;
```
## 修改 UI 参数
在打开 UI 时，我们可以传入参数，默认情况下，可以传入所有的 `BaseProps`，也就是所有元素通用属性，以及自己定义的 UI 参数。`BaseProps` 内容较多，可以参考 [API 文档](../api/motajs-render-vue/RenderItem.md)。除此之外，我们还为这个自定义怪物手册添加了 `floorId` 参数，它也可以在打开 UI 时传入。如果需要打开的 UI 参数具有响应式，例如可以动态修改楼层 id，可以使用 `reactive` 方法。示例如下：
```ts
import { MyBookProps, MyBookUI } from './myUI';
const props = reactive<MyBookProps>({
floorId: 'MT0',
zIndex: 100
});
mainUIController.open(MyBookUI, props);
```
我们可以监听状态栏更新来实时更新参数：
```ts
import { hook } from '@user/data-base';
// 监听状态栏更新事件
hook.on('updateStatusBar', () => {
// 状态栏更新时，修改怪物手册的楼层为当前楼层 id
props.floorId = core.status.floorId,
});
```
## 总结
通过以上的学习，你已经可以做出一个自己的怪物手册了！试着做一下吧！