聊天 API · Needless UI

匯入

import-chat.ts

import { NuiChat, NuiChatSession, nuiEventStream } from '@needless-ui/angular/chat';

NuiChat

對話和輸入框，合而為一。

選擇器: nui-chat

NuiChat: 屬性
名稱	型別	預設值	說明
`session`輸入	`NuiChatSession`		要顯示的對話。
`assistant`輸入	`string`	`'Assistant'`	助理的名稱，用於螢幕閱讀器朗讀的標題中。
`headingLevel`輸入	`number`	`3`	每則訊息標題的層級，這些標題只有螢幕閱讀器看得到。回覆中的標題再低一層。
`announce`輸入	`'reply' \| 'notice' \| 'off'`	`'reply'`	回覆完成時螢幕閱讀器朗讀的內容：全部、簡短通知或不朗讀。
`images`輸入	`boolean`	`false`	顯示回覆中的圖片；否則以圖片的文字作為指向圖片的連結。
`value`雙向繫結	`string`	`''`	正在輸入的文字。
`placeholder`輸入	`string`		輸入框為空時顯示的提示。
`suggestions`輸入	`string[]`	`[]`	點一下就能送出的提示詞，會顯示到第一則訊息送出為止。
`sendOn`輸入	`'enter' \| 'mod+enter'`	`'enter'`	按 Enter 送出，還是按 Ctrl 或 ⌘ + Enter 送出。
`disabled`輸入	`boolean`	`false`	禁止輸入框送出訊息。
`attach`輸入	`boolean`	`false`	接收檔案：選取、貼上或拖放皆可。
`accept`輸入	`string`	`''`	可接收的檔案類型，寫法同 `<input type="file">`。
`maxFiles`輸入	`number`	`10`	一則訊息最多可附加的檔案數。
`maxSize`輸入	`number`	`20_000_000`	可接收的最大檔案大小，單位為位元組。
`labels`輸入	`NuiChatLabelsInput`		聊天元件顯示或朗讀的所有文字，供翻譯使用。
`rated`輸出	`{ message, rating }`		發出使用者評分的回覆及其評分；收回評分時為 `null`。
`focus`方法	`() => void`		讓文字欄位取得焦點。
`scrollToEnd`方法	`(behavior?) => void`		捲動到最新訊息，並持續跟隨。

NuiChatSession

不含任何 DOM 的對話本身。在元件中以 respond、messages 和 id 選項建立它。

NuiChatSession: 屬性
名稱	型別	說明
`respond`屬性	`(request) => NuiChatReply`	由你實作：針對 `request.messages` 寫出回覆，並在 `request.signal` 中止時停止。
`messages`屬性	`Signal<NuiChatMessage[]>`	畫面上的對話。
`all`屬性	`Signal<NuiChatMessage[]>`	所有版本的所有訊息，可儲存後再以 `messages` 傳回。
`busy`屬性	`Signal<boolean>`	是否有回覆正在傳送中。
`send`方法	`(text, files?) => Promise<void>`	送出一則訊息並要求回覆。
`stop`方法	`() => void`	停止回覆，並保留已寫出的內容。
`retry`方法	`(message?) => Promise<void>`	重新提問。新回覆會成為與舊回覆並列的一個版本。
`edit`方法	`(message, text) => Promise<void>`	為使用者的某則訊息送出新版本。
`versions`方法	`(message) => NuiChatMessage[]`	一則訊息的所有版本，由舊到新排列。
`show`方法	`(message) => void`	將對話切換到這個版本。
`rate`方法	`(message, 'up' \| 'down' \| null) => void`	記錄使用者對某則回覆的評分。
`remove, load, clear`方法	`(…) => void`	移除一則訊息及其後的內容、取代整段對話，或從頭開始。

NuiChatMessage

一則訊息。parent 相同的訊息互為版本。

NuiChatMessage: 屬性
名稱	型別	說明
`id, parent`屬性	`string, string \| null`	訊息的 key，以及它所接續的那則訊息。
`role`屬性	`'user' \| 'assistant'`	由誰撰寫。
`text`屬性	`string`	助理傳來的是 Markdown，使用者傳來的是純文字。
`status`屬性	`'pending' \| 'streaming' \| 'done' \| 'stopped' \| 'error'`	回覆目前的階段，從等待到完成。
`reasoning`屬性	`string`	模型在回答前的思考內容。
`tools`屬性	`NuiChatTool[]`	它呼叫的工具，以及工具的狀態、輸入和輸出。
`sources`屬性	`{ url, title? }[]`	它引用的網頁。
`attachments`屬性	`NuiChatAttachment[]`	隨訊息送出的檔案。
`rating`屬性	`'up' \| 'down' \| null`	使用者的評分。
`data`屬性	`unknown`	需要一併保存的其他資料，例如模型名稱。

NuiChatToolTemplate

繪製工具呼叫，例如一張天氣卡片。其 context 包含該次呼叫和它所屬的訊息。

選擇器: ng-template[nuiChatTool]

NuiChatToolTemplate: 屬性
名稱	型別	預設值	說明
`nuiChatTool`輸入	`string`		工具名稱。未指定時，會繪製其他範本都未指定的所有呼叫。

NuiChatThread

單獨的對話部分，用於你自己的版面。它接收 nui-chat 中與對話有關的輸入屬性。

選擇器: nui-chat-thread

NuiChatComposer

單獨的輸入框。它接收 nui-chat 中與撰寫訊息有關的輸入屬性。

選擇器: nui-chat-composer

NuiServerEvent

nuiEventStream 為每個事件產出的物件。nuiTextStream 讀取純文字，nuiJsonStream 讀取 JSON Lines；三者都接收 fetch 的回應。

NuiServerEvent: 屬性
名稱	型別	預設值	說明
`event`屬性	`string`	`'message'`	事件名稱。
`data`屬性	`string`		串接後的 data 行。
`id`屬性	`string`		串流最後傳送的 id。

NuiChatError

從 respond 擲出它，就會顯示它的訊息。其他錯誤只會顯示一般訊息，因此不會洩漏內部資訊。