Files
template/docs/render-guide/index.md
T

14 KiB
Raw Blame History

渲染指南

本指南只讲画屏幕 / 写 UI:怎样用 TSX 画出界面、摆好位置、处理交互、拆成组件,以及 UI 系统与性能的取舍。数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统不在这里讲,仍见中级 / 高级教程;普通教程只保留主要的渲染逻辑,具体写法集中到本指南。

本指南只收现有 27 篇自定义 UI 文档,不新增系统文档,也不增设系统页面。

两级结构

分区 定位 页面数
渲染基础 模板、元素、坐标、图形、文字与元素属性 10
渲染进阶 响应式、事件、组件化、UI 系统/性能与完整示例 17

分层是深度标签,不是领域分类:同一层里可能既有元素,也有组件或示例;读到哪一层取决于你要解决的问题,不必按层读完全部页面。

适合谁

  • 完全没写过 UI:从 UI 通用模板(TSX) 起步,先拿模板跑起来,再用 UI 入门 认识标签、组件与渲染树。
  • 写过基础界面,想加交互与组件:从响应式接手,把状态、事件与条件渲染接进已有界面。
  • 想了解 UI 系统与性能:从 UI 系统读起,再看 UI 性能的日常优化习惯。

阅读路径

四条路径都建议先读 UI 通用模板(TSX);模板是后面所有页面的起点。

页面目录

渲染基础

篇目 一句话说明 前置
UI 通用模板(TSX) 写 UI 时从这段模板开始:复制、改名、在 container 里写内容 无
UI 入门 怎样打开 UI、TSX 的标签与组件怎么写、渲染树是什么样 无
第一个静态界面 从头拼一个静态界面:深色底、标题、图标、图形、分隔线与层级 UI 入门
容器与坐标 坐标从哪里算起、loc 与锚点怎么配合、嵌套后子元素怎么算 第一个静态界面
基础图形 八种图形元素的几何参数,以及共用的填充、描边与颜色规则 容器与坐标
文字 Font 与文字元素:单行绘制、尺寸测量与锚点对齐 容器与坐标、基础图形
图片与纹理 从贴图管理器按别名或索引取纹理,按 loc 显示并处理比例 容器与坐标
自绘元素与自定义容器 用 Canvas 2D 自绘内容,或接管子元素的绘制与事件传递 容器与坐标、基础图形
通用参数 大多数元素都能写的一组属性,以及它们在什么条件下有意义 容器与坐标、基础图形
层级、变换与性能 渲染树的层级与绘制顺序、缩放旋转,以及缓存的取舍 容器与坐标、通用参数

渲染进阶

篇目 一句话说明 前置
响应式 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 UI 入门、第一个静态界面
事件与交互 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 容器与坐标、响应式
条件渲染与循环渲染 用 hidden 或三元做条件、用 .map() 做循环 响应式、事件与交互
按键与快捷键 按键指令、分组、作用域,以及组件里怎么接 响应式、事件与交互
什么是组件 组件最基本的形态、props 的传法,以及组件与 GameUI 的关系 UI 入门
内置组件:基础 Input、Icons、Arrow、Selection、Progress、Background 与 Slider 什么是组件
内置组件:布局 Scroll、Page、List 与 ListPage 的区域与列表用法 什么是组件、内置组件:基础
内置组件:文本 TextContent 的折行与打字机、ScrollText 的自动滚动 什么是组件、内置组件:基础
自定义组件 怎么接收参数、发事件、留出内容位置与透传属性 什么是组件、内置组件:基础
UI 系统 控制器、实例与栈:打开关闭、隐藏显示与显示策略 事件与交互
UI 性能 一组日常习惯,用来减少不必要的绘制与内存占用 层级、变换与性能、UI 系统
示例(一)目标与骨架 定下背包 / 装备面板的目标、组件拆分与骨架 第一个静态界面、容器与坐标
示例(二)道具网格 把道具数据、ItemCell 与 ItemGrid 填进左侧,让网格能显示与选中 示例(一)目标与骨架、基础图形
示例(三)详情区 用 ItemDetail 填右侧:名称、数量、描述与空选中提示 示例(二)道具网格、文字、通用参数
示例(四)滚动与列表 把普通网格换成 Scroll,并说明渲染树、事件与数据流的变化 示例(三)详情区、内置组件:布局
示例(五)交互与状态 加 ActionBar:装备、使用、关闭,并把状态收口到面板 示例(四)滚动与列表、响应式、事件与交互
示例(六)动画、拆分与注册 让选中态与提示动起来,把代码落回文件并注册成 GameUI 示例(五)交互与状态、自定义组件、UI 系统

边界与注意

  • 本指南只讲绘制屏幕与编写 UI;数据端、存档与录像、插件系统、编辑器等内容见中级 / 高级教程,这里不重复。
  • 元素坐标相对父容器,不是屏幕绝对坐标;需要跨元素比较位置时,用事件里的画布坐标。
  • 示例里的预览是文档站内固定尺寸的演示,与真实画布的尺寸、缩放和素材都不同;实际效果以接入后的画布为准。
  • 文字元素只画一行,不自动换行;长文本用内置的文本组件。
  • 缓存的默认值与开关只是当前实现的取舍,超出容器的绘制不要依赖缓存行为。