用 API 開啟空白 Word — 探索我的 AI 助手背後程式碼 (3)

在前兩篇，我們學會了如何用 API 開啟記事本和小畫家。

但光是開應用程式還不夠，我還希望 AI 能幫我操作 Word 文件，像是新增文件、輸入內容、儲存檔案。這一篇，先從最基礎的功能開始：開啟一個空白的 Word 文件。

功能簡介

這個 API 的功能是：

• 檢查 Word 是否已經啟動
• 如果沒開，幫你開啟 Word
• 自動新增一個空白文件

程式碼解析

@app.post("/open-blank-word")
def open_blank_word():
    """
    純粹開啟一個空白的 Word 應用程式，不寫入任何內容。
    """
    print(f"[DEBUG] 收到 open-blank-word 請求")
    logger.info("收到 open-blank-word 請求")
    
    word_app = None
    try:
        # 在多執行緒環境中，必須先初始化 COM
        pythoncom.CoInitialize()
        
        # 嘗試取得現有的Word實例，如果沒有則創建新的
        try:
            word_app = win32.GetObject(Class="Word.Application")
            if word_app.Documents.Count == 0:
                # 沒有開啟的文件，創建新文件
                doc = word_app.Documents.Add()
            else:
                # 已有Word開啟，直接顯示不創建新文件
                word_app.Visible = True
                logger.info("Word 已經在運行，直接顯示現有實例。")
                return {"status": "success", "message": "Word 已經在運行，已顯示現有實例。"}
        except:
            # 如果取得現有實例失敗，創建新的Word應用程式
            word_app = win32.Dispatch("Word.Application")
            word_app.Visible = True
            doc = word_app.Documents.Add()
        
        # 確保Word是可見的
        word_app.Visible = True
        
        logger.info("已成功開啟空白的 Word 應用程式。")
        return {"status": "success", "message": "已成功開啟空白的 Word 應用程式。"}
        
    except Exception as e:
        error_msg = str(e)
        logger.error(f"開啟空白 Word 時發生錯誤: {error_msg}")
        
        if "(-2147352567" in error_msg:
            return {"status": "error", "message": "Word 啟動失敗。請確保 Microsoft Word 已正確安裝。"}
        else:
            return {"status": "error", "message": f"開啟空白 Word 時發生錯誤: {error_msg}"}
            
    finally:
        try:
            pythoncom.CoUninitialize()
        except:
            pass

逐行拆解：

1. 函數定義
   def open_blank_word():

2. COM 環境初始化
   pythoncom.CoInitialize() - 多執行緒環境下操作 COM 物件的必要步驟

3. 智能檢查現有實例
   win32.GetObject(Class="Word.Application") - 先嘗試連接已存在的 Word 實例

   • 如果成功：檢查是否有開啟的文件
   • 如果失敗：創建新的 Word 應用程式

4. 條件式處理

   • 若 Word 已開啟且有文件：直接顯示
   • 若 Word 已開啟但無文件：新增空白文件
   • 若 Word 未開啟：啟動 Word 並新增文件

5. 安全清理
   finally 區塊確保 COM 環境正確清理

6. 完整錯誤處理

   • 特定錯誤碼檢查 (如 Word 未安裝)
   • 統一的錯誤回傳格式

運作流程

1. 使用者發送請求：

   POST http://127.0.0.1:8000/open-blank-word
   
   

2. API 智能檢查：

• 先檢查 Word 是否已在運行
• 如果有，檢查是否有開啟的文件

3. 條件式執行：

• 情況1： Word 已開啟有文件 → 直接顯示
• 情況2： Word 已開啟無文件 → 新增空白文件
• 情況3： Word 未開啟 → 啟動 Word 並新增文件

4. API 回傳結果：

成功時：

{
  "status": "success", 
  "message": "已成功開啟空白的 Word 應用程式。"
}
    

Word 已運行時：

{ 
  "status": "success", 
  "message": "Word 已經在運行，已顯示現有實例。"
}