# 插件开发指南

# 插件开发入门

本章带你从 0 写出一个可加载、可重载、能扩展 UI 的 ASG.Director 插件，并把“真实可用的 API”串起来。

你需要会什么

基础 JavaScript（ES6+） 即可；了解 Node.js / Electron 会更顺手。

# 1. 插件放在哪里？

最常用的是把插件文件夹放到用户插件目录（手动安装路径见：插件使用指南）。

开发时建议配合：启动台 → 插件管理 → 重载，做到“改代码 → 重载 → 立即验证”。

# 2. 最小可用插件（Hello + 命令 + 状态栏）

创建一个文件夹，例如 demo-hello/，包含两个文件：

# (1) package.json

{
  "name": "demo-hello",
  "displayName": "示例：Hello",
  "version": "0.1.0",
  "description": "我的第一个 ASG.Director 插件",
  "main": "index.js",
  "engines": {
    "asg-director": ">=1.4.0"
  },
  "activationEvents": ["onStartup"],
  "contributes": {
    "commands": [
      { "command": "demoHello.sayHello", "title": "示例：打个招呼" }
    ]
  }
}

更完整的字段解释见：插件清单（package.json）

# (2) index.js

async function activate(context) {
  context.log('插件激活：', context.pluginId)

  // 1) 注册命令
  const cmd = context.api.commands.registerCommand('demoHello.sayHello', async () => {
    const counter = context.globalState.get('counter', 0) + 1
    context.globalState.set('counter', counter)
    context.api.notifications.showInfo(`Hello！已触发 ${counter} 次`)
  })
  context.subscriptions.push(cmd)

  // 2) 放一个状态栏提示（可选）
  const item = context.api.statusBar.createStatusBarItem('right', 100)
  item.text = 'Demo 插件已加载'
  item.tooltip = '点击执行：demoHello.sayHello'
  item.command = 'demoHello.sayHello'
  item.show()
  context.subscriptions.push(item)
}

function deactivate() {
  // 如果你把 disposable 都 push 到 context.subscriptions
  // 停用/重载时会自动 dispose，无需额外清理
}

module.exports = { activate, deactivate }

# 3. 扩展 UI（卡片/页面/菜单/前台组件）

如果你希望在启动台主页加卡片、加一个插件页面，或往前台画面加“可拖拽组件”，请看：

UI 扩展：卡片 / 页面 / 菜单 / 前台组件

# 4. API 与存储（以实现为准）

插件 context 的真实字段（globalState/workspaceState/subscriptions/api 等）与常用 API 用法见：

插件 API 与 Context

# 5. 调试与排错

调试与排错

插件清单（package.json） →