Script System

From version v3.3.0, PicList has introduced a script system that allows users to extend and customize PicList's functionality through custom scripts.

Introduction

Unlike the plugin system derived from PicGo, PicList's script system is designed to be lightweight and easy to use. The plugin system requires users to have a Node.js environment installed on their local machine, and plugins need to go through packaging and publishing processes. Installation is also limited by network conditions and requires downloading many dependencies.

In the script system, users can write JavaScript scripts directly within the software to achieve specific functions without needing to install a Node.js environment. Scripts can access PicList's core APIs and some built-in modules to perform operations such as file uploading, processing, and management.

The script system is suitable for the following scenarios:

• Custom upload processes: Customize file upload logic based on specific needs
• Batch file processing: Implement batch renaming, categorization, and other functions
• Integration with third-party services: Call external APIs through scripts to integrate with other services
• Automated tasks: Schedule certain operations, such as regular file cleanup
• Customized requirements: Meet individual special needs

Using Scripts

Script Creation and Management

Open PicList and navigate to the Scripts interface, where you can create, edit, and manage scripts. By default, PicList stores script files in the scripts folder within the user data directory.

Writing Scripts

PicList's scripts are categorized based on their execution timing:

• On software startup: Executed when PicList starts, suitable for initialization operations
• On software shutdown: Executed before PicList closes, suitable for cleanup operations
• Before upload processing: Executed immediately after operations such as watermarking and compression during file upload, suitable for final processing of uploaded files
• Before image transformation: Corresponds to the beforeTransformer hook in plugins
• During image transformation: Corresponds to the transformer hook in plugins
• Before upload: Corresponds to the beforeUpload hook in plugins
• During upload: Corresponds to the uploader hook in plugins
• After upload: Corresponds to the afterUpload hook in plugins
• On successful upload: Executed after upload completion and image insertion into the gallery
• On album deletion: Executed when images are deleted from the album, suitable for synchronizing deletion of files in third-party storage
• Manual trigger: Executed manually through the script interface

Additionally, advanced custom image hosting scripts correspond to the use of advanced custom image hosting, allowing you to write upload scripts to support any image hosting service.

Script API

Default script template is as follows:

// ctx is the core PicList instance, extra is an additional parameter, where extra.galleryItem is the currently deleted album object
// Available additional APIs: axios, crypto, fs, path, os, setTimeout, setInterval, clearTimeout, clearInterval, base64Decode, base64Encode
// Image hosting upload scripts must return the ctx object, other scripts can return any data as needed

async function main(ctx, extra) {
  return ctx
}

Scripts can access the following APIs and modules:

• ctx: The core PicList instance, containing properties and methods for configuration, uploaders, transformers, and more
• extra: An additional parameter object, where extra.galleryItem is the currently deleted album object (only available in album deletion scripts)
• axios: A library for sending HTTP requests
• crypto: Node.js's cryptography module
• fs: Node.js's file system module
• path: Node.js's path module
• os: Node.js's operating system module
• Timer functions: setTimeout, setInterval, clearTimeout, clearInterval
• Encoding functions: base64Decode, base64Encode

Additionally, for the ctx object, common properties and methods include:

• getConfig(key): Get configuration item
• saveConfig(key, value): Save configuration item
• input: Current list of files being uploaded, type string[]
• output: List of upload results, type IImgInfo[]
• log: Logger
• request(options): Send HTTP request, based on axios, can use axios as an alternative

Script Example

An example of uploading images to the SM.MS image hosting service through an upload script:

const postOptions = (fileName, image, apiToken, domain = '') => {
  return {
    method: 'POST',
    url: `https://${domain}/api/v2/upload`,
    headers: {
      contentType: 'multipart/form-data',
      'User-Agent': 'PicList',
      Authorization: apiToken,
    },
    formData: {
      smfile: {
        value: image,
        options: { filename: fileName },
      },
      ssl: 'true',
    },
  }
}

async function main(ctx){
  const domain = 'smms.app'

  const imgList = ctx.output
  for (const img of imgList) {
    if (!img.fileName) continue

    const imageBuffer = img.buffer || (img.base64Image ? Buffer.from(img.base64Image, 'base64') : undefined)
    if (!imageBuffer) continue

    const postConfig = postOptions(img.fileName, imageBuffer, 'xxxxxxx', domain)
    const res = await ctx.request(postConfig)
    const body = JSON.parse(res)

    if (body.code === 'success') {
      img.imgUrl = body.data.url
      img.hash = body.data.hash
    }

    delete img.base64Image
    delete img.buffer
  }
  return ctx
}