@xz-summer/summer-types

Summer 插件开发 TypeScript 类型定义包。

📖 English Documentation

安装

npm install @xz-summer/summer-types --save-dev
# 或
pnpm add @xz-summer/summer-types -D

快速开始

import type { ISummerPlugin, BaseContext } from '@xz-summer/summer-types'

export default class MyPlugin implements ISummerPlugin {
  async onLoad(ctx: BaseContext): Promise<void> {
    // 注册设置
    ctx.settings.register([
      {
        key: 'myOption',
        label: '我的选项',
        type: 'boolean',
        default: true
      }
    ])
    
    // 监听事件（使用 Events 常量）
    ctx.events.on(ctx.Events.FILE_OPEN, (data) => {
      console.log('文件打开:', data.path)
    })
  }
  
  onUnload(ctx: BaseContext): void {
    // 清理资源
  }
}

主要特性

✨ 纯类型定义

• 只包含类型定义，不包含运行时代码
• 可以放在 devDependencies 中
• 零运行时开销

🎯 自动注入

• 插件不需要写 constructor
• id 和 manifest 由运行时自动注入
• 代码更简洁

🔒 类型安全

• 完整的 TypeScript 类型支持
• 通过 ctx.Events 访问事件常量
• IDE 自动补全和类型检查

核心类型

插件接口

interface ISummerPlugin {
  // 运行时自动注入（可选）
  id?: string
  manifest?: PluginManifest
  
  // 必需方法
  onLoad(ctx: BaseContext): void | Promise<void>
  onUnload(ctx: BaseContext): void
  
  // 可选生命周期钩子
  onBeforeInit?(ctx: BaseContext): void | Promise<void>
  onInit?(ctx: BaseContext): void | Promise<void>
  onAfterInit?(ctx: BaseContext): void | Promise<void>
  onBeforeReady?(ctx: BaseContext): void | Promise<void>
  onReady?(ctx: BaseContext): void | Promise<void>
  onBeforeDestroy?(ctx: BaseContext): void | Promise<void>
  onDestroy?(ctx: BaseContext): void | Promise<void>
  
  // Editor 相关钩子
  onBeforeEditorCreate?(ctx: EditorConfigContext): void | Promise<void>
  onEditorCreated?(ctx: EditorInstanceContext): void | Promise<void>
  onEditorReady?(ctx: EditorInstanceContext): void | Promise<void>
  onBeforeEditorDestroy?(ctx: EditorInstanceContext): void | Promise<void>
  onEditorDestroyed?(ctx: BaseContext): void | Promise<void>
}

Context 类型

// 基础上下文（所有生命周期可用）
interface BaseContext {
  events: EventAPI
  Events: EventsConstant  // 事件常量
  slots: SlotAPI
  tabs: TabAPI
  storage: StorageAPI
  commands: CommandAPI
  settings: SettingsAPI
  services: ServiceAPI
  lifecycle: LifecycleAPI
  ui: UIAPI
  menu: MenuAPI
  manifest: PluginManifest
}

// Editor 配置上下文（onBeforeEditorCreate）
interface EditorConfigContext extends BaseContext {
  editor: EditorConfigAPI
}

// Editor 实例上下文（onEditorCreated, onEditorReady 等）
interface EditorInstanceContext extends BaseContext {
  editor: EditorInstanceAPI
}

事件系统

// 事件 API
interface EventAPI {
  emit<T>(event: string, payload?: T): void
  on<T>(event: string, handler: EventHandler<T>): UnsubscribeFn
  once<T>(event: string, handler: EventHandler<T>): UnsubscribeFn
}

// 事件常量（通过 ctx.Events 访问）
interface EventsConstant {
  // 文件相关
  FILE_OPEN: 'file:open'
  FILE_NEW: 'file:new'
  FILE_OPEN_DIALOG: 'file:open-dialog'
  FILE_OPEN_FOLDER: 'file:open-folder'
  FILE_SYSTEM_CHANGED: 'file:system-changed'
  
  // 编辑器相关
  EDITOR_READY: 'editor:ready'
  EDITOR_CHANGE: 'editor:change'
  EDITOR_VIEW_MODE_SWITCH: 'editor:switchViewMode'
  
  // 设置相关
  SETTINGS_TOGGLE: 'settings:toggle'
  SETTINGS_CLOSE: 'settings:close'
  SETTINGS_REGISTERED: 'settings:registered'
  SETTINGS_CHANGED: 'settings:changed'
  SETTINGS_BATCH_CHANGED: 'settings:batch-changed'
  
  // 插件管理器
  PLUGIN_MANAGER_OPEN: 'plugin-manager:open'
  PLUGIN_MANAGER_CLOSE: 'plugin-manager:close'
  
  // 根目录
  ROOT_REMOVE: 'root:remove'
}

使用示例

监听和发送事件

async onLoad(ctx: BaseContext) {
  // 监听文件打开事件
  ctx.events.on(ctx.Events.FILE_OPEN, (data) => {
    console.log('文件打开:', data.path)
  })
  
  // 发送自定义事件
  ctx.events.emit('my-plugin:custom-event', { data: 'value' })
}

注册设置

async onLoad(ctx: BaseContext) {
  ctx.settings.register([
    {
      key: 'enabled',
      label: '启用功能',
      type: 'boolean',
      default: true
    },
    {
      key: 'theme',
      label: '主题',
      type: 'select',
      default: 'dark',
      options: [
        { label: '深色', value: 'dark' },
        { label: '浅色', value: 'light' }
      ]
    }
  ], {
    category: '我的插件',
    icon: '🎨'
  })
}

注册 Milkdown 插件

async onBeforeEditorCreate(ctx: EditorConfigContext) {
  // 注册 Milkdown 插件
  ctx.editor.use(myMilkdownPlugin)
  
  // 配置 Milkdown
  ctx.editor.config((milkdownCtx) => {
    milkdownCtx.set(/* ... */)
  })
}

访问 Editor 实例

async onEditorReady(ctx: EditorInstanceContext) {
  // 获取内容
  const content = ctx.editor.getContent()
  
  // 设置内容
  ctx.editor.setContent('# Hello World')
  
  // 监听内容变化
  ctx.editor.onContentChange((newContent) => {
    console.log('内容变化:', newContent)
  })
}

更新日志

查看 CHANGELOG.md 了解版本更新详情。

文档

完整文档请访问：Summer 插件开发指南

许可证

MIT