mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-05-04 14:40:45 +00:00
7ca7fec18d
- Add comprehensive Adapter-README documenting data transformation flow - Update README.md with correct package name (@qwen-code/webui) - Add platform adapter guide for Chrome/Web/Share implementations - Update Storybook configuration and preview styles - Remove obsolete migration plan and example component Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
122 lines
3.7 KiB
Markdown
122 lines
3.7 KiB
Markdown
## WebUI Platform Adapter Guide (Chrome / Web / Share)
|
|
|
|
This guide is for extending `@qwen-code/webui` to new runtime platforms (e.g., Chrome Extension, pure Web pages, Share pages).
|
|
|
|
For VSCode adapter implementation reference, see:
|
|
`packages/vscode-ide-companion/src/webview/context/VSCodePlatformProvider.tsx`
|
|
|
|
---
|
|
|
|
### 1. Core Goals
|
|
|
|
- Reuse WebUI **without modifying UI components**.
|
|
- Inject platform capabilities via `PlatformProvider` (messaging, files, login, clipboard, etc.).
|
|
- Provide **fallback solutions** or mark `features` for missing capabilities.
|
|
|
|
---
|
|
|
|
### 2. PlatformContext Key Points (Minimum Implementation)
|
|
|
|
Required fields:
|
|
|
|
- `platform`: `'chrome' | 'web' | 'share'`
|
|
- `postMessage`: Send messages to host
|
|
- `onMessage`: Subscribe to host messages
|
|
|
|
Optional capabilities (by platform support):
|
|
|
|
- `openFile`
|
|
- `openDiff`
|
|
- `openTempFile`
|
|
- `attachFile`
|
|
- `login`
|
|
- `copyToClipboard`
|
|
- `getResourceUrl`
|
|
- `features` (mark capability availability)
|
|
|
|
Type definitions location:
|
|
`packages/webui/src/context/PlatformContext.tsx`
|
|
|
|
---
|
|
|
|
### 3. Adaptation Steps (Recommended Flow)
|
|
|
|
1. **Set up message channel**
|
|
- Chrome Extension: `chrome.runtime.sendMessage` + `chrome.runtime.onMessage`
|
|
- Web/Share: `window.postMessage` + `message` event, or custom event bus
|
|
|
|
2. **Implement PlatformProvider**
|
|
- Map platform APIs to `PlatformContextValue`
|
|
- Return `undefined` for missing capabilities and set `features`
|
|
|
|
3. **Application entry integration**
|
|
- Wrap with `<PlatformProvider value={platformValue}>` at platform entry
|
|
- Ensure all UI components are within the Provider
|
|
|
|
4. **Styles and themes**
|
|
- Import `@qwen-code/webui/styles.css`
|
|
- Define CSS variables on platform side (can copy initial values from `packages/webui/src/styles/variables.css`)
|
|
|
|
5. **Build and dependencies**
|
|
- Tailwind uses `@qwen-code/webui/tailwind.preset`
|
|
- `content` must include `node_modules/@qwen-code/webui/dist/**/*.js`
|
|
|
|
6. **Feature validation**
|
|
- Message send/receive works (`postMessage`/`onMessage`)
|
|
- Clicking file/diff output doesn't throw errors (can fallback)
|
|
- `@`/`/` completion and input box interactions work
|
|
|
|
---
|
|
|
|
### 4. Reference Implementation (Web Platform Example)
|
|
|
|
```tsx
|
|
import type React from 'react';
|
|
import { PlatformProvider } from '@qwen-code/webui';
|
|
import type { PlatformContextValue } from '@qwen-code/webui';
|
|
|
|
const platformValue: PlatformContextValue = {
|
|
platform: 'web',
|
|
postMessage: (message) => {
|
|
window.postMessage(message, '*');
|
|
},
|
|
onMessage: (handler) => {
|
|
const listener = (event: MessageEvent) => handler(event.data);
|
|
window.addEventListener('message', listener);
|
|
return () => window.removeEventListener('message', listener);
|
|
},
|
|
copyToClipboard: async (text) => navigator.clipboard.writeText(text),
|
|
features: {
|
|
canCopy: true,
|
|
},
|
|
};
|
|
|
|
export const WebPlatformProvider: React.FC<{ children: React.ReactNode }> = ({
|
|
children,
|
|
}) => <PlatformProvider value={platformValue}>{children}</PlatformProvider>;
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Chrome Extension Suggested Mapping
|
|
|
|
- `postMessage` -> `chrome.runtime.sendMessage`
|
|
- `onMessage` -> `chrome.runtime.onMessage.addListener`
|
|
- `openFile`/`openDiff` -> Trigger background script to open tab / side panel
|
|
- `attachFile` -> `chrome.tabs` or `<input type="file">`
|
|
|
|
---
|
|
|
|
### 6. Web/Share Scenario Fallback Strategies
|
|
|
|
- `openFile/openDiff`: Display content in new window/modal
|
|
- `openTempFile`: Generate `Blob` and open or download
|
|
- `login`: Redirect to login URL or popup login window
|
|
|
|
---
|
|
|
|
### 7. Common Pitfalls
|
|
|
|
- Tailwind styles not working: `content` missing `@qwen-code/webui`
|
|
- Theme colors not working: `styles.css` not loaded or CSS variables not set
|
|
- `postMessage` no response: Host side hasn't registered corresponding message channel
|