ApiCloud開發經驗總結

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源碼，從而影響後續項目款的按時支付。
• !!!注意!!!： config.xml中的access配置項能夠配置在哪些類型的頁面裏面能夠訪問APICloud的擴展API方法，可訪問域的設置以及越獄限制等。
• !!!注意!!!： config.xml中的checkSslTrusted配置項配置是否檢查https證書是受信任的。
• !!!注意!!!： config.xml中的appCertificateVerify配置項配置是否校驗應用證書。若配置爲true，應用被重簽名後將沒法再使用。
• !!!注意!!!： 對重要參數變量進行必要的加密處理，對重要的常量數據應放入key.xml中，使用api.loadSecureValue方法進行數據讀取；

 

30. 安裝包大小：雲編譯生成的安裝包的大小由4部份內容組成：引擎、模塊、網頁文件和資源文件。引擎的大小是固定的（Android約爲400K，iOS約爲1.2M），應該控制減小模塊、網頁文件和資源文件的大小，刪除無用的模塊和文件。

• !!!注意!!!：編譯正式版本的時候，要檢查一下控制檯選定的模塊是否都在實際代碼中使用到了。一些開發者在開發過程當中會不斷引入一些「預計使用」或"測試使用"的模塊，可是在最終的代碼中沒有使用，這部分模塊要雲編譯的時候去掉，無用的模塊不只僅會增大安裝包的體積，還有可能引發於其它模塊的衝突或編譯選項，形成編譯失敗。
• !!!注意!!!：在config.xml文件中配置的模塊，在控制檯沒法刪除，由於config中feature配置項的forceBind屬性默認true，是強制綁定的，能夠經過在配置forceBind屬性來修過。
• !!!注意!!!：在編譯正式版本的時候，要刪除Widget包中的icon和launch目錄下的圖片以減少安裝包體積。