iframe Import

Integration Flow

1. Load the import page through an iframe.

<iframe src="${domain_name}/app/import"></iframe>

2. Generate a file file_key through OpenAPI. See Create File, then pass the data to Pixso.

3. Call Pixso through postMessage.

iframe.contentWindow.postMessage({
    name: "/file/convert";
    type: "msg-api";
    data: {
        files: [{
            fileKey: string,
            name: "pixso.pix",
            buffer: ArrayBuffer,
            isHtml: true // Whether to import an Axure file as an HTML file.
	}],
    };
}, *);

4. Listen for file import status changes. When the status of the corresponding file_key is success, the import has succeeded.

window.addEventListener("message", (event) => {
  if (event.data.name === "/file/convert") {
    const {
      data: { status, message, progress },
    } = event.data;
    // do something
  }
});

API Type Definitions

// External page sends file information to Pixso.
interface FileConvertReqMsg {
  name: "/file/convert";
  type: "msg-api";
  data: {
    files: {
      fileKey: string; // fileKey created by the backend.
      name: string; // imported file name. The file extension is required.
      buffer: ArrayBuffer; // imported file data.
      isHtml?: boolean; // When importing an Axure file, whether to import it as HTML. This option has no effect on other file types.
      libraryType?: "library" | "design" | "normal"; // imported file type. Default is normal. library means resource library, design means design file. Only valid for Sketch files. file_key must follow the specification.
    }[];
  };
}

// Pixso returns file import status to the external page. Every file status change triggers a notification.
interface FileConvertResMsg {
  name: "/file/convert";
  type: "msg-event";
  data: {
    fileKey: string;
    status: "loading" | "success" | "error";
    // When status is loading, message is a progress enum value.
    // When status is error, message is the error reason.
    message?: ProgreesMessage | string;
    progress?: string; // returned when status is loading.
  };
}

ProgreesMessage Enum

Enum	Description	Progress format
NONE	none	none
DECOMPRESS	decompress	percentage
PARSE_FILE	parse	percentage
UPLOAD_PREVIEW	upload cover image	percentage
UPLOAD_FILE	upload file	percentage
UPLOAD_IMAGES	upload images	progress (1/n)

Progress Aggregation

You can aggregate stage progress into a single progress bar by referring to the following code.

const progressMap = new Map<string, string>();
const updateProgress = (
  fileKey: string,
  message: ProgreesMessage,
  progress: string
) => {
  const ratio = {
    DECOMPRESS: 0.1,
    PARSE_FILE: 0.5,
    UPLOAD_PREVIEW: 0.1,
    UPLOAD_FILE: 0.1,
    UPLOAD_IMAGES: 0.2,
  };

  switch (message) {
    case "DECOMPRESS":
      const cur = ratio.DECOMPRESS * parseFloat(progress);
      progressMap.set(fileKey, cur.toFixed(2) + "%");
      break;
    case "PARSE_FILE":
      const cur = ratio.DECOMPRESS + ratio.PARSE_FILE * parseFloat(progress);
      progressMap.set(fileKey, cur.toFixed(2) + "%");
      break;
    case "UPLOAD_PREVIEW":
      const cur =
        ratio.DECOMPRESS +
        ratio.PARSE_FILE +
        ratio.UPLOAD_PREVIEW * parseFloat(progress);
      progressMap.set(fileKey, cur.toFixed(2) + "%");
      break;
    case "UPLOAD_FILE":
      const cur =
        ratio.DECOMPRESS +
        ratio.PARSE_FILE +
        ratio.UPLOAD_PREVIEW +
        ratio.UPLOAD_FILE * parseFloat(progress);
      progressMap.set(fileKey, cur.toFixed(2) + "%");
      break;
    case "UPLOAD_IMAGES":
      const [_, total] = progress.split("/");
      const cur =
        ratio.DECOMPRESS +
        ratio.PARSE_FILE +
        ratio.UPLOAD_PREVIEW +
        ratio.UPLOAD_FILE +
        ratio.UPLOAD_IMAGES * (1 / total) * 100;
      progressMap.set(fileKey, cur.toFixed(2) + "%");
      break;
    default:
      break;
  }
};

Sketch Import

Normal Sketch Import

Generate a file file_key through OpenAPI, then import it.

postMessage({
    name: "/file/convert";
    type: "msg-api";
    data: {
        files: [{
            fileKey: string,
            name: "normal.sketch", // The file extension must be .sketch.
            buffer: ArrayBuffer,
	}],
    };
}, *);

Sketch Design File Import

Generate a file file_key through OpenAPI. Compared with normal import, this mode preserves instance associations.

postMessage({
    name: "/file/convert";
    type: "msg-api";
    data: {
        files: [{
            fileKey: string,
            name: "design.sketch",
            buffer: ArrayBuffer,
			libraryType: "design"
	}],
    };
}, *);

Sketch Library Import

1. Parse the Sketch library to obtain the unique library file_key and the isExists flag.

postMessage({
    name: "/file/parse";
    type: "msg-api";
    data: {
       name: "library.sketch",
       buffer: ArrayBuffer,
    };
}, *);

2. If isExists is true, the library already exists and continuing will overwrite it. If isExists is false, create the file_key parsed in step 1 through OpenAPI.

3. Import the Sketch file as a library. Set libraryType to library.

postMessage({
    name: "/file/convert";
    type: "msg-api";
    data: {
        files: [{
            fileKey: string,
            name: "library.sketch",
            buffer: ArrayBuffer,
			libraryType: "library"
	}],
    };
}, *);