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

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

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信息。 这个方法不会写入配置文件 ,一次流程执行结束后不会改变配置文件本身,却可以在流程过程中实现后续部件读取的配置。

示例:

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

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

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

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

cmd

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

cmd.program

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

示例:

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一致。参考配置项的处理一章。通常PicGo内部会将其和插件的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方法来实现命令行交互,并且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

guiApi

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

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

upload([file])

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

  • file: Array || undefined
  • return: 返回一个Promise对象,resolve的值是PicGo上传成功后的output值,是一个数组。