API 列表

picgo 本身是一个流程系统应用。除了最关键的上传之外,picgo 还支持配置、log 输出、插件、命令行交互等等功能。

ctx

picgo 传入插件的ctx其实就是 picgo 本身。ctx拥有 picgo 暴露的所有对象和方法。所以 picgo 本身拥有的方法,你在插件里使用的ctx也具备同样的方法。

首先我们来初始化一个 picgo 实例。

const PicGo = require('picgo')
const picgo = new PicGo()
1
2

接下去介绍 picgo 的详细 API。

upload([input])

picgo 的上传函数。

  • input: Array<any> || undefined
  • return: Promise<IImgInfo[] | Error> 1.4.21+

upload 接收两种情况:

  • 空数组或者undefined

当为空数组或者undefined的时候,picgo 将会上传剪贴板里的第一张图片(由于跨平台限制只能为 png 格式)。若剪贴板里不存在图片将会报错。

提示

Linux 平台需要安装xclip

示例:

picgo.upload()

// or

picgo.upload([])
1
2
3
4
5
  • 非空数组

当为非空数组的时候,对应于 picgo 默认的两种 transformer,支持 path 数组以及 base64 图片信息数组。参考 Transformer 章节。

示例:

picgo.upload(['/xxx/xxx.jpg', '/yyy/yyy.png'])
1

v1.4.21+ 开始,支持调用后获取结果:

const main = async () => {
  const res = await picgo.upload(['/xxx/xxx.jpg', '/yyy/yyy.png'])
  console.log(res) // [https://xxx.com/xxxxx.jpg, https://xxx.com/yyyyy.jpg]
}
1
2
3
4

getConfig([name])

获取 picgo 的 config 信息。

  • name: string

默认的配置长这样:

{
  "picBed": {
    "current": "smms"
  }
}
1
2
3
4
5

你可以通过getConfig()获取完整信息:

picgo.getConfig()
1

输出:

{
  "picBed": {
    "current": "smms"
  },
  "plugins": {...}
}
1
2
3
4
5
6

或者你可以选择你要查看的具体配置项:

picgo.getConfig('picBed.current') // 支持多级查找
1

输出:smms

setConfig(config)

配置 picgo 的 config 但不写入配置文件,用于上下文使用。

  • config: object

需要传入一个合法的对象去配置 picgo 的 config 信息。 这个方法不会写入配置文件 ,一次流程执行结束后不会改变配置文件本身,却可以在流程过程中实现后续部件读取的配置。

注意

如果是 GUI 插件,setConfig 虽然不会写入配置文件,但是会一直保存在 config 上下文中,如果插件有重置的需求,请在合适的地方调用 unsetConfig(见下文) 来重置 config。

示例:

picgo.setConfig({
  'picBed.current': 'gitlab'
})
1
2
3

saveConfig(config)

配置 picgo 的 config 并写入配置文件,用于持久化保存配置。

  • config: object

需要传入一个合法的对象去配置 picgo 的 config 信息。这个方法会写入配置文件,并影响之后每次 picgo 读取的配置文件。

示例:

picgo.saveConfig({
  'picgo-plugin-test': {
    xxx: 'xxx',
    yyy: 'yyy'
  }
})
1
2
3
4
5
6

unsetConfig(key, propName) 1.4.0+

删除 picgo 的 config 中的某个配置但不写入配置文件,用于上下文使用。

  • key: string
  • propName: string

传入需要删除的字段来删除 picgo 的 config 信息。 这个方法不会写入配置文件 ,一次流程执行结束后不会改变配置文件本身。

示例:

原始的 config:

{
  "picgoPlugin": {
    "picgo-plugin-xxx": { ... }
  }
}
1
2
3
4
5
picgo.unsetConfig('picgoPlugin', 'picgo-plugin-xxx')
1

unsetConfig 后的 config:

{
  "picgoPlugin": {}
}
1
2
3

removeConfig(key, propName) 1.4.0+

删除 picgo 的 config 中的某个配置并写入配置文件,用于持久化保存配置。

  • key: string
  • propName: string

传入需要删除的字段来删除 picgo 的 config 信息。 这个方法会写入配置文件 ,并影响之后每次 picgo 读取的配置文件。

示例:

原始的 config file:

{
  "picgoPlugin": {
    "picgo-plugin-xxx": { ... }
  }
}
1
2
3
4
5
picgo.removesetConfig('picgoPlugin', 'picgo-plugin-xxx')
1

removesetConfig 后的 config file:

{
  "picgoPlugin": {}
}
1
2
3

emit(event, [message])

事件派发。继承于 EventEmmitter。

  • event: string
  • message: any

通过emit可以派发事件,再通过on方法监听。

提示

一个特殊的事件名是notification,picgo 以及一些插件将会使用这个事件名,详情可以查看 消息通知章节。

示例:

picgo.emit('xxx', { message: 'xxx' })
1

on(event, [callback])

事件监听。继承于 EventEmmitter。

  • event: string
  • callback: function

通过on可以监听emit派发的事件。picgo 自带的事件可以参考 事件监听一章。

picgo.emit('xxx', message => {
  console.log(message) // { message: 'xxx' }
})
1
2
3

input

  • type: Array<any>

picgo 的输入。是一个数组。

console.log(picgo.input)
1

output

  • type: Array<any>

picgo 的输出。是一个数组。通常上传成功之后要给这个数组里每一项加入imgUrl以及url项。可以参考 picgo 默认的 smms Uploader。

注意

input 通过 Transformer 之后就会进入 output 数组中,而不是经过 Uploader 才会变成 output。

console.log(picgo.output)
1

configPath

  • type: string

picgo 的 config 所在路径。

console.log(picgo.configPath)
1

baseDir

  • type: string

picgo 的 config 文件所在的文件夹路径。

console.log(picgo.baseDir)
1

VERSION

  • type: string

获取当前 picgo 的版本。

console.log(picgo.VERSION) // x.x.x
1

GUI_VERSION

  • type: string || undefined

如果当前环境为 PicGo GUI,可以获取当前 PicGo GUI 的版本,否则是undefined。

console.log(picgo.GUI_VERSION) // x.x.x
1

helper

helper 是 picgo 的主要插件的集中管理者,包含 5 个部件,拥有相同的 api,不过所在生命周期不同,详情可见 生命周期流程。因此只介绍helper.transformer即可。

helper.transformer

register(id, plugin)

  • id: string
  • plugin: object

如果你只是要开发一个简单的插件,而不是发布一个 npm 包的话(发布 picgo 的 npm 插件包请查看 插件开发指南),那么只需要调用helper[module].register方法即可。

第一个参数代表插件的 id(相同的部件只能拥有唯一的 id,不过不同的部件可以拥有相同的 id),第二个参数应当是一个对象,至少包括一个handle方法供 picgo 调用。如果你还想要拥有 配置项功能,可以考虑再加入config方法供 picgo 调用。

示例:

picgo.helper.transformer.register('test', {
  handle (ctx) {
    return ctx
  },
  config (ctx) {
    return [...]
  }
})
1
2
3
4
5
6
7
8

helper.uploader

同上。

helper.beforeTransformPlugins

同上,不过不拥有配置项功能。

helper.beforeUploadPlugins

同上,不过不拥有配置项功能。

helper.afterUploadPlugins

同上,不过不拥有配置项功能。

Request.request

v1.5.0开始这个属性将被废弃,请直接使用 ctx.request

Request.request 是 picgo 内部暴露的一个 Request-Promise-Native 对象,拥有一个可以使用 request 库里的所有方法,并且返回的是原生的 Promise。

小贴士

值得注意的是,使用这个对象来发送请求的话,能自动读取用户配置给 picgo 的 proxy 值。比较适合用于书写 Uploder 的核心部分。

示例:

picgo.Request.request({
  method: 'post',
  uri: 'xxxx',
  body: fs.readFileSync('yyy')
})
1
2
3
4
5

request 1.4.16+

v1.4.16 开始,默认的请求方法从 ctx.Request.request 换成了 ctx.request。目前的底层实现是 Request-Promise-Native ,从 v1.5.0 开始,将会换成 got

示例:

picgo.request({
  method: 'post',
  uri: 'xxxx',
  body: fs.readFileSync('yyy')
})
1
2
3
4
5

cmd

用于提供 picgo 的命令行程序。

cmd.program

用于注册 CLI 命令。实际上是一个 commander.js 的实例,用法和commander.js几乎一致。 不过请不要手动调用 picgo.cmd.program.parse(process.argv) 否则会导致出错 。参考 [注册命令](/zh/dev-guide/cli.html#注册 cli 命令)一章。

示例:

picgo.cmd.program
  .commands('test', 'This is a test commands')
  .action(() => {
    console.log(123)
  })
1
2
3
4
5

cmd.inquirer

用于提供 CLI 命令行交互。实际上是一个 inquirer.js 的实例,用法和inquirer.js一致。参考 [配置项的处理](/zh/dev-guide/cli.html#配置项的处理)一章。通常 PicGo 内部会将其和插件的 [config](/zh/dev-guide/cli.html#config 方法)方法一起使用。

示例:

const handleConfig = async ctx => {
  const prompts = config(ctx)
  const answer = await ctx.cmd.inquirer.prompt(prompts)
  ctx.saveConfig({ // 调用 saveConfig 保存配置
    'picBed.xxx': answer
  })
}
1
2
3
4
5
6
7

提示

你可以通过这个工具来制作你自己的命令行交互。不过需要注意的是,通常你应该直接使用插件的 [config](/zh/dev-guide/cli.html#config 方法)方法来实现命令行交互,并且 PicGo 会自动存储config相关配置项的结果。

log

用于在命令行输出漂亮的信息,给予用户提示。

截图:

log.info(message)

  • message: string

示例:

picgo.log.info('Hello world')
1

log.warn(message)

  • message: string

示例:

picgo.log.warn('Hello world')
1

log.success(message)

  • message: string

示例:

picgo.log.success('Hello world')
1

log.error(message)

  • message: string | error

示例:

picgo.log.error('Hello world')
1

PluginHandler 1.4.0+

提供了安装、更新、卸载 picgo 插件的底层接口。同时还暴露了对应的成功、失败事件用于开发者处理。 它依赖于系统 npm 命令。

pluginHandler.install([...pluginName])

用于安装插件,接收一个数组作为参数。其中 pluginName

  1. 可以为完整的 picgo 插件名字,比如 picgo-plugin-xxx
  2. 也可以是简化名 xxx
  3. 支持scope类型插件,比如 @xxx/picgo-plugin-yyy
  4. 还支持本地路径。例如 ./xxx/yyy/picgo-plugin-zzz
const res = picgo.pluginHandler.install(['xxx'])
picgo.on('installSuccess', (res) => {
  console.log(res) // ['picgo-plugin-xxx']
})
picgo.on('installFailed', err => {})

// v1.4.19 开始会直接返回调用结果。示例:
res.then((result) => {
  if (result.success) {
    console.log(result.body) // ['picgo-plugin-xxx']
  } else {
    console.log(result.body) // error message
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14

pluginHandler.uninstall([...pluginName])

用于卸载插件,接收一个数组作为参数。其中 pluginName

  1. 可以为完整的 picgo 插件名字,比如 picgo-plugin-xxx
  2. 也可以是简化名 xxx
  3. 支持scope类型插件,比如 @xxx/picgo-plugin-yyy
  4. 还支持本地路径。例如 ./xxx/yyy/picgo-plugin-zzz
const res = picgo.pluginHandler.uninstall(['xxx'])
picgo.on('uninstallSuccess', (res) => {
  console.log(res) // ['picgo-plugin-xxx']
})
picgo.on('uninstallFailed', err => {})

// v1.4.19 开始会直接返回调用结果。示例:
res.then((result) => {
  if (result.success) {
    console.log(result.body) // ['picgo-plugin-xxx']
  } else {
    console.log(result.body) // error message
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14

pluginHandler.update([...pluginName])

用于更新插件,接收一个数组作为参数。其中 pluginName

  1. 可以为完整的 picgo 插件名字,比如 picgo-plugin-xxx
  2. 也可以是简化名 xxx
  3. 支持scope类型插件,比如 @xxx/picgo-plugin-yyy
  4. 还支持本地路径。例如 ./xxx/yyy/picgo-plugin-zzz
const res = picgo.pluginHandler.update(['xxx'])
picgo.on('updateSuccess', (res) => {
  console.log(res) // ['picgo-plugin-xxx']
})
picgo.on('updateFailed', err => {})

// v1.4.19 开始会直接返回调用结果。示例:
res.then((result) => {
  if (result.success) {
    console.log(result.body) // ['picgo-plugin-xxx']
  } else {
    console.log(result.body) // error message
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14

PluginLoader 1.4.17+

提供了动态加载、卸载 picgo 插件的方法。比较适合用于在 Node 项目中使用 picgo 时动态引入插件。

pluginLoader.registerPlugin(pluginName, plugin)

用于注册并加载插件。

示例:

const pluginXXX = require('picgo-plugin-xxx')

// 注意pluginName要唯一
picgo.pluginLoader.registerPlugin('xxx', pluginXXX)
1
2
3
4

pluginLoader.unregisterPlugin(pluginName)

用于卸载插件。

示例:

// 注意pluginName要唯一
picgo.pluginLoader.unregisterPlugin('xxx')
1
2

pluginLoader.getPlugin(pluginName)

用于获取某个插件。

示例:

const plugin = picgo.pluginLoader.getPlugin('xxx')
1

pluginLoader.hasPlugin(pluginName)

用于确认是否存在某个插件。

  • return: boolean

示例:

const res = picgo.pluginLoader.hasPlugin('xxx') // true or false
1

guiApi GUI VERSION 2.0.0+

guiApi 仅在 electron 版本的 PicGo 里提供,详细信息可以参考 GUI 插件开发一章

guiApi.showInputBox([option])

调用之后打开一个输入弹窗,可以用于接受用户输入。

  • option: Object || undefined
  • return: 返回一个 Promise 对象,resolve 的值是用户输入的结果。

其中 option 是可选值,可以传入一个{title, placeholder}的对象,用于弹窗的标题和输入框的placeholder显示。

const guiMenu = ctx => {
  return [
    {
      label: '打开 InputBox',
      async handle (ctx, guiApi) {
        const value = await guiApi.showInputBox({
          title: '打开对话框',
          placeholder: '请输入文件地址'
        })
        console.log(value)
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

guiApi.showFileExplorer([option])

调用之后打开一个文件浏览器,可以得到用户选择的文件(夹)路径。

  • option: Object || undefined
  • return: 返回一个 Promise 对象,resolve 的值是用户选择的文件路径数组。

其中 option 是可选值,可以传入一个合法的 electron 的 dialog 的 options 对象,用于指定是否可多选,用于选择文件还是文件夹等等。

const guiMenu = ctx => {
  return [
    {
      label: '打开文件浏览器',
      async handle (ctx, guiApi) {
        const files = await guiApi.showFileExplorer({
          properties: ['openFile', 'multiSelections']
        })
        console.log(files)
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

guiApi.upload([file])

调用之后使用 PicGo 底层来上传,可以实现自动更新相册图片、上传成功后自动将 URL 写入剪贴板。

  • file: Array || undefined
  • return: 返回一个 Promise 对象,resolve 的值是 PicGo 上传成功后的 output 值,是一个数组。所以推荐用async await获取。

提示

实际上如果通过上面的showInputBox获得输入项,或者showFileExplorer选中文件,再通过upload上传的话,也可以很好的达到上传的目的。 推荐还是书写 Uploader 或者 Transformer 等插件,来实现接管 PicGo 的上传流程。

示例:

const guiMenu = ctx => {
  return [
    {
      label: '独立上传',
      async handle (ctx, guiApi) {
        const files = await guiApi.showFileExplorer({
          properties: ['openFile', 'multiSelections'
        })
        guiApi.upload(files)
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

guiApi.showNotification(option) 2.0.1+

调用之后弹出系统通知窗口。

  • option: Object || undefined
  • return: undefined(无返回值)

其中 option 是必选值,需要提供{title, body}用于通知窗口的显示。

示例:

const guiMenu = ctx => {
  return [
    {
      label: '显示通知',
      async handle (ctx, guiApi) {
        guiApi.showNotification({
          title: '提示',
          body: '本提示来自插件'
        })
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

guiApi.showMessageBox([option]) 2.1.0+

调用之后弹出系统的对话框窗口。

  • option: Object || {title: '', message: '', type: 'info', buttons: ['Yes', 'No']}
  • return: Object -> {result, checkboxChecked}

其中,option 的完整参数可以参考 Electron 的 dialog.showMessageBox。返回的值里,result为你指定的 buttons 的 index 值。比如上图如果我点了是 (Y), 那么我会收到如下返回值:

{
  result: 0,
  checkboxChecked: false // 如果你在 options 里指定了 checkboxLabel 则会出现一个 checkbox,如果不提供,默认返回 false
}
1
2
3
4

示例:

const guiMenu = ctx => {
  return [
    {
      label: '显示 MessageBox',
      async handle (ctx, guiApi) {
        const result = await guiApi.showMessageBox({
          title: '这是 title',
          message: '这是 message',
          type: 'info',
          buttons: ['Yes', 'No']
        })
        console.log(result) // { result: 0, checkboxChecked: false }
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

guiApi.galleryDB GUI VERSION 2.3.0+

从 PicGo GUI 2.3.0 开始,相册数据使用 galleryDB 操作,不再使用 config 里的 uploaded 字段。

galleryDB的使用可以参考 PicGo/store 提供的api,以此为准。下文不一定更新及时。

galleryDB.get(filter?)

获取相册列表。可以提供filter字段用于过滤,如果不提供则默认获取全部列表。示例:

const guiMenu = ctx => {
  return [
    {
      label: '获取相册数据',
      async handle (ctx, guiApi) {
        const result = await guiApi.galleryDB.get({
          orderBy: 'asc', // 升序
          limit: 10, // 取10个
          offset: 5 // 从index 5之后开始取(slice(5))
        })
        console.log(result) // [{...}, {...}, {...}, ...]
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

galleryDB.insert(value)

往相册中插入数据。注意插入的数据一定要是符合要求的 output 中的格式(参考 transformer 一章,否则无法展示在相册中。

galleryDB.insertMany([...value])

往相册中批量插入数据。注意插入的数据一定要是符合要求的 output 数组格式(参考 transformer 一章,否则无法展示在相册中。

galleryDB.updateById(id, value)

  • id: string 相册中某张图片的id
  • value: IImgInfo
  • return: Promise<boolean>

根据相册数据中的id更新某张图片的信息。返回boolean。如果更新成功返回true,反之返回false。

galleryDB.getById(id)

  • id: string 相册中某张图片的id
  • return: Promise<IImgInfo>

根据id获取某张图片的信息。

galleryDB.removeById(id)

  • id: string 相册中某张图片的id
  • return: void

根据id删除某张图片的信息。无返回值。

注意,删除图片是敏感操作,GUI版本会提示用户是否允许删除。