mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-09-04 06:21:47 +08:00
557 lines
19 KiB
Markdown
557 lines
19 KiB
Markdown
# 组件使用指南
|
||
|
||
2.B 内置了很多实用的组件，本节将会介绍一些常用组件的使用方式。
|
||
|
||
## 组件引入
|
||
|
||
组件都在 `packages-user/client-modules/src/render/components` 文件夹中，如果在 `ui` 文件夹下引用，注意路径关系，应该如下引入：
|
||
|
||
```ts
|
||
// 从 components 文件夹引入，注意路径关系
|
||
import { TextContent } from '../components';
|
||
```
|
||
|
||
## 组件与元素
|
||
|
||
一般情况下，组件会包含所有元素拥有的参数，例如 `loc` `alpha` `zIndex`，甚至是 `noevent` `cache` 等，也可以监听 `onClick` `onEnter` 这些交互事件。
|
||
|
||
除了元素的参数，组件自身可能还会包含一些参数和事件。
|
||
|
||
有些组件还提供了暴露接口，可以使用这些接口直接控制组件内部。
|
||
|
||
## 多行文本 TextContent
|
||
|
||
类似于 2.x 的 `drawTextContent`，可以用于多行文本，包含打字机功能。相比于 `drawTextContent` 的主要优势是支持了英文以及更好的性能表现。
|
||
|
||
### 显示文字
|
||
|
||
直接调用组件即可：
|
||
|
||
```tsx
|
||
import { TextContent } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 显示一段长文字
|
||
const toShow = 'man what can i say '.repeat(10);
|
||
|
||
return () => (
|
||
<container>
|
||
{/* 直接调用组件，其中宽度 width 必填，而 loc 中设定的宽度是无效的 */}
|
||
<TextContent loc={[0, 0, 240, 200]} width={240} text={toShow} />
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 常用配置
|
||
|
||
| 配置 | 数据类型 | 说明 |
|
||
| ------------- | --------- | ------------------------------------------ |
|
||
| `font` | `Font` | 文字字体 |
|
||
| `interval` | `number` | 打字机效果每两个字之间的时间间隔，单位毫秒 |
|
||
| `lineHeight` | `number` | 行间距，单位像素 |
|
||
| `fill` | `boolean` | 是否填充文字，默认填充 |
|
||
| `stroke` | `boolean` | 是否描边文字，默认不描边 |
|
||
| `fillStyle` | `string` | 文字填充样式 |
|
||
| `strokeStyle` | `string` | 文字描边样式 |
|
||
|
||
使用示例：
|
||
|
||
:::code-group
|
||
|
||
```tsx [自定义字体]
|
||
import { Font } from '@motajs/style'; // [!code ++]
|
||
import { TextContent } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 显示一段长文字
|
||
const toShow = 'man what can i say '.repeat(10);
|
||
// 24px 大小的 Arial 字体
|
||
const myFont = new Font('Arial', 24); // [!code ++]
|
||
|
||
return () => (
|
||
<container>
|
||
<TextContent
|
||
loc={[0, 0, 240, 200]}
|
||
width={240}
|
||
text={toShow}
|
||
font={myFont} // 使用自定义字体 [!code ++]
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
```tsx [修改字体颜色]
|
||
import { TextContent } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 显示一段长文字
|
||
const toShow = 'man what can i say '.repeat(10);
|
||
|
||
return () => (
|
||
<container>
|
||
<TextContent
|
||
loc={[0, 0, 240, 200]}
|
||
width={240}
|
||
text={toShow}
|
||
fill // 文字填充 [!code ++]
|
||
stroke // 文字描边 [!code ++]
|
||
fillStyle="yellow" // 文字填充为黄色 [!code ++]
|
||
strokeStyle="cyan" // 文字描边为青色 [!code ++]
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
```tsx [修改行间距]
|
||
import { TextContent } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 显示一段长文字
|
||
const toShow = 'man what can i say '.repeat(10);
|
||
|
||
return () => (
|
||
<container>
|
||
<TextContent
|
||
loc={[0, 0, 240, 200]}
|
||
width={240}
|
||
text={toShow}
|
||
lineHeight={8} // 行间距为 8px [!code ++]
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
:::
|
||
|
||
### 自动调整高度
|
||
|
||
如果我们不知道这些文字显示的时候会有多高，那么我们可以使用 `autoHeight` 来让组件自动确定自身的高度，可以用于滚动条等场景。
|
||
|
||
```tsx
|
||
import { TextContent } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 显示一段长文字
|
||
const toShow = 'man what can i say '.repeat(10);
|
||
|
||
return () => (
|
||
<container>
|
||
<TextContent
|
||
loc={[0, 0, 240, 200]}
|
||
width={240}
|
||
text={toShow}
|
||
autoHeight // 使用 autoHeight，让组件自动确定自己的高度 [!code ++]
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 转义字符
|
||
|
||
与 2.x 类似，2.B 的 `TextContent` 也允许转义字符。具体请参考[此文档](../../api/user-client-modules/TextContentParser.md#转义字符语法说明)。
|
||
|
||
### API 参考
|
||
|
||
`TextContent` 还有很多功能和特性，这里只做最基础的教学，如果需要其他功能，请参考[API 文档](../../api/user-client-modules/组件%20TextContent.md)
|
||
|
||
## 滚动条 Scroll
|
||
|
||
`Scroll` 是滚动条组件，如果内容在一个界面大小内显示不下，可以使用滚动条组件，这样玩家可以使用鼠标滚轮或点击拖动来滚动内容。
|
||
|
||
### 基本使用
|
||
|
||
直接调用组件，然后填写组件内容即可：
|
||
|
||
```tsx {7-10}
|
||
import { Scroll } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
// loc 必填，表示组件位置
|
||
<Scroll loc={[0, 0, 416, 416]}>
|
||
<text text="text1" />
|
||
{/* 省略更多内容 */}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 平铺布局
|
||
|
||
在使用 `Scroll` 组件时，我们推荐使用平铺式布局，即所有内容平铺在 `Scroll` 组件中，而不是将整体用一个 `container` 将它包起来，这非常有助于提高滚动条组件的性能。
|
||
|
||
例如下面这种格式就是**好的写法**：
|
||
|
||
```tsx {8-10}
|
||
import { Scroll } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
<Scroll loc={[0, 0, 416, 416]}>
|
||
{/* 平铺内容，性能表现更好 */}
|
||
<text text="text1" />
|
||
<text text="text2" />
|
||
<text text="text3" />
|
||
{/* 省略更多内容 */}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
而下面这种就是**不好的写法**：
|
||
|
||
```tsx {8-12}
|
||
import { Scroll } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
<Scroll loc={[0, 0, 416, 416]}>
|
||
{/* 用一个 container 包裹，性能表现不好 */}
|
||
<container>
|
||
<text text="text1" />
|
||
<text text="text2" />
|
||
<text text="text3" />
|
||
</container>
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 横向滚动条
|
||
|
||
添加 `hor` 标记，即可使滚动条变为横向。暂时没有既可以横向又可以纵向的滚动条。
|
||
|
||
```tsx {7}
|
||
import { Scroll } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
// 添加 hor 标记，变为横向
|
||
<Scroll loc={[0, 0, 416, 416]} hor>
|
||
<text text="text1" />
|
||
{/* 省略更多内容 */}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 隐藏滚动条
|
||
|
||
有时候可能需要隐藏滚动条（例如样板的浏览地图界面中左侧的楼层列表），可以使用 `noscroll` 标记实现：
|
||
|
||
```tsx {7}
|
||
import { Scroll } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
// 添加 noscroll 标记，隐藏滚动条
|
||
<Scroll loc={[0, 0, 416, 416]} noscroll>
|
||
<text text="text1" />
|
||
{/* 省略更多内容 */}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 布局补偿
|
||
|
||
有时候我们需要在滚动条滚动到最后时填充一些空白内容，可以使用 `padEnd` 来实现：
|
||
|
||
```tsx {7}
|
||
import { Scroll } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
// 使用 padEnd 在滚动条最后填充空白内容，单位像素
|
||
<Scroll loc={[0, 0, 416, 416]} padEnd={120}>
|
||
<text text="text1" />
|
||
{/* 省略更多内容 */}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 代码控制滚动条
|
||
|
||
可以使用 `Scroll` 提供的接口来用代码控制滚动条：
|
||
|
||
```tsx {5-12,15-16}
|
||
import { Scroll, ScrollExpose } from '../components'; // [!code ++]
|
||
import { vue } from 'vue'; // [!code ++]
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 使用响应式变量定义 scroll 引用
|
||
const scrollRef = ref<ScrollExpose>();
|
||
|
||
onMounted(() => {
|
||
// 滚动至 100 像素的位置，动画时长 500ms
|
||
scrollRef.value?.scrollTo(100, 500);
|
||
});
|
||
|
||
return () => (
|
||
// 将 ref 属性设为 scrollRef 来获取 Scroll 的接口
|
||
<Scroll loc={[0, 0, 416, 416]} ref={scrollRef}>
|
||
<text text="text1" />
|
||
{/* 省略更多内容 */}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### API 参考
|
||
|
||
API 参考[此文档](../../api/user-client-modules/组件%20Scroll.md)。
|
||
|
||
## 图标组件
|
||
|
||
在 `components/icons.tsx` 中内置了一些图标，可以直接使用。
|
||
|
||
### 基本使用
|
||
|
||
以箭头图标为例：
|
||
|
||
```tsx {8}
|
||
import { ArrowDownTailless } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
<container>
|
||
{/* 调用图标组件 */}
|
||
<ArrowDownTailless loc={[0, 0, 48, 48]} />
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
所有图标都可以填写图形元素的参数，例如 `fill` `stroke` `strokeStyle` `lineWidth` 等。大部分图标默认都是描边样式，如果使用填充可能会导致效果不好。例如修改描边样式和线宽：
|
||
|
||
```tsx {8}
|
||
import { ArrowDownTailless } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
<container>
|
||
<ArrowDownTailless
|
||
loc={[0, 0, 48, 48]}
|
||
strokeStyle="cyan" // 描边使用青色
|
||
lineWidth={2} // 线宽为 2px
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 图标列表
|
||
|
||
目前样板包含这些图标：
|
||
|
||
- `RollbackIcon`: 回退图标
|
||
- `RetweenIcon`: 回收图标
|
||
- `ViewMapIcon`: 浏览地图图标
|
||
- `DanmakuIcon`: 弹幕图标
|
||
- `ReplayIcon`: 回放图标
|
||
- `numpadIcon`: 数字键盘图标
|
||
- `PlayIcon`: 开始播放图标
|
||
- `PauseIcon`: 暂停播放图标
|
||
- `DoubleArrow`: 双箭头图标（向右）
|
||
- `StepForward`: 单步向前图标
|
||
- `SoundVolume`: 音量图标
|
||
- `Fullscreen`: 全屏图标
|
||
- `ExitFullscreen`: 退出全屏图标
|
||
- `ArrowLeftTailless`: 无尾巴左箭头图标
|
||
- `ArrowRightTailless`: 无尾巴右箭头图标
|
||
- `ArrowUpTailless`: 无尾巴上箭头图标
|
||
- `ArrowDownTailless`: 无尾巴下箭头图标
|
||
|
||
### API 及参数参考
|
||
|
||
参数参考[此文档](../../api/motajs-render-vue/GraphicBaseProps.md)。
|
||
|
||
API 参考[此文档](../../api/user-client-modules/图标组件.md)
|
||
|
||
## 分页 Page
|
||
|
||
分页可以用来展示大量内容，在极端情况下，其性能要比 `Scroll` 更好，但交互手感与易用性不如滚动条。
|
||
|
||
### 基本使用
|
||
|
||
`Page` 组件需要传入两个必填参数 `pages` 和 `loc`，`pages` 代表总页数，`loc` 代表位置。
|
||
|
||
每个页面的内容使用插槽形式传入，接收 `page` 作为参数，代表当前是第几页。你可能不理解这句话，用代码写的话就是这样：
|
||
|
||
```tsx {6-17}
|
||
import { Page } from '../components';
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
<Page
|
||
loc={[0, 0, 416, 416]} // 位置
|
||
pages={10} // 总页码数
|
||
>
|
||
{/* 插槽内容，传入一个函数，参数代表当前是第几页 */}
|
||
{(page: number) => (
|
||
<container>
|
||
{/* 这里面填写当前页显示的内容，例如添加一个文字显示当前第几页 */}
|
||
<text text={page.toString()} />
|
||
</container>
|
||
)}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 第一种设置与获取当前页
|
||
|
||
可以通过 `v-model` 指令来创建双向数据绑定，从而达到设置与获取当前页码的功能。
|
||
|
||
这种方式一般情况下相对来说没有下一节提到的方式更好，因此相对不推荐。使用示例如下：
|
||
|
||
```tsx {7-13}
|
||
import { Page } from '../components';
|
||
// 从 vue 引入 ref 响应式函数
|
||
import { ref, watch } from 'vue'; // [!code ++]
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 定义响应式变量
|
||
const nowPage = ref(0);
|
||
|
||
// 监听当且页码的变化，需要的时候直接用 nowPage.value 获取也可
|
||
watch(nowPage, value => core.drawTip(`切换至${value}页！`));
|
||
/** 设置当前页码 */
|
||
const changePage = (value: number) => void (nowPage.value = value);
|
||
|
||
return () => (
|
||
<Page
|
||
loc={[0, 0, 416, 416]}
|
||
pages={10}
|
||
// 使用 v-model 指令创建双向数据绑定
|
||
v-model:page={nowPage.value} // [!code ++]
|
||
>
|
||
{(page: number) => (
|
||
<container>
|
||
<text text={page.toString()} />
|
||
</container>
|
||
)}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 第二种设置与获取当前页方式
|
||
|
||
相比于上一种方式，我们更推荐使用下面这种方式来设置与获取当前页。
|
||
|
||
可以使用 `Page` 组件提供的 `changePage` 和 `movePage` 来切换页码，其中前者是直接切换至某一页，后者是在当前页的基础上移动页码数。
|
||
|
||
可以使用 `now` 来获取当前页。
|
||
|
||
二者的示例如下：
|
||
|
||
:::code-group
|
||
|
||
```tsx [切换页码] {6-16,19-20}
|
||
import { Page, PageExpose } from '../components'; // [!code ++]
|
||
import { vue } from 'vue'; // [!code ++]
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 使用响应式变量定义 Page 引用
|
||
const pageRef = ref<PageExpose>();
|
||
|
||
onMounted(() => {
|
||
// 切换至第五页
|
||
pageRef.value?.changePage(5);
|
||
// 在当前页的基础上增加两页，也就是切换到第七页
|
||
pageRef.value?.movePage(2);
|
||
// 在当前页的基础上减少两页，也就是切换回第五页
|
||
pageRef.value?.movePage(-2);
|
||
});
|
||
|
||
return () => (
|
||
// 将 ref 属性赋值为 pageRef 来获取其接口
|
||
<Page loc={[0, 0, 416, 416]} pages={10} ref={pageRef}>
|
||
{(page: number) => (
|
||
<container>
|
||
<text text={page.toString()} />
|
||
</container>
|
||
)}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
```tsx [获取页码] {6-12,15-16}
|
||
import { Page, PageExpose } from '../components'; // [!code ++]
|
||
import { vue } from 'vue'; // [!code ++]
|
||
|
||
// 不再展示完整 UI 模板，只展示核心部分
|
||
export const MyCom = defineComponent(() => {
|
||
// 使用响应式变量定义 Page 引用
|
||
const pageRef = ref<PageExpose>();
|
||
|
||
onMounted(() => {
|
||
const page = pageRef.value?.now();
|
||
core.drawTip(`当前是第${page}页！`);
|
||
});
|
||
|
||
return () => (
|
||
// 将 ref 属性赋值为 pageRef 来获取其接口
|
||
<Page loc={[0, 0, 416, 416]} pages={10} ref={pageRef}>
|
||
{(page: number) => (
|
||
<container>
|
||
<text text={page.toString()} />
|
||
</container>
|
||
)}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
:::
|
||
|
||
## 更多组件
|
||
|
||
本文只简单讲解了部分常用的组件，样板还有很多内置的组件。以下是所有内置组件的 API 参考：
|
||
|
||
- [ConfirmBox](../../api/user-client-modules/组件%20ConfirmBox.md)：确认框，一般使用 `getConfirm` 接口，不直接使用组件。
|
||
- [Choices](../../api/user-client-modules/组件%20Choices.md)：选择框，一般使用 `getChoice` 接口，不直接使用组件。
|
||
- [FloorSelector](../../api/user-client-modules/组件%20FloorSelector.md)：楼层选择组件，浏览地图左侧的楼层选择就是使用的本组件。
|
||
- [图标组件](../../api/user-client-modules/图标组件.md)：一些常用图标。
|
||
- [Input](../../api/user-client-modules/组件%20Input.md)：输入组件，可以放到组件内部，可以用于搜索栏等。
|
||
- [InputBox](../../api/user-client-modules/组件%20InputBox.md)：输入框组件，类似于确认框，一般使用 `getInput` 或 `getInputNumber` 接口，不使用本组件。
|
||
- [List](../../api/user-client-modules/组件%20List.md)：列表组件，可以用于展示一列内容。
|
||
- [ListPage](../../api/user-client-modules/组件%20ListPage.md)：左侧是列表，右侧是当前选项对应的详情页，可以用于游戏机制说明等。
|
||
- [Progress](../../api/user-client-modules/组件%20Progress.md)：进度条组件，播放录像时右下角的进度条就是本组件。
|
||
- [Arrow](../../api/user-client-modules/组件%20Arrow.md)：箭头组件，画一个箭头。
|
||
- [ScrollText](../../api/user-client-modules/组件%20ScrollText.md)：滚动文本组件，可以用于长剧情或是 staff 表等。
|
||
- [Selection](../../api/user-client-modules/组件%20Selection.md)：选择光标，列表组件的选择光标就是使用的本组件。
|
||
- [Background](../../api/user-client-modules/组件%20Background.md)：背景组件，可以设置为纯色或 `winskin`。
|
||
- [WaitBox](../../api/user-client-modules/组件%20WaitBox.md)：等待框，一般使用 `waitbox` 接口，不直接使用组件。
|
||
- [Page](../../api/user-client-modules/组件%20Page.md)：分页组件，本文已经详细讲解。
|
||
- [Scroll](../../api/user-client-modules/组件%20Scroll.md)：滚动条组件，本文已经详细讲解。
|
||
- [TextContent](../../api/user-client-modules/组件%20TextContent.md)：多行文本组件，本文已经详细讲解。
|
||
- [Textbox](../../api/user-client-modules/组件%20Textbox.md)：文本框组件，就是事件的显示文字，一般不会直接用。
|
||
- [Thumbnail](../../api/user-client-modules/组件%20Thumbnail.md)：缩略图组件，用于展示某个地图的缩略图。
|
||
- [Tip](../../api/user-client-modules/组件%20Tip.md)：提示组件，就是左上角的提示，一般不会直接使用。
|