From 5e1ea25d6da5283bed53deb57d80e2850486f5a9 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Thu, 13 Mar 2025 19:38:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20UI=20=E6=8C=87=E5=8D=97=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.ts | 14 +- docs/guide/diff.md | 4 +- docs/guide/img/image.png | Bin 0 -> 23091 bytes .../img/mermaid-diagram-2025-03-12-210212.svg | 3 + docs/guide/system.md | 49 +- docs/guide/ui-elements.md | 754 ++++++++++++++++ docs/guide/ui-faq.md | 61 ++ docs/guide/ui-perf.md | 142 +++ docs/guide/ui-system.md | 243 +++++ docs/guide/ui.md | 850 ++++++++++++++++++ 10 files changed, 2107 insertions(+), 13 deletions(-) create mode 100644 docs/guide/img/image.png create mode 100644 docs/guide/img/mermaid-diagram-2025-03-12-210212.svg create mode 100644 docs/guide/ui-elements.md create mode 100644 docs/guide/ui-faq.md create mode 100644 docs/guide/ui-perf.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index cadc032..cd11689 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -5,12 +5,17 @@ export default defineConfig({ title: 'HTML5 魔塔样板 V2.B', description: 'HTML5 魔塔样板 V2.B 帮助文档', base: '/_docs/', + markdown: { + math: true + }, themeConfig: { // https://vitepress.dev/reference/default-theme-config + outline: [2, 3], nav: [ { text: '主页', link: '/' }, { text: '指南', link: '/guide/diff' }, - { text: 'API', link: '/api/' } + { text: 'API', link: '/api/' }, + { text: '错误代码', link: '/logger/' } ], sidebar: { '/guide/': [ @@ -18,7 +23,12 @@ export default defineConfig({ text: '深度指南', items: [ { text: '差异说明', link: '/guide/diff' }, - { text: '系统说明', link: '/guide/system' } + { text: '系统说明', link: '/guide/system' }, + { text: 'UI 编写', link: '/guide/ui' }, + { text: 'UI 优化', link: '/guide/ui-perf' }, + { text: 'UI 系统', link: '/guide/ui-system' }, + { text: 'UI 元素', link: '/guide/ui-elements' }, + { text: 'UI 常见问题', link: '/guide/ui-faq' } ] } ] diff --git a/docs/guide/diff.md b/docs/guide/diff.md index 2e75502..0319ff6 100644 --- a/docs/guide/diff.md +++ b/docs/guide/diff.md @@ -6,7 +6,7 @@ lang: zh-CN 本文档暂时只会对新样板新增内容进行说明，其余请查看[旧样板文档](https://h5mota.com/games/template/_docs/#/)。 -本指南建立在你已经大致了解 js 的基础语法的基础上。如果还不了解可以尝试对指南内容进行模仿，或者查看[人类塔解析](https://h5mota.com/bbs/thread/?tid=1018&p=1) +本指南建立在你已经大致了解 js 的基础语法的基础上。如果还不了解 js 语法可以尝试对指南内容进行模仿，或者查看[人类塔解析](https://h5mota.com/bbs/thread/?tid=1018&p=1) 如果你有能力直接使用源码版样板进行创作，也可以直接 fork 或 clone 2.B 样板[存储库](https://github.com/unanmed/HumanBreak/tree/template-v2.B)。2.B 样板使用了 vite 作为了构建工具，同时使用了 ts 等作为了开发语言。 @@ -22,7 +22,7 @@ lang: zh-CN - 使用全新的 UI 编写方式，速度快，效率高 - 模块化，可以使用 ES6 模块化语法 - 移除插件系统，可以自定义代码目录结构，更加自由 -- 优化渲染端（client 端）与数据端（data 端）的通讯，渲染段现在可以直接引用数据端，不过数据端还不能直接引用渲染端 +- 优化渲染端（client 端）与数据端（data 端）的通讯，渲染端现在可以直接引用数据端，不过数据端还不能直接引用渲染端 ## 差异内容 diff --git a/docs/guide/img/image.png b/docs/guide/img/image.png new file mode 100644 index 0000000000000000000000000000000000000000..bcc2908a49b126e5b507676581d059e3f4d5f1d3 GIT binary patch literal 23091 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 + +

是

否

加载 index.html

加载 2.x 样板的第三方库

是否在游戏中？

加载渲染端入口

加载数据端入口

初始化数据端，写入 Mota 全局变量

dataRegistered

初始化渲染端

clientRegistered

registered

执行数据端各个模块的初始化函数

执行渲染端各个模块的初始化函数

加载数据端入口

初始化数据端，写入 Mota 全局变量

dataRegistered 与 registered

执行数据端各个模块的初始化函数

执行 main.js 初始化

加载全塔属性

加载 core.js 及其他 libs 中的脚本

coreInit

开始资源加载

自动元件加载完毕后触发 autotileLoaded

资源加载完毕后触发 loaded

进入标题界面

 \ No newline at end of file diff --git a/docs/guide/system.md b/docs/guide/system.md index 2914b5d..6e3ec12 100644 --- a/docs/guide/system.md +++ b/docs/guide/system.md @@ -26,7 +26,7 @@ lang: zh-CN - [@motajs/system](../api/motajs-system) - [@motajs/system-action](../api/motajs-system-action) - [@motajs/system-ui](../api/motajs-system-ui) -- [@motajs/types](../api/types) +- [@motajs/types](../api/motajs-types) - [@user/client-modules](../api/user-client-modules) - [@user/data-base](../api/user-data-base) - [@user/data-fallback](../api/user-data-fallback) @@ -97,13 +97,11 @@ hook.on('afterBattle', enemy => { 1. 加载渲染端入口 2. 加载数据端入口 - 3. 并行初始化数据端，写入 `Mota` 全局变量 - 4. 初始化完毕后执行 `loading.emit('dataRegistered')` 钩子 - 5. 并行初始化渲染端 - 6. 初始化完毕后执行 `loading.emit('clientRegistered')` 钩子 - 7. 二者都初始化完毕后执行 `loading.emit('registered')` 钩子 - 8. 执行数据端各个模块的初始化函数 - 9. 执行渲染段各个模块的初始化函数 + 3. 并行初始化数据端与渲染端，在数据端写入 `Mota` 全局变量 + 4. 数据端初始化完毕后执行 `loading.emit('dataRegistered')` 钩子，渲染端初始化完毕后执行 `loading.emit('clientRegistered')` 钩子 + 5. 二者都初始化完毕后执行 `loading.emit('registered')` 钩子 + 6. 执行数据端各个模块的初始化函数 + 7. 执行渲染端各个模块的初始化函数 4. 如果是录像验证中： @@ -121,6 +119,10 @@ hook.on('afterBattle', enemy => { 11. 资源加载完毕后执行 `loading.emit('loaded')` 钩子 12. 进入标题界面 +使用流程图表示如下： + +![加载流程图](./img/mermaid-diagram-2025-03-12-210212.svg) + ## 函数重写 在 2.B 模式下，如果想改 `libs` 的内容，如果直接在里面改会很麻烦，而且两端通讯也不方便，因此我们建议在 `package-user` 中对函数重写，这样的话就可以使用模块化语法，更加方便。同时，2.B 也提供了函数重写接口，他在 `@motajs/legacy-common` 模块中，我们可以这么使用它： @@ -146,7 +148,7 @@ export function patchMyFunctions() { } ``` -然后，我们找到 `client-modules` 文件夹下的 `index.ts` 文件，然后在 `create` 函数中调用 `patchMyFunctions`，这样我们的函数重写就完成了。 +然后，我们找到 `client-modules` 文件夹下的 `index.ts` 文件，然后在 `create` 函数中引入并调用 `patchMyFunctions`，这样我们的函数重写就完成了。**注意**，如果两个重写冲突，会在控制台弹出警告，并使用最后一次重写的内容。 ::: warning **注意**，在渲染端重写的函数在录像验证中将无效，因为录像验证不会执行任何渲染端内容！ @@ -155,3 +157,32 @@ export function patchMyFunctions() { ## 目录结构 我们建议每个文件夹中都有一个 `index.ts` 文件，将本文件夹中的其他文件经由此文件导出，这样方便管理，同时结构清晰。可以参考 `packages-user/client-modules` 文件夹中是如何做的。 + +## ES6 模块化语法 + +我们推荐使用 ES6 模块化语法来编写代码，这会大大提高开发效率。下面来简单说明一下模块化语法的用法，首先是引入其他模块： + +```ts +import { Patch } from '@motajs/legacy-common'; // 从样板库中引入接口 +// 引入本地文件，注意不要填写后缀名，只可以在同一个 packages-user 子文件夹下使用 +// 不可以跨文件夹使用，例如 packages-user/client-modules 就不能直接引用 packages-user/data-base 文件夹 +// 需要使用 import { ... } from '@user/data-base' +import { patchMyFunctions } from './override'; +``` + +然后是从当前模块导出内容： + +```ts +// 导出函数 +export function myFunc() { ... } +// 导出变量/常量 +export const num = 100; +// 导出类 +export class MyClass { ... } +// 从另一个模块中导出全部内容，即将另一个模块的内容转发为当前模块 +export * from './xxx'; +``` + +更多模块化语法内容请查看[这个文档](https://h5mota.com/bbs/thread/?tid=1018&p=3#p33) + +与 TypeScript 相关语法请查看[这个文档](https://h5mota.com/bbs/thread/?tid=1018&p=3#p41) diff --git a/docs/guide/ui-elements.md b/docs/guide/ui-elements.md new file mode 100644 index 0000000..9e35192 --- /dev/null +++ b/docs/guide/ui-elements.md @@ -0,0 +1,754 @@ +# UI 元素 + +本节将会讲解 UI 系统中常用的渲染元素以及基础使用。 + +## 通用属性 + +UI 元素包含很多通用属性，我们先来介绍这些属性，它们可以用在任何渲染元素和 UI 组件中。 + +### 定位属性 + +元素包含若干定位属性，其中最常用的是 `loc` 属性，我们也推荐全部使用这个属性来修改元素定位。其类型声明如下： + +```ts +type ElementLocator = [ + x?: number, + y?: number, + w?: number, + h?: number, + ax?: number, + ay?: number +]; +``` + +这些属性两两组成一组（`x, y` 一组，`w, h` 一组，`ax, ay` 一组），每组可选填，也就是说 `x` 和 `y` 要么都填，要么都不填，以此类推。 + +- `x` `y`: 元素的位置，描述了在没有旋转时元素的锚点位置，例如 `[32, 32]` 就表示这个元素锚点在 `32, 32` 的位置，默认锚点在元素左上角，也就表示元素左上角在 `32, 32`。 +- `w` `h`: 元素的长宽，描述了在没有缩放时元素的矩形长宽，默认是没有放缩的。 +- `ax` `ay`: 元素的锚点位置，描述了元素参考点的位置，所有位置变换等将以此点作为参考点。0 表示元素最左侧或最上侧，1 表示最右侧或最下侧，可以填不在 0-1 范围内的值，例如 `[-1, 1]` 表示锚点横坐标在元素左侧一个元素宽度的位置，纵坐标在元素下边缘的位置。 + +![锚点图示](./img/image.png) + +示例如下： + +```tsx +// 元素相对于 32, 32 位置居中（锚点在元素正中间），宽高为 64 + +``` + +除了 `loc` 属性之外，还可以通过设置 `anc` 属性来修改锚点位置，示例如下： + +```tsx +// 设置锚点，效果为靠右对齐，上下居中对齐 + +``` + +你还可以手动指定 `x` `y` `width` `height` `anchorX` `anchorY` 属性，但是这种方式比较啰嗦，并不建议使用： + +```tsx + +``` + +最后说明一下元素的 `type` 属性，此属性描述了元素的定位模式，默认为 `static` 常规定位，此定位模式下元素位置会按照上述内容更改，而在 `absolute` 模式下，不论怎么修改定位属性，它都会保持在左上角的位置，可能会在一些特殊场景下使用（极度不建议使用此属性，很可能在 2.B.1 版本就会将其删除）。 + +### 纵深属性 + +可以通过 `zIndex` 属性来调整一个元素的纵深。纵深描述了元素之间的重叠关系，纵深高的会处在纵深低的元素上方，同时也会阻碍交互事件向纵深低的元素传播。必要的时候，需要通过设置纵深属性来调整层级关系。未设置时，后面的元素会处在前面的元素之上。 + +```tsx +// 这个元素会处在上层 + +// 这个元素会处在下层 + +``` + +### 效果属性 + +效果属性包含 `filter` `composite` 及 `alpha` 三个属性。 + +`filter` 表示此元素的滤镜，参考 [CanvasRenderingContext2D.filter](https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter)，可以填写内置函数或 svg 滤镜。默认不包含任何滤镜。示例如下： + +```tsx +// 亮度变为 150%，对比度变为 120% + +``` + +`composite` 属性描述了当前元素与在此之前渲染的元素之间的混合模式，参考 [CanvasRenderingContext2D.globalCompositeOperation](https://developer.mozilla.org/zh-CN/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation)，可以填写 26 个值。默认使用简单 `alpha` 混合，即 `source-over`。例如： + +```tsx +// 使用加算方式叠加，两个颜色的 RGB 值分别相加得到最终结果 + +``` + +`alpha` 属性描述了此元素的不透明度，1 表示完全不透明，0 表示完全透明。在叠加时，所有颜色都会乘以此不透明度后叠加。默认值是完全不透明，即 1。但需要注意的是，虽然 1 表示完全不透明，但是如果画布内容本身包含透明内容（例如一个半透明矩形），即使是 1 也会表现为透明，因为叠加时会乘以 1，不透明度不变。示例如下： + +```tsx +// 一个半透明元素 + +``` + +### 缓存属性 + +可以通过 `cache` 和 `nocache` 属性来指定这个元素的缓存行为，其中 `nocache` 表示禁用此元素的缓存机制，优先级最高，设置后必然不使用缓存。`cache` 表示启用此元素的缓存行为，常用于一些默认不启用缓存的元素，优先级低于 `cache`。这两个元素都不能动态设置，也就是说不能使用响应式来修改其值。示例如下： + +```tsx +// 内部渲染内容比较简单，不需要启用缓存 + + + +// 路径较为复杂，因此启用 g-path 的缓存行为 + +``` + +### 元素溢出行为 + +溢出行为是指，当其子元素超出父元素的大小时，执行的行为。例如，假如父元素大小为 `200 * 200`，里面有一个子元素，大小为 `100 * 100`，位于 `(150, 50)` 的位置，这时候子元素的一部分就会超出父元素的范围。 + +在本渲染系统中，所有元素的默认溢出行为是裁剪，即不会显示任何溢出内容，注意调整容器的宽高。在 `nocache` 模式下，由于不受到缓存的约束，溢出内容依然会显示，不过不建议利用此特性来编写 UI，因为这种行为可能会在后续的更新中修改。 + +### 隐藏元素 + +可以使用 `hidden` 属性来隐藏元素： + +```tsx +const hidden = ref(false); +// 一般使用一个响应式变量来控制隐藏行为，因为设置成常量没有任何意义 +