@jiangzhongxi0322/messagechannel 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,181 @@
+# MessageChannel 库
+
+一个轻量级的消息通道库，用于在 VSCode 扩展和 Webview 之间进行通信。
+
+## 特性
+
+- **双向通信**：在 VSCode 扩展和 Webview 之间实现无缝通信。
+- **事件订阅**：允许订阅特定事件类型以进行有针对性的消息处理。
+- **基于 Promise 的 API**：支持使用 async/await 模式处理消息和响应。
+- **跨扩展通信**：促进不同 VSCode 扩展之间的通信。
+
+## 安装
+
+通过 npm 安装库：
+
+```bash
+npm install messagechannel
+```
+
+## 使用方法
+
+### 基本设置
+
+#### 在 VSCode 扩展（Node.js 端）
+
+```typescript
+import MessageChannel from 'messagechannel';
+
+const channel = MessageChannel();
+
+// 设置载体（VSCode Webview）
+channel.setCarrier(yourWebview);
+
+// 订阅一个事件
+channel.subscribe('eventType1', (data) => {
+  console.log('接收到的数据:', data);
+});
+
+// 发布一个事件
+channel.publish('eventType2', { key: 'value2' });
+```
+
+#### 在 Webview（浏览器端）
+
+```typescript
+import MessageChannel from 'messagechannel';
+
+const channel = MessageChannel();
+
+// 初始化通道（Webview 中不需要载体）
+channel.setCarrier(undefined);
+
+// 订阅一个事件
+channel.subscribe('eventType2', (data) => {
+  console.log('接收到的数据:', data);
+});
+
+// 发布一个事件
+channel.publish('eventType1', { key: 'value1' });
+```
+
+### 高级用法
+
+#### 使用 `pubWithSub` 进行请求-响应模式
+
+```typescript
+import MessageChannel from 'messagechannel';
+
+const channel = MessageChannel();
+
+// 发布并订阅一次调用
+const response = await channel.pubWithSub('eventType', { key: 'value' }); // 也可以channel.pubWithSub('eventType', { key: 'value' }, (response) => {})
+console.log('响应:', response);
+```
+
+#### 跨扩展通信
+插件A的web端
+```typescript
+import MessageChannel from 'messagechannel';
+
+const channel = MessageChannel();
+
+// 向另一个扩展发布事件
+channel..pubWithSub(extensionId, options, callback);
+```
+
+1. extensionId，要通信的插件的唯一标识，由package.json中的name和publisher组成。
+ 
+2. options，是一个对象，包含如下选项：
+
+   1. viewType，要打开的webview的type，一般声明为静态类型。
+
+   2. source
+
+	| 文件预览型webview | 命令打开的webview面板 |
+	| ----- | ----- |
+	| D:\\\\project\\\\vscode\\\\vscode-extension-samples\\\\url-webview-sample\\\\exampleFiles\\\\example.cscratch' | 相应的命令 |
+
+   3. selector，打开web后要自动点击的元素的选择器列表，多个元素依次点击。比如打开env的页面后自动添加添加按钮。
+
+   4. payload，要传递的额外参数，这个参数会自动添加为selector对应元素的payload属性
+
+3. callback，接受另一个插件的web部分回传的数据
+###### 示例
+
+```typescript
+// 扩展 A webviewProvider
+const channel = MessageChannel();
+channel.initiator(ColorsViewProvider.viewType);
+// 这俩顺序没关系
+channel.setCarrier(webview);
+// 扩展 A web 在某个时机比如点击按钮调用下面就会自动打开扩展B的webview
+channel.pubWithSub('extensionB', 
+  { 
+	viewType: 'catCustoms.catScratch',
+	source: 'D:\\\\project\\\\vscode\\\\vscode-extension-samples\\\\url-webview-sample\\\\exampleFiles\\\\example.cscratch',
+	selector: ['input'],
+	payload: value
+  },
+  (data) => {
+	console.log(data);
+  });
+
+// 扩展 B webviewProvider  
+const channel = MessageChannel();
+channel.initiator(CatCodingPanel.viewType);
+// 这俩顺序没关系
+channel.setCarrier(webview);
+// 扩展 B web 在某个实际比如点击事件，可以通过feedbackResult回馈数据
+const channel = MessageChannel();
+document.querySelector('button').addEventListener('click', (args) => {
+  const result = document.querySelector('input').value;
+  feedbackResult && feedbackResult(result);
+});
+channel.setCarrier();
+channel.initiator();
+```
+
+## API 参考
+
+### `MessageChannel()`
+
+创建一个新的消息通道实例。
+
+#### 返回值
+
+一个包含以下方法的对象：
+
+- `publish(typename: string, msg?: any)`：向通道发布消息。
+- `subscribe(typename: string, subscriber: (data: FeedbackData) => any, once?: boolean)`：订阅一个消息类型。
+- `setCarrier(carrier: any)`：设置消息通道的载体。
+- `pubWithSub(typename: string, msg: any, subscriber?: (data: FeedbackData) => any)`：发布消息并订阅响应。
+- `initiator(viewType: string)`：初始化特定 Webview 类型的通信。
+- `getCarrier()`：获取当前载体。
+
+### 接口
+
+#### `Event`
+
+```typescript
+interface Event {
+  typename?: string;
+  key?: string;
+  channelId: string;
+  data: FeedbackData;
+}
+```
+
+#### `FeedbackData`
+
+```typescript
+interface FeedbackData {
+  code: 0 | 1 | 2;
+  msg: string;
+  data: any;
+}
+```
+
+## 许可证
+
+本项目采用 MIT 许可证。详情请见 [LICENSE](LICENSE) 文件。

package/dist/messageChannel.d.ts

@@ -0,0 +1,10 @@
+import * as vscode from 'vscode';
+declare const MessageChannel: () => {
+    publish: (typename: string, data?: any) => void;
+    subscribe: (typename: string, subscriber: (data: any) => any, once?: boolean) => (() => void) | undefined;
+    setCarrier: (carrier?: null | vscode.Webview) => void;
+    pubWithSub: (typename: string, msg: any, subscriber?: (data: any) => any) => Promise<unknown>;
+    initiator: (viewType?: string) => void;
+    getCarrier: () => vscode.Webview | null;
+};
+export default MessageChannel;

package/dist/{messageChennel.js → messageChannel.js}

@@ -46,6 +46,12 @@ const vscode = __importStar(require("vscode"));
 const MessageChannel = () => {
     let cachedCarrier;
     let dispose;
+    /**
+     * @carrier 在vscode的webviewProvider以及webview的web内都调用这个接口，设置发送和接受事件的载体
+     * webviewProvider示例：CI.setCarrier(webviewView.webview); // 在最早获取到webview的地方
+     * webview的react项目示例：CI.setCarrier(); // 在根组件
+     * carrier如果为空，则清空之前的载体
+    */
     const setCarrier = (carrier) => {
         if (carrier === undefined) {
             cachedCarrier = window.acquireVsCodeApi();
@@ -58,19 +64,18 @@ const MessageChannel = () => {
             dispose.dispose();
         }
         cachedCarrier = carrier;
-        if (carrier === null) {
+        if (cachedCarrier === null) {
             return;
         }
         dispose = cachedCarrier.onDidReceiveMessage((event) => messageHandler(event));
     };
     const subscribers = {};
     const messageHandler = (event) => __awaiter(void 0, void 0, void 0, function* () {
-        const { data: feedbackData, typename } = event;
-        const data = feedbackData.data;
+        const { data, typename } = event;
         const isTalkInExtension = typename && subscribers[typename];
         if (isTalkInExtension) {
             subscribers[typename].forEach((resolver) => {
-                resolver(feedbackData);
+                resolver(data);
             });
             return;
         }
@@ -106,6 +111,11 @@ const MessageChannel = () => {
             }
         }
     });
+    /**
+     * typename: 消息类型，消息的发布和订阅都依赖这个typename
+     * subscriber：收到消息后把消息传递给subscriber
+     * once：一次性订阅，收到消息后就把订阅者移除
+    */
     const subscribe = (typename, subscriber, once = false) => {
         if (!subscriber || !(subscriber instanceof Function)) {
             return;
@@ -145,18 +155,25 @@ const MessageChannel = () => {
             }
         };
     };
-    const publish = (typename, msg) => {
+    /**
+     * typename: 消息类型，消息的发布和订阅都依赖这个typename
+     * msg：消息发布时带的参数
+    */
+    const publish = (typename, data) => {
         try {
             cachedCarrier === null || cachedCarrier === void 0 ? void 0 : cachedCarrier.postMessage({
                 typename: typename,
-                data: msg,
+                data: data,
             });
         }
         catch (error) {
             0;
         }
     };
-    // vscode.WebviewViewProvider的静态方法中调用
+    /**
+     * 如果要唤醒其余插件的webview，则双方插件的provider、web都要调用这个函数初始化
+     * viewType：provider传递WebviewProvieder的viewType，web则不用传递参数
+    */
     const initiator = (viewType) => {
         // for node
         if (viewType) {
@@ -191,7 +208,7 @@ const MessageChannel = () => {
             }));
             return;
         }
-        publish('webviewRenderDone', null);
+        publish('webviewRenderDone');
         subscribe('clickAnyElement', (data) => {
             const clickAnyElement = (data) => __awaiter(void 0, void 0, void 0, function* () {
                 const selectorList = data === null || data === void 0 ? void 0 : data.selector;

package/examples/command-webview-sample/.eslintrc.js

@@ -0,0 +1,23 @@
+/**@type {import('eslint').Linter.Config} */
+// eslint-disable-next-line no-undef
+module.exports = {
+	root: true,
+	parser: '@typescript-eslint/parser',
+	plugins: [
+		'@typescript-eslint',
+	],
+	extends: [
+		'eslint:recommended',
+		'plugin:@typescript-eslint/recommended',
+	],
+	ignorePatterns: [
+		'media'
+	],
+	rules: {
+		'semi': [2, "always"],
+		'@typescript-eslint/no-unused-vars': 0,
+		'@typescript-eslint/no-explicit-any': 0,
+		'@typescript-eslint/explicit-module-boundary-types': 0,
+		'@typescript-eslint/no-non-null-assertion': 0,
+	}
+};

package/examples/command-webview-sample/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"dbaeumer.vscode-eslint"
+	]
+}

package/examples/command-webview-sample/.vscode/launch.json

@@ -0,0 +1,18 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Run Extension",
+			"type": "extensionHost",
+			"request": "launch",
+			"runtimeExecutable": "${execPath}",
+			"args": ["--extensionDevelopmentPath=${workspaceRoot}"],
+			"outFiles": ["${workspaceFolder}/out/**/*.js"],
+			"preLaunchTask": "npm: watch"
+		}
+	]
+}

package/examples/command-webview-sample/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "editor.insertSpaces": false
+}

package/examples/command-webview-sample/.vscode/tasks.json

@@ -0,0 +1,20 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "npm",
+			"script": "watch",
+			"problemMatcher": "$tsc-watch",
+			"isBackground": true,
+			"presentation": {
+				"reveal": "never"
+			},
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			}
+		}
+	]
+}

package/examples/command-webview-sample/README.md

@@ -0,0 +1,47 @@
+# Cat Coding — A Webview API Sample
+
+Demonstrates VS Code's [webview API](https://code.visualstudio.com/api/extension-guides/webview). This includes:
+
+- Creating and showing a basic webview.
+- Dynamically updating a webview's content.
+- Loading local content in a webview.
+- Running scripts in a webview.
+- Sending message from an extension to a webview.
+- Sending messages from a webview to an extension.
+- Using a basic content security policy.
+- Webview lifecycle and handling dispose.
+- Saving and restoring state when the panel goes into the background.
+- Serialization and persistence across VS Code reboots.
+
+## Demo
+
+![demo](demo.gif)
+
+## VS Code API
+
+### `vscode` module
+
+- [`window.createWebviewPanel`](https://code.visualstudio.com/api/references/vscode-api#window.createWebviewPanel)
+- [`window.registerWebviewPanelSerializer`](https://code.visualstudio.com/api/references/vscode-api#window.registerWebviewPanelSerializer)
+
+## Running the example
+
+- Open this example in VS Code 1.47+
+- `npm install`
+- `npm run watch` or `npm run compile`
+- `F5` to start debugging
+
+Run the `Cat Coding: Start cat coding session` to create the webview.
+
+## Commands
+
+This extension provides the following commands:
+
+- `Cat Coding: Start cat coding session`: Creates and displays the Cat Coding webview.
+- `Cat Coding: Do refactor`: Halves the count of lines of code displayed in the Cat Coding webview.
+
+## Messages
+
+The Cat Coding webview can send the following messages to the extension:
+
+- `alert`: Sent when the cat introduces a bug. The message includes the text '🐛  on line ' followed by the current line count.

package/examples/command-webview-sample/media/jsconfig.json

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"module": "commonjs",
+		"target": "es2020",
+		"jsx": "preserve",
+		"checkJs": true,
+		"strict": true,
+		"strictFunctionTypes": true,
+		"lib": [
+			"dom"
+		]
+	},
+	"exclude": [
+		"node_modules",
+		"**/node_modules/*"
+	],
+	"typeAcquisition": {
+		"include": [
+			"@types/vscode-webview"
+		]
+	}
+}

package/examples/command-webview-sample/media/main.js

@@ -0,0 +1,41 @@
+// This script will be run within the webview itself
+// It cannot access the main VS Code APIs directly.
+
+(function () {
+    const vscode = acquireVsCodeApi();
+
+    const oldState = /** @type {{ count: number} | undefined} */ (vscode.getState());
+
+    const counter = /** @type {HTMLElement} */ (document.getElementById('lines-of-code-counter'));
+    console.log('Initial state', oldState);
+
+    let currentCount = (oldState && oldState.count) || 0;
+    counter.textContent = `${currentCount}`;
+
+    setInterval(() => {
+        counter.textContent = `${currentCount++} `;
+
+        // Update state
+        vscode.setState({ count: currentCount });
+
+        // Alert the extension when the cat introduces a bug
+        if (Math.random() < Math.min(0.001 * currentCount, 0.05)) {
+            // Send a message back to the extension
+            vscode.postMessage({
+                command: 'alert',
+                text: '🐛  on line ' + currentCount
+            });
+        }
+    }, 100);
+
+    // Handle messages sent from the extension to the webview
+    window.addEventListener('message', event => {
+        const message = event.data; // The json data that the extension sent
+        switch (message.command) {
+            case 'refactor':
+                currentCount = Math.ceil(currentCount * 0.5);
+                counter.textContent = `${currentCount}`;
+                break;
+        }
+    });
+}());

package/examples/command-webview-sample/media/reset.css

@@ -0,0 +1,30 @@
+html {
+	box-sizing: border-box;
+	font-size: 13px;
+}
+
+*,
+*:before,
+*:after {
+	box-sizing: inherit;
+}
+
+body,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+p,
+ol,
+ul {
+	margin: 0;
+	padding: 0;
+	font-weight: normal;
+}
+
+img {
+	max-width: 100%;
+	height: auto;
+}

package/examples/command-webview-sample/media/vscode.css

@@ -0,0 +1,91 @@
+:root {
+	--container-padding: 20px;
+	--input-padding-vertical: 6px;
+	--input-padding-horizontal: 4px;
+	--input-margin-vertical: 4px;
+	--input-margin-horizontal: 0;
+}
+
+body {
+	padding: 0 var(--container-padding);
+	color: var(--vscode-foreground);
+	font-size: var(--vscode-font-size);
+	font-weight: var(--vscode-font-weight);
+	font-family: var(--vscode-font-family);
+	background-color: var(--vscode-editor-background);
+}
+
+ol,
+ul {
+	padding-left: var(--container-padding);
+}
+
+body > *,
+form > * {
+	margin-block-start: var(--input-margin-vertical);
+	margin-block-end: var(--input-margin-vertical);
+}
+
+*:focus {
+	outline-color: var(--vscode-focusBorder) !important;
+}
+
+a {
+	color: var(--vscode-textLink-foreground);
+}
+
+a:hover,
+a:active {
+	color: var(--vscode-textLink-activeForeground);
+}
+
+code {
+	font-size: var(--vscode-editor-font-size);
+	font-family: var(--vscode-editor-font-family);
+}
+
+button {
+	border: none;
+	padding: var(--input-padding-vertical) var(--input-padding-horizontal);
+	width: 100%;
+	text-align: center;
+	outline: 1px solid transparent;
+	outline-offset: 2px !important;
+	color: var(--vscode-button-foreground);
+	background: var(--vscode-button-background);
+}
+
+button:hover {
+	cursor: pointer;
+	background: var(--vscode-button-hoverBackground);
+}
+
+button:focus {
+	outline-color: var(--vscode-focusBorder);
+}
+
+button.secondary {
+	color: var(--vscode-button-secondaryForeground);
+	background: var(--vscode-button-secondaryBackground);
+}
+
+button.secondary:hover {
+	background: var(--vscode-button-secondaryHoverBackground);
+}
+
+input:not([type='checkbox']),
+textarea {
+	display: block;
+	width: 100%;
+	border: none;
+	font-family: var(--vscode-font-family);
+	padding: var(--input-padding-vertical) var(--input-padding-horizontal);
+	color: var(--vscode-input-foreground);
+	outline-color: var(--vscode-input-border);
+	background-color: var(--vscode-input-background);
+}
+
+input::placeholder,
+textarea::placeholder {
+	color: var(--vscode-input-placeholderForeground);
+}