xiaokun/netease-bedrock-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat:上传mcguide-开发指南部份

Browse Source
This commit is contained in:
Othniel su
2024-12-23 10:57:59 +08:00
parent 7292166c88
commit 0dc59fa4f0
3297 changed files with 63375 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

374
mcguide/20-玩法开发/15-自定义游戏内容/5-自定义书本/01-自定义基础书本.md Normal file
View File

@@ -0,0 +1,374 @@
---
front:
hard: 入门
time: 分钟
sidebarDepth: 4
---
# 自定义基础书本
## 1.概述
书本作为一种物品，主要是供玩家浏览信息，基于自定义书本，你可以提供一个书本界面给玩家，可以让玩家用翻书本的方式获取知识。
开发者需要先在行为包和资源包的“**netease_items_res**”目录下，配置自定义书本这个自定义物品，详见[自定义基础物品](../1-自定义物品/1-自定义基础物品.md)。
然后通过在“**behavior_pack/customBooks**”中配置json来添加自定义书本，可以通过编写脚本拓展书本样式、功能，添加的书本支持”**MOD SDK文档**“中与书本相关的所有事件和接口。
下面将通过定义一本名叫”**customBook**“的书本来展现如何定义一本自定义书本。（详见示例[CustomBookMod](../../13-模组SDK编程/60-Demo示例.md#CustomBookMod)）。
<img src="../picture/customBook/bookView.png" alt="bookView" style="zoom: 75%;"/>
## 2.json配置书本
### 1.创建书本
一本书本对应一个文件夹，我们必须在“**behavior_pack/customBooks**”这一目录下创建该书本的文件夹”**customBook**“，然后在”**customBook**“文件夹中创建文件”**book.json**“以及空文件夹”**category**“，**”entry“**，完整的目录结构如下：
```
| customBook（文件夹，名字可自定义）
| book.json（文件名字固定）
| category（文件夹，名字固定）
| entry（文件夹，名字固定）
```
”**category**“存放的是书本中所有目录的信息，”**entry**“存放的是书本中所有章节的信息，这两个文件夹后面会具体展开，而”**book.json**“描述的是书本的基础信息。
类似资源标识符，每个书本实际上都有自己的<span id="目录identifier">**identifier**</span><span id="书本identifier"></span>，即对应的**文件夹**名称，本次示例的为"**customBook**"。
### 2.编写json
我们将一本完整的书本分为三个索引层级：书本，目录，章节。章节是最基础的层级，它包含最基础的内容页，而目录比章节高一个层级，它包含多个章节，书本则是包含多个目录，比如你要索引到书本中含有介绍蔬菜水果的那一页，需要到目录“页面类型”，然后索引章节“轮播物品页”，第二页就是你的目标页。
<img src="../picture/customBook/openBook.gif" alt="openBook" style="zoom: 85%;" />
<center>先是找到customBook这一物品（本地名称为“测试自定义书本”），然后使用物品打开界面，按照层级一层一层索引到目标</center>
#### 1.book.json编写
”**book.json**“包含两部分的信息，一个是指明使用何种物品可以打开书本界面，一个是描述书本首页的排版信息，编写”**book.json**“如下：
```
{
"item": "custombooks:test0",
"title1": "自定义书本的一级标题",
"title2": "自定义书本的二级标题",
"content": "第一页为书本首页，第二页为书本目录显示页。\n如果把一本书本比作一个大文件夹，\n那么\"目录\"就是它里面的子文件夹，\n\"章节\"就是\"目录\"的子文件夹。",
"titleArea":{
"offset": [-10,0],
"textSize1": 9,
"textSize2":8,
"padding": 1
},
"pageConfig": {
"subtitle":"默认的副标题"
}
}
```
<img src="../picture/customBook/bookFront.png" alt="bookFront" style="zoom: 40%;" />
<center>书本首页的结构</center>
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| item | 书本对应的物品的**identifier**。 |
| title1 | 书本首页的主标题文本内容，默认值为""。 |
| title2 | 书本首页的副标题文本内容，默认值为""。 |
| titleArea | 书本首页主标题和副标题的排版属性，该值可以不写，默认值为所有子属性的默认值。下面为子属性的介绍：<br>offset：主标题和副标题的整体相对于默认位置的整体偏移（坐标参见[“自定义书本UI坐标系”](#页面编写)），默认值为[-10, 0]。<br>textSize1：主标题的字体大小，默认值为9。 <br>textSize2：副标题的字体大小，默认值为8。 <br>padding：两个标题之间的垂直间隔，默认值为1。 |
| content | 书本首页内容文本，默认值为""，文本框的高度为100px，如果文本内容过多将不显示超出的部分文字。 |
| contentTextSize | 书本首页内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
| pageConfig | 页面的配置默认值，用**object**表示，页面中的属性默认值继承这里所定义的属性值。<br>该属性无默认值，如果不写该属性，则页面中的属性默认值继承系统默认值。<br>关于系统默认值以及配置默认值的区别请见下文备注。 |
| categoryConfig | 目录的配置默认值，用**object**表示，目录中的默认值继承这里所定义的属性值。<br/>该属性无默认值，如果不写该属性，则目录中的属性默认值继承系统默认值。<br/>关于系统默认值以及配置默认值的区别请见下文备注。 |
| entryConfig | 章节的配置默认值，用**object**表示，章节中的默认值继承这里所定义的属性值。<br/>该属性无默认值，如果不写该属性，则章节中的属性默认值继承系统默认值。<br/>关于系统默认值以及配置默认值的区别请见下文备注。 |
备注：
1. 关于系统默认值以及配置默认值的区别，**请在阅读此处前先对[目录编写](#目录编写)，[章节编写](#章节编写)，[页面编写](#页面编写)有一定的了解**。在编写目录以及章节，页面的属性时，部分携带默认值的属性，使用默认值的时候会优先使用配置默认值，如果没有配置默认值就会使用系统默认值，请不要在配置默认值里面配置不携带默认值的属性，否则会产生意想不到的问题。
我们以一个用例说明，我们希望所有的目录首页中的文本内容字体大小（属性名为"**contentTextSize**"）默认都是12px，所有页面的文本内容字体大小（属性名为"**contentTextSize**"）默认为8px（章节的首页是用户自定义的一个页面，并不一定含有"**contentTextSize**"属性），则可以这样编写：
book.json
```python
{
"item": "custombooks:test0",
"title1": "自定义书本的一级标题",
"title2": "自定义书本的二级标题",
"content": "第一页为书本首页，第二页为书本目录显示页。\n如果把一本书本比作一个大文件夹，\n那么\"目录\"就是它里面的子文件夹，\n\"章节\"就是\"目录\"的子文件夹。",
"titleArea":{
"offset": [-10,0],
"textSize1": 9,
"textSize2":8,
"padding": 1
},
"categoryConfig":{
"contentTextSize": 12
},
"pageConfig":{
"contentTextSize": 8
}
}
```
这些默认值我们称为配置默认值，如果目录json文件，章节json文件中均无对"**contentTextSize**"属性定义，则取这里的默认值。而如果book.json中没有定义"categoryConfig"，"entryConfig"，"pageConfig"，则它们的属性值取系统默认值。
2. 因为支持富文本，如果你想修改文字样式，可以通过[格式化代码](https://zh.minecraft.wiki/w/%E6%A0%BC%E5%BC%8F%E5%8C%96%E4%BB%A3%E7%A0%81)来修改。
3. 所有的文本都遵循UI控件中的Label控件规范，具体见[UI说明文档-Label](../../../18-界面与交互/30-UI说明文档.md#label)。
#### 2.目录的编写<span id="目录编写"></span>
目录的json文件都定义在“**category**”文件夹中，主要描述该目录首页的信息，比如其中的”**pages.json**“，需注意，目录中的章节信息并不是存在目录json文件中，而是章节json文件指向该目录，后续“[章节的编写](#章节编写)”会具体说明。
每个目录实际上都有自己的<span id="目录identifier">**identifier**</span>，即对应的**json**文件名称（去除后缀），比如目录文件”**pages.json**“的**identifier**就是"**pages**"。
```python
{
"title": "页面类型",
"content": "该目录下的每个章节分别展示一种页面类型",
"isLocked": false
}
```
<img src="../picture/customBook/categoryFront.png" alt="categoryFront" style="zoom: 40%;" />
<center>目录"页面类型"的首页</center>
属性说明：
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| title | 目录首页的标题文本。 |
| content | 目录首页内容文本，默认值为""，文本框的高度为100px，如果文本内容过多将不显示超出的部分文字。 |
| contentTextSize | 目录首页内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
| icon | 目录在书本首页中显示的图标以及目录首页中的标题图标，这里写的是路径字符串，比如要索引”**resource_pack/textures/items/apple.png**“这一图片 就写地址 ”**textures/items/apple**“。<br>该属性系统默认值为 **BookConfig.Images.categoryDefaultIcon** （详见[书本配置](05-常用脚本对象.md#书本配置)），可以不写。 |
| isLocked | 目录是否被锁住，如果为 true，该目录变成上锁状态，用户无法查看到该目录下的内容。<br>该属性系统默认值为 false，可以不写。 |
| lockIcon | 目录上锁状态下的锁图标路径，格式和icon属性相同。<br>该属性系统默认值为 **BookConfig.Images.lockBtn_dark**（详见[书本配置](05-常用脚本对象.md#书本配置)，如果在**book.json**中定义了**categoryConfig**，则默认值为**categoryConfig**的**lockIcon**值），可以不写。 |
| lockMsg | 目录上锁状态下在书本首页中被点击显示的消息。<br>如果该属性的值为""，则将不显示该消息，而是显示该目录的标题。<br>该属性系统默认值为""，可以不写。 |
| parent | 目录的父目录json文件名称。<br>该属性有系统默认值，如果不写该属性，则默认的父目录为书本，即目录成为一级目录。 |
| sortnum | 目录的排列优先级，用**int**类型数值表示，数字越小表示优先级越高，则排列在更前面。<br>该属性没有默认值，如果不写该属性，则该目录的优先级最低（多个无**sortnum**属性的目录排列按照目录标题文本字符串排序）。 |
下面的图片对属性“**icon**”，“**lockIcon**”，“**lockMsg**”进行补充。
<img src="../picture/customBook/category1.png" alt="category1" style="zoom:40%;" />
<center>目录"页面类型"在书本首页的图标，对应“icon”属性</center><br>
<img src="../picture/customBook/category2.png" alt="category2" style="zoom:40%;" />
<center>目录在上锁状态下的锁图标，对应"lockIcon"属性，这里显示的是默认图标</center><br>
<img src="../picture/customBook/category3.png" alt="category3" style="zoom:40%;" />
<center>目录在上锁状态下的提示消息文本，对应"lockMsg"属性。</center>
<span id="目录嵌套">属性“**parent**”的用法可以参见**demo**中的”**subcategoryTest.json**“和 其对应的两个子目录”**subcategory1.json**“以及”**subcategory2.json**“，目录这一层级是支持多层嵌套的，你可以定义一级，二级，三级，四级乃至五级的子目录。</span>但是需要注意一点，书本系统不支持**目录与章节同层级**，比如一个**子目录**的“**parent**”为”**subcategoryTest**“，而有一个**章节**的“**parent**”也为”**subcategoryTest**“，此时会造成冲突报错。
#### 3.章节的编写<span id="章节编写"></span>
章节的json文件都定义在“**entry**”文件夹中，我们以最简单的”**imageEntry.json**“为例说明，该章节共有4页，第一页总体介绍，后三页展示的是图片以及对应的内容。
和目录类似，每个章节都有自己的<span id="章节identifier">**identifier**</span>，即对应的**json**文件名称（去除后缀），比如章节文件”**imageEntry.json**“的**identifier**就是"**imageEntry**"。
```
{
"parent": "pages",
"icon": "textures/items/sign",
"title": "图片",
"pages":[
{
"type": "textPage",
"content": "该章节为图片页\n\"imagePage\"的介绍"
},
{
"type": "imagePage",
"subtitle": "内容页的标题1",
"content": "subtitle是内容页的标题，image是图片的路径（摆放到resource_pack的ui文件夹中即可）",
"image": "textures/ui/myCustomBook/testImage_1",
"info": "图片说明，对应info属性"
},
{
"type": "imagePage",
"subtitle": "内容页的标题2",
"content": "subtitle是内容页的标题，image是图片的路径（摆放到resource_pack的ui文件夹中即可）",
"image": "textures/ui/myCustomBook/testImage_2",
"info": "图片说明，对应info属性"
},
{
"type": "imagePage",
"subtitle": "内容页的标题3",
"content": "subtitle是内容页的标题，image是图片的路径（摆放到resource_pack的ui文件夹中即可）",
"image": "textures/ui/myCustomBook/testImage_3",
"info": "图片说明，对应info属性"
}
]
}
```
<img src="../picture/customBook/entry1.png" alt="entry1" style="zoom:40%;" />
<center>章节"图片"在目录"页面类型"的首页的图标以及标题，对应"icon"属性和"title"属性</center>
<img src="../picture/customBook/entry2.png" alt="entry2" style="zoom:40%;" />
<center>章节"图片"的前两页。</center>
属性说明：
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| title | 章节的标题文本。 |
| icon | 章节在目录首页中显示的图标以及目录首页中的标题图标，这里写的是路径字符串，比如要索引”**resource_pack/textures/ui/apple.png**“这一图片 就写地址 ”**textures/items/apple**“。<br>该属性系统默认值为 **BookConfig.Images.categoryDefaultIcon** （详见[书本配置](05-常用脚本对象.md#书本配置)），可以不写。 |
| isLocked | 章节是否被锁住，如果为 true，该章节变成上锁状态，用户无法查看到该章节下的内容。<br>该属性系统默认值为 false，可以不写。 |
| lockIcon | 章节上锁状态下的锁图标路径，格式和icon属性相同。<br>该属性系统默认值为**BookConfig.Images.lockBtn_dark**（详见[书本配置](05-常用脚本对象.md#书本配置)），可以不写。 |
| lockMsg | 章节上锁状态下在目录首页中被点击显示的消息。<br>如果该属性的值为""，则将不显示该消息，而是显示该章节的标题。<br/>该属性系统默认值为""，可以不写。 |
| parent | 该章节所属目录的json文件名。<br>该属性无默认值，必须写。 |
| pages | 该章节下的所有页面，详见页面类型介绍 |
| sortnum | 章节的排列优先级，用**int**类型数值表示，数字越小表示优先级越高，则排列在更前面。<br>该属性没有默认值，如果不写该属性，则该章节的优先级最低（多个无**sortnum**属性的章节排列按照章节标题文本字符串排序）。 |
### 3.浏览历史记录<span id="浏览历史记录"></span>
历史记录的入口位于书本首页的历史按钮中，历史记录中显示的是用户所浏览过的所有章节，并按照浏览先后顺序排序（最近浏览的排列在前），用户可以点击列表中的章节进行页面跳转。
<img src="../picture/customBook/history.png" alt="history" style="zoom: 90%;" />
### 4.预设页面类型<span id="页面编写"></span>
#### 1.书本界面坐标系，界面大小，页面共同属性
目前提供的页面类型共5种，先介绍下书本的UI布局坐标系，它遵循常规的图像坐标系，原点位于书本界面左上角，所有的偏移属性方向都按照这个坐标系，如下图所示，**书本界面大小默认为（268, 200）**，单位为像素，然后是每种页面的共同属性。而<span id="全局坐标系">**全局坐标系**</span>实际上就是屏幕坐标系，二者区别详见下图。
<img id="book_ui_coordinate" src="../picture/customBook/pages/axis.png" alt="axis" style="zoom: 41%;" />
<center>UI布局坐标系。</center>
<img id="book_ui_coordinate" src="../picture/customBook/pages/global_axis.png" alt="axis" style="zoom: 42%;" />
<center>全局坐标系。</center>
页面的共同属性：
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| type | 页面的类型，可选的值为："textPage"，"highlightPage"，"imagePage"，"entityPage"，"tableRecipePage"，开发者可以通过编写python类来自定义更多的类型，详见[python编写部分](02-脚本自定义书本.md#脚本自定义组件)。 |
| subtitle | 页面的标题文本，如果不写该属性，则无标题，内容直接置顶。 |
<img src="../picture/customBook/pages/subtitle.png" alt="subtitle" style="zoom: 41%;" />
<center>左边的页面是带有标题的，右边的页面不带标题。</center>
对于一个章节的首页，一般不定义"**subtitle**"属性，因为会默认给该页添加一个主标题（就是章节的标题）。
<img src="../picture/customBook/pages/title.png" alt="title" style="zoom: 41%;" />
#### 2.文本页
文本页在json文件中的type属性值为 "**textPage**"，示例在**behavior_pack/customBooks/entry/textEntry.json**。
<img src="../picture/customBook/pages/textPage.png" alt="textPage" style="zoom: 41%;" />
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| content | 内容文本，默认值为""，支持格式化文本。文本框大小会自动适应页面，如果文本内容过多将不显示超出页面的文字。 |
| contentTextSize | 内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
#### 3.图片页
图片页在json文件中的type属性值为 "**imagePage**"，示例在**behavior_pack/customBooks/entry/imageEntry.json**。
<img src="../picture/customBook/pages/imagePage.png" alt="imagePage" style="zoom: 41%;" />
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| image | 图片路径，开发者需要先把图片放到resource_pack中，比如要索引"**resource_pack/textures/ui/myCustomBook/testImage_1.png**"这一图片就写地址 "**textures/ui/myCustomBook/testImage_1**"。 |
| imageSize | 图片的大小，用二维浮点数组表示。<br>该属性系统默认值为 [80.0, 80.0]，可以不写。 |
| info | 图片的备注文本，显示在图片的下方。如果不写该属性，则无备注，内容文本会自动往上对齐。 |
| content | 内容文本，默认值为""，支持格式化文本。文本框大小会自动适应页面，如果文本内容过多将不显示超出页面的文字。 |
| contentTextSize | 内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
#### 4.轮播物品页
轮播物品页在json文件中的type属性值为 "**highlightPage**"，示例在**behavior_pack/customBooks/entry/highlightEntry.json**。
<img src="../picture/customBook/pages/highlightPage.png" alt="highlightPage" style="zoom: 41%;" />
点击当前轮播的物品能显示其物品本地名称。
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| itemData | 需要轮播的所有物品数据，用数组表示，存储要轮播的每个物品的信息，见下面的表格。 |
| itemSize | 物品显示的大小，用二维浮点数组表示。<br/>该属性系统默认值为 [30.0, 30.0]，可以不写。 |
| info | 轮播物品的备注文本，显示在物品的下方。如果不写该属性，则无备注，内容文本会自动往上对齐。 |
| content | 内容文本，默认值为""，支持格式化文本。文本框大小会自动适应页面，如果文本内容过多将不显示超出页面的文字。 |
| contentTextSize | 内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
每个物品的信息：
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| item | 物品的**identifier**，比如MC中的苹果，则该属性写为: "**minecraft:apple**"，支持[自定义物品](../1-自定义物品/1-自定义基础物品.md) |
| data | 物品的附加值**AuxValue**，该属性可以不写，系统默认值为0（整型）。 |
#### 5.工作台合成表页
工作台合成表页在json文件中的type属性值为 "tableRecipePage"，示例在**behavior_pack/customBooks/entry/tableRecipeEntry.json**。
<img src="../picture/customBook/pages/tableRecipePage.png" alt="tableRecipePage" style="zoom: 41%;" />
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| recipeId | 合成配方的ID，一般为合成的物品的**identifier**，支持[自定义配方](../5-自定义配方.md) |
| recipeSize | 合成表显示的大小，用二维浮点数组表示。<br/>该属性系统默认值为 [90.0, 48.0]，可以不写。 |
| aux | 合成物品的附加值**AuxValue**，该属性可以不写，系统默认值为0（整型）。 |
| info | 合成物品的备注文本，显示在物品的下方。如果不写该属性，则无备注，内容文本会自动往上对齐。 |
| content | 内容文本，默认值为""，支持格式化文本。文本框大小会自动适应页面，如果文本内容过多将不显示超出页面的文字。 |
| contentTextSize | 内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
#### 6.实体页
实体页在json文件中的type属性值为 "**entityPage**"，展示的实体会**自动顺时针旋转**，示例在**behavior_pack/customBooks/entry/entityEntry.json**。
<img src="../picture/customBook/pages/entityPage.png" alt="entityPage" style="zoom: 41%;" />
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| entity | 包含要展示的实体的信息，详细见下方表格 |
| entitySize | 实体显示的大小，用二维浮点数组表示。<br/>该属性系统默认值为 [100.0, 100.0]，可以不写。 |
| info | 展示的实体的备注文本，显示在实体的下方。如果不写该属性，则无备注，内容文本会自动往上对齐。 |
| content | 内容文本，默认值为""，支持格式化文本。文本框大小会自动适应页面，如果文本内容过多将不显示超出页面的文字。 |
| contentTextSize | 内容文本的字体大小。<br>该属性系统默认值为**BookConfig.TextSize.content**，数值为**10**（整型），可以不写。 |
entity包含的属性：
| <div style="width:100px">属性</div> | 解释 |
| :---------------------------------: | ------------------------------------------------------------ |
| name | 实体的**identifier**，比如这里的猫是 "**minecraft:cat**"，支持[自定义生物](../3-自定义生物/01-自定义基础生物.md) |
| offset | 显示的实体相对于外边框的偏移，用于微调，用二维浮点数组表示，该属性必须填写，无偏移则填写[0, 0] |
| molang_dict | molang表达式字典 |
## 3.Demo说明
示例Demo（[CustomBookMod](../../13-模组SDK编程/60-Demo示例.md#CustomBookMod)）中包含了三本书本，对应的物品名称为："测试自定义书本"，"链接测试书本"，"回收组件测试书本"。
### 1."测试自定义书本"
- 供开发者预览书本的基础功能，结合本文进行理解。
- “页面类型”这一目录下的“测试页No Title”，“测试页With Title”，这两章节演示的是[如何自定义页面](02-脚本自定义书本.md#脚本自定义页面)
- “页面类型”这一目录下的“测试自定义组件”，这章节演示的是[如何自定义组件](02-脚本自定义书本.md#脚本自定义组件)
- “页面类型”这一目录下的“测试buttonComp”，这章节分别演示的是[点击按钮显示消息](05-常用脚本对象.md#显示消息文本)，[点击按钮进行跳转](05-常用脚本对象.md#页面跳转机制)。
- “目录嵌套测试”这一目录演示的是[目录嵌套](#目录编写)。
### 2."链接测试书本"
- 该书本只有一个章节，演示的是[书本的页面跳转机制](05-常用脚本对象.md#页面跳转机制)。
### 3."回收组件测试书本"
- 该书本只有一个章节，演示的是[自定义组件开启回收时需注意的问题](03-组件API.md#Reset)。

389
mcguide/20-玩法开发/15-自定义游戏内容/5-自定义书本/02-脚本自定义书本.md Normal file
View File

@@ -0,0 +1,389 @@
---
front:
hard: 入门
time: 分钟
sidebarDepth: 4
---
# 脚本自定义书本
## 1.概述
书本界面本质上也是个ScreenNode控件，用户可以通过获取UI节点的接口来获取它：
```
import mod.client.extraClientApi as clientApi
# 其中参数 nameSpace = "BookMod"，uiKey = "book_screen.main"
node = clientApi.GetUI("BookMod", "book_screen.main")
print node
```
在自定义书本框架中，一个章节由每一个特定类型的页面组成，而组成一个页面的UI元素我们又称之为组件，下图简单的展示了何为页面，何为组件。
<img src="../picture/customBook/script/pageAndComps.png" alt="pageAndComps" style="zoom: 85%;" />
按照功能定义，书本的三个层级“书本”，“目录”，“章节”决定了每一个页的排版（比如双页结构的书本，第1页就会放置在书本的左侧，第2页会放置在书本的右侧）以及每一个页是否能被显示。
页面则相当于组件的容器，对内在的组件按需排版，而组件是实际存放数据和处理显示数据的单位，所谓的数据实际就是开发者定义的书本json文件，经由页面获取后分配给其内置的组件。
<img src="../picture/customBook/script/dataFlowInBook.png" alt="dataFlowInBook" style="zoom: 100%;" />
<center>以上图的图片页为例子显示数据流向。</center>
## 2.自定义页面<span id="脚本自定义页面"></span>
### 1.创建页面
在预设的页面中（比如图片页，文本页等）普遍含有标题的处理，这里我们先编写个没有标题处理的页面，学习通用的页面是如何编写，其次再做类似预设页面的标题处理，下面以[CustomBookMod](../../13-模组SDK编程/60-Demo示例.md#CustomBookMod)中的页面类型"**MyNoTitlePage**"为例说明。
<img src="../picture/customBook/script/pages/noTitleTestPage.png" alt="noTitleTestPage" style="zoom: 85%;" />
<center>自定义的一个页面</center>
在编写脚本类之前，我们先将数据定义在”**behavior_pack/customBooks/customBook/entry/noTitlePage.json**“这一文件中，对于一个自定义页面，除了"**type**"属性外，其他属性均可以自定义（由后续编写的脚本类来解析），"**type**"值为要编写的页面的名称（后面注册页面的时候会详述），这里自定义了"**testTitle**"，"**image**"，"**content1**"，"**content2**"四个属性，后面编写类的时候我们将分别用文本组件，图片组件，文本组件，文本组件去存储显示。
myNoTitlePage.json
```
{
"parent": "pages",
"icon": "textures/items/bed_lime",
"title": "测试页No Title",
"lockMsg": "需解锁固定成就",
"lockIcon": "textures/ui/book_gui/icon02",
"isLocked": false,
"pages":[
{
"type": "CustomMod:MyNoTitlePage",
"testTitle": "标题文本",
"image": "textures/ui/myCustomBook/testImage",
"content1": "第一段文本",
"content2": "第二段文本"
}
]
}
```
在[CustomBookMod](../../13-模组SDK编程/60-Demo示例.md#CustomBookMod)中，与**myNoTitlePage.json**相对应的脚本类是“**behavior_pack/tutorialScripts/pages/noTitlePage.py**”中的**MyNoTitlePage**，一个页面需要编写3个基本的函数接口：
- 类初始化函数 "\_\_init\_\_"
- 获取json传过来的数据的函数"SetData"
- 显示页面的函数"Show"
这些接口需符合链式调用的格式，最终返回**self**。**MyNoTitlePage**实现的是最基本的页面，所以这里继承是**BasePage**，**BasePage**不包含对标题的预处理，如果需要对标题进行预处理，则需要继承**TitlePage**，后续会再提到该页面。**BasePage**的接口详见 [“页面API”](04-页面API.md)。另外，下面的代码中含有很多预设组件的用法，详细请参考[“组件API”](03-组件API.md)。
myNoTitlePage.py
```python
#-*- coding: UTF-8 -*-
import mod.client.extraClientApi as clientApi
# 获取书本管理对象，详细用法见“05-常见脚本对象”
bookManager = clientApi.GetBookManager()
# 获取书本配置常量，详细API见“05-常见脚本对象”
bcf = bookManager.GetBookConfig()
# 获取页面基类 BasePage
BasePage = bookManager.GetBasePageCls()
# 获取预设组件类 TextComp
TextComp = bookManager.GetTextCompCls()
# 获取预设组件类 ImageComp
ImageComp = bookManager.GetImageCompCls()
class MyNoTitlePage(BasePage):
"""
自定义的页类
"""
def __init__(self, size = None, position = None):
""""
编写该接口需按照如下编写。
1. 先调用父类的同名方法。
2. 定义需要用到的组件。
3. 调用AddComps接口添加所有组件。
"""
# 调用父类__init__方法
BasePage.__init__(self, size, position)
# 实例化需要用到的组件
self.testTitle = TextComp(bcf.TextAlign.Fit_Center) # 使用文本组件存储显示自定义属性"testTitle""
self.content1 = TextComp(bcf.TextAlign.Left) # 使用文本组件存储显示自定义属性"content1""
self.image = ImageComp() # 使用图片组件存储显示自定义属性"image""
self.content2 = TextComp(bcf.TextAlign.Left) # 使用文本组件存储显示自定义属性"content2""
# 调用AddComps接口添加所有定义了的组件
self.AddComps(self.testTitle, self.content1, self.image, self.content2)
# 照应SetData方法
self.data = None
def SetData(self, data):
"""
书本在调用Show之前会调用该方法将json中的数据打包成Dict变量"data"作为参数传进来。
建议是将数据存储下来然后在Show方法中进行读取。
"""
# 存储各个组件的数据
self.data = data
return self
def Show(self):
"""
书本向页面传递数据后调用该接口，这里负责为每个组件填充数据并且排版它们的位置。
编写该接口需按照如下编写。
1. 向所有组件注入数据。
2. 调用父类的同名方法。
3. 重置所有组件相对于页面的位置。
4. 对组件进行排版（通过调用组件的排版API，每个API的解释见“03-组件API”）。
"""
if self.data:
# 为每个组件注入数据，data中的键值对应json文件中的页面属性值
self.testTitle.SetDataBeforeShow(self.data["testTitle"], bcf.TextSize.title)
self.content1.SetDataBeforeShow(self.data["content1"], bcf.TextSize.content)
self.content2.SetDataBeforeShow(self.data["content2"], bcf.TextSize.content)
self.image.SetDataBeforeShow(self.data["image"])
# 执行父类的Show方法，该方法会依次调用会所有组件的Show方法
BasePage.Show(self)
# 重置所有组件相对页面的位置，保证每次调用Show的时候组件的排版都是相对于页面的原点
self.ResetCompsPosition()
# 获取该页面的中心坐标和大小，方便后面使用
pageCenter = self.Center()
pageSize = self.GetSize()
# 布局自己的组件，组件在调用Align以及Move方法前需要先调用SetSize方法，因为这些方法都是基于GetSize来计算的。
# testTitle 是Fit类型文本，会根据文本内容来调整自己的大小，无需调用SetSize。将其中心对齐到页面的中心，将其上边界与 页面 的上边界对齐，然后往下移动4px
self.testTitle.AlignCenterToX(pageCenter[0]).AlignTopToY(self.Top()).MoveY(4)
# 对 content1 设置大小后，将其左边界对齐到页面的左边界，将其上边界与 testTitle 的下边界对齐，然后往下移动5px
self.content1.SetSize((pageSize[0], 20)).AlignLeftToX(self.Left()).AlignTopToY(self.testTitle.Bottom()).MoveY(5)
# 对 image 设置大小后，将其左中心对齐到页面的中心，将其上边界与 content1 的下边界对齐，然后往下移动5px
self.image.SetSize((80, 80)).AlignCenterToX(pageCenter[0]).AlignTopToY(self.content1.Bottom()).MoveY(5)
# 对 content2 设置大小后，将其左边界对齐到页面的左边界，将其上边界与 image 的下边界对齐，然后往下移动5px
self.content2.SetSize((pageSize[0], 40)).AlignLeftToX(self.Left()).AlignTopToY(self.image.Bottom()).MoveY(5)
return self
else:
print "in MyNoTitlePage Show: no data present"
return self
```
在**MyNoTitlePage**这个页中，其实是包含了简单的文本标题处理（**self.testTitle**这个文本组件），而本书提供了**TitlePage**这个类为开发者省去对标题的处理，详述见 [“页面API”](04-页面API.md)，以及Demo中的“**behavior_pack/customBooks/customBook/entry/myTitlePage.json**”以及“**behavior_pack/tutorialScripts/pages/myTitlePage.py**”。
### 2.注册页面
创建好自定义的页面以及对应的json文件后，需要系统中注册你的自定义页面，使系统在解析json文件的时候能读取到类信息。仅需要在**客户端System**初始化的时候调用注册接口即可，**BookManager**包含了自定义书本的各种接口，详见[BookManager API](05-常用脚本对象.md#BookManager)。因为自定义书本系统中内置了一些常用的页面类型，所以开发者尽量使用规范的名称来命名自己的页面类型，这里建议使用固定格式"**Mod名称:页面类型名称**"，其中页面类型名称建议就和定义的类名是一致的（类名后置如果带上“**page**”会更加有辨识度），比如上面的则**MyNoTitlePage**可以命名为"**CustomMod:MyNoTitlePage**"，这个自定义的页面类型名称，是用于**json**数据中对应的**type**字段属性值。
```python
# -*- coding: utf-8 -*-
# 获取客户端引擎API模块
import mod.client.extraClientApi as clientApi
# 获取客户端system的基类ClientSystem
ClientSystem = clientApi.GetClientSystemCls()
# 在modMain中注册的Client System类
class TutorialClientSystem(ClientSystem):
# 客户端System的初始化函数
def __init__(self, namespace, systemName):
# 首先初始化TutorialClientSystem的基类ClientSystem
super(TutorialClientSystem, self).__init__(namespace, systemName)
print "==== TutorialClientSystem Init ===="
# 注册自定义的page
# 先import定义好的页面类
from tutorialScripts.pages.myNoTitlePage import MyNoTitlePage
from tutorialScripts.pages.myTitlePage import MyTitlePage
from tutorialScripts.pages.customCompPage import MyCustomCompPage
from tutorialScripts.pages.buttonPage import MyButtonPage
from tutorialScripts.pages.addrPage import MyAddrPage
from tutorialScripts.pages.recyclePage import MyRecyclePage
# 获取书本管理对象，详细用法见“05-常见脚本对象”
bookManager = clientApi.GetBookManager()
# 注册自定义的页面类，同时为它们命名，这些名称是在json中使用的
bookManager.AddPageType("CustomMod:MyNoTitlePage", MyNoTitlePage)
bookManager.AddPageType("CustomMod:MyTitlePage", MyTitlePage)
bookManager.AddPageType("CustomMod:MyCustomCompPage", MyCustomCompPage)
bookManager.AddPageType("CustomMod:MyButtonPage", MyButtonPage)
bookManager.AddPageType("CustomMod:MyAddrPage", MyAddrPage)
bookManager.AddPageType("CustomMod:MyRecyclePage", MyRecyclePage)
print "============== add MyTestPage success =============="
# 函数名为Destroy才会被调用，在这个System被引擎回收的时候会调这个函数来销毁一些内容
def Destroy(self):
pass
```
### 3.如何供其他人使用
其他开发者若想使用你的自定义页面，只需要加载你的MOD，然后在配置自定义书本的json的时候使用你的页面类型名称即可。
## 3.自定义组件（进阶）<span id="脚本自定义组件"></span>
该内容为**进阶向**话题，如果开发者不满足于系统提供的**预设组件**，则可以通过这里学习如何自定义组件。需注意以下两点：
- 在阅读此处前请先掌握[界面与交互](../../../18-界面与交互/2-从零开始创建UI.md)中**MC Studio**的使用以及对各类**UI控件**（**BaseUIControl**）的熟悉，**UI json**文件的编写。
- 目前书本仅支持使用这些控件来封装组件，关于它们的介绍具体见[UI说明文档](../../../18-界面与交互/30-UI说明文档.md)：
- Label
- Image
- Button
- Panel
- StackPanel
- NeteasePaperDoll
- ItemRenderer
- ProgressBar
在自定义书系统中，是通过加载**UI json**文件的方式来获取UI控件对象，而获取到的UI控件对象又被封装成组件使用，我们在[CustomBookMod](../../13-模组SDK编程/60-Demo示例.md#CustomBookMod)中定义了一个自定义组件**MyCustomComp**，它的脚本文件为”**behavior_pack/tutorialScripts/comps/customComp.py**“，与该组件相关的UI json文件为”**resource_pack/ui/CustomComp.json**“，并且又自定义了一个页面来使用组件**MyCustomComp**，它的脚本文件为“**behavior_pack/tutorialScripts/pages/customCompPage.py**”，然后我们用一个章节来调用该页面，数据定义在”**behavior_pack/customBooks/customBook/entry/customCompPage.json**“文件中，最终该章节的页面展示结果如下。
<img src="../picture/customBook/script/comps/自定义组件效果图.png" alt="自定义组件效果图" style="zoom: 85%;" />
<center>该自定义组件可以填充图片，文本，设置文本字体大小，而该页面有两个这样的组件，分别位于左上和右下。</center>
### 1.定义UI json文件<span id="UI模板库"></span>
和[界面与交互](../../../18-界面与交互/2-从零开始创建UI.md)一样， 我们可以通过MC Studio来创建一个组件的UI模板，也可以按照**UI**的**json**文件规范来编写**UI**的**json**文件，在本例中我们使用了MC Studio创建一个名为**testComp**的UI控件，它将作为自定义组件**MyCustomComp**的封装对象，同时，该**UI json**文件需要满足以下的节点结构才能供组件使用，我们将comps下的所有UI控件节点的集合称为组件的**UI模板库**。
需注意！**请不要将该json文件起名为“book_preset.json”**，该名字已被预设模板使用。
```
main （名字固定，必须为"main")
| comps （panel控件，名字固定，必须为"comps")
| testComp （组件要使用的UI的根节点，本例中为 testComp，并且该节点的控件类型无规定）
| ...
```
你可以在**comps**层级下创建多个UI根节点，但是一个根节点只会和一个组件进行绑定。
并且为了让自定义组件坐标系与预设组件坐标系一致，**comps**节点的的大小必须设置如下
<img src="../picture/customBook/script/comps/comps节点属性.png" alt="comps节点属性" style="zoom: 85%;" />
对应到**UI json**文件中的属性为 **"size" : [ "100.0%+0.0px", "100.0%+0.0px" ]**
```json
"comps" : {
"alpha" : 1.0,
"anchor_from" : "center",
"anchor_to" : "center",
"clip_offset" : [ 0, 0 ],
"clips_children" : false,
"controls" : [
{
"testComp@CustomComp.testComp" : {}
}
],
"enabled" : true,
"layer" : 0,
"max_size" : [ 0, 0 ],
"min_size" : [ 0, 0 ],
"offset" : [ 0, 0 ],
"priority" : 0,
"propagate_alpha" : false,
"size" : [ "100.0%+0.0px", "100.0%+0.0px" ],
"type" : "panel",
"visible" : true
}
```
并且**Comps**下的子节点（比如**testComp**）的锚点坐标系必须设置如下图：
<img src="../picture/customBook/script/comps/testComp节点属性.png" alt="testComp节点属性" style="zoom: 100%;" />
对应到**UI json**文件中的属性为如下：
```json
"anchor_from" : "top_left",
"anchor_to" : "top_left",
```
### 2.创建组件类
类似页面，一个组件类需要编写3个基本的函数接口：
- 类初始化函数 "\_\_init\_\_"
- 将从页面传过来的数据存储下来的方法 "SetDataBeforeShow"
- 显示组件的函数 "Show"
这些接口需符合链式调用的格式，最终返回**self**。**MyCustomComp**实现的是一个图文控件，可以根据传入的数据更改文本大小，颜色，内容，图片。
这里继承的父类是**BaseComp**，详细请参考[“组件API”](03-组件API.md)。
customComp.py
```python
#-*- coding: UTF-8 -*-
import mod.client.extraClientApi as clientApi
# 获取书本管理对象，详细用法见“05-常见脚本对象”
bookManager = clientApi.GetBookManager()
# 获取书本配置常量，详细API见“05-常见脚本对象”
bcf = bookManager.GetBookConfig()
# 获取组件基类 BaseComp
BaseComp = bookManager.GetBaseCompCls()
class MyCustomComp(BaseComp):
"""
自定义的书本组件类
"""
def __init__(self):
"""
编写该接口需按照如下编写。
1. 先调用父类的同名方法。
2. 定义自定义的属性
"""
# 调用父类__init__方法，该方法会注册书本自定义组件名称，因此该方法只能调用一次（一个组件绑定一个控件节点）。
# 第1个参数为组件的注册名称，为了防止重名，建议名字格式为 'mod名称:任意名称'，最好就是带“Comp”后缀。
# 第2个参数为组件所封装的UI控件所在的json文件名+'.main'
# 第3个参数为组件所封装的UI控件节点名称
# 通过第2，3个参数可以让组件定位到所要封装的UI控件节点，更详细的内容可见 "组件API" 章节。
BaseComp.__init__(self, "CustomMod:MyCustomComp", "CustomComp.main", "testComp")
# 定义自定义的属性，这些都是向页面暴露的属性
self.text = None # 组件的文本字符串，类型为str
self.textSize = None # 组件的文本大小，类型为int
self.textColor = None # 组件的文本颜色，类型为tuple(4)
self.image = None # 组件的图片路径，类型为str
def SetDataBeforeShow(self, image, text, textColor, textSize):
"""
页面在调用组件的Show之前默认会先调用该方法进行数据的存储
建议是将数据存储下来然后在Show方法中进行读取。
"""
# 存储页面传过来的数据
self.text = text
self.textSize = textSize
self.textColor = textColor
self.image = image
return self
def Show(self):
"""
页面向组件传递数据后调用该接口，组件在这里对UIControl节点进行操作。
编写该接口需按照如下编写。
1. 调用父类的同名方法。
2. 按照特定逻辑处理你的UIControl节点
"""
# 执行父类的Show方法，执行该方法后组件才能得到对应的UI控件节点并用_node_属性指向它。
BaseComp.Show(self)
# 往UI控件节点填充数据，_node_为组件所对应的UI控件节点（本demo中为 testComp，即__init__方法中的第3个参数）。
textNode = self.GetRootUINode().GetChildByPath("/text").asLabel()
# 如果是LabelUIControl节点，设置文本和字体大小时需要分别调用 SetNodeText 和 SetTextFontSize，具体可见 "组件API" 章节。
self.SetNodeText(textNode, self.text).SetNodeTextFontSize(textNode, 10, self.textSize)
textNode.SetTextColor(self.textColor)
imageNode = self.GetRootUINode().GetChildByPath("/image").asImage()
imageNode.SetSprite(self.image)
return self
```
本质上组件就是一个带数据的UI控件节点，当组件调用Show的时候，自定义书系统将UI模板中对应的节点拷贝到组件中，所以如果组件没调用Show而调用了它里面的UI控件或者该UI控件下的子节点都是会报错的。
尽管大部分编写的节点都存在拷贝操作，但是可以在初始化节点的时候设置为可回收，防止UI控件节点的过度拷贝和删除，具体可见[“组件API”](03-组件API.md) 章节

1543
mcguide/20-玩法开发/15-自定义游戏内容/5-自定义书本/03-组件API.md Normal file
View File

File diff suppressed because it is too large Load Diff

398
mcguide/20-玩法开发/15-自定义游戏内容/5-自定义书本/04-页面API.md Normal file
View File

@@ -0,0 +1,398 @@
---
front:
hard: 入门
time: 分钟
sidebarDepth: 4
---
# 页面API
## 1.BasePage<span id="BasePage"></span>
所有书本页面都继承**BasePage**，页面负责排版页内的组件。
### 1.重写方法
#### \_\_init\_\_
- 描述
初始化页面
- 参数
| 参数名 | 数据类型 | 说明 |
| -------- | --------------- | ------------------------------------------------------------ |
| size | tuple(int, int) | 页的大小，单位为像素<br>默认值为**None**，书本系统会根据当前书本界面自动获取页面的大小 |
| position | tuple(int, int) | 页的位置（锚点为左上角），单位为像素<br/>默认值为**None**，书本系统会根据当前书本界面自动获取页面的位置 |
- 返回值
| 数据类型 | 说明 |
| -------- | -------- |
| BasePage | 页面实例 |
- 备注
- 当你自定义一个页类的时候**必须重写类初始化方法**，并执行父类"**\_\_init\_\_**"方法，如何重写请参考[脚本自定义书本](02-脚本自定义书本.md#脚本自定义页面)。
#### Show
- 描述
显示页面
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | -------- |
| BasePage | 页面实例 |
- 备注
- 当你自定义一个页面的时候**必须重写该方法**，并执行父类**Show**方法，必须返回自身以支持链式调用。如何重写请参考[脚本自定义书本](02-脚本自定义书本.md#脚本自定义页面)。
- 该方法会依次调用页内组件的**Show**方法，因此在调用该方法前需调用**AddComps**方法将组件添加至页面中。
#### Hide
- 描述
隐藏页面
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | -------- |
| BasePage | 页面实例 |
- 备注
- 当你自定义一个页面的时候**可以不重写该方法**，但如果重写该方法一定要在最后主动调用父类**Hide**方法，必须返回自身以支持链式调用。
- 该方法的调用时机：该方法由书本系统进行调用，当用户翻页的时候，当前页会被隐藏。
### 2.排版方法
BasePage提供了一系列方法方便开发者在页面中进行排版，这些方法依照的UI坐标系参见[“自定义书本UI坐标系”](01-自定义基础书本.md#页面编写)。在对组件调用排版方法之前，确保组件已经加入到页面中（在初始化的时候调用**AddComps**添加组件），以及调用了页面父类的**Show**方法。
#### GetPosition
- 描述
获取页面在书本坐标系中的位置
- 参数
无
- 返回值
| 数据类型 | 说明 |
| --------------- | ---------------------------------------------------- |
| tuple(int, int) | 页面在书本坐标系中的位置（锚点在左上角），单位为像素 |
#### GetSize
- 描述
获取页面的大小
- 参数
无
- 返回值
| 数据类型 | 说明 |
| --------------- | ------------------------ |
| tuple(int, int) | 页面的大小，单位为像素。 |
#### Center
- 描述
获取页面的中心坐标
- 参数
无
- 返回值
| 数据类型 | 说明 |
| --------------- | ---------------------------- |
| tuple(int, int) | 页面的中心坐标，单位为像素。 |
#### Left
- 描述
获取页面左边界的X值
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | ----------------------------- |
| int | 页面左边界的X值，单位为像素。 |
#### Right
- 描述
获取页面右边界的X值
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | ----------------------------- |
| int | 页面右边界的X值，单位为像素。 |
#### Top
- 描述
获取页面上边界的Y值
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | ----------------------------- |
| int | 页面上边界的Y值，单位为像素。 |
#### Bottom
- 描述
获取页面下边界的Y值
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | ----------------------------- |
| int | 页面下边界的Y值，单位为像素。 |
#### ResetCompsPosition
- 描述
重置所有组件的位置为页面当前的位置
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | -------- |
| BasePage | 页面实例 |
- 备注
- 该函数在调用页面父类的**Show**方法后使用，在调用组件的排版方法前使用，相当于将组件先对齐页面后再进行平移，具体用法可见[脚本自定义书本](02-脚本自定义书本.md#脚本自定义页面)。
### 3.工具方法
#### GetPageGroup
- 描述
获取页面当前所在的页组对象
- 参数
无
- 返回值
| 数据类型 | 说明 |
| --------- | ------------------------------------------------------------ |
| PageGroup | 页面当前所在的[页组对象](05-常用脚本对象)<br>如果没有则返回**None** |
#### AddComps
- 描述
向页面中添加组件
- 参数
| 参数名 | 数据类型 | 说明 |
| ------ | -------------------------- | :------------- |
| comps | 可变长参数，元素为BaseComp | 添加的组件对象 |
- 返回值
| 数据类型 | 说明 |
| -------- | -------- |
| BasePage | 页面实例 |
- 备注
- 该函数在页面初始化函数中使用，只有将组件添加进页面后，页面在调用**Show**方法的时候才会调用组件的**Show**方法，具体用法可见[脚本自定义书本](02-脚本自定义书本.md#脚本自定义页面)。
#### Call
- 描述
调用回调函数
- 参数
| 参数名 | 数据类型 | 说明 |
| ------------ | -------- | -------------------------------- |
| callbackDict | dict | 回调函数以及其参数（属性见备注） |
- 返回值
| 数据类型 | 说明 |
| -------- | ---------------- |
| object | 回调函数的返回值 |
- 备注
- 该函数主要用于将回调函数作为额外的数据传进到组件中（比如**ButtonComp**）
- callbackDict的格式如下：
| 参数名 | 数据类型 | 说明 |
| ------ | -------- | ------------------------------------------------------ |
| func | function | 回调的函数 |
| args | list | 回调函数的参数列表，如果回调函数无参，则该属性无需定义 |
- 示例
```python
"""
我们定义两个回调函数，然后分别使用 Call 回调它
"""
def func_1():
pass
def func_2(args1, args2):
pass
callbackDict_1 = {
"func": func_1
}
callbackDict_2 = {
"func": func_2,
"args": [1, 2]
}
page = BasePage()
page.Call(callbackDict_1)
page.Call(callbackDict_2)
```
## 2.TitlePage
### 1.概述
TitlePage提供了对标题的处理方法，方便开发者，具体的示例详见Demo中的“**behavior_pack/customBooks/customBook/entry/myTitlePage.json**”以及“**behavior_pack/tutorialScripts/myTitlePage.py**”。
该页面对标题的处理逻辑为：
1. 当前页面是否为章节的首页，如果是则设置其标题为章节的标题（包括章节的图标）
2. 当前页面如果不是首页，分两种情况：若传进页面的**Data**中定义了"**subtitle**"属性，则标题为"**subtitle**"的值，若无，则不显示标题，页面剩余内容自动往上顶。
标题的页面样式可以这样划分，存在大标题的情况下，可以有图标也可以没有图标，不存在大标题但存在小标题的情况下，就显示小标题，我们结合示例中的**json**文件中的不同属性值来看：
<img src="../picture/customBook/API/title/icon_title2.png" style="zoom: 85%"></img>
```json
"title": {
"icon": "textures/items/apple",
"text": "带图标的标题"
}
```
如果当前页非首页，**title**如上定义为一个对象，则显示的效果为带图标的大标题。
<img src="../picture/customBook/API/title/title.png" style="zoom: 85%"></img>
```json
"title": "大标题"
```
如果当前页非首页，**title**如上定义为一个字符串，则显示的效果为不带图标的大标题。
<img src="../picture/customBook/API/title/subtitle.png" style="zoom: 85%"></img>
```json
"subtitle": "默认的副标题"
```
如果当前页非首页，只定义**subtitle**而不定义**title**则显示如上的文本副标题。
### 2.方法
#### SetTitleData
- 描述
设置标题的数据
- 参数
无
- 返回值
| 数据类型 | 说明 |
| --------- | -------- |
| TitlePage | 页面实例 |
- 备注
- 该函数是在你自定义页面重写**Show**方法的时候调用，往标题中注入数据，如何使用见Demo。
#### LayoutTitle
- 描述
排版页面的标题
- 参数
无
- 返回值
| 数据类型 | 说明 |
| -------- | ------------------------------------ |
| int | 排版标题后，标题的下边界，单位为像素 |
- 备注
- 该函数是在你自定义页面重写**Show**方法的时候调用，用于排版标题，如何使用见Demo。

1106
mcguide/20-玩法开发/15-自定义游戏内容/5-自定义书本/05-常用脚本对象.md Normal file
View File

File diff suppressed because it is too large Load Diff