@xz-summer/summer-types

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

> 📖 English Documentation

安装

``bash
npm install @xz-summer/summer-types --save-dev

或

pnpm add @xz-summer/summer-types -D
`

快速开始

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

export default class MyPlugin implements ISummerPlugin {
async onLoad(ctx: BaseContext): Promise {
// 注册设置
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 {
// 清理资源
}
}
`

主要特性

$3

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

$3

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

$3

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

核心类型

$3

`typescript
interface ISummerPlugin {
// 运行时自动注入（可选）
id?: string
manifest?: PluginManifest

// 必需方法
onLoad(ctx: BaseContext): void | Promise
onUnload(ctx: BaseContext): void

// 可选生命周期钩子
onBeforeInit?(ctx: BaseContext): void | Promise
onInit?(ctx: BaseContext): void | Promise
onAfterInit?(ctx: BaseContext): void | Promise
onBeforeReady?(ctx: BaseContext): void | Promise
onReady?(ctx: BaseContext): void | Promise
onBeforeDestroy?(ctx: BaseContext): void | Promise
onDestroy?(ctx: BaseContext): void | Promise

// Editor 相关钩子
onBeforeEditorCreate?(ctx: EditorConfigContext): void | Promise
onEditorCreated?(ctx: EditorInstanceContext): void | Promise
onEditorReady?(ctx: EditorInstanceContext): void | Promise
onBeforeEditorDestroy?(ctx: EditorInstanceContext): void | Promise
onEditorDestroyed?(ctx: BaseContext): void | Promise
}
`

$3

`typescript
// 基础上下文（所有生命周期可用）
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
}
`

$3

`typescript
// 事件 API
interface EventAPI {
emit(event: string, payload?: T): void
on(event: string, handler: EventHandler): UnsubscribeFn
once(event: string, handler: EventHandler): 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'
}
`

使用示例

$3

`typescript
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' })
}
`

$3

`typescript
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: '🎨'
})
}
`

$3

`typescript
async onBeforeEditorCreate(ctx: EditorConfigContext) {
// 注册 Milkdown 插件
ctx.editor.use(myMilkdownPlugin)

// 配置 Milkdown
ctx.editor.config((milkdownCtx) => {
milkdownCtx.set(/ ... /)
})
}
`

$3

`typescript
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