如何開發出優秀的APICloud應用

APICloud定制平臺項目實施規范
APICloud應用優化策略Top30
如何開發出運行體驗良好、高性能的App
如何開發出客戶滿意、能夠順利交付的App

1. 引擎或模塊問題：

遇到應用層無法解決的問題，如果能確定需要引擎和模塊支持的，不要自己想辦法繞過去，要第一時間在開發者社區提交問題，或找APICloud項目經理提出。

在開發者社區中，會有版主和APICloud技術支持對您的問題進行驗證和解答。
定制平臺項目問題提出后2天之內沒有解決的，可以直接找APICloud項目總監投訴。

2. 開發工具：

推薦使用Sublime Text＋APICloud插件，調試工具使用自定義Loader，真機同步使用WiFi真機同步，日志輸出使用WiFi日志輸出。

推薦視頻：Sublime使用教程Window&Mac
推薦文檔：Sublime插件使用說明

3. 前端框架：

盡量不要使用jQuery、AngularJS、BootStrap等重型的框架，擺脫對$的依賴，培養自己動手的習慣，但是可以根據功能需求在特定頁面中使用功能獨立的Mobile First框架

默認樣式設置、DOM操作和字符串處理推薦使用APICloud前端框架(api.js和api.css)
移動端UI框架推薦使用AUI

4. 屏幕適配：

要正確設置viewport，建議使用720*1280尺寸的UI圖，優先考慮絕對計量類的單位 px，應先在UI效果圖中（如720x1280尺寸圖）量出元素的寬或高對應的 px 值，再除以屏幕倍率（如分辨率為720x1280設備的屏幕倍率通常為 2) 來得到書寫樣式時的確切數值。

APICloud項目驗收時會根據設計提供的UI圖尺寸（如720x1280），在對應屏幕分辨率的手機設備(如720x1280）中安裝運行，將運行后的頁面與UI效果圖一一進行對比。
H5界面的實現要與UI設計完全一致，精細到0.5px。
openFrame/FrameGroup等時，應使用auto結合margin布局，以動態適應變化無常的android設備屏幕。
推薦文檔：屏幕適配原理及實現

5. UI布局：

要求使用APICloud五大組件（Widget、Layout、Window、Frame、UIModules）進行APP的UI架構設計。
SPA的模式不適合APP開發，DIV＋JS的窗口切換影響用戶體驗。APICloud的UI結構設計可以從整體上解決H5在Interaction、Animation和Render方面的性能問題。
推薦文檔：培訓講義：APICloud界面布局和APP架構設計

6. 窗口切換：

避免出現任何卡頓、閃屏、白屏等情況；動畫效果流暢，不能出現丟幀的情況。

要理解并控制窗口好切與界面渲染之間的關系，要適時更新UI，如果Window或Frame中所加載的靜態頁面內容過多，建議等動畫執行完畢再進行頁面的加載和渲染。無論是Android還是iOS系統，在進行窗口切換的時候，如果窗體本身正在進行渲染（Window或Frame所加載的網頁沒有渲染完畢），則會影響切換動畫運行的流暢性，出現卡頓或丟幀的情況。

建議在打開Window或Frame的時候，如果所加載的靜態網頁不能過大，內容不要太多，不能快速的渲染完畢。為了不影響窗體切換動畫的執行，可以在切換動畫執行完畢后再進行動態數據的加載和界面的刷新。

7. 窗口切換動畫：

如果沒有特別要求盡量使用平臺默認的動畫效果，即api.openWin時不指定動畫類型，使用默認值。
無論是在Android還是iOS上，APICloud引擎會從整體上保證默認的窗口動畫類型是性能最好的。
三星、小米等大屏Android6.0及以上手機，可以嘗試在云編譯的時候選擇使用Android引擎渲染優化版本
如果窗體所加載的靜態網頁內容比較多(如：初始的Dom樹很大或圖片很多)，在Android平臺上openWindow的時候可以嘗試使用movein或fade的動畫類型

8. 窗口關閉處理：

開發過程中根據需要處理Android的keyback事件和iOS的回滑手勢。

Android上要在Window中才能監聽到keyback事件，Frame中無法監聽到keyback事件；在iOS7以上的系統上可以在openWin的時候通過設置slidBackEnabled參數來實現是否支持回滑手勢關閉窗口的功能。

在后臺關閉頁面時，應注意在關閉方法中添加animation:{type:"none"}，來防止切換動畫的出現影響用戶體驗；

9. 窗體背景圖片：

避免使用H5來實現body級別的背景圖片，可以使用Window或Frame的bgColor參數以原生的方式來高效實現
不建議通過給body元素指定background的方式來實現body級別的背景圖片，特別是高清的大背景圖片用H5方式實現會嚴重影響渲染性能。

10. 導航切換：

切換底部導航或頂部分類菜單的時候，要求切換體驗平滑，切換過程不能出現白屏、閃屏等現象

建議使用FrameGroup來實現Frame的切換，要按需合理配置預加載的Frame數量，每個Frame要有明顯的刷新機制，不能每次切換都進行刷新和重繪。

如果使用模塊來實現底部導航欄推薦使用NVTabBar模塊。

11. 列表滾動：

滾動效果要平滑流暢，不能使用iscroll等JS的方式來實現滾動

建議使用Window+Frame的UI結構，以Native的方式來實現列表頁面的滾動。

在iOS上要支持點擊狀態欄能自動回到頂部的效果，可以通過在openWin或openFrame的時候配置scrollToTop參數來實現；此效果在FrameGroup中使用的時候要注意確保只有當前顯示的Frame的scrollToTop屬性為true，其它Frame的scrollToTop屬性為false。

12. 界面之間參數傳遞：

可以使用pageParam來實現，但要避免使用過大的pageParam。界面切換的時候如果pageParam過大，則JSON解析就會比較耗時，影響界面切換的執行和動畫運行體驗。

不要使用使用URL+?的形式進行參數的傳遞，此方式在Android上存在兼容問題。

13. 交互響應：

點擊事件必須處理click事件的300ms延遲問題，優化點擊響應速度，建議通過為可點擊的元素增加tapmode屬性來優化點擊速度。

引擎對具有tapmode屬性的元素點擊事件的優化處理會在apiready事件觸發之前，根據當前的dom樹自動進行優化。在apiready之后加載的數據使用要顯式的調用api.parseTapmode方法來進行主動的tapmode處理，例如在上拉加載更多數據后，要調用一下api.parseTapmode方法.

要按UE設計確定可點擊區域的大小，可以適當擴大點擊區域來保障點擊反應的靈敏。

api.parseTapmode調用會有性能成本，不需要的情況下不要隨便調用。

要按照需求明確所有按鈕點擊時的交互效果，為tapmode屬性設置正確的樣式值，對于沒有交互效果的點擊實現，可以不為tapmode屬性指定任何樣式，但是為了優化點擊速度，必須要給元素增加tapmode屬性。

14. 下拉刷新效果：

建議不要使用APICloud默認的下拉刷新效果（灰色箭頭），要使用模塊來實現UE/UI所設計的下拉刷新效果。

如果UE/UI所設計的下拉刷新效果，使用目前APICloud平臺模塊無法實現，要第一時間跟項目經理提出，由APICloud進行模塊封裝來實現。

15. 網絡通信方式：

必須使用api.ajax，并且設置合適的超時時間，并進行超時和請求失敗的異常情況。

JQuery的ajax在開啟全包加密的時候會有問題，不建議使用。

16. 網絡請求狀態處理：

APP要判斷當前的網絡狀態，請求過程要按UI設計有明顯的狀態提示；網絡超時或網絡請求失敗的時候要進行相關處理并有錯誤提示。

api對象和dialogBox模塊下面封裝了常用的提示對話框方法。

17. 數據緩存：

要對GET請求進行數據的緩存處理，在用戶沒用網絡的情況下，仍然能夠看到APP的靜態界面布局以及上次已經緩存的服務器端數據。

可以在api.ajax方法中設置cache參數為true來開啟緩存；也可以使用api.writeFile和api.readFile方法，在獲取數據后自己實現簡單的數據緩存，或使用fs和db模塊來緩存數據。

18. 圖片緩存：

必須手動進行圖片的緩存處理，需要調用api.imageCache方法實現。

Webview默認的緩存機制存在缺陷，在跨窗口時表現不好，并且存在對所緩存圖片的尺寸限制等問題，所有APICloud應用的圖片緩存不能依賴Webview默認的緩存機制，必須手動實現。

19. 圖片處理：

要減少由圖片造成的內存占用，減少圖片縮放等耗性能的操作，服務器端要根據產品設計提供合適尺寸的大圖、小圖、縮略圖等

APICloud應用所占用的內存大小由所加載的網頁大小決定，通常圖片過多過大會造成整個應用的內存占用過大，另外在瀏覽器中進行圖片的縮放處理成本也很高。

列表中的頭像等縮略圖，寬高應控制在250-300px之間，小于這個范圍大屏手機容易失真，大于這個范圍消耗更多內存和性能。

20. 狀態欄效果：

Android和iOS上都要求實現沉浸式狀態欄效果的適配

可以通過在config.xml中開啟沉浸式效果]配置項，然后在Window或Frame的apiready事件后，調用$api.fixStatusBar()方法來實現。如果由于各種原因造成apiready執行太晚，當Header高度變化時會產生頁面跳動的現象，也可以根據需求自己來實現，在合適的時機（如onload事件中）判斷平臺類型后，手動調整Header的高度，Android的狀態欄高度是25px，iOS是20px。

要根據當前界面的背景顏色，通過調用api.setStatusBarStyle方法來設置當前狀態欄的風格或背景色。

21. 鍵盤處理：

在打開帶有輸入框的Window或Frame的是，默認要自動讓輸入框自動獲得焦點。

在config.xml中有關于鍵盤顯示方式，彈出方式和第三方鍵盤使用的各種配置，要根據需要正確配置。

由于在Android上input元素的focus事件存在兼容性問題，要完成輸入框自動獲取焦點的功能，建議使用擴展模塊UIInput模塊。

在打開Window的時候，如果自動彈出鍵盤，彈出鍵盤的行為影響切換動畫執行的流暢性，出現卡頓或丟幀的情況。建議可以對鍵盤彈出的行為設置適當的延遲，例如在apiready中設置延遲200ms后再讓UIInut元素獲得焦點。

可以在同一個界面中（如登陸界面）創建多個UIInput模塊的實例，來實現多個輸入框。

輸入框位于設備屏幕下半部份的應用場景，config.xml中的的鍵盤彈出模式參數softInputMode務必設置為resize模式，或者使用UIInput相關模塊。

為了讓應用看起來更接近原生，盡量配置config.xml中的softInputBarEnabled參數來隱藏iOS鍵盤上面的工具條。也可以在openWin或openFrame的時候通過softInputBarEnabled參數來單獨指定。

22. 配置外部字體：

可以根據項目的需要引入外部字體，但是要控制外部字體文件的大小，字體文件不宜過大。

Android上默認有3種字體：sans, serif, monospace，在開發人員不指定的情況下，默認為sans，這3種字體在開發過程中都是通過字體名進行引用，系統會自動對應到內置字體文件。但是，對于外部的字體文件，Android上無法實現通過引擎配置后成為內置的字體文件，只能通過@font-face的方式在每個頁面中重復加載，每一個要使用外部字體的Window或Frame都要引入一遍，如果字體體積過大會占用大量內存，并且影響頁面的加載速度。

iOS可以在config.xml文件中進行外部字體文件的配置，配置完成后就可以像系統內置字體一樣在頁面中指定了，無需在每個Window或Frame中通過@font-face的方式引入。

23. JavaScript模版：

建議使用doT模版等輕量級的模版。

要優先選擇使用Mobile First的模版，體量小，生成的文本效率高。

doT模版文檔

24. 支付業務：

支付寶，微信等密鑰必須存放在服務器端，不應暴露在APP代碼中。

支付訂單金額應由服務器產生，服務器一定要對支付寶、微信服務器回調的支付結果做最終校驗。

alipay模塊要調用payOrder方法來進行支付，自己處理訂單信息以及簽名過程；不要使用config接口和pay接口把訂單信息以及簽名過程交予模塊內部處理（官方提供此種支付方式只是為了方便開發者調試）。

25. 使用同步接口：

對于文件、數據庫、偏好設置等操作推薦使用同步接口(方法名增加Sync后綴)來簡化代碼的實現，解決異步callback層次過深的問題。

fs對象的同步方法
db對象的同步方法
偏好設置操作的同步方法

對于異步callback嵌套的問題，也可以通過調用api.sendEvent方法來解耦，通過事件機制來實現。

26. 網頁代碼組織：

盡量將同一個界面的HTML、CSS和JS代碼寫在一個html文件中，提高頁面加載速度；公用的CSS、JS盡量少和小，不要在html頁面中隨意加載無用的CSS或JS文件；盡量減少頁面中的link或script標簽的使用。在瀏覽器中，外部文件的引入和加載過程是同步操作，影響整個頁面的執行效率。

27. 應用代碼組成：

要遵循APICloud Widget包結構，結構清晰規范。
推薦文檔：APICloud Widget包結構

28.文件命名規范：

要有統一規范，如首頁Windowhome文件命名為home.html，首頁Frame文件命名為home_frame.html，所有文件名(網頁和資源文件)避免使用中文命名、也不要包含大寫字母。原生系統內部資源文件管理不支持中文名和大寫字母，使用中文或大寫的資源文件在真實設備運行中會出現各種問題。

例如在自定義Loader中運行沒有問題，但云編譯的包就有問題，出現頁面無法加載或資源找不到等問題，通常就是使用了中文或大寫的文件命名。因為官方Loader或自定義Loader的Widget是存放在SDCard中，而云編譯后的安裝包Widget是存在應用的沙箱中，沙箱中是要采用的原生系統的內部資源文件管理機制。

29. 安全機制：

要從代碼、數據存儲、網絡通信等方面保證APP的內容和數據的安全。

開發過程中每次云編譯的無論測試包還是正式包都建議選擇全包加密，因為在APICloud定制平臺上，客戶可以全程監控項目的實施過程，可以查看代碼提交紀錄，但是沒有獲取代碼的權限；客戶可以查看云編譯紀錄，如果編譯的安裝包沒有使用全包加密則客戶可能通過解壓安裝包輕松獲取APP的H5源碼，從而影響后續項目款的按時支付。