window.source 元数据参考

每个插件必须向 window.source 赋值一个对象，声明插件的元信息。本章列出所有字段的详细说明。

必填字段

字段	类型	说明	示例
`id`	`string`	插件唯一标识，格式为大写字母 + 下划线	`SUCH_NETEASE_NCM_WIDGET`
`name`	`string`	插件显示名称	`网易云音乐 NCM 解析器`
`version`	`string`	语义化版本号 (SemVer)	`1.0.0`
`author`	`string`	作者名称	`enzymeym`

id 命名规范

使用大写字母和下划线
前缀建议使用 SUCH_ 避免与未来内置功能冲突
体现插件用途，例如 SUCH_NETEASE_IMPORT、SUCH_BILIBILI_DOWNLOAD

// ✅ 推荐
id: 'SUCH_NETEASE_NCM_WIDGET'

// ❌ 不规范
id: 'my-plugin'
id: 'such-ncm'

可选字段

字段	类型	默认值	说明
`icon`	`string`	—	图标 URL，支持 SVG / PNG / 远程链接
`description`	`string`	—	插件功能描述文字，展示在插件列表
`permissions`	`string[]`	`[]`	权限列表，声明所需宿主能力
`isUIWidget`	`boolean`	`false`	是否为 UI 插件（有 uiSchema 时须设为 `true`）
`uiSchema`	`PluginUISchema`	—	JSON UI Schema，定义插件前端界面

生命周期方法

initialization()

插件加载时由宿主调用一次，适合执行初始化逻辑：

initialization() {
  console.log('插件已加载')
  // 读取设置、初始化状态等
  const musicFolder = suchmusic.getSetting('musicFolder')
  this.setProps({ musicFolder })
}

checkUpdate()

检查插件更新，被宿主在「检查更新」时调用。返回 null 或不实现此方法时，表示暂不支持更新检查。

async checkUpdate() {
  try {
    const response = await suchmusic.fetch('https://api.example.com/plugin/latest-version')
    const latest = await response.json()

    if (latest.version !== this.version) {
      return {
        hasNew: true,
        version: latest.version,
        url: latest.downloadUrl,
        changelog: latest.changelog
      }
    }
    return { hasNew: false, version: '', url: '', changelog: '' }
  } catch {
    // 网络异常时返回 null 表示检查失败
    return null
  }
}

返回值类型：

interface CheckUpdateResult {
  hasNew: boolean
  version: string
  url: string
  changelog: string
}

⚠️ 更新检查由插件开发者自行实现，通常通过请求 GitHub Releases API 或其他版本接口获取最新版本号，与 this.version 比较。

完整示例

window.source = {
  // 必填
  id: 'SUCH_NETEASE_NCM_WIDGET',
  name: '网易云音乐 NCM 解析器',
  version: '1.0.0',
  author: 'enzymeym',

  // 可选
  icon: 'https://example.com/ncm-icon.svg',
  description: '支持解析 .ncm 文件并转换为 MP3 格式',
  permissions: ['local_program', 'file_system', 'app_info', 'fetch'],
  isUIWidget: true,
  uiSchema: { /* ... */ },

  // 生命周期
  initialization() {
    console.log('NCM 解析器已就绪')
  },

  async checkUpdate() {
    // ...
  }
}

window.source 元数据参考

window.source 元数据参考

必填字段

id 命名规范

可选字段

生命周期方法

initialization()

checkUpdate()

完整示例

相关参考

On this page