XPages 裡其實有兩個 document,別改錯邊
你在 XPages 的 SSJS 裡寫 document1,心裡想的是「這份文件」。但嚴格講,document1 不是文件本身——它是 XPages 的 document data source,一個 NotesXspDocument 物件,是畫面與資料之間的那層包裝。
真正那份「後端文件」要用 document1.getDocument() 才拿得到,它是一個 NotesDocument——就是你在 agent、script library 裡熟悉的那個後端文件類別。兩個物件指向同一份 note,卻是兩套不同的 API:包裝這邊用 getValue / setValue,後端那邊用 getItemValue / replaceItemValue,而且各有各的 save。搞不清楚你手上是哪一個、或兩邊都去存,正是 XPages 存檔怪象的來源。
這篇只講後端那一個 NotesDocument:怎麼在 SSJS 拿到它、它能做什麼、它跟包裝的分界在哪。
重點摘要
document1是包裝,不是後端文件。它是NotesXspDocument(資料源);官方自己說,要「直接對資料庫動作」就用NotesDocument。- 後端文件用
document1.getDocument()拿,或完全不經過資料源,直接database.getDocumentByUNID(...)/view.getDocumentByKey(...)/database.createDocument()生出來。 - 兩套 API 別混:資料源用
getValue/setValue(綁定控制項的那層);後端NotesDocument用getItemValue/replaceItemValue、computeWithForm、save、remove、universalID——跟 LotusScript 的 NotesDocument 一模一樣。 - 存檔分界:要把整份資料源連同畫面輸入存回 →
document1.save();你拿了後端文件、要單獨存它 →doc.save()。不要兩個都呼叫。 - 最常見的坑:同一份文件上既
doc.save()(後端)又document1.save()(資料源),版本戳記對不上,Domino 就產出一份$Conflict存檔衝突文件。詳見下方與存檔衝突那篇。
兩個 document:包裝 vs 後端
先把名詞分清楚,後面才不會亂。
NotesXspDocument——XPages 的 document data source。官方定義:「Represents a document associated with the XPage context in which the server script is running.」一個 XPage 綁了 Domino document 當資料源時,就會有一個這型別的全域變數,叫document1、document2…;currentDocument指最近的那個。它負責的是畫面控制項與文件之間的綁定,所以它的getValue/setValue是走「這份資料源目前的狀態」。NotesDocument——後端文件。就是lotus.domino那套裡的 Document,你在 SSJS、Java、LotusScript 裡用的是同一套 API。它直接對應資料庫裡那份 note,沒有畫面綁定這回事。
官方在 NotesXspDocument 頁面講得很白:要「直接對 Domino 資料庫動作」,請用 NotesDocument。換句話說,資料源是給你接畫面用的方便層;要碰真正的文件,往下拿後端那個。
怎麼在 SSJS 拿到後端 NotesDocument
有兩條路,看你要不要經過資料源。
(1) 從現在這份資料源拿——最常見,你人在某個 XPage 的事件裡:
var doc:NotesDocument = document1.getDocument();getDocument() 的官方說明是「Gets the document as a NotesDocument object」。它還有一個帶參數的版本 getDocument(applyChanges):true 會先「apply any changes made to the data store」再回傳、false(預設)不套用。那個參數在「程式改了值又要馬上拿後端文件」時很關鍵,不過它屬於另一個主題——實際套用了什麼、什麼時候非加不可,見getDocument(true) 的 true 到底在做什麼,這裡不重講。
(2) 完全不經過資料源——你在 SSJS 裡要處理的根本不是當前這份,而是別份文件(查表、批次、跨庫):
var db:NotesDatabase = database; // 全域變數 databasevar doc:NotesDocument = db.getDocumentByUNID(unid);// 或用視圖查:var view:NotesView = db.getView("vwUsers");var doc2:NotesDocument = view.getDocumentByKey("USER_001");// 或開新文件:var newDoc:NotesDocument = db.createDocument();這條路拿到的就是純後端文件,跟 document1 沒關係,也不會動到畫面資料源。
後端文件能做什麼
拿到 NotesDocument 之後,它的方法就是你熟悉的那套後端 API(與 LotusScript 完全相同):讀值 getItemValue / getItemValueString、寫值 replaceItemValue、跑表單公式與驗證 computeWithForm、存檔 save、刪除 remove、拿識別 getUniversalID / getNoteID、判斷 isNewNote / isResponse。
一段完整的「取文件 → 改欄位 → 存檔」:
try { var view:NotesView = database.getView("vwUsers"); var doc:NotesDocument = view.getDocumentByKey("USER_001"); if (doc != null) { doc.replaceItemValue("Status", "Active"); doc.replaceItemValue("LastUpdated", session.createDateTime("Today"));
// computeWithForm(dodatatypes, raiseError):跑表單的預設值與驗證公式 if (doc.computeWithForm(true, false)) { doc.save(true, false); // save(force, makeResponse) print("更新完成,UNID=" + doc.getUniversalID()); } else { print("computeWithForm 驗證沒過"); } }} catch (e) { print("處理失敗:" + e.toString());}兩個參數值得記一下:save(force, makeResponse) 的 force 控制「別人同時改了同一份時要不要硬存」;computeWithForm(dodatatypes, raiseError) 的第二個參數決定驗證失敗時是丟例外還是回傳 false——上面用 false,所以自己檢查回傳值。
分界線:什麼時候用哪一邊
這是最容易出錯、也最該記住的一段。同一份 note,兩個物件、兩套存法:
| 你要做的事 | 用哪一個 |
|---|---|
| 讀/寫綁定控制項那層的值 | 資料源 document1.getValue / setValue |
| 讀/寫文件欄位本身 | 後端 doc.getItemValue / replaceItemValue |
| 存回「整份資料源+畫面輸入」 | document1.save() |
| 只存你手上這份後端文件 | doc.save() |
跑 computeWithForm、remove、拿 UNID | 後端 doc(資料源沒有這些) |
一句話:畫面綁定的事交給資料源,文件本身的事交給後端 NotesDocument。需要跨過去時,用 getDocument() 那座橋。
最常見的坑:兩邊都 save
分界沒守住,最典型的後果是存檔衝突。情境是這樣:頁面載入時,資料源 document1 記住了這份文件當下的版本戳記(sequence number)。你在 SSJS 裡 var doc = document1.getDocument() 拿到後端文件、呼叫了 doc.save()——磁碟上的版本已經被你更新了。接著 XPages 生命週期又觸發 document1.save(),資料源卻還拿著舊的戳記去寫,Domino 一比對發現磁碟上的比記憶體裡的新,就判定衝突、生出一份 $Conflict 文件。
避法就是守住分界:一份文件,只用一邊存。走畫面就全程 document1.setValue(...) + document1.save(),別再 doc.save();真要直接操作後端就 doc.save(),那就別再讓資料源去 save()。這個坑的完整重現與實測(含在 Domino 12.0.2 / 14.5.1 上跑過),見XPages 存檔衝突那篇。
同類別在其他語言
後端 NotesDocument 這個類別,跨語言幾乎是同一套——因為它本來就是同一個 lotus.domino.Document:
- LotusScript:
NotesDocument,db.GetDocumentByUNID、doc.ReplaceItemValue、doc.Save——方法名一樣,只差大小寫慣例與語法。 - Java:
lotus.domino.Document,db.getDocumentByUNID(...)、doc.replaceItemValue(...)、doc.save();Java 這邊多一件事要顧——用完要recycle()放掉記憶體,這點 SSJS / LS 不用。那個故事見 Java 的 NotesDocument 與欄位處理。 - SSJS 專屬的其實不是
NotesDocument本身,而是它上面多包的那層NotesXspDocument(資料源)——這層是 XPages 才有的,也是這篇要你分清楚的重點。
參考來源
- NotesXspDocument(XPages 的 document data source、取內層 Document、getValue / setValue / replaceItemValue / save)— HCL Domino Designer(官方)
- getDocument (NotesXspDocument - JavaScript)(取後端 NotesDocument、applyChanges 參數)— HCL Domino Designer(官方)
- NotesDocument class(後端文件類別,SSJS / Java / LotusScript 共用同一套 API)— HCL Domino Designer(官方)