Socket 用戶端 (sails.io.js)
此文件章節是關於瀏覽器的 Sails socket 用戶端 SDK。它是以 JavaScript 撰寫，並且也可用於伺服器端。
也有一些社群專案實作了適用於原生 iOS、Android 和 Windows Phone 的 Sails/Socket.IO 用戶端。
概觀
Sails socket 用戶端 (sails.io.js) 是一個小型的瀏覽器函式庫，預設會捆綁在新的 Sails 應用程式中。它是一個輕量級的封裝器，位於 Socket.IO 用戶端之上，其目的是盡可能簡化從您的 Sails 後端發送和接收訊息。
sails.io.js 的主要職責是為使用 WebSockets/Socket.IO 與您的 Sails 應用程式通訊提供一個熟悉的、類似 Ajax 的介面。這基本上意味著提供 .get()、.post()、.put() 和 .delete() 方法，讓您能夠利用即時功能，同時仍然重複使用您應用程式其他部分所使用的相同後端路由。換句話說，在您的瀏覽器中執行 io.socket.post('/user') 將在您的 Sails 應用程式中以與對相同路由的 HTTP POST 請求完全相同的方式進行路由。
基本用法 (瀏覽器)
在瀏覽器中，使用 sails.io.js 所需的一切就是將該函式庫包含在 <SCRIPT> 標籤中。Sails 將該函式庫新增到所有新應用程式的 assets/js/dependencies 資料夾中，因此您可以寫入
<!--
This will import the sails.io.js library bundled in your Sails app by default.
The bundled version embeds minified code for the Socket.io client as well.
One tick of the event loop after importing this script, a new "eager" socket
will automatically be created begin connecting unless you configure it not to.
-->
<script type="text/javascript" src="/js/dependencies/sails.io.js"></script>
然後在後續的內聯或外部腳本中使用 io.socket 作為全域變數。如需日常使用的詳細說明和範例，請參閱 io.socket。
基本用法 (Node.js)
若要在 Node.js 腳本中使用 Sails socket 用戶端 SDK，您需要安裝並要求 sails.io.js 和 socket.io-client 函式庫
// Initialize the sails.io.js library with the socket.io-client module,
// which will automatically create and connect a new socket as io.socket
// unless you configure it not to.
var io = require('sails.io.js')( require('socket.io-client') );
請參閱 sails.io.js GitHub 儲存庫，以取得有關從 Node.js 使用 Sails socket 用戶端的更多資訊。
設定 sails.io.js 函式庫
本節重點介紹 JavaScript socket 用戶端最常見的執行階段環境：瀏覽器。請參閱
sails.io.jsGitHub 儲存庫，以取得有關設定 socket 用戶端以在 Node.js 腳本中使用的協助。
有兩種方法可以在瀏覽器中設定 Sails 的 socket 用戶端：使用 <script> 標籤上的 HTML 屬性，或以程式設計方式修改 io.sails 物件。
使用 HTML 屬性的基本設定
設定 socket 用戶端四個最常見設定 (autoConnect、environment、headers 和 url) 的最簡單方法是在 script 標籤上貼上一個或多個 HTML 屬性
<script src="/js/dependencies/sails.io.js"
autoConnect="false"
environment="production"
headers='{ "x-csrf-token": "<%= typeof _csrf !== 'undefined' ? _csrf : '' %>" }'
></script>
此範例將停用急切的 socket 連線，強制用戶端環境為「production」（這會停用日誌），並設定一個 x-csrf-token 標頭，該標頭將在每個 socket 請求中發送（除非被覆寫）。請注意，複合值 (如 headers 字典) 包裝在一對單引號中。這是因為以這種方式指定的複合值必須是 JSON 編碼，這表示它們的鍵名和值字串必須用雙引號括起來 (基於類似的原因，值字串中的字串用單引號括起來)。
可以作為 HTML 屬性提供的任何設定都可以選擇以 data- 作為前綴提供 (例如 data-autoConnect、data-environment、data-headers、data-url)。這是為了滿足需要支援對非標準 HTML 屬性有問題的瀏覽器 (或者如果您只是對使用非標準 HTML 屬性的想法感到不安) 的人們。如果同時提供了標準 HTML 屬性和以 data- 作為前綴的 HTML 屬性，則以後者為優先。
注意： 為了使用此方法設定 socket 用戶端，如果您使用的是預設的 Grunt 資產管道 (它會自動注入 script 標籤)，您需要從您的
pipeline.js檔案中移除sails.io.js，而是包含一個明確的<script>標籤來匯入它。
使用 io.sails 的程式化設定
從 Sails v0.12.x 開始，只有最基本的設定選項可以使用 HTML 屬性設定。如果您想要設定上面未提及的任何其他選項，您需要以程式設計方式與 io.sails 互動。幸運的是，上面描述的方法實際上只是執行此操作的便捷快捷方式！以下是它的運作方式
當您在 <script> 標籤中將其載入頁面時，sails.io.js 函式庫會等待一個事件迴圈週期，然後自動連線 socket (如果啟用了 io.sails.autoConnect，請參閱下文)。這允許在 socket 開始連線之前設定您在 io.sails 上指定的任何屬性。但是，為了確保在連線之前讀取 io.sails 屬性，您應該將設定這些屬性的程式碼放在包含 sails.io.js 的 <script> 標籤之後。
<script src="/js/dependencies/sails.io.js"></script>
<script type="text/javascript">
io.sails.url = 'https://myapp.com';
</script>
<!-- ...other scripts... -->
通常，socket 用戶端始終連線到提供腳本的伺服器。上面的範例將導致急切 (自動連線) 的 socket 嘗試 (跨網域) socket 連線到在 https://myapp.com 上執行的 Sails 伺服器，而不是連線到目前的伺服器。
注意： 如果您使用的是預設的 Grunt 資產管道 (它會自動注入 script 標籤)，最好從您的
pipeline.js檔案中排除sails.io.js，而是明確地為其新增一個<script>標籤。這可確保您的設定會在「急切」的自動連線 socket 開始連線之前套用，因為這表示您用於程式化設定 (例如，設定io.sails.url = 'https://myapp.com';) 的內聯<script>標籤會在 socket 用戶端之後立即執行。
進階用法
您也可以使用 io.sails.connect 手動建立和連線用戶端 socket。這會傳回 SailsSocket 的實例。如需關於較不常見和更進階的用例 (例如連線多個 socket) 的更多資訊，請參閱 SailsSocket。
進階設定
sails.io.js 函式庫及其個別的用戶端 socket 有一些設定選項。全域設定位於 io.sails 中，其中 (除其他外) 允許您停用「急切」socket 和新 socket 的預設設定。個別 socket 也可以在手動連線時設定 — 請參閱 io.sails.connect() 以取得更多相關資訊。
常見問題
我可以在 XYZ 前端框架中使用這個嗎？
可以。Sails socket 用戶端可以與任何前端框架完美搭配使用，無論是 Angular、React、Ember、Backbone、Knockout、jQuery、FishBerry 等等。
我必須使用這個嗎？
否。當在基於瀏覽器的 UI 中建置即時/聊天功能時，Sails socket 用戶端非常有用，但與 assets/ 目錄的其餘部分一樣，如果您正在建置 原生 Android 應用程式或完全沒有使用者介面的 API，則可能不是特別有用。
幸運的是，與 Sails 中的每個其他樣板檔案和資料夾一樣，socket 用戶端是完全可選的。若要移除它，只需刪除 assets/js/dependencies/sails.io.js。
這是如何運作的？
在底層，socket 用戶端 (sails.io.js) 發出具有保留名稱的 Socket.IO 訊息，當 Sails 解譯這些訊息時，會根據您應用程式的路由和藍圖設定將其路由到適當的政策/控制器/等等。
我該如何告訴我的 Sails 應用程式不要將 socket 與目前的瀏覽器工作階段連線？
預設情況下，socket 連線將使用初始 socket 交握時發送的 cookie 標頭連結到目前的瀏覽器工作階段 (如果有的話)。為了關閉此行為，請在 socket 連線之前，將 nosession=true 新增至 socket 的 query 屬性。例如
<script src="/js/dependencies/sails.io.js"></script>
<script type="text/javascript">io.sails.query='nosession=true';</script>
我可以繞過此用戶端並直接使用 Socket.IO 嗎？
可以繞過您的 Sails 應用程式中的請求解譯器，並直接與 Socket.IO 通訊。但是，不建議這樣做，因為這會破壞框架中其他地方使用的慣例優於設定的哲學。Sails socket 用戶端 (sails.io.js) 是非侵入式的：它的運作方式是封裝原生 Socket.IO 用戶端，並公開一個更高等級的 API，該 API 利用 Sails 中的虛擬請求解譯器來發送模擬 HTTP 請求。這使您的後端程式碼更具可重複使用性，降低了開發人員使用 WebSockets/Socket.IO 的門檻，並使您的應用程式更易於理解。
注意： 在極少數情況下 (例如，與直接使用 Socket.IO 的現有/舊版前端相容)，繞過請求解譯器是必要的。如果您發現自己處於這種情況，您可以使用 Socket.IO 用戶端、SDK，然後在後端使用
sails.io來存取原始 Socket.IO 實例。請僅在您具有直接使用 Socket.IO 的豐富經驗，且僅在您首先檢閱socketshook 的內部結構 (特別是「管理員匯流排」實作，這是一個 Redis 整合，位於 @sailshq/socket.io-redis 之上，並為 Sails 的多伺服器支援加入/離開房間提供支援) 時，才踏上這條路。
為了在 sailsjs.com 上獲得更好的體驗，請更新您的瀏覽器。
參考
- 應用程式
- 藍圖 API
- 命令列介面
-
設定
- sails.config.*
- sails.config.blueprints
- sails.config.bootstrap()
- sails.config.custom
- sails.config.datastores
- sails.config.globals
- sails.config.http
- sails.config.i18n
- sails.config.log
- sails.config.models
- sails.config.policies
- sails.config.routes
- sails.config.security
- sails.config.session
- sails.config.sockets
- sails.config.views
-
Request (`req`)
- req._startTime
- req.body
- req.cookies
- req.fresh
- req.headers
- req.hostname
- req.ip
- req.ips
- req.isSocket
- req.method
- req.options
- req.originalUrl
- req.params
- req.path
- req.protocol
- req.query
- req.secure
- req.signedCookies
- req.socket
- req.subdomains
- req.url
- req.wantsJSON
- req.xhr
- req.accepts()
- req.acceptsCharsets()
- req.acceptsLanguages()
- req.allParams()
- req.file()
- req.get()
- req.is()
- req.param()
- req.setLocale()
- req.setTimeout()
- req.host
- Response (`res`)
- Waterline (ORM)
- WebSockets
參考
用愛建置
Sails 框架是由位於德州奧斯汀的一家 網路與行動商店，在我們的貢獻者的幫助下建置的。我們在 2012 年建立 Sails，以協助我們進行 Node.js 專案。自然地，我們將其開源。我們希望它可以讓您的生活更輕鬆一點！
© 2012-2024 The Sails Company.
Sails 框架是免費且開源的，採用 MIT 授權條款。
插圖由 Edamame 提供。