MIP DESKTOP · 扩展开发

快速开始

创建一个自包含的扩展页面，完成打包与开发环境验证。

更新于 2026-10-25约 5 分钟

先做一个只显示页面并保存一条本地便笺的扩展。这个示例使用公开 WebView Bridge，不依赖公共 npm SDK、业务后台或真实用户数据。

准备开发环境

准备能安装开发扩展的 Desktop 调试环境和一个文本编辑器。正式发行版的开发包安装与签名要求由发布方确认；不要把未签名示例当作正式可分发制品。

下面的版本范围只展示字段写法，发布前应根据目标 Desktop 实测收紧。当前教程提供代码与打包步骤，不声明已完成所有目标发行版的原生安装验证。

创建目录与清单

建立以下目录。.mipx 内的根目录必须直接包含 Manifest，不能多包一层项目目录。

mip.example.notes/
  manifest.json
  webviews/
    home/
      index.html
      main.js
      style.css

创建 manifest.json：

{
  "schemaVersion": 1,
  "id": "mip.example.notes",
  "displayName": "便笺示例",
  "publisher": "Example",
  "version": "1.0.0",
  "description": "演示扩展页面与私有存储。",
  "engines": {
    "desktop": ">=1.5.3",
    "extensionApi": "^1.0.0"
  },
  "permissions": ["webview", "storage"],
  "contributes": {
    "views": [
      {
        "id": "mip.example.notes.home",
        "title": "便笺示例",
        "type": "webview",
        "entry": "webviews/home/index.html"
      }
    ]
  },
  "webviews": {
    "mip.example.notes.home": "webviews/home/index.html"
  }
}

这个示例没有命令处理逻辑，因此不需要 Host main 或激活事件。

编写页面

创建 webviews/home/index.html，脚本和样式使用包内相对路径：

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>便笺示例</title>
    <link rel="stylesheet" href="./style.css">
  </head>
  <body>
    <main>
      <h1>我的便笺</h1>
      <label for="note">内容</label>
      <textarea id="note" rows="5"></textarea>
      <button id="save" type="button">保存</button>
      <p id="status" role="status" aria-live="polite"></p>
    </main>
    <script src="./main.js" defer></script>
  </body>
</html>

创建 webviews/home/main.js：

const note = document.getElementById('note');
const save = document.getElementById('save');
const status = document.getElementById('status');
const bridge = window.mip?.extension;

async function initialize() {
  save.disabled = true;
  if (!bridge?.storage) {
    save.disabled = true;
    status.textContent = '请在支持扩展存储的 Desktop 中打开此页面。';
    return;
  }
  try {
    const result = await bridge.storage.get('note');
    if (result.code !== 1) throw new Error(result.message || '读取失败');
    note.value = typeof result.data === 'string' ? result.data : '';
  } catch (error) {
    status.textContent = error instanceof Error ? error.message : '读取失败';
  } finally {
    save.disabled = false;
  }
}

save.addEventListener('click', async () => {
  if (!bridge?.storage || save.disabled) return;
  save.disabled = true;
  try {
    const result = await bridge.storage.set('note', note.value);
    if (result.code !== 1) throw new Error(result.message || '保存失败');
    status.textContent = '已保存。';
  } catch (error) {
    status.textContent = error instanceof Error ? error.message : '保存失败';
  } finally {
    save.disabled = false;
  }
});

void initialize();

创建 webviews/home/style.css：

:root {
  font: 16px/1.7 system-ui, sans-serif;
  color: var(--mip-text, #1e293b);
  background: var(--mip-bg, #f5f8fb);
}
main { max-width: 640px; margin: 32px auto; padding: 24px; }
textarea { display: block; box-sizing: border-box; width: 100%; margin: 12px 0; font: inherit; }
button { min-height: 44px; padding: 8px 20px; font: inherit; cursor: pointer; }

需要读取和跟随完整主题时，继续阅读主题与界面。

打包开发示例

.mipx 使用 ZIP 容器。在项目目录中执行对应系统的命令。

macOS / Linux：

zip -r ../mip.example.notes-1.0.0.mipx manifest.json webviews

Windows PowerShell：

Compress-Archive -Path manifest.json,webviews -DestinationPath ../mip.example.notes-1.0.0.zip -Force
Move-Item ../mip.example.notes-1.0.0.zip ../mip.example.notes-1.0.0.mipx -Force

这些命令只演示开发包容器的生成，不生成正式签名。正式发布流程见调试、打包与发布。

安装后验证

在支持开发扩展安装的 Desktop 中，进入扩展管理并选择生成的包。打开应用中心中的“便笺示例”，输入内容后保存，再关闭并重新打开页面验证读取结果。

同时验证停用和卸载：停用后入口应移除；重新启用后重新计算入口。安装失败时先查看明确错误，再按常见问题排查，避免通过扩大权限解决未知问题。

需要更完整的开发体验时，按 SDK 交付方式获取扩展 SDK，并将其打包进自己的资源。

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

#准备开发环境

#创建目录与清单

#编写页面

#打包开发示例

#安装后验证

准备开发环境

创建目录与清单

编写页面

打包开发示例

安装后验证