擴充功能：字庫中之漢字於工作表中之座標

.vscode/launch.json

@@ -8,7 +8,7 @@
             "name": "a000",
             "type": "debugpy",
             "request": "launch",
-            "program": "a000.py",
+            "program": "mod_字庫.py",
             "console": "integratedTerminal",
         },
         {

Documents/標音字典串列.md

@@ -0,0 +1,55 @@
+# 標音字典
+
+## 需求
+
+程式 a702 可依據【漢字注音】工作表之內容，自每列、每欄中之【漢字】(row,col)儲存格取得漢字。然後在【漢字庫】資料庫查找【台語音標】,
+隨後填入【漢字】儲存格上方之【台語音標】儲存格(row-1,col)。
+
+由於【在漢字庫查找台語音標作業】，可能會發生狀況：（1）找不到漢字對映之台語音標；（2）漢字庫儲存的台語音標為【白話音】，不是我文章想要
+的【文讀音】...。上述狀況，都會需要事後更正作業。所以，我需要建立如以下的資料結構，用來儲存更正作業所需使用之資訊。
+
+## 資料結構
+
+```python
+ji_khoo_dict = {
+    '慶':                                   # 漢字
+        [
+            'khing3',                       # 【台語音標】羅馬拼音字母
+            3,                              # 總數：在【漢字注音】工作表出現的總數
+            [ (5,3), (133, 11), (145, 7)],  # 座標：在【漢字注音】工作表出現的（列,欄）座標位置
+        ],
+    '人':
+        [
+            'jin5',
+            2,
+            [ (5,6), (97, 9)],
+        ],
+}
+```
+
+ - 【漢字】欄：存字串資料，用於登錄【漢字注音】工作表，存放在【漢字】儲存格中的漢字；
+ - 【台語音標】欄：存字串資料，登錄【程式自漢字庫找到的台語音標】；
+ - 【總數】欄：存放整數資料，記錄【漢字】在【漢字注音】工作表出現的總數；
+ - 【座標】欄：存放【數列】資料，用於記錄漢字在【漢字注音】工作表出現的（列 row,欄 col）座標值。
+
+## 程式碼規格
+
+ 1. 請用【類別】撰寫；
+ 2. 需有方法函式：能用【漢字】新建，【台語音標】、【總數】、【座標】欄
+ 3. 需有方法函式：能用【漢字】為【總數】欄值加一，並罝入一新【座標】
+ 4. 需有方法函式：能用【漢字】取用：【台語音標】、【總數】、【座標】各欄之值
+ 5. 需有方法函式：能將【字典】寫入【工作表】，透過 Excel 儲存
+
+    def write_to_excel_sheet(ji_khoo_dict: JiKhooDict, wb, sheet_name: str) -> status_code: int:
+
+    Excel 工作表欄位：
+
+     - 漢字（A欄）
+     - 總數（B欄）
+     - 台語音標（C欄）
+     - 校正音標（D欄）
+     - 座標（E欄）
+
+ 6. 需有方法函式：能自【工作表】建立 JiKhooDict 字典：
+
+    def create_ji_khoo_dict(wb, sheet_name: str) -> result: JiKhooDict:

mod_excel_access.py

@@ -56,6 +56,22 @@ def logging_process_step(msg):
 # =========================================================================
 # 程式用函式
 # =========================================================================
+def ensure_sheet_exists(wb, sheet_name):
+    """
+    確保指定名稱的工作表存在，如果不存在則新增。
+    :param wb: Excel 活頁簿物件。
+    :param sheet_name: 工作表名稱。
+    :return: 新增或取得的工作表物件。
+    """
+    try:
+        # 嘗試取得工作表
+        sheet = wb.sheets[sheet_name]
+    except KeyError:
+        # 如果工作表不存在，新增一個
+        sheet = wb.sheets.add(sheet_name)
+    return sheet
+
+
 def delete_sheet_by_name(wb, sheet_name: str, show_msg: bool=False):
     """
     刪除指定名稱的工作表

mod_字庫.py

@@ -0,0 +1,212 @@
+from mod_excel_access import ensure_sheet_exists
+
+
+class JiKhooDict:
+    def __init__(self):
+        """
+        初始化字典數據結構。
+        """
+        self.ji_khoo_dict = {}
+
+
+    def add_entry(self, han_ji: str, tai_gi_im_piau: str, coordinates: tuple):
+        """
+        新建一筆【漢字】的資料。
+
+        :param han_ji: 漢字。
+        :param tai_gi_im_piau: 台語音標。
+        :param coordinates: 漢字在【漢字注音】工作表中的座標 (row, col)。
+        """
+        if han_ji not in self.ji_khoo_dict:
+            # 如果漢字不存在，初始化資料結構
+            self.ji_khoo_dict[han_ji] = [1, tai_gi_im_piau, 'N/A', [coordinates]]
+        else:
+            raise ValueError(f"漢字 '{han_ji}' 已存在，請使用 update_entry 方法來更新資料。")
+
+
+    def update_entry(self, han_ji: str, coordinates: tuple):
+        """
+        使用【漢字】為【總數】欄加一，並新增一個座標。
+
+        :param han_ji: 漢字。
+        :param coordinates: 新的座標 (row, col)。
+        """
+        if han_ji in self.ji_khoo_dict:
+            # 增加總數
+            self.ji_khoo_dict[han_ji][0] += 1
+            # 增加新的座標
+            self.ji_khoo_dict[han_ji][3].append(coordinates)
+        else:
+            raise ValueError(f"漢字 '{han_ji}' 不存在，請先使用 add_entry 方法新增資料。")
+
+
+    def get_entry(self, han_ji: str):
+        """
+        使用【漢字】取用其【台語音標】、【總數】、【座標】欄的值。
+
+        :param han_ji: 漢字。
+        :return: 包含台語音標、總數和座標的列表 [台語音標, 總數, 座標列表]。
+        """
+        if han_ji in self.ji_khoo_dict:
+            return self.ji_khoo_dict[han_ji]
+        else:
+            raise ValueError(f"漢字 '{han_ji}' 不存在於字典中。")
+
+
+    def write_to_excel_sheet(self, wb, sheet_name: str) -> int:
+        """
+        將【字典】寫入 Excel 工作表。
+
+        :param wb: Excel 活頁簿物件。
+        :param sheet_name: 工作表名稱。
+        :return: 狀態碼（0 表成功，1 表失敗）。
+        """
+        try:
+            sheet = wb.sheets[sheet_name]
+        except Exception:
+            sheet = wb.sheets.add(sheet_name)
+
+        # 清空工作表內容
+        sheet.clear()
+
+        # 寫入標題列
+        headers = ["漢字", "總數", "台語音標", "校正音標", "座標"]
+        sheet.range("A1").value = headers
+
+        # 寫入字典內容
+        data = []
+        for han_ji, (total_count, tai_gi_im_piau, kenn_ziann_im_piau, coordinates) in self.ji_khoo_dict.items():
+            coords_str = "; ".join([f"({row}, {col})" for row, col in coordinates])
+            data.append([han_ji, total_count, tai_gi_im_piau, kenn_ziann_im_piau, coords_str])
+
+        sheet.range("A2").value = data
+        return 0
+
+
+    @classmethod
+    def create_ji_khoo_dict(cls, wb, sheet_name: str):
+        """
+        自 Excel 工作表建立 JiKhooDict 字典。
+
+        :param wb: Excel 活頁簿物件。
+        :param sheet_name: 工作表名稱。
+        :return: JiKhooDict 物件。
+        """
+        try:
+            sheet = wb.sheets[sheet_name]
+        except Exception as e:
+            raise ValueError(f"無法找到工作表 '{sheet_name}'：{e}")
+
+        # 讀取工作表內容
+        data = sheet.range("A2").expand("table").value
+
+        # 初始化 JiKhooDict
+        ji_khoo = cls()
+
+        # 確保資料為 2D 列表
+        if not isinstance(data[0], list):
+            data = [data]
+
+        # 將工作表內容轉換為字典結構
+        for row in data:
+            han_ji = row[0] or ""
+            total_count = int(row[1]) if isinstance(row[1], (int, float)) else 0
+            tai_gi_im_piau = row[2] or ""
+            kenn_ziann_im_piau = row[3] or ""
+            coords_str = row[4] or ""
+
+            # 解析座標字串
+            coordinates = []
+            if coords_str:
+                coords_list = coords_str.split("; ")
+                for coord in coords_list:
+                    coord = coord.strip("()")
+                    row_col = tuple(map(int, coord.split(", ")))
+                    coordinates.append(row_col)
+
+            # 新增至字典
+            ji_khoo.ji_khoo_dict[han_ji] = [total_count, tai_gi_im_piau, kenn_ziann_im_piau, coordinates]
+
+        return ji_khoo
+
+
+    def __getitem__(self, han_ji: str):
+        """
+        支持通過下標訪問漢字的資料。
+        """
+        if han_ji in self.ji_khoo_dict:
+            return self.ji_khoo_dict[han_ji]
+        else:
+            raise KeyError(f"漢字 '{han_ji}' 不存在於字典中。")
+
+
+    def __repr__(self):
+        """
+        顯示整個字典的內容，用於調試。
+        """
+        return repr(self.ji_khoo_dict)
+
+
+def ut01():
+    # 初始化 JiKhooDict
+    ji_khoo = JiKhooDict()
+
+    han_ji = "慶"
+    result = ji_khoo.get_entry(han_ji)
+    print(result)
+
+    print(f'漢字：{han_ji}')
+    print(f'台語音標：{result[0]}')
+    print(f'總數：{result[1]}')
+    print(f'座標：{result[2]}')
+
+    # 顯示所有座標
+    # for row, col in result[2]:
+    #     print(f'座標：({row}, {col})')
+    for idx, (row, col) in enumerate(result[2], start=1):
+        print(f"座標{idx}：({row}, {col})")
+
+    # 取得第三個座標
+    sn = 3
+    print(f"\n座標{sn}：({result[2][sn-1][0]}, {result[2][sn-1][1]})")
+
+
+def ut02():
+    import xlwings as xw
+
+    # 測試用 Excel 活頁簿
+    wb = xw.Book()
+
+    # 初始化 JiKhooDict
+    ji_khoo = JiKhooDict()
+
+    # 新增資料
+    ji_khoo.add_entry("慶", "khing3", (5, 3))
+    ji_khoo.add_entry("人", "jin5", (5, 6))
+
+    # 更新資料
+    ji_khoo.update_entry("慶", (133, 11))
+    ji_khoo.update_entry("慶", (145, 7))
+    ji_khoo.update_entry("人", (97, 9))
+
+    # 寫入 Excel
+    ji_khoo.write_to_excel_sheet(wb, "漢字庫")
+
+    # 從 Excel 建立字典
+    new_ji_khoo = JiKhooDict.create_ji_khoo_dict(wb, "漢字庫")
+
+    # 查看整個字典
+    print(new_ji_khoo)
+
+    # 取得第三個座標
+    # sn = 3
+    # print(f"\n座標{sn}：({new_ji_khoo[2][sn-1][0]}, {new_ji_khoo[2][sn-1][1]})")
+    entry = new_ji_khoo["慶"]  # 獲取 '慶' 的資料
+    third_coordinate = entry[3][2]  # 取得第三個座標
+    print(f"座標3：({third_coordinate[0]}, {third_coordinate[1]})")
+
+
+# 單元測試
+if __name__ == "__main__":
+    # ut01()
+    ut02()

process_log.txt

@@ -3211,3 +3211,8 @@ IndexError: string index out of range
 2025-01-16 22:08:21,023 - INFO - 完成【處理作業】...
 2025-01-16 22:08:21,128 - INFO - 釋放 Excel 資源，處理完成。
 2025-01-16 22:08:21,128 - INFO - 作業成功完成！
+2025-01-18 11:44:28,378 - INFO - 作業開始
+2025-01-18 11:44:28,380 - INFO - 專案根目錄為: C:\work\Piau-Im
+2025-01-18 11:47:02,586 - INFO - 己存檔至路徑：{file_path}
+2025-01-18 11:47:02,586 - INFO - a702_查找及填入漢字標音.py 程式已執行完畢！
+2025-01-18 11:47:02,586 - INFO - 作業完成！