外掛程式上下文呼叫

PluginContext 向外掛程式提供了以下能力：

• page: 當前 Flet Page 實例，可用於建構 UI 控件或註冊事件。
• register_navigation(view): 註冊一個主導覽視圖（見下文）。
• register_route(view): 註冊一個附加路由，透過 page.go() 存取。
• register_startup_hook(hook): 註冊應用程式啟動後執行的回呼。
• set_initial_route(route): 可選地改變初始路由。
• logger: 已綁定外掛程式 identifier 的 loguru.Logger，直接 logger.info("...") 即可。
• metadata: 字典，可用於在外掛程式及核心系統之間傳遞額外資訊；也可透過 context.add_metadata(key, value) 輔助寫入。
• 全域資料介面：
  • register_data_namespace(identifier, *, description="", permission=None)：註冊命名空間，宣告資料歸屬以及存取權限。
  • publish_data(namespace_id, entry_id, payload)：寫入 / 更新命名空間中的資料條目。
  • latest_data(namespace_id) / get_data(namespace_id, entry_id) / list_data(namespace_id)：讀取共享資料快照，需被授予命名空間所要求的權限。
• 儲存路徑工廠：plugin_data_path、plugin_config_path、plugin_cache_path 以及對應的 *_dir 方法用於存取 / 初始化外掛程式專屬的資料、設定、快取目錄。傳入 create=True 時會確保目錄存在。
• add_bing_action(factory): 在「資源 → Bing 每日」操作列追加自訂按鈕或其他控件。
• add_spotlight_action(factory): 在「資源 → Windows 聚焦」操作列追加控件。
• register_settings_page(label, builder, *, icon=None, button_label="外掛程式設定", description=None): 註冊外掛程式的專屬設定頁面。外掛程式管理面板會在對應外掛程式卡片中顯示一個「外掛程式設定」按鈕，並在新頁面中渲染 builder 返回的控件。
• 收藏管理介面（核心外掛程式啟用後可用，需在 manifest 中宣告並獲批對應的 favorites_* 權限；使用前可透過 context.has_favorite_support() 判斷）：
  • context.favorites：返回 FavoriteService 實例，包裹了全部收藏操作並在內部執行權限校驗。歷史屬性 context.favorite_manager 仍可用，但會返回同一服務實例。
  • 讀取：favorites.list_folders() / favorites.get_folder(id) / favorites.list_items(folder_id="__all__") / favorites.get_item(item_id) / favorites.find_by_source(source)（需 favorites_read）。
  • 寫入：favorites.create_folder(...)、favorites.update_folder(...)、favorites.delete_folder(...)、favorites.add_or_update_item(...)、favorites.update_item(...)、favorites.remove_item(...)、favorites.register_classifier(...)、favorites.classify_item(...)（需 favorites_write）。
  • 匯入匯出：favorites.export_folders(target_path, folder_ids=None, include_assets=True)、favorites.import_package(path)、favorites.localize_items_from_files(mapping)、favorites.localization_root()（需 favorites_export）。 相關資料型別（FavoriteSource、FavoriteItem 等）可直接從 app.plugins 匯入。 相關資料型別（FavoriteSource、FavoriteItem 等）可直接從 app.plugins 匯入。
• 系統操作介面（返回 PluginOperationResult，詳見下文）：
  • open_route(route: str): 請求跳轉到指定路由。需宣告並獲得 app_route 權限。
  • switch_home(navigation_id: str): 切換首頁側邊欄導覽項（例如 home、resource）。需 app_home 權限。
  • open_settings_tab(tab: int): 開啟設定頁並定位到指定標籤（按設定tabs順序，從0開始）。需 app_settings 權限。
  • set_wallpaper(path: str): 將本機圖片設定為系統壁紙。需 wallpaper_control 權限。
  • ipc_broadcast(channel: str, payload: dict): 透過跨行程廣播發布訊息。需 ipc_broadcast 權限。
  • ipc_subscribe(channel: str): 訂閱跨行程廣播頻道，成功時結果的 data 為 IPCSubscription 物件，可呼叫 .get() 讀取佇列訊息。
  • ipc_unsubscribe(subscription_id: str): 取消訂閱，傳入 ipc_subscribe 返回的訂閱 ID。