函式庫

KatanA Document Viewer

將文件預覽以及 HTML、PDF、影像輸出整合到應用程式的 Rust 函式庫,處理不依賴 UI 框架的文件資料。

將文件 viewer 以及 HTML、PDF、影像輸出整合到應用程式的 Rust 開發者

01

已實作功能

處理文件 snapshot、輸出 artifact 與 diagnostic 資訊的 API

依據

連接 Markdown 文件結構與 KRR 圖表渲染的流程

依據

匯出 HTML、PDF、PNG、JPEG

依據

02

開始使用

  1. 取得儲存庫,並透過 README 確認執行環境與字型需求。
  2. 使用 export_debug 範例指定 Markdown 檔案和輸出位置,確認產生的文件。

請準備 Rust 與必要的開發工具,並在導入前透過連結的 README 確認環境需求。執行範例是功能入口,不保證在所有環境中運作。

依據
sh
git clone https://github.com/HiroyukiFuruno/katana-document-viewer.git
cd katana-document-viewer
cargo run -p katana-document-viewer --example export_debug -- README.md ./export-output

01 / KDV

使用情境

顯示和匯出文件的通用平臺

當您想要將 Markdown 視為 KDV 文件框架、狀態和診斷而不直接將其繫結到特定於應用程式的 UI,並且想要從同一渲染管道生成 HTML、PDF、PNG 和 JPEG 時,它非常適合。檢視器顯示和匯出處理邊界可以共享。

準備匯出包含圖形和表格的文件

您可以使用 KDV 構建包含圖表和公式的 Markdown,將圖表渲染委託給 KRR,並保留不支援的含義作為診斷和原始來源。當您希望將無法在顯示端解釋的輸入保留為稍後可以處理的狀態,而不是默默地丟棄它時,這是基礎。

02 / KDV

從輸入到輸出的流程

  1. 標準化輸入

    讀取輸入檔案,把 CRLF/CR 統一為 LF,並用 MarkdownFenceNormalizer 規範化 Markdown fence。為輸入 source 設定 URI、source kind、revision 和正文。

  2. 建立 snapshot 和 build graph

    用 KatanaMarkdownModel::parse 解析 Markdown,再用 DocumentSnapshotFactory::from_kmm 建立 snapshot。將 markdown export profile 和 theme 傳給 BuildRequest,通過 ForgePipeline::build 生成包含診斷資訊的 BuildGraph。

  3. 儲存工件和診斷

    將構建圖傳遞給 ForgePipeline::export 來為每種格式建立工件,並將它們與構建圖、覆蓋率和摘要 TOML 一起輸出。如果工件為空,則示例匯出過程將導致錯誤,並且使用者將不會收到不完整的工件。

03 / KDV

主要 API 與 CLI

DocumentSnapshotFactory — 文件快照
組合 KMM 文件和 DocumentSource 以建立檢視器/forge 將處理的 DocumentSnapshot。快照的先決條件不僅是輸入正文,還有 URI 和修訂版。
ForgePipeline::build — 建置流程
處理 BuildRequest 的快照、BuildProfile 和主題,並返回包含文件快照、配置檔案、診斷和渲染圖表的 BuildGraph。
ForgePipeline::export — 文件匯出
從 ExportRequest 的構建圖、格式和主題返回 ExportOutput。格式為 HTML、PDF、PNG 和 JPEG,工件和forge diagnostics可以組合並傳遞到下一階段。
KRR diagram backend — 圖表後端
通過將DiagramRenderingBackend 和KrrDiagramRenderEngine 傳遞到管道,將圖表渲染器連線到KRR 邊界。 KDV 本身並不是一個直接擁有應用程式 UI 或其他圖表實現的 API。

04 / KDV

透過範例理解

構建README並檢查文件節點數的示例

此程式碼讀取 README.md,對其進行規範化、解析和快照,建立帶有 markdown 匯出配置檔案的 BuildGraph,並顯示節點數。構建部分是從公開export_debug示例中提取的,它不會儲存到檔案或匯出為4種格式。

rust
use katana_document_viewer::{
    BuildProfile, BuildRequest, DiagramRenderingBackend, DocumentSnapshotFactory,
    DocumentSource, ForgePipeline, KrrDiagramRenderEngine, MarkdownFenceNormalizer,
    SourceKind, SourceRevision, SourceUri,
};
use katana_markdown_model::{KatanaMarkdownModel, MarkdownInput};
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = "README.md";
    let content = MarkdownFenceNormalizer::normalize(&fs::read_to_string(path)?);
    let source = DocumentSource {
        uri: SourceUri(format!("file://{path}")),
        kind: SourceKind::Markdown,
        revision: SourceRevision("local".to_string()),
        content: content.clone(),
    };
    let document = KatanaMarkdownModel::parse(MarkdownInput::from_content(path, content))?;
    let snapshot = DocumentSnapshotFactory::from_kmm(source, document);
    let request = BuildRequest {
        snapshot,
        profile: BuildProfile::markdown_export(),
        theme: Default::default(),
    };
    let pipeline = ForgePipeline::new(DiagramRenderingBackend::new(KrrDiagramRenderEngine));
    let graph = pipeline.build(&request)?;
    println!("nodes={}", graph.snapshot.document.nodes.len());
    Ok(())
}

05 / KDV

整合條件與責任邊界

不要引入 UI 後端

KDV 不依賴於 egui/eframe 等 UI 後端,也不向公開 API 公開 KUC 型別。 KatanA 等更高級別的應用程式負責同步檢視器和編輯器,而 KDV 則專注於文件/檢視器/匯出邊界。

作為腳手架引入

公開 README 的狀態為 Scaffolding,v0.1.0 是獨立於 UI 的 artifact/forge/export 基礎。整合時不能用重新解析來掩蓋 KMM parser 的缺口,也不能把 KRR 尚不支援的語義當成已完成的能力。

依據

內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。

儲存庫閱讀指南99371a97dbc5
依據 · KDV
所有產品