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 0000000..bcc2908 Binary files /dev/null and b/docs/guide/img/image.png differ diff --git a/docs/guide/img/mermaid-diagram-2025-03-12-210212.svg b/docs/guide/img/mermaid-diagram-2025-03-12-210212.svg new file mode 100644 index 0000000..2105c7e --- /dev/null +++ b/docs/guide/img/mermaid-diagram-2025-03-12-210212.svg @@ -0,0 +1,3 @@ + + +

是

否

加载 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); +// 一般使用一个响应式变量来控制隐藏行为，因为设置成常量没有任何意义 +