#Tutorial
標記為 #Tutorial · 68 篇文章
- Domino Web View 翻頁的真相：Start 不是流水號，是階層座標
「我以為 Start=31 就是第 31 列，然後我錯了。」一篇 classic view ?OpenView Start 參數的除錯實測報告：純數字跳到第 N 個最上層分類、像 1.1.1.1.6 的點號值是階層座標、末段會 clamp 但中段不會、而你沒辦法用一個 URL 跳到絕對最後一頁。外加三個實用應用 —— 分類內序號、@DocNumber("")（含必須單獨使用的地雷）、以及用 ReadViewEntries 做麵包屑。
2026.07.23 - 你的 Domino view 表頭為什麼永遠歪一格：passthrough HTML 黑魔法考古
接手一個老 classic-web Domino view，你常會發現直欄標題整體往右偏一格 —— 而且沒人知道為什麼。一篇實測報告，挖出藏在二十年前 view 設計裡的 passthrough HTML 把戲：直欄值與標題裡的方括號 HTML、間隔欄、每列 checkbox，以及真正的元兇 —— 一個故意不閉合的 <input 標籤吞掉 </td><td> 欄界線、把兩個直欄合併成一格，讓它之後的每個表頭都往右偏。
2026.07.22 - DQL 跳「Domino Query 執行時錯誤」怎麼辦：三層診斷階梯
一個 DQL 查詢失敗，你看到「Domino Query 執行時錯誤:」後面接一大串文字。一篇讀懂這個訊息的實測報告：你在 Err 裡找到的 4854 對診斷毫無用處（每個 DQL 失敗都回它），答案永遠在「詳細原因」那一行。涵蓋四段訊息結構、三層階梯（catalog / view 沒建 / partial TIMEDATE）、讓查詢時好時壞的 design catalog 半殘、以及「0 筆且無錯誤」的排查清單。
2026.07.21 - DQL view 日期直欄查詢：型別與時區怎麼無聲吃掉你的結果（三個成因）
「直欄轉成日期反而有些抓得到有些沒抓到，蠻怪的。」一篇實測報告：一個 DQL view 直欄日期查詢結果不一致，拆開來發現有三個獨立成因。DQL 從不自動轉型（所以直欄的輸出型別要跟查詢詞相符）、底層欄位存了文字與日期混型、而 @dt 不帶時區位移就是 UTC——它會在不改變總筆數的情況下弄壞邊界文件。兩個解法皆實測 6/6 全中。
2026.07.20 - NotesXSLTransformer：用 LotusScript 以 XSLT 轉換 XML 與 DXL
NotesXSLTransformer 把 XSLT stylesheet 套到 XML 或 DXL 上、寫出轉換結果 — 是 Domino XML 工具組裡繼 DOM 與 SAX parser 之後的最後一塊。本文說明 session.CreateXSLTransformer 與它的三種來源、stylesheet 必須是 stream 的規則、把 DXL export → 轉換 → import 串起來而不落暫存檔的 pipelining 模型、以及那個透過 Log 屬性與 On Error（而非事件）運作的錯誤處理。
2026.07.19 - NotesJSONNavigator：LotusScript 原生 JSON 解析，不必再做字串手術
在 Domino 10.0.1 之前，用 LotusScript 解析 JSON 意味著 Evaluate 花招或手刻的字串手術。NotesJSONNavigator 用一個真正的 parser 取代了那些：session.CreateJSONNavigator 給你一棵可用 GetElementByName、GetNthElement、JSON Pointer 路徑導覽的型別化樹。本文說明 navigator、element/object/array 類別、型別常數，以及命名上的意外（是 GetFirstElement 不是 GetFirstItem；AppendElement 是 value 在前 name 在後）。
2026.07.18 - 用程式管理全文索引：CreateFTIndex、UpdateFTIndex，與本機 vs 伺服器的分界
FTSearch 要快、要能用萬用字元與相關性排序，就需要全文索引 — 而 NotesDatabase 能用 LotusScript 建立、更新、移除索引。陷阱是一個幾乎沒人料到的分界：CreateFTIndex / UpdateFTIndex / RemoveFTIndex 只對本機資料庫有效，而 FTIndexFrequency 只對伺服器有效，伺服器索引其實是由 Updall 工作管理的（updall -X 是重建、不是建立）。本文說明 options bitmask、create 與 update 的差別、以及那個分界。
2026.07.17 - LotusScript 的文件鎖定：Lock、LockProvisional，與每個人都忘記的前置條件
Domino 能鎖定一份文件、讓兩個使用者不會同時編輯它 — NotesDocument 上的 Lock、LockProvisional、UnLock、LockHolders。但這些方法會拋錯，除非資料庫啟用了鎖定（IsDocumentLockingEnabled）而且設好了 master lock server；persistent 與 provisional 鎖取決於那台伺服器是否可達；而鎖在 web 應用裡根本不能用。本文說明 API 與每個前置條件。
2026.07.16 - NotesDocument.ComputeWithForm：用程式跑表單驗證 — 以及為什麼它擋不住你的 Save
ComputeWithForm 把表單的預設值、輸入轉換、輸入驗證公式跑在後端文件上 — 相當於使用者在表單上按存檔時觸發的驗證。但三件事會讓人意外：它回一個它從不強制執行的通過/失敗旗標（它照樣讓你把無效文件存進去）、輸入轉換公式可能改寫你的欄位值、而且除非你釘住 Form item、它會悄悄退回預設表單。
2026.07.15 - LotusScript 的回應文件：MakeResponse、ParentDocumentUNID，與遍歷整棵串
Domino 的父子文件階層 — 主文件、回應、回應之回應 — 用幾個 NotesDocument 成員就能建立與遍歷。本文說明 MakeResponse（以及你必須在它之後呼叫的 Save）、用 ParentDocumentUNID 往上走到父文件、以及 Responses 屬性那個關鍵限制：它只回傳直接子文件 — 所以完整的樹需要遞迴。
2026.07.14 - NotesDateTime 與時區：GMTTime、ConvertToZone，與那個絆倒每個人的正負號慣例
一個 NotesDateTime 是單一個瞬間，你可以用三種方式讀出來 —— GMT、機器的本地時間、以及轉換後的時區。本文說明 GMTTime vs LocalTime vs ZoneTime、TimeZone 整數那個反直覺的 Notes 正負號慣例（正值代表 GMT 以西）、ConvertToZone 與它的 DST 陷阱、用 LSGMTTime 做原生日期運算，以及為什麼 GMTTime 是唯一能跨機器安全儲存與比較的形式。
2026.07.13 - 用 LotusScript 簽章與加密文件：Sign、Encrypt，與 Save 的順序規則
Domino 能簽章一份文件以證明是誰寫的、能加密 item 讓只有持金鑰的人讀得到 —— 兩者都能用 LotusScript 做、也都有陷阱。本文說明 NotesDocument.Sign 與它在伺服器 agent 需要的權限、Encrypt 那個必要的「標記 item / Encrypt / Save」順序、逐 item 選擇性加密，以及為什麼 EncryptOnSend 跟「加密儲存的副本」是完全兩回事。
2026.07.12 - Profile documents：Domino 的快取式設定儲存區，以及那個快取為什麼會咬人
profile document 是一份隱藏、在 view 裡看不到、以名稱（與可選的使用者）為鍵的文件 —— 很適合放應用設定與個人偏好，而且因為有快取所以很快。本文說明 GetProfileDocument、IsProfile / NameOfProfile / Key 屬性、透過 unique key 做個人化 profile，以及快取造成的陷阱：另一個程序的寫入可能對你已開啟的 session 看不見，而且沒有 refresh API 能強制重讀。
2026.07.11 - 用程式做 Readers 與 Authors 欄位：靠一個 NotesItem 旗標設定的文件層級安全
Domino 的文件層級存取控制不是什麼特殊 API —— 它就是一個帶旗標的普通 item。本文說明怎麼在 LotusScript 用 ReplaceItemValue 加上 NotesItem.IsReaders / IsAuthors 建立 Readers 與 Authors 欄位、安全模型（沒有 Readers item = 所有人可見；有 Readers item = 只有列出的人）、以及鎖死陷阱：把自己和 agent 漏在清單外，你會把一份文件對所有人藏起來，包括產生它的那段程式。
2026.07.10 - 多層分類 view 裡的 GetAllDocumentsByKey：為什麼你的 count 悄悄就錯了
在單層分類 view，GetAllDocumentsByKey('Belgien', True) 正確回傳那個分類下的 2 筆文件。但加上第二層分類 — Form 再 Country — GetAllDocumentsByKey('Customer', True) 回傳 3，不是全部。它停在第一個子分類就不走了。本文記錄這個實測驗證過的陷阱與繞法。
2026.07.09 - NotesStream 與文字編碼：字元集、BOM，與位元組 vs 字元的陷阱
NotesStream 讀寫檔案，但只要你的文字不是純 ASCII，三件事就會咬人：你用哪個字元集開的、有沒有寫進 BOM，以及 Position 是位元組位移、而且「不支援多位元組字元」。本文說明 Open 的字元集參數、EOL 常數、WriteText 到底何時寫 BOM（UTF-16 會、UTF-8 不會），以及為什麼 Bytes 永遠不等於 Len()。
2026.07.08 - LotusScript 處理附件：EmbedObject、NotesEmbeddedObject 與 GetAttachment 捷徑
附加一個檔案、列出附了什麼、把它抽取到磁碟、再移除它 —— 全部用程式做。本文說明 NotesRichTextItem.EmbedObject 搭配 EMBED_ATTACHMENT 常數、NotesEmbeddedObject 類別、ExtractFile，以及兩個絆倒人的陷阱：NotesDocument.EmbeddedObjects 不會回傳檔案附件（要用 GetAttachment 或 rich text item），而 ExtractFile 對非附件的東西會出錯。
2026.07.07 - LotusScript 裡的 XML 宣告、DTD 節點與 SAX 錯誤
Domino DOM 裡很少見的那一層 —— XML 宣告、DOCTYPE、processing instruction、notation、entity —— 加上 SAX 那一側的 NotesSAXException。本文說明每個節點實際給你什麼（多半：沒什麼）、你必須先設好才看得到宣告的 AddXMLDeclNode 旗標，以及為什麼 NotesSAXException 是解析出錯時唯一能拿到含行列號豐富錯誤資料的地方。
2026.07.05 - 承載內容的 DOM 節點：LotusScript 的 TextNode、AttributeNode、Comment、CDATASection
當你開始巡覽解析後的 DOM，真正的資料住在內容節點裡 —— 文字、屬性、註解、CDATA。本文說明繼承關係（CharacterData 是 Text/Comment/CDATA 的基底；CDATA 衍生自 Text；AttributeNode 自成一格）、CharacterData 的編輯方法，以及最大的陷阱：LotusScript 繫結是透過 NodeValue 讀內容 —— 沒有 W3C 風格的 Data、Length、Name 或 Value 屬性。
2026.07.04 - 用 LotusScript 巡覽解析後的 XML DOM：DocumentNode、ElementNode、NodeList、NamedNodeMap
NotesDOMParser 把 XML 解析完之後，你用一組節點類別來導覽結果。本文說明怎麼從 domParser.Document 取得根、用 DocumentElement 抵達根元素、用 GetElementsByTagName 查詢（回傳 NotesDOMNodeList）、透過元素的 NamedNodeMap 讀屬性，以及 LotusScript 特有的眉角：GetItem 是 1-based、沒有 ChildNodes 屬性（用 FirstChild/NextSibling 走）、也沒有 GetItemByName。
2026.07.03 - NotesRichTextDocLink 與 NotesRichTextSection：用程式做 doclink 與摺疊區段
兩個你平常會在 Designer 裡手動插入的 rich-text 功能 —— 跳到資料庫／view／文件的 doclink，以及可摺疊區段 —— 都能用程式做。但這兩個類別都不是你 New 出來的：你透過 NotesRichTextItem（AppendDocLink、BeginSection/EndSection）建立元件，再透過 NotesRichTextNavigator 讀回來。本文說明這個「寫用一套 API、讀用另一套」的拆分、doclink 屬性、BeginSection/EndSection 規則，以及陷阱。
2026.07.02 - NotesRichTextParagraphStyle、NotesRichTextTab 與 NotesColorObject：用程式排版 rich text
用 LotusScript 產 rich text 不只是接字串 —— 邊界、對齊、行距、tab 停點、顏色都是你在「加文字之前」蓋上去的獨立物件。本文說明 NotesRichTextParagraphStyle（版面）、NotesRichTextTab（tab 停點，由 style 唯讀生出）、NotesColorObject（色彩運算）、twips 度量、「先蓋 style 再加文字」規則，以及那個不直覺的點：NotesColorObject 不會直接幫文字上色 —— 你是用它推算出一個 Domino 色值。
2026.07.01 - NotesInternational：別再寫死日期分隔符號和貨幣符號
NotesInternational 是一扇唯讀的窗，讓你看見程式所在那台機器的地區設定 —— 日期順序、分隔符號、上午/下午字串、貨幣符號與格式、時區、以及 DST 旗標。本文說明怎麼從 session.International 取得、值得知道的屬性分組、一段偵測地區日期順序的可跑範例，以及三個陷阱：它反映的是執行端 OS（不是終端使用者）、它是唯讀的、而它的 TimeZone 正負號是經典又反直覺的 Notes 慣例。
2026.06.30 - NotesAdministrationProcess：用 LotusScript 送出 AdminP 請求
改使用者名稱、乾淨地刪除一個使用者、重新認證、搬移郵件檔、改 Internet 密碼 —— 這些平常你會在 Administration 用戶端點來點去的 AdminP 工作，NotesAdministrationProcess 讓你用程式把同樣的請求送進 admin4.nsf。本文說明 session.CreateAdministrationProcess、各請求方法與它們回傳的 note ID、certifier 屬性，以及三個最常絆倒人的點：它需要 unrestricted 權限、它是非同步的、而 '*' 代表「不變更」。
2026.06.29 - NotesTimer：在 Notes client 裡每隔幾秒觸發一次事件
想在 Notes client 開著的畫面上每隔幾秒做一件事 — 自動刷新 view、輪詢有沒有新信、更新一個狀態顯示？NotesTimer 就是這個：建立時給一個秒數間隔，它就週期性觸發 Alarm 事件。本文拆解建立、Interval / Enabled / Comment 屬性、用 On Event 綁事件處理，以及四個一定要知道的限制：只能在 UI 不能在 agent、要宣告在全域、handler 必須在間隔內跑完、預設就是啟用。
2026.06.28 - NotesViewColumn：用程式讀一個 view 有哪些欄、各自的公式與排序
你想盤點一個 view 有哪些欄、每欄是欄位還是公式、有沒有排序或分類、哪些被隱藏 — 不用開 Designer，用 NotesViewColumn 就能在程式裡讀出來。本文拆解從 view.Columns 取得、Title / ItemName / Formula / Position / IsSorted / IsCategory / IsHidden / IsField / IsFormula 等屬性，以及它跟先前 NotesViewEntry 的 ColumnValues 怎麼對應（同一個 Position 索引）。
2026.06.26 - NotesRichTextTable：在程式裡往 rich text 塞一個表格
你在程式裡用 NotesRichTextItem 組一封 rich text 信或文件，需要一個表格來排版摘要或報表 — NotesRichTextItem.AppendTable 建出來的就是 NotesRichTextTable。本文拆解怎麼建立、RowCount / ColumnCount、AddRow / RemoveRow、SetColor / SetAlternateColor 交替色、RightToLeft，以及怎麼用 NotesRichTextNavigator 走訪既有表格與一個關鍵限制：不知道 rich text 的確切結構，就讀不出儲存格內容。
2026.06.24 - NotesDXLImporter：把 DXL 灌回 Domino，設計元素 / 文件 / ACL 各有匯入策略
你用 NotesDXLExporter 把設計或文件匯出成 DXL（Domino XML）之後，怎麼把它灌回資料庫？NotesDXLImporter 就是反向那一半。本文拆解它的建立、三個關鍵匯入策略（DesignImportOption / DocumentImportOption / ACLImportOption 各自的 create / ignore / replace / update）、Import 方法與取回匯入 note 的方式，以及它跟 DXLExporter 怎麼組成完整的 DXL round-trip。
2026.06.23 - NotesViewEntry × NotesViewEntryCollection：不開文件就高效讀 view 的每一列
要把一個 view 裡每份文件的某些欄位值讀出來，很多人迴圈跑文件、逐筆 GetItemValue — 但那會把每份文件都打開，幾千筆就很慢。NotesViewEntry 讓你直接讀 view 已經算好的 ColumnValues、完全不開文件；NotesViewEntryCollection 是這些列的集合，還能跳過分類/總計列、做集合運算與 StampAll 批次蓋章。本文拆解這對「高效讀 view」的搭檔、ColumnValues 的效能關鍵、entry 的身份與階層屬性。
2026.06.22 - 開發者很少注意的 ODS：Domino 資料庫格式版本演進，與「什麼時候會升、由什麼決定」
你整天寫 LotusScript / XPages，大概從來沒在意過資料庫的 ODS（on-disk structure）版本 — 直到某個功能（像 LargeSummary）需要特定 ODS，或你把一顆舊 DB 在 server 之間搬動，搞不清楚 ODS 會不會跟著變。本文從開發者角度整理 ODS 的版本對應、最反直覺的一點（升 server 版本不等於升 ODS），以及 ODS 到底「什麼時候會變、由什麼決定」，最後回答一個具體情境：R9 的 ODS51 資料庫用 R12 client 新複製到 R12 server，ODS 會自動異動嗎？
2026.06.21 - 「Field is too large (32K)」在騙你：真正的牆通常是 64K summary buffer
一個 XPages 存檔錯誤：訊息寫「32K」，但你檢查每個欄位都沒破 32K（最大才 26K），照樣存不了。因為它指的數字常常不是你的問題 — 真正撞到的是「整份文件 summary 資料合計 64K」這道牆。本文先建立 summary / non-summary 與兩道大小限制的心智模型，再講 ODS 與 LargeSummary 為什麼是兩件事，最後用「這資料該不該是 summary」這個問題分流出兩種解法。
2026.06.21 - LotusScript 的 Evaluate：在程式裡直接跑 @formula
有時候你心裡那個剛好的工具是一個 @function — @Name、@Unique、@Explode、@DbLookup — 但你人在 LotusScript 裡。Evaluate 就是那座橋：把 @formula 當字串丟進去、在程式裡執行、拿回結果。本文拆解兩種呼叫形式（帶不帶 document context）、一個一定會踩的陷阱（回傳值永遠是陣列），以及哪些 @function 不支援（@Command、@Prompt、@PickList 等 UI 類）。
2026.06.20 - NotesRichTextStyle：在程式裡設定粗體、字級、顏色（兼談 STYLE_NO_CHANGE）
你在程式裡用 NotesRichTextItem 組 rich text，想讓某段變粗體、放大、換顏色 — 那個「樣式」就是 NotesRichTextStyle。本文拆解它怎麼建立、Bold / Italic / FontSize / NotesColor 等屬性、用 AppendStyle 與 SetStyle 套用，以及一個關鍵設計：新建的 style 所有屬性預設都是 STYLE_NO_CHANGE（不更動），你只需要設你想改的那幾個、其餘維持原樣。
2026.06.19 - NotesNewsletter：把一堆文件變成一封含 doclink 的摘要信
你想做一個「每日摘要」或「搜尋結果通知」 — 把符合條件的一堆文件，整理成一封信寄給使用者，信裡每一筆都能點回原文件。這正是 NotesNewsletter 的工作：吃一個 NotesDocumentCollection，用 FormatMsgWithDoclinks 產生一封含 doclink 的摘要信，或用 FormatDocument 逐筆渲染。本文拆解它的建立、DoScore / DoSubject / SubjectItemName 屬性、兩個 Format 方法的差別，以及搭配 FTSearch 的經典寄信範例。
2026.06.18 - NotesDbDirectory：列出 server 上的每一個資料庫
想寫一支 agent 掃過伺服器上所有 NSF、檢查每個 db 的 ACL 或大小？那是 NotesDbDirectory 的工作 — 別跟先前介紹過的 NotesDirectory（查 Domino Directory 裡的人與群組）搞混，兩個都叫 Directory 但做的事完全不同。本文拆解 GetDbDirectory 建立、GetFirstDatabase / GetNextDatabase 走訪、四個 file-type 常數、Open / CreateDatabase / OpenDatabaseByReplicaID 等方法，以及最容易中的坑：走訪拿到的 NotesDatabase 預設是「關閉」的，必須先 Open 才能用。
2026.06.14 - NotesAgent：用程式呼叫另一支 Agent（Run vs RunOnServer）
你有一支很重的處理 agent，想讓另一支 agent、或一個按鈕在需要時觸發它 — 不是用排程、是用程式直接叫起來。NotesAgent 就是做這件事的類別：db.GetAgent() 拿到 agent，再用 Run 或 RunOnServer 跑它。本文拆解這兩個方法最關鍵的差異（在 client 跑還是在 server 跑）、怎麼用 noteID 把一份文件傳給被呼叫的 agent、IsEnabled / Trigger / Target 等屬性，以及四個限制：不能遞迴、不能 debug、使用者不能互動、輸出只進 Domino log。
2026.06.12 - NotesRichTextNavigator × NotesRichTextRange：用程式走訪與改寫 Rich Text
你有 500 份文件的 Body 欄位，要找出每一個 doclink、或把某個字串全部換掉 — 光靠 NotesRichTextItem 拿到整個欄位還不夠，你需要更細的工具。NotesRichTextNavigator 讓你依「元素型態」一個一個走訪 rich text，NotesRichTextRange 讓你選定一段、然後套樣式或刪除。本文拆解這兩個 Release 6 起的搭檔、element-type 常數、FindAndReplace 的選項與回傳值，以及一個踩了就 debug 半天的鐵則：FindAndReplace 之後所有 navigation marker 全部失效。
2026.06.11 - NotesUIWorkspace × NotesUIDocument：LotusScript 的前端自動化
站上前面拆過的 NotesDatabase、NotesDocument 都是後端類別 — 但當你要在使用者按下按鈕的當下、讀他「螢幕上還沒存檔」的欄位值、跳一個對話框問他、或把當前文件切到編輯模式，靠的是另一半：NotesUIWorkspace 與 NotesUIDocument。本文拆解這組前端雙人組、最關鍵的「前端值 vs 後端 Document」觀念、FieldGetText/FieldSetText、Prompt 與 PickList 對話框，以及一個最容易忘的鐵則：UI class 不能在背景 / 排程 agent 裡跑。
2026.06.10 - NotesName：別再用字串切 Domino 階層名稱
要從 CN=王小明/OU=Sales/O=Acme/C=TW 取出「王小明」，你還在用 Mid、InStr、@Name 硬切字串嗎？NotesName 是 Domino 內建的名稱解析類別 — session.CreateName() 一句，就能在 canonical、abbreviated、common、Internet（RFC 821/822）各種格式間互轉，並逐段拆出 O / OU / C / G / S 等元件。本文拆解全部唯讀屬性、三種格式互轉、flat name 與 Internet 名稱的行為差異、以及「abbreviation 會有歧義時不縮寫」這個容易忽略的規則。
2026.06.09 - Nomad 定位三件組：NotesGPS / NotesGPSPosition / NotesGPSCoordinates
傳統 LotusScript 沒有定位 API — 但跑在 HCL Nomad 上的 app 其實拿得到使用者的經緯度。NotesGPS 是 Domino 為 Nomad 補上的客戶端定位類別，從 NotesSession.CreateGPS() 起手，經 RequestAccess() 取得授權、GetCurrentPosition() 拿到 NotesGPSPosition、再從 Coordinates 讀出 NotesGPSCoordinates 的 Latitude / Longitude。本文拆解這條三類別鏈、官方範例逐行解說，以及 error 4508、iOS 首呼叫 Speed/Heading 為空、HighAccuracy 室內失準等幾個一定要知道的坑。
2026.06.08 - NotesLog：LotusScript Agent 的 Production Logging
LotusScript 的 Print 語句只在 Designer debug 視窗出現、production agent 跑完沒有任何紀錄。NotesLog 是 Domino 內建的 logging class — 可以把 action 跟 error 記到 agent log、指定 NSF、或寄郵件。本文拆解四種 Open 方式（OpenAgentLog / OpenFileLog / OpenMailLog / OpenNotesLog）、LogAction 跟 LogError 的呼叫格式、NumActions / NumErrors 計數、OverwriteFile 控制是否覆蓋、跟一個可以直接拿來用的 production agent logging 範本。
2026.06.07 - NotesReplication + NotesReplicationEntry：用 LotusScript 管理資料庫複製設定
Domino 的複製（Replication）是讓多台伺服器資料同步的核心機制，每個 NSF 都有一份複製設定。LotusScript 的 NotesReplication class 讓你用程式讀寫這份設定 — 暫停 / 恢復複製、調整優先等級、設定截止日期過濾、清除複製歷史。NotesReplicationEntry 則管理「這個 NSF 跟哪台伺服器之間的複製規則」。本文拆解取得方式（db.ReplicationInfo）、IsDisabled / Priority / Abstract 屬性、ClearHistory 清歷史、GetEntry 取特定伺服器對的規則、以及 Save 呼叫的必要性。
2026.06.06 - NotesDirectory + NotesDirectoryNavigator：LotusScript 查詢 Domino 目錄
Domino 目錄（Domino Directory）是整個 Notes 環境的使用者資料庫 — 人員、群組、伺服器都在裡面。LotusScript 的 NotesDirectory 提供高層次的查詢 API（不需要自己開 names.nsf 走 view）。本文拆解取得方式（session.GetDirectory）、LookupNames 依名稱查詢指定欄位、LookupAllNames 掃全部、GetMailInfo 取郵件伺服器資訊、CreateNavigator 建立 NotesDirectoryNavigator 走訪快取結果、以及 SearchAllDirectories / LimitMatches 兩個影響效能跟結果數量的屬性。
2026.06.05 - NotesMIMEEntity + NotesMIMEHeader：LotusScript 解析郵件 MIME 結構
Domino 收到的郵件是 MIME 多層巢狀結構 — HTML body、純文字備用、附件、inline image 各自是不同的 MIME entity。LotusScript 用 NotesMIMEEntity 代表每一個節點、NotesMIMEHeader 代表節點的 header 欄位。本文拆解取得方式（session.ConvertMIME = False 的必要性）、ContentType / ContentSubType 識別 MIME 類型、GetFirstChildEntity + GetNextSibling 走訪 MIME 樹、GetContentAsText 取出文字內文、GetNthHeader / GetSomeHeaders 讀取 header 值、CreateMIMEEntity 從頭建立 MIME 郵件、以及 body 跟 attachment 的實戰辨別方法。
2026.06.04 - NotesCalendar：LotusScript 讀寫 Domino 行事曆的三個 Class
Domino 行事曆資料不是放在一般文件裡、而是用結構化的 iCalendar 格式存在 mail.nsf。LotusScript 提供三個 class 處理這層結構：NotesCalendar（行事曆物件本身）、NotesCalendarEntry（單一行事曆項目）、NotesCalendarNotice（會議邀請通知）。本文拆解取得方式（session.GetCalendar 傳入 mail.nsf）、CreateEntry 寫入 iCalendar 格式的字串、ReadRange 批次讀取時間段內的項目、GetNewInvitations 取得未處理邀請、NoticeAction 接受/拒絕邀請、跟幾個一定會踩的坑（ConvertMIME 必須設 False、行事曆文件不能當一般 NotesDocument 操作）。
2026.06.03 - NotesDocumentCollection：LotusScript 文件集合的完整操作指南
幾乎每個 Domino agent 最後都會回傳一個 NotesDocumentCollection — 但多數程式碼只用到 GetFirstDocument / GetNextDocument 就停了。本文完整拆解這個 class：七種取得 collection 的方式、走訪四個方向（First / Next / Prev / Last / Nth）、集合運算三劍客（Intersect / Merge / Subtract 都是直接改原物件）、StampAll 批次寫值跟走訪中修改的陷阱、RemoveAll force 參數的並發語意、以及 FTSearch 縮減 + 集合運算的接力模式。
2026.06.02 - NotesRegistration：用 LotusScript 自動化使用者註冊
Domino 管理員每天都會收到新人報到、離職、留停的通知 — 一筆一筆在 Admin Client 點滑鼠很快就成為時間殺手。NotesRegistration 是 LotusScript 內建解法、把使用者註冊 / 認證 / ID 檔管理整套搬進可程式化的世界。本文從人事系統觸發的實務場景切入、拆解 RegisterNewUser 的 14 個參數、必要的屬性 setup、跟伺服器權限的關係、跟批次處理的範例。
2026.05.30 - db.Search：用 @Formula 暴力搜尋 — 不需要 index 的那條路
NotesDatabase.Search 是 LotusScript 第二種搜尋機制 — 不靠 full-text index、靠 @Formula 在每一份文件上跑判斷式。本文拆解三個參數（formula / dateTime / maxDocs）跟 FTSearch 不一樣的語意、為什麼回傳 unsorted collection、dateTime 怎麼當作增量處理的 cursor、maxDocs=0 是真的「不限」（不像 FTSearch 預設 5000 上限）、formula 裡哪些 @function 不能用（UI 互動類 / lookup 類）、Stamp 改完 collection 不會 refresh 的陷阱、跟 production-ready 增量 agent 範例。三部曲第二篇、續篇會把這個跟 FTSearch / DQL 三選一比較。
2026.05.28 - FTSearch：Domino 全文檢索的三層 API（NotesDatabase / NotesView / NotesDocumentCollection）
FTSearch 是 Domino 三個 class 都有的方法 — 三個層級回傳不同型別、語意各異。本文拆解 NotesDatabase.FTSearch（回傳新的 collection）、NotesView.FTSearch（直接過濾 view 本身、回傳 Long 計數）、NotesDocumentCollection.FTSearch（直接縮減 collection 本身、無回傳）三者差異、sortopt 與 options 常數、query syntax operators 速查、CreateFTIndex 的 5 個 options bitmask、跟 `load updall -x` 的對應、沒建 index 時 method 還會跑（只是降速）、5000 doc 預設上限、wildcard `*` 只能放 term 結尾、operators 必須大寫等實戰陷阱。三部曲第一篇、後續會接 db.Search 跟三選一決策篇。
2026.05.27 - LotusScript 把 NotesView 匯出 Excel：四條路、CSV 預設、何時要升 POI
「把這個 view 匯出 Excel 給 user」是 Domino 圈最常被問的需求之一。四條路 — CSV via NotesStream（推薦預設）、HTML-as-xls（舊版格式技巧）、OLE Excel.Application（僅 client 端臨時用）、Apache POI via Java agent（正式環境級 .xlsx） — 各有適用場景。本文整理四條路的取捨表、CSV 完整實作（含 UTF-8 BOM、CSV escape、用 NotesViewNavigator 加速 5-10x）、HTML-as-xls / OLE / POI 的何時用何時不該用、Web download 模式、跟三個常見坑（BOM 漏寫、escape 不對、用 GetFirstDocument 而不是 ViewNavigator）。
2026.05.26 - NotesDateTime + NotesDateRange：LotusScript 日期時間處理的雙人組
Domino code 裡最常摸到的 utility class 之一 — NotesDateTime 代表單一時間點、NotesDateRange 代表一段時間區間。本文整理建立方式（New 跟 session.CreateDateTime 差別）、三組時區屬性（Local / GMT / Zone）的正確用法、6 個 Adjust 方法做日期算術、TimeDifference vs TimeDifferenceDouble 的精度差異、ConvertToZone 直接改物件本身、不是回傳新物件、NotesDateRange 的 4 個 property（沒有任何 method）、SetAnyDate / SetAnyTime 是搜尋 wildcard 用、跟 NotesItem.DateTimeValue 互動的 timezone 陷阱、跟兩個實戰範例（期限檢查 agent + 跨時區會議排程）。
2026.05.25 - NotesJSONArray / Element / Object：LotusScript parse + build JSON 的三個組成元件
之前發佈過的 lotusscript-http-json 介紹了 NotesHTTPRequest + NotesJSONNavigator 把『打 REST API 拿 JSON』完整收進 LS。本篇接續寫 navigator 下面的 3 個組成元件 — NotesJSONElement（name/value pair）、NotesJSONObject（物件節點）、NotesJSONArray（陣列節點）— 詳細 method、屬性、parse 時怎麼走整棵樹、反向 build JSON 怎麼用 Append* 系列 + Stringify、64K 限制版本敏感的三層解法（含 10.0.1 FP2 SPR# DCONB8VMAV / ASHEB95LFR 修補、跟 14.5 還活著的 element value > 64K 隱形地雷），跟一個完整 round-trip 範例（POST 出去 + parse 回應）。
2026.05.24 - NotesLLMRequest：4 行 LotusScript 把 LLM 接進 Domino app
Domino 14.5 引入 NotesLLMRequest / NotesLLMResponse 兩個 LotusScript class，把 LLM 推論能力以同步 API 形式給 app 開發者。本篇實戰：session.CreateLlmRequest() 工廠方法、Completion 三參數簽名、CompletionStream 串流模式、IsCommandAvailable / GetAvailableCommands 防禦性檢查、NotesLLMResponse 的 Content / FinishReason / Role 三個欄位。為什麼 API 設計用 commandName 而不是直接吃 prompt — Command document 抽離讓 admin 跟 dev 各自控制自己那層。附自動回信 + 摘要兩個實戰範例、跟 Java 對位 LLMReq / LLMRes。
2026.05.23 - NotesOutline / NotesOutlineEntry 全攻略 — Domino UI 導覽控件的程式化建構、4 種 entry type、24 個 property
NotesOutline 是 Domino 應用程式的左側 / 上方導覽控件，由 NotesOutlineEntry 條目以樹狀組成。透過 LotusScript 可以動態建立、修改、走訪 outline — 典型 use case 是多語切換（依 user locale 動態改 Label）、條件式 menu（依 role 顯示／隱藏）、動態使用者連結。本文整理 NotesOutline ↔ NotesOutlineEntry 關係、8 個 tree-walking 方法、6 個 manipulation 方法、24 個 entry property、4 個 Set* 方法、4 種 entry type 常數、9 個 EntryClass 常數、完整 CRUD 範例、五個踩雷點，跟 Java / SSJS 對照。
2026.05.20 - NotesDOMParser 全攻略 — XML 整棵樹載入記憶體、14 個 Node 類別、走訪／修改／序列化
NotesDOMParser 把 XML 整棵載入記憶體蓋成 DOM 樹、用 NotesDOMDocumentNode 當 root、配 14 個 Node 子類別代表不同 XML 元素（Element / Text / Attribute / Comment / CDATA 等）。可任意走訪、可修改、可 Serialize 回 XML。本文整理 DOM 樹結構概念、CreateDOMParser 初始化、14 個 Node class 關係表、NotesDOMNode 的 tree-walking API（FirstChild / NextSibling / NodeType）、完整 parse → walk → modify → serialize 範例、五個踩雷點，跟 Java/SSJS 對照。
2026.05.17 - NotesSAXParser 全攻略 — LotusScript 串流式 XML 解析、12 個 SAX 事件、On Event 綁定模式
NotesSAXParser 用 SAX（Simple API for XML）事件驅動模式處理 XML — 不把整份檔案載入記憶體、而是邊讀邊觸發 SAX_StartElement / SAX_Characters / SAX_EndElement 等 12 個事件。大檔案 / 只讀特定 element / 記憶體吃緊場景的首選。本文整理 SAX vs DOM 的本質差異、CreateSAXParser 初始化、On Event 綁定機制、12 個事件的觸發時機、NotesSAXAttributeList 怎麼拿 attribute、完整 LotusScript 範例、五個踩雷點，跟 Java / SSJS 對照。
2026.05.16 - NotesACLEntry 全攻略 — Domino 資料庫存取控制的程式化管理、7 個 access level、20 個 property、Roles 機制
NotesACLEntry 代表 Domino 資料庫 ACL 裡的單一條目（個人、群組或 server）。本文整理 NotesACL ↔ NotesACLEntry 容器關係、拿到 ACL 跟 entry 的三種途徑、7 個 access level 常數、UserType 跟 IsPerson/IsGroup/IsServer 三組旗標、20 個細粒度權限 property、Roles 自訂角色機制、acl.Save 的強制要求、五個踩雷點，跟完整 CRUD 範例。同時跟 14.5 NRPC encryption / trust store 系列文章連結，形成完整的 Domino security 圖譜。
2026.05.15 - NotesSession 全攻略 — LotusScript 的入口、單例規則、UserName 的三個變體、Evaluate 把 @Formula 拉進 LS
NotesSession 是每支 LotusScript 一定會碰到的入口 class — 它代表「當前 script 的執行環境」，提供 CurrentDatabase、UserName / EffectiveUserName / CommonUserName 三個 user 屬性、Evaluate 從 LS 跑 @Formula、CreateLog 寫 NotesLog、GetEnvironmentString 讀 notes.ini。本文整理 class 角色、一個 script 一個 session 的規則、核心 property / method、UserName 三變體在 On Behalf Of agent 的差異、server 端 vs client 端存取權限差異、五個踩雷點，跟完整範例。
2026.05.14 - NotesDocument 全攻略 — LotusScript 最核心類別的拿到、CRUD、五個踩雷點
NotesDocument 是 LotusScript 操作 Domino 文件最核心的類別 — 但它的細節很容易踩雷：GetItemValue 永遠回陣列、Save 的三個參數中 createResponse 常被誤解、Remove 的 force 不是軟刪除開關（軟刪除是 DB 層設定，要永久刪用 RemovePermanently）、direct property 跟 ReplaceItemValue 的微妙差別、漏 Save 是最常見的 silent bug。本文整理拿到 NotesDocument 的所有途徑、Item / Field 的觀念、CRUD 範例、五個必懂的坑、sibling methods 跟 Java/SSJS 對照。
2026.05.13 - NotesView.GetAllDocumentsByKey 全攻略：你以為簡單，但它有五個踩雷點
GetAllDocumentsByKey 是 LotusScript 開發中最常用的查詢方法 —— 給一個 key、拿回符合的所有 doc。但「key 對應 sorted column 不是 doc field」「exactMatch 預設 False 是前綴比對」「反斜線分類欄位讓查詢失效」這些細節，HCL 官方文件寫了但很多人沒讀完。本文整理 signature、整個 by-key 方法家族、五個常見踩雷點，附完整範例。
2026.05.09 - LotusScript 的對外 HTTP / JSON 工具鏈：NotesHTTPRequest + NotesJSONNavigator
Domino V12 起 LotusScript 內建 NotesHTTPRequest 跟 NotesJSONNavigator 兩個 class，可以直接從 LS 打外部 REST API 拿 JSON 回來解析 — 不再需要 ActiveX 或 shell 出去呼叫 curl。本文整理兩個 class 的 method、屬性、PreferJSONNavigator 把兩者串起來的官方途徑、完整範例，跟 Java / SSJS 的對位差異。
2026.05.07 - LotusScript NotesStream 實戰指南：把檔案讀寫做對
NotesStream 是 LotusScript 從 Notes/Domino 代理人讀寫檔案的標準抽象。本文整理 Open 真正的 signature、Truncate-before-write 的寫入慣例、文字與二進位 I/O 的差異，以及官方文件實際載明的陷阱。
2026.05.02 - NotesRichTextItem 入門：用 LotusScript 操作富文本欄位
NotesRichTextItem（富文本項目）繼承自 NotesItem，所以 NotesItem 的全部屬性與方法都能用；但它另外有 22 個專屬方法處理段落、樣式、表格、嵌入物件、Navigator/Range 進階遍歷。本文整理建立方式、22 個方法分類、繼承關係，與寫程式時常踩的雷。
2026.04.30 - NotesNoteCollection 入門：操作 NSF 設計元素的瑞士刀
NotesNoteCollection（筆記集合）跟 NotesDocumentCollection 不同，它代表的是 NSF 裡所有「note」—— 包含資料文件、表單、視圖、ACL、代理程式、程式庫等設計元素。本文整理 32 個屬性、14 個方法、CreateNoteCollection 的 True/False 兩種起始模式，以及最常用的場景：DXL 匯出。
2026.04.29 - NotesViewNavigator 入門：用導航器走視圖，不要再 GetFirstDocument 硬撈
NotesViewNavigator（視圖導航器）是 LotusScript 走視圖的進階工具：能拿到 ViewEntry（視圖條目，含類別、總計、位置等視圖才有的中介資料）、能從子集合（單一類別、未讀、某層以下）建立、效能上比 GetFirstDocument 迴圈高，但使用之前要先把 AutoUpdate 關掉。本文整理 4 個屬性、約 36 個方法、7 個 CreateViewNav* 變體與重要注意事項。
2026.04.29 - Domino V12 起 notes.ini 支援多個 HTTPAdditionalRespHeader
舊版 Domino 的 notes.ini 只能塞一個 HTTPAdditionalRespHeader，第二行會把第一行蓋掉。HCL 在 V12.0.x 加了編號式的 HTTPAdditionalRespHeader01、02 寫法，讓你能用純 notes.ini 設好整套安全標頭——尤其是當網頁伺服器（HTTP task）起不來、Internet Site 文件也用不了的時候，這是唯一的後備路徑。
2026.04.28 - NotesQueryResultsProcessor 入門：DQL 之後的下一步
NQRP 是 Domino V12 引入的 LotusScript 類別，讓你把 DQL（或任何 NotesDocumentCollection）的結果重新排序、分類、加欄位、輸出成 JSON 或暫存 view。本文整理建立流程、所有方法簽名、官方範例與安全用法。
2026.04.28 - DQL 入門：用 SQL 風格的語法操作 Notes 文件
Domino Query Language（DQL）讓你用近 SQL 的語法直接查詢 Notes 文件，免再為每種查詢條件設計 view。本文是「DQL 三部曲」系列的 Part 1：介紹 DQL 的設計初衷、第一個 query 怎麼寫、從 LotusScript / Java / REST API 怎麼呼叫，以及常用語法速查。寫 query 結果不如預期的細節在 Part 2，上 production 的 catalog 維運與權限在 Part 3。
2026.04.28