前言

本文將介紹前端如何封裝一款 js-sdk 以及如何快速將你的應用變成 js-sdk , 我們將總結一些封裝 js-sdk 的原則和案例, 來幫大家更快的上手 sdk 開發. 其中筆者還會以H5-Dooring 為例子, 介紹如何將 H5 頁面編輯器封裝成一個 js-sdk 供他人使用.

正文

在開始文章之前, 筆者先來介紹一下什么是 sdk .

sdk 即軟件開發工具包, 一般是一些軟件工程師為特定的軟件包、軟件框架、硬件平臺、操作系統等建立應用軟件時的開發工具的集合。

對于 js-sdk 而言, 我們能舉出很多例子, 如下:

• UI組件庫
• 性能監控工具, 如阿里 arms
• 統計分析工具
• 阿里云智能驗證sdk
• 極驗驗證sdk

sdk 的目的是提高我們開發項目的效能, 安全性和便捷性等問題, 所以我們在設計 sdk 時一定要遵循一些原則, 如下: 

• 最小可用性原則: 也就是沒有必要的功能/代碼盡量不額外添加, 使代碼達到最簡
• 最少依賴原則: 也就是沒有必要的依賴堅決不添加, 以達到最低限度的外部依賴
• 易擴展: 插件化，最大限度支持擴展和自定義
• 穩定性: 絕不能導致宿主應用崩潰，向后兼容, 可測試

在熟悉以上的背景和原則之后, 我們來看看如何實現一個 sdk 的案例.

將 H5-Dooring 封裝成一個 js-sdk

筆者在這拿 開源頁面制作工具 H5-Dooring 來作為案例(當然將其封裝成 sdk 也是我們迭代中的一部分, 甚至后期會做成npm包), 介紹如何封裝js-sdk, 我們先看一張抽象圖:

我們的 sdk 就好像一個完整系統的一個零件, 可以和系統中的其他模塊通信, 互相交換數據. 總體而言 sdk 是為宿主系統服務的, 在 dooring-sdk 中 我們一方面要提供對外的接口支持, 另一方面需要支持宿主能控制 H5 編輯器的界面, 所以綜合分析下來我們有如下的初步規劃圖:

首先我們 sdk 采用 js 動態加載 iframe 的模式來實現, 并通過 iframe 通信來實現props 傳遞, 此時可以有兩種比較靠譜的通信方案:

• 使用 postmessage 實現跨域跨系統通信
• 使用 url 參數通信

由于 postmessage 對宿主系統要求比較高, 需要宿主手動配置 origin 白名單, 對可插拔式體驗不夠友好, 所以筆者這里采用了比較常用的 url 通行方式, 這里需要對參數做解析, 最后達到一個比較簡單的接入方式, 如下:

var dooringOpts = { 
    container: '',  // 掛載到哪個dom節點上 
    iframeStyle: {  // iframe自定義樣式 
        width: '', 
        height: '', 
        border: '' 
    }, 
    controls: { 
      gallery: false,  // 是否啟動圖片庫 
      template: false, // 是否啟用模版庫 
      saveTemplate: true,  // 參數可以是true/false,表示是否啟動下載代碼, 也可以是函數, 用來自定義下載代碼邏輯 
      save: true,  // 參數可以是true/false,表示是否啟動下載代碼, 也可以是函數, 用來自定義下載代碼邏輯 
      downCode: true, // 參數可以是true/false,表示是否啟動下載代碼, 也可以是函數, 用來自定義下載代碼邏輯 
      isPhoneTest: false, 
      helpPage: true,   // false/true表示隱藏/顯示幫助頁面 
      uploadApi: '',  // 自定義上傳api 
      formApi: '',  // 自定義表單提交api 
      screenshotsApi: ''  // 自定義截圖提交api 
    } 

用戶只需要在全局定義好配置的 props 和 callback , 即可自由定制 H5-Dooring. 接下來我們只需要再引入 dooring-sdk即可(注意先定義全局變量, 再引入sdk):

<script src="http://49.234.61.19/dooring-sdk.js"></script> 

以上只是確定了 js-sdk 的方案和最終調用效果, 接下來我們來看看如何去實現它. 也就是 dooring-sdk 內部到底做了那些工作. 我們先看一張實現機制圖:

由上圖分析可知我們需要提前把用戶定義的全局配置解析成 url 參數, 然后將動態創建的 iframe 的 src 屬性設置為 dooring url + parmas的結構, 具體實現如下:

(function(){ 
      let iframe = document.createElement('iframe'); 
      let tid = Date.now(); 
      let sdk_domain_path = 'http://xxxx/xxxx'; 
      iframe.src = sdk_domain_path + '/h5_plus/editor?tid=' + tid + '&' + getDooringApiStr(dooringOpts) + '&isOpen=1'; 
 
      iframe.style.border = 'none'; 
      iframe.style.width = '100vw'; 
      iframe.style.height = '100vh'; 
      if(dooringOpts && dooringOpts.iframeStyle) { 
          iframe.style.border = dooringOpts.iframeStyle.border || 'none'; 
          iframe.style.width = dooringOpts.iframeStyle.width || '100vw'; 
          iframe.style.height = dooringOpts.iframeStyle.height || '100vh'; 
      } 
 
      document.querySelector(dooringOpts.container || 'body').appendChild(iframe); 
 
      function getDooringApiStr(opt) { 
          let controls = Object.assign({ 
              gallery: false, 
              template: false, 
              saveTemplate: true,  // 參數可以是true/false,表示是否啟動下載代碼, 也可以是函數, 用來自定義下載代碼邏輯 
              save: true,  // 參數可以是true/false,表示是否啟動下載代碼, 也可以是函數, 用來自定義下載代碼邏輯 
              downCode: true, // 參數可以是true/false,表示是否啟動下載代碼, 也可以是函數, 用來自定義下載代碼邏輯 
              isPhoneTest: false, 
              helpPage: true,   // false/true表示隱藏/顯示幫助頁面 
              uploadApi: '', 
              formApi: '', 
              screenshotsApi: '' 
          }, opt.controls || {}) 
 
          let params = ''; 
          for(let key in controls) { 
              params += key + '=' + encodeURI(controls[key]) + '&' 
          } 
          return params.slice(0, params.length -1) 
      } 
})() 

以上只是個簡單的實現實現思路, 是不是有點傳統的寫jquery插件的感覺? 同時我們還需要配合 h5-dooring 內部去支持解析 parmas 等操作, 這里感興趣的可以自行研究. 當然 sdk 的實現方式還有很多, 期待大家的探索.

最后

以上方案筆者已經集成到 H5-Dooring 中，大家可以以 sdk 的方式體驗一下。github 地址：所見即所得的H5頁面編輯器H5-Dooring