From 92520a50daea18e4fece9c6357d2c10b0224cb83 Mon Sep 17 00:00:00 2001 From: blank Date: Mon, 7 Jun 2021 16:20:50 +0800 Subject: [PATCH] readme --- README.cn.md | 288 --------------------------------------------------- README.md | 16 ++- 2 files changed, 11 insertions(+), 293 deletions(-) delete mode 100644 README.cn.md diff --git a/README.cn.md b/README.cn.md deleted file mode 100644 index a799633..0000000 --- a/README.cn.md +++ /dev/null @@ -1,288 +0,0 @@ -# cx-cocos -**一个基于cocos creator3.1.1的应用App和游戏开发框架** - -关键词：cocos creator、应用开发、App开发、游戏开发、跨平台、框架 - - cocos creator是一个开源的游戏开发引擎，在游戏开发方面，拥有大量开发者。然而在应用App方面，却少有人使用，cx-cocos的出现，填补了cocos creator在应用App开发上的空白。 - - 使用cx-cocos，你可以轻松愉快地开发出一个跨平台应用App，包括ios、mac、android、web等，当然你也可以使用cx-cocos开发游戏，这是一个高效简洁的开发框架，极大提升开发者的效率。 - -**本说明文档包括以下内容：** -- cx-cocos主要功能 -- cx-cocos结构和原理 -- 如何运行demo app -- 如何使用cx-cocos开始一个自己的项目 -- 问题和技术支持 - - -## 1. 主要功能 -**cx-cocos的主要功能包括以下内容：** -- 应用App的核心UI交互 -- 页面和组件访问、资源访问、远程服务访问 -- 与原生代码的交互 -- 真正的启动屏 -- 热更新 - - -### 1.1 应用App的核心UI交互 ----- - cx-cocos在页面的显示与交互细节上，与iOS原生App有着相似的体验， - 包括页面的进入退出与手势、提示弹窗、ScrollView、Loading等待、选择器等等。 - cx3-demo是一个demo，建议你从它入手，了解cx-cocos。 - -- **屏幕适配：** 通常情况下，应用App是宽度适应（fitWidth）、高度随着屏幕高度自动铺满。cx-cocos提供了一个“最小设计宽/高度”的配置，即使在浏览器或Pad上，App也能按最佳的方式显示界面——你只需按你的设计尺寸来设计UI。 - -- **刘海屏适配：** 对于iphoneX等屏幕，通过添加cx.safearea脚本，可自动调节标题栏、内容层、底部导航栏的高度和位置。 - -- **界面进入与退出：** 动画进入与退出、手势划动退出、上一页面随动、阴影效果、响应android返回键。 - -- **对话框：** Alert提示框、Confirm确认框。框架还提供了一种Hint动画文字提示，你可以多点击几次试试。 - -- **选择器：** 框架提供了1栏或多栏的选择器，你可以轻松地实现年月日选择、年月选择、文字或对象列表选择。 - -- **ScrollView：** 扩展了下拉刷新、上滑增量添加数据的能力。 - -- **PageView：** 扩展了定时自动下一页、循环播放、点击回调的能力。 - -- **等待动画：** 可以在页面正中或任意控件内显示Loading动画，并且有延时显示能力，这在查询数据时非常实用，比如0.5秒后还没有返回数据，才显示Loading动画。 - -- **原生视图：** 原生UI在cocos UI中显示，并且随着ScrollView滚动或窗体滑动；原生UI遮罩能力，例如对话弹框、标题栏在原生UI之上显示，不被遮挡。 - - -### 1.2 页面和组件访问、资源访问、远程服务访问 ----- - 操作UI组件在应用开发中非常频繁，cx-cocos提供了便捷的方式对组件进行访问和操作。 - -| UI常用方法 | 说明 | -| ---- | ---- | -| cx.sw | 适配后的屏幕宽度 | -| cx.sh | 适配后的屏幕高度 | -| cx.gn(pageOrNode, nodeName) | 获取场景树中的节点 | -| setTouchCallback(page, callback, ...params) | 给Node添加点击事件 | -| cx.hint(content) | 显示提示 | -| cx.alert(content, callback?, labelOK?) | 显示对话窗 | -| cx.confrm(content, callback?, labelOK?, labelCancel?) | 显示确认窗 | -| cx.showLoading(page, parentNode, delayShowSeconds?) | 显示等待动画 | -| cx.removeLoading(parentNode) | 移除等待动画 | -| cx.addPage(parentNode, prefabName, scripts?, callbackOrParams, runAction?) | 添加一个页面 | -| cx.showPage(prefabName, scripts?, callbackOrParams) | 添加一个页面(动画进入) | -| cx.closePage(pageOrSender) | 关闭本页面 | -| | | - -**示例代码：** -```typescript -var lblTitle: Node = cx.gn(this, "lblTitle"); //获取场景树中的名称为lblTitle的节点 - -//给lblTitle添加一个点击事件 -lblTitle.setTouchCallback(this, this.myClick); - -//你也可以定义回调时的参数： -lblTitle.setTouchCallback(this, this.myClick, 1, "a", {tip:"任意类型和数量的参数"}); - -myClick(sender, p1, p2, p3) -{ - //sender = lblTitle - //p1 = 1 - //p2 = "a" - //p3 = {remark:"任意类型和数量的参数"} -} - -cx.showPage("ui/pageChild"); //显示ui/pageChild.prefab -cx.hint("cx.hint(content)"); -cx.alert("cx.alert(content, callback, labelOk)"); -cx.confirm("cx.confirm(content, callback, labelOk, labelCancel)", cx.hint); -cx.showLoading(this); -cx.removeLoading(this); -cx.closePage(this); - -//给scrollView添加增量新增数据能力 -cx.script.scrollView.initDeltaInsert(this, "view", this.queryData); - -//给scrollView添加下拉刷新能力 -cx.script.scrollView.initDropRefresh(this, "view", this.refreshData); - -//给PageView添加自动循环滚动能力 -cx.script.pageView.initAutoScroll(this, "viewBanner", 2, true, this.onBannerClick); -```` - -| 资源常用方法 | 说明 | -| ---- | ---- | -| cx.setImageFromRes(spriteOrNode, prefab, sizeMode?, callback?) | 给节点设置图片(从resources) | -| cx.setImageFromBundle(spriteOrNode, prefab, sizeMode?, callback?) | 给节点设置图片(从bundle) | -| cx.setImageFromRemote(spriteOrNode, url, localPath?, sizeMode?, callback?) | 给节点设置图片(从远程url，存储至本地localPath，并优先从localPath加载图片) | -| cx.loadBundleRes(prefab, callback?) | 加载1个或多个prefab | -| | | - - -| 远程访问常用方法 | 说明 | -| ---- | ---- | -| cx.call(url, callback?, context?) | 调用服务端服务(call方式) | -| cx.post(url, data?, callback?, context?) | 调用服务端服务(post方式) | -| cx.upload(url, filePath, callback?) | 调用服务端服务，上传文件 | -| cx.setCommonHeaders(headers: string[]) | 设置http请求的默认headers | -| cx.loadFile(url, localPath?, callback?) | 从url加载文件，存储至本地并优先从本地加载 | -| cx.loadAsset(url: string, callback?) | 从url加载Asset | -| | | - - -| utils常用方法 | 说明 | -| ---- | ---- | -| cx.utils.xxx | cx.func中定义了常用的工具方法，如时间等，具体参见cx.d.ts | -| | | - - -### 1.3 与原生代码的交互 ----- - cx-cocos提供了一个cxnative原生类，通过它可以方便地与原生代码、第三方SDK交互。 - 与iOS/mac的交互是通过jsb/c++ ———— 避免了苹果审核风险 - 与android的交互是通过jsb.reflection - - * 可参照demo中的SystemIntf编写你自己的原生类 - -**原生类的定义：** -iOS/mac：在jsIntf.cpp中定义你的类名和处理类，类继承自cxDefine.h中的NativeIntfClass -android：在jsIntf.java中定义你的类名和处理类 - -- 在JavaScript/TypeScript中调用原生方法： -```typescript -cx.native.ins("className").call("functionName", [...params], callback); -```` - -- 在iOS/mac中调用JS方法： -```c++ -this->callback(int, string); -```` - -- 在android中调用JS方法： -```java -NativeIntf.callJs("className", int, string); -```` - - -### 1.4 真正的启动屏 ----- - cocos creator提供了一个定时长的启动画面，你无法在首页渲染完成后再移除画面，也无法提前移除。并且它只能在加载cc.js之后显示，而不是在App真正启动时。 - cx-cocos针对iOS/mac和Android，提供了原生的启动画面处理，你可以在App启动时显示，在任意时刻移除。 - -iOS/mac启动屏实现代码：见demo中的AppController.mm -android启动屏实现代码：见demo中的CocosActivity.java - -```typescript -// ios/Mac: LaunchImage.png -// android: lanuch_image.png -// 移除启动屏，如果你在config.ts中配置了自动移除，那么不需要执行这句，cx会在开始页(startPage)加入场景时自动调用 -cx.removeLaunchImage(); -```` - - -### 1.5 热更新 ----- - cx-cocos在执行main.js之前执行热更新。 - cx-cocos提供了一个update.js工具用于生成热更新需要的manifest文件，执行命令为： - $ node update.js -v 1.0 - * 在执行之前，你需要将update.js中的更新地址替换为你的服务器地址。 - -****实现原理：见demo中的boot.js*** - - -## 2. cx-cocos结构和原理 - ->**cx-framework目录结构：** -- **cocos3-libs:** 这里是从creator构建项目中提取的引擎libs，我们把它独立出来，所有项目就只需要assets - - **cocos-libcc:** cocos android jar，你的android工程需要依赖它 - - **cocos-libso:** cocos android so，编译生成libcocos.so的工程，android需要这个.so - - **cocos3-ios.xcodeproj:** 编译生成libcocos3 iOS.a的工程，iOS需要这个.a - - **cocos3-mac.xcodeproj:** 编译生成libcocos3 Mac.a的工程，mac需要这个.a -- **cx:** cx-cocos的ts代码，你的creator工程需要它，请拷贝到你项目中的assets目录，或在assets目录中建立链接cx链接到它，链接命令：ln -s ../../cx-framework3.1/cx cx - - **core:** cx-cocos框架实现类 - - **prefab:** cx-cocos内置的预制资源 - - **scripts:** cx-cocos内置的组件脚本 - - **template:** cx-cocos提供的组件模板，在设计页面时可以使用它 -- **cx-native:** 负责原生交互，你的iOS/mac工程需要它，android不需要（它已经在libcocos.so中） -- **cx.d.ts:** cx-cocos的TypeScript声明文件 - - ->**demo的目录结构：** -- **project:** 原生工程都在这里了（并非creator构建生成的工程） - - **assets: 注意，** 它来源于cocos构建发布，你可以创建iOS、mac、android任意一种构建，将生成的assets拷贝到这里，建议你在这里建立一个assets链接，链接到你构建生成的assets目录，这样在每次重新构建后就不需再拷贝assets，链接命令：ln -s 路径 assets - - **boot:** 启动js和热更新manifest文件 - - **cxdemo.android:** demo android studio工程 - - **cxdemo.ios:** demo iOS/mac工程 - - **statics:** 一些仅供原生使用的静态资源 - - **update.js:** 生成热更新文件的脚本 -- **其他目录:** cocos creator生成的目录 - - ->**cx-cocos设计结构** -- 在ts层面，cx-cocos包括： - - cx: 常用变量、常用方法、UI方法 - - cx.native: 与原生交互相关 - - cx.picker: 选择器相关 - - cx.res: 资源处理相关 - - cx.script: 组件扩展功能脚本，例如为ScrollView扩展下拉刷新能力 - - cx.serv: 服务交互相关 - - cx.sys: 系统环境和配置相关 -- 在原生层面，cx-cocos包括： - - cxnative: 原生JSB接口类，对应于cx.native的实现 - - sysIntf: 内置的系统原生类，用于获取包名、环境等 - - maskIntf：内置的遮罩原生类，用于给原生UI添加遮罩 - ->**cx-cocos运行机制** -- app启动首先加载boot.js，处理热更新，然后加载assets的main.js、cc.js等 -- app加载cc.js后，加载项目js，cx作为项目的一部分被加载，cx作为全局对象存储于window.cx -- 在你的组件脚本中，你不需要import cx-cocos的任何脚本，因为它是全局的，直接使用就可以 -- **整个app只有一个场景，所有页面都是预制资源** - - 在主场景中有一个根节点RootNode，负责滑动事件、android返回键的处理 - - 你在config.ts中定义的startPage，在主场景启动时，被addPage到RootNode中 - - 其他页面你可以通过addPage或showPage方法显示，默认会运行与页面同名的脚本（可在该方法的参数中指定加载的脚本） - - 通过addPage或showPage方法显示的页面，它们的parent都是RootNode - - 在addPage或showPage方法回调参数中，你可以向子页面传递参数或控制子页面 - - 如果页面定义了onChildPageClosed方法，那么子页面在关闭时，会触发这个方法 - - 你可以自定义页面进入和退出时的动画 -- cx-cocos定义和实现了通用的原生交互方式 - - 通过cx.native.ins("名称").call("方法", [...参数], 回调方法)调用原生方法 - - 分别在iOS的jsIntf-ios.mm、android的jsIntf.java定义你自己的“名称”处理类 - - -## 3 如何运行demo app -1. 安装cocos creator 3.1.1 -2. 确保cx-framework3.1和cx3-demo在同一目录下 -3. iOS/mac环境：在xcode中打开cx3-demo/project/cxdemo.ios/cx3-demo.xcodeproj，运行 -4. android环境：在android studio中打开cx3-demo/project/cxdemo.android，运行 -```typescript -* 在iOS/mac、android上编译或运行demo，你可以不需要打开cocos creator -* android的video遮罩暂未完成（技术困难，如果你有好的实现方式，请告诉我） -``` - - -## 4 如何使用cx-cocos开始一个自己的项目 -1. 使用cocos creator3.1.1创建一个项目，与cx-framework3.1在同一目录下 -```typescript -* 建议你使用cocos creator3.1.1 (2021.06.01发布) -* 如果你使用的是creator3.1.0，可能需要重新编译cx-framework3.1中.so和.a - 重新编译前，可使用vscode编辑器，查找3.1.1，全部替换成3.1.0 -* 如果你使用的是creator3.0.x，那么cx-framework3.1中的libs工程不适用，你需要从creator构建生成的项目中，提取cocos2d（支持3.0.x的框架我并未上传至git，如有需要请联系我） -``` -2. 拷贝cx3-demo中的tsconfig.json文件和project目录到你的项目目录下 -```typescript -* 拷贝tsconfig.json的目的仅仅是因为——它定义了cx.d.ts的引用，你也可以不拷贝而自行定义： -"compilerOptions": {"types": ["../cx-framework3.1/cx"]} -``` -3. 根据自己的需要，修改project目录内的工程的内容 -4. creator项目设置 - - 项目数据 - - 设计宽度：750 - - 设计高度：1334 - - 适配屏幕宽度：是 - - 适配屏幕高度：否 - - 功能裁剪： - - 去掉3D - - 去掉2D中的：2D物理系统、2D相交检测算法、2D粒子系统、Tiled地图、Spine动画 -5. creator构建发布设置： - - 发布路径：不要填写成project，那会弄乱你的project目录，建议设置为native或build - - MD5缓存：不要勾选 - - 替换插屏：**勾选，并且最小显示时间设置为0** - - 屏幕方向(Orientation)：只勾选portrait - - -## 5 问题和技术支持 diff --git a/README.md b/README.md index fef41db..27cca9b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ App development framework based on cocos creator3.1.1 关键词：cocos creator、应用开发、App开发、游戏开发、跨平台、框架 - cocos creator是一个开源的游戏开发引擎，在游戏开发方面，拥有大量开发者。然而在应用App方面，却少有人使用，cx-cocos的出现，填补了cocos creator在应用App开发上的空白。 + cocos creator是一个开源的游戏开发引擎，在游戏开发方面，拥有大量开发者。 + 然而在应用App方面，却少有人使用，cx-cocos的出现， + 填补了cocos creator在应用App开发上的空白。 使用cx-cocos，你可以轻松愉快地开发出一个跨平台应用App，包括ios、mac、android、web等，当然你也可以使用cx-cocos开发游戏，这是一个高效简洁的开发框架，极大提升开发者的效率。 @@ -164,8 +166,10 @@ NativeIntf.callJs("className", int, string); ### 1.4 真正的启动屏 ---- - cocos creator提供了一个定时长的启动画面，你无法在首页渲染完成后再移除画面，也无法提前移除。并且它只能在加载cc.js之后显示，而不是在App真正启动时。 - cx-cocos针对iOS/mac和Android，提供了原生的启动画面处理，你可以在App启动时显示，在任意时刻移除。 + cocos creator提供了一个定时长的启动画面，你无法在首页渲染完成后再移除画面，也无法提前移除。 + 并且它只能在加载cc.js之后显示，而不是在App真正启动时。 + cx-cocos针对iOS/mac和Android，提供了原生的启动画面处理， + 你可以在App启动时显示，在任意时刻移除。 iOS/mac启动屏实现代码：见demo中的AppController.mm android启动屏实现代码：见demo中的CocosActivity.java @@ -264,7 +268,9 @@ cx.removeLaunchImage(); * 建议你使用cocos creator3.1.1 (2021.06.01发布) * 如果你使用的是creator3.1.0，可能需要重新编译cx-framework3.1中.so和.a 重新编译前，可使用vscode编辑器，查找3.1.1，全部替换成3.1.0 -* 如果你使用的是creator3.0.x，那么cx-framework3.1中的libs工程不适用，你需要从creator构建生成的项目中，提取cocos2d（支持3.0.x的框架我并未上传至git，如有需要请联系我） +* 如果你使用的是creator3.0.x，那么cx-framework3.1中的libs工程不适用， + 你需要从creator构建生成的项目中，提取cocos2d + （支持3.0.x的框架我并未上传至git，如有需要请联系我） ``` 2. 拷贝cx3-demo中的tsconfig.json文件和project目录到你的项目目录下 ```typescript @@ -289,4 +295,4 @@ cx.removeLaunchImage(); ## 5 问题和技术支持 - +https://forum.cocos.org/t/topic/114696