translime-sdk 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021-2025 slime7 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,153 +1,222 @@
-# Translime SDK
-
-这是 Translime 插件开发的官方 SDK。它提供了完善的类型提示 (.d.ts) 并简化了对主程序 API 的访问。
-
-## 安装
-
-```bash
-pnpm add translime-sdk
-```
-
-## 使用 Vite 插件
-
-在插件的 `vite.config.js` 中使用内置插件，可以自动处理 `electron` 等依赖的外部化：
-
-```javascript
-import { defineConfig } from 'vite';
-import { translimeSdk } from 'translime-sdk/vite';
-
-export default defineConfig({
-  plugins: [
-    translimeSdk(),
-    // ... 其他插件
-  ]
-});
-```
-
-## 代码示例
-
-### 主进程逻辑 (src/index.js)
-
-```javascript
-import { usePluginConfig } from 'translime-sdk';
-
-const config = usePluginConfig('my-plugin-id');
-const myValue = config.get('settingsKey', 'default');
-```
-
-### 渲染进程 UI (src/ui/ui.vue)
-
-```javascript
-import { useIpc, useVuetifyComponents } from 'translime-sdk';
-
-const ipc = useIpc();
-const { VBtn, VCard } = useVuetifyComponents();
-```
-
-## 核心 API
-
-### 主进程 (Main Process)
-
-- `getMainStore()`: 获取主程序的全局 Store。
-- `usePluginConfig(pluginId)`: 获取针对特定插件的配置工具。
-
-### 渲染进程 (Renderer Process)
-
-- `useIpc()`: 获取 IPC 工具。
-- `useVuetifyComponents()`: 获取所有 Vuetify 组件。
-- `useVuetifyDirectives()`: 获取所有 Vuetify 指令。
-- `useDialog()`: 获取 Electron 对话框 API。
-- `useShell()`: 获取 Shell API。
-- `getPluginSetting(...args)`: 获取插件设置。
-- `setPluginSetting(...args)`: 设置插件设置。
-- `useWindowControl()`: 获取窗口控制工具。
-- `useClipboard()`: 获取剪贴板工具。
-- `openLink(...args)`: 在浏览器中打开链接。
-- `isPreviewMode()`: 检查当前是否为 Preview 模式。
-
-### 通用 (Common)
-
-- `useLogger()`: 获取标准日志工具，支持 `log`, `info`, `warn`, `error`, `debug`。在渲染进程中会自动通过 IPC 发送到主进程记录，在主进程中则直接写入日志文件。
-
----
-
-## Preview 模式
-
-Preview 模式允许你在普通浏览器中预览和调试插件 UI，无需依赖 Electron 环境。这使得开发过程中能够享受 Vite 的 HMR (热模块替换) 便利性。
-
-### 特性
-
-- ✅ **零配置**：插件代码无需任何修改，SDK 会自动检测 preview 模式并注入 mock 实现
-- ✅ **完整的 Vuetify 支持**：Preview Shell 自动提供 Vuetify 组件和主题
-- ✅ **API Mock**：所有 Electron 相关的 API (IPC, Dialog, Shell 等) 都有对应的 mock 实现
-- ✅ **设置持久化**：插件设置使用 localStorage 存储，刷新页面后仍然保留
-- ✅ **主题切换**：Preview 界面提供浅色/深色主题切换
-
-### 快速开始
-
-1. **在插件的 `package.json` 中添加 preview 脚本**：
-
-```json
-{
-  "scripts": {
-    "preview:ui": "vite -c ui.vite.config.mjs --mode preview"
-  }
-}
-```
-
-2. **运行 preview 模式**：
-
-```bash
-pnpm preview:ui
-```
-
-3. **访问预览页面**：在浏览器中打开 Vite 提供的地址 (通常是 `http://localhost:5173`)
-
-### Vite 插件配置
-
-`translimeSdk()` 插件会自动处理 preview 模式的配置。你可以通过 `previewComponent` 选项指定要预览的组件路径：
-
-```javascript
-import { defineConfig } from 'vite';
-import { translimeSdk } from 'translime-sdk/vite';
-
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    translimeSdk({
-      // 可选：指定要预览的组件路径，默认使用 lib.entry
-      previewComponent: './src/ui/ui.vue'
-    }),
-  ],
-  // ... 其他配置
-}));
-```
-
-### Mock API 行为
-
-在 Preview 模式下，SDK 提供的 API 会有以下行为：
-
-| API | Mock 行为 |
-|-----|----------|
-| `useIpc().invoke()` | 打印调用日志，返回 `null` |
-| `useDialog().showOpenDialog()` | 使用浏览器原生文件选择器 |
-| `getPluginSetting()` | 从 localStorage 读取 |
-| `setPluginSetting()` | 保存到 localStorage |
-| `useClipboard()` | 使用浏览器 Clipboard API |
-| `openLink()` | 使用 `window.open()` 打开新窗口 |
-
-### 条件代码
-
-如果需要在 preview 模式下执行不同的逻辑，可以使用 `isPreviewMode()` 函数：
-
-```javascript
-import { isPreviewMode, useIpc } from 'translime-sdk';
-
-if (isPreviewMode()) {
-  console.log('当前运行在 Preview 模式');
-  // 执行替代逻辑
-} else {
-  const ipc = useIpc();
-  await ipc.invoke('some-api@plugin-id');
-}
-```
-
+# Translime SDK
+
+Translime 官方插件 SDK，提供插件开发常用的运行时 API、类型提示和 Vite 集成能力。
+
+## 安装
+
+```bash
+pnpm add translime-sdk
+```
+
+## Vite 集成
+
+在插件的 `vite.config.mjs` 中使用 `translimeSdk()`，可以自动处理 `electron` 等依赖的外部化，并支持 preview 模式。
+
+```javascript
+import { defineConfig } from 'vite';
+import { translimeSdk } from 'translime-sdk/vite';
+
+export default defineConfig({
+  plugins: [
+    translimeSdk(),
+  ],
+});
+```
+
+## 代码示例
+
+### 主进程
+
+```javascript
+import { usePluginConfig } from 'translime-sdk';
+
+const config = usePluginConfig('my-plugin-id');
+const myValue = config.get('settingsKey', 'default');
+```
+
+### 插件 UI
+
+```javascript
+import { useIpc, useVuetifyComponents } from 'translime-sdk';
+
+const ipc = useIpc();
+const { VBtn, VCard } = useVuetifyComponents();
+```
+
+## 核心 API
+
+### 主进程 (Main Process)
+
+- `getMainStore()`: 获取主程序全局 Store。
+- `usePluginConfig(pluginId)`: 获取当前插件配置读写工具。
+- `usePluginInterop()`: 获取插件间通信工具。
+
+#### 插件间通信
+
+`usePluginInterop()` 用于在一个插件的主进程代码中访问另一个插件导出的公共 API。
+
+```javascript
+import { usePluginInterop } from 'translime-sdk';
+
+const doSomething = async () => {
+  const interop = usePluginInterop();
+  if (!interop) {
+    return;
+  }
+
+  const targetApi = interop.getExports('target-plugin-id');
+  if (targetApi) {
+    targetApi.someMethod();
+  }
+
+  try {
+    const api = await interop.waitForPlugin('target-plugin-id', 5000);
+    api.someMethod();
+  } catch (error) {
+    console.error('目标插件未就绪', error);
+  }
+};
+```
+
+### 渲染进程 (Renderer Process)
+
+- `useIpc()`: 获取 IPC 工具。
+- `useVuetify()`: 获取 Vuetify 实例。
+- `useVuetifyComponents()`: 获取所有 Vuetify 组件。
+- `useVuetifyDirectives()`: 获取所有 Vuetify 指令。
+- `useDialog()`: 获取 Electron 对话框 API。
+- `useShell()`: 获取 Shell API。
+- `getPluginSetting(...args)`: 获取插件设置。
+- `setPluginSetting(...args)`: 设置插件设置。
+- `useWindowControl()`: 获取窗口控制工具。
+- `useClipboard()`: 获取剪贴板工具。
+- `openLink(...args)`: 在浏览器中打开链接。
+- `isPreviewMode()`: 检查当前是否为 preview 模式。
+- `electronNetAdapter(config)`: 基于 `window.ts.net` 的 axios adapter。
+
+### 通用 (Common)
+
+- `useLogger()`: 获取标准日志工具，支持 `log`, `info`, `warn`, `error`, `debug`。
+
+## 网络请求 Adapter
+
+如果插件需要在 UI 渲染层直接发起 HTTP 请求，并复用主程序通过 `window.ts.net` 暴露的网络层，可以使用 SDK 导出的 `electronNetAdapter`。
+
+适用场景：
+
+- 需要在插件 UI 中直接请求远程接口。
+- 需要绕过浏览器环境下的跨域限制。
+- 需要配合 axios 的 `signal` / `AbortController` 取消请求。
+
+最小示例：
+
+```javascript
+import axios from 'axios';
+import { electronNetAdapter } from 'translime-sdk';
+
+const response = await axios({
+  url: 'https://example.com/api/data',
+  method: 'GET',
+  adapter: electronNetAdapter,
+});
+
+console.log(response.data);
+```
+
+也可以在 axios 实例中统一配置：
+
+```javascript
+import axios from 'axios';
+import { electronNetAdapter } from 'translime-sdk';
+
+const request = axios.create({
+  adapter: electronNetAdapter,
+});
+```
+
+注意事项：
+
+- 该 adapter 仅适用于插件 UI / Renderer，不适用于插件主进程。
+- 真实 Electron 环境下会调用 `window.ts.net.request()` 和 `window.ts.net.abort()`。
+- Preview 模式下会自动回退到 SDK 提供的 mock `window.ts.net` 实现，适合基础联调。
+- 如果请求逻辑包含敏感凭据、签名或更复杂的业务编排，仍建议放在插件主进程，再通过插件自己的 IPC 暴露给 UI。
+
+## 宿主优先的开发流程
+
+开发插件时，应把真实的 Translime 宿主作为主要运行环境。推荐顺序如下：
+
+1. 在你自己的插件仓库中开发并重新构建插件。
+2. 通过 `pnpm link` 将插件包链接到 Translime 的 `plugins_dev/node_modules` 目录。
+3. 直接在 Translime 中打开插件，验证真实的宿主布局、设置、IPC 和窗口行为。
+
+`preview:ui` 仍然可用，但只建议作为独立 UI 调试的辅助工具。对于依赖 Translime 上下文的页面，不应以 preview 结果替代宿主内验证。
+
+## Preview 模式
+
+Preview 模式允许你在普通浏览器中预览和调试插件 UI，无需依赖 Electron 环境。
+
+### 特性
+
+- 零配置：SDK 会自动检测 preview 模式并注入 mock 实现。
+- 完整的 Vuetify 支持：Preview Shell 自动提供 Vuetify 组件和主题。
+- API Mock：IPC、Dialog、Shell、插件设置等接口都有对应 mock。
+- 设置持久化：插件设置使用 `localStorage` 存储。
+
+### 快速开始
+
+1. 在插件的 `package.json` 中添加脚本：
+
+```json
+{
+  "scripts": {
+    "preview:ui": "vite -c ui.vite.config.mjs --mode preview"
+  }
+}
+```
+
+2. 运行：
+
+```bash
+pnpm preview:ui
+```
+
+3. 在浏览器中打开 Vite 输出的本地地址，通常是 `http://localhost:5173`。
+
+### Vite 插件配置
+
+```javascript
+import { defineConfig } from 'vite';
+import { translimeSdk } from 'translime-sdk/vite';
+
+export default defineConfig(() => ({
+  plugins: [
+    translimeSdk({
+      previewComponent: './src/ui/ui.vue',
+    }),
+  ],
+}));
+```
+
+### Mock API 行为
+
+| API | Mock 行为 |
+|-----|----------|
+| `useIpc().invoke()` | 打印调用日志，返回 `null` |
+| `getPluginSetting()` | 从 `localStorage` 读取 |
+| `setPluginSetting()` | 保存到 `localStorage` |
+| `useClipboard()` | 使用浏览器 Clipboard API |
+| `openLink()` | 使用 `window.open()` 打开新窗口 |
+| `electronNetAdapter()` | 通过 mock `window.ts.net` 发起基础请求 |
+
+### 条件代码
+
+```javascript
+import { isPreviewMode, useIpc } from 'translime-sdk';
+
+if (isPreviewMode()) {
+  console.log('当前运行在 Preview 模式');
+} else {
+  const ipc = useIpc();
+  await ipc.invoke('some-api@plugin-id');
+}
+```