MIP Desktop开发文档
应用下载下载 Desktop
跳到文档正文
章节目录 主题与界面

MIP DESKTOP · 扩展开发

主题与界面

跟随宿主主题，让扩展页面融入同一个工作环境。

更新于 约 2 分钟

宿主负责窗口、标签页与容器，扩展负责页面内部。通过公开主题上下文保持一致，而不是复制宿主组件和整套样式。

使用主题变量

为页面定义合理的默认值，并使用宿主提供的 --mip-* 变量：

CSS
:root {
  color: var(--mip-text, #1e293b);
  background: var(--mip-bg, #f5f8fb);
  font: 16px/1.7 system-ui, sans-serif;
}
.panel {
  padding: 20px;
  color: var(--mip-text, #1e293b);
  background: var(--mip-surface, #ffffff);
  border: 1px solid var(--mip-border, #dbe5ee);
  border-radius: 8px;
}

采用组件库时，在扩展自己的样式中映射变量。不要依赖宿主内部 CSS 类名或把 Desktop 的完整前端依赖复制进包。

应用并监听主题

先读取初始主题，再监听变化；只处理协议公开的主题变量。

TypeScript
import { createExtensionSdk } from '@mip/desktop-extension-sdk/webview';

const sdk = createExtensionSdk();
function applyTheme(theme: ReturnType<typeof sdk.theme.get>) {
  if (!theme) return;
  document.documentElement.dataset.theme = theme.resolved;
  for (const [name, value] of Object.entries(theme.variables)) {
    if (name.startsWith('--mip-')) {
      document.documentElement.style.setProperty(name, value);
    }
  }
}

applyTheme(sdk.theme.get());
sdk.lifecycle.add(sdk.theme.onDidChange(applyTheme));
window.addEventListener('pagehide', () => {
  void sdk.lifecycle.dispose();
}, { once: true });

未知字段忽略处理，旧宿主缺少主题能力时保留默认样式。页面刷新后重新读取当前上下文。

保持页面职责清楚

扩展页面不重复绘制 Desktop 的窗口栏、主侧栏和标签栏。页面标题、主要操作、内容区和错误状态在自己的容器内组织。

长内容合理限制行宽，表格和代码块在自身区域滚动，避免整页横向溢出。加载、空数据、失败和无权限状态应分别表达。

检查可访问性

  • 浅色与深色分别检查文字和控件对比度。
  • 为输入提供可见标签，为仅图标按钮提供可访问名称。
  • 使用真实按钮和链接，保留键盘焦点提示。
  • 窄窗口和系统字号放大后，内容仍可阅读和操作。
  • 状态变化提供文字反馈，不能只依赖颜色。

基础契约：Extension API 1.x；具体能力以目标 Desktop 发行版为准。