Expo 打印

为 Android 和 iOS (AirPrint) 提供打印功能的库。

Android

iOS

Web

Included in Expo Go

Recommended version:

~57.0.2

expo-print 提供用于 Android 和 iOS（AirPrint）的打印功能的 API。

安装

🌐 Installation

Terminal

- npx expo install expo-print

- yarn expo install expo-print

- pnpm expo install expo-print

- bun expo install expo-print

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

🌐 Usage

Print usage

import { useState } from 'react';
import { View, StyleSheet, Button, Platform, Text } from 'react-native';
import * as Print from 'expo-print';
import { shareAsync } from 'expo-sharing';

const html = `
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no" />
  </head>
  <body style="text-align: center;">
    <h1 style="font-size: 50px; font-family: Helvetica Neue; font-weight: normal;">
      Hello Expo!
    </h1>
    <img
      src="https://expo.nodejs.cn/static/images/expo-logo.svg"
      style="width: 90vw;" />
  </body>
</html>
`;

export default function App() {
  const [selectedPrinter, setSelectedPrinter] = useState();

  const print = async () => {
    // On iOS/android prints the given html. On web prints the HTML from the current page.
    await Print.printAsync({
      html,
      printerUrl: selectedPrinter?.url, // iOS only
    });
  };

  const printToFile = async () => {
    // On iOS/android prints the given html. On web prints the HTML from the current page.
    const { uri } = await Print.printToFileAsync({ html });
    console.log('File has been saved to:', uri);
    await shareAsync(uri, { UTI: '.pdf', mimeType: 'application/pdf' });
  };

  const selectPrinter = async () => {
    const printer = await Print.selectPrinterAsync(); // iOS only
    setSelectedPrinter(printer);
  };

  return (
    <View style={styles.container}>
      <Button title="打印" onPress={print} />
      <View style={styles.spacer} />
      <Button title="打印为 PDF 文件" onPress={printToFile} />
      {Platform.OS === 'ios' && (
        <>
          <View style={styles.spacer} />
          <Button title="选择打印机" onPress={selectPrinter} />
          <View style={styles.spacer} />
          {selectedPrinter ? (
            <Text style={styles.printer}>{`Selected printer: ${selectedPrinter.name}`}</Text>
          ) : undefined}
        </>
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    backgroundColor: '#ecf0f1',
    flexDirection: 'column',
    padding: 8,
  },
  spacer: {
    height: 8,
  },
  printer: {
    textAlign: 'center',
  },
});

应用接口

🌐 API

import * as Print from 'expo-print';

Constants

`Print.Orientation`

Android

iOS

Web

Type: OrientationType

The orientation of the printed content.

Methods

`Print.printAsync(options)`

Android

iOS

Web

Parameter	Type	Description
options	`PrintOptions`	A map defining what should be printed.

Prints a document or HTML, on web this prints the HTML from the page.

Note: On iOS, printing from HTML source doesn't support local asset URLs (due to WKWebView limitations). As a workaround you can use inlined base64-encoded strings. See this comment for more details.

Note: on iOS, when printing without providing a PrintOptions.printerUrl the Promise will be resolved once printing is started in the native print window and rejected if the window is closed without starting the print. On Android the Promise will be resolved immediately after displaying the native print window and won't be rejected if the window is closed without starting the print.

Returns:

Promise<void>

Resolves to an empty Promise if printing started.

`Print.printToFileAsync(options)`

Android

iOS

Web

Parameter	Type	Description
options(optional)	`FilePrintOptions`	A map of print options. Default:`{}`

Prints HTML to PDF file and saves it to app's cache directory. On Web this method opens the print dialog.

Returns:

Promise<FilePrintResult>

`Print.selectPrinterAsync()`

iOS

Chooses a printer that can be later used in printAsync

Returns:

Promise<Printer>

A promise which fulfils with an object containing name and url of the selected printer.

Interfaces

`OrientationType`

Android

iOS

Web

The possible values of orientation for the printed content.

Property	Type	Description
landscape	`string`	-
portrait	`string`	-

Types

`FilePrintOptions`

Android

iOS

Web

Property	Type	Description
base64(optional)	`boolean`	Whether to include base64 encoded string of the file in the returned object.
height(optional)	`number`	Height of the single page in pixels. Defaults to `792` which is a height of US Letter paper format with 72 PPI.
html(optional)	`string`	HTML string to print into PDF file.
margins(optional)	`PageMargins`	Only for: iOS Page margins for the printed document.
textZoom(optional)	`number`	Only for: Android The text zoom of the page in percent. The default is 100.
useMarkupFormatter(optional)	`boolean`	Only for: iOS Alternative to default option that uses UIMarkupTextPrintFormatter instead of WebView, but it doesn't display images.
width(optional)	`number`	Width of the single page in pixels. Defaults to `612` which is a width of US Letter paper format with 72 PPI.

`FilePrintResult`

Android

iOS

Web

Property	Type	Description
base64(optional)	`string`	Base64 encoded string containing the data of the PDF file. Available only if `base64` option is truthy. It doesn't include data URI prefix `data:application/pdf;base64,`.
numberOfPages	`number`	Number of pages that were needed to render given content.
uri	`string`	A URI to the printed PDF file.

`PageMargins`

Android

iOS

Web

Property	Type	Description
bottom	`number`	-
left	`number`	-
right	`number`	-
top	`number`	-

`Printer`

Android

iOS

Web

Property	Type	Description
name	`string`	Name of the printer.
url	`string`	URL of the printer.

`PrintOptions`

Android

iOS

Web

Property	Type	Description
height(optional)	`number`	Height of the single page in pixels. Defaults to `792` which is a height of US Letter paper format with 72 PPI. Available only with `html` option.
html(optional)	`string`	Only for: Android iOS HTML string to print.
margins(optional)	`PageMargins`	Only for: iOS Page margins for the printed document.
markupFormatterIOS(optional)	`string`	Deprecated: This argument is deprecated, use `useMarkupFormatter` instead. Might be removed in the future releases. iOS
orientation(optional)	`OrientationType[portrait] \| OrientationType[landscape]`	Only for: iOS The orientation of the printed content, `Print.Orientation.portrait` or `Print.Orientation.landscape`.
printerUrl(optional)	`string`	Only for: iOS URL of the printer to use. Returned from `selectPrinterAsync`.
uri(optional)	`string`	Only for: Android iOS URI of a PDF file to print. Remote, local (ex. selected via `DocumentPicker`) or base64 data URI starting with `data:application/pdf;base64,`. This only supports PDF, not other types of document (e.g. images).
useMarkupFormatter(optional)	`boolean`	Only for: iOS Alternative to default option that uses UIMarkupTextPrintFormatter instead of WebView, but it doesn't display images.
width(optional)	`number`	Width of the single page in pixels. Defaults to `612` which is a width of US Letter paper format with 72 PPI. Available only with `html` option.

本地图片

🌐 Local images

在 iOS 上，从 HTML 源打印不支持本地资源 URL（由于 WKWebView 限制）。相反，图片需要转换为 base64 并内嵌到 HTML 中。

🌐 On iOS, printing from HTML source doesn't support local asset URLs (due to WKWebView limitations). Instead, images need to be converted to base64 and inlined into the HTML.

Example

import { Asset } from 'expo-asset';
import { useImageManipulator } from 'expo-image-manipulator';
import { printAsync } from 'expo-print';
import { useEffect } from 'react';

const IMAGE = Asset.fromModule(require('@/assets/images/icon.png'));

export function ImageManipulatorExample() {
  const context = useImageManipulator(IMAGE.uri);

  useEffect(() => {
    async function generateAndPrint() {
      try {
        await IMAGE.downloadAsync();
        const manipulatedImage = await context.renderAsync();
        const result = await manipulatedImage.saveAsync({ base64: true });

        const html = `
          <html>
            <img
              src="data:image/png;base64,${result.base64}"
              style="width: 90vw;" />
          </html>
        `;

        await printAsync({ html });
      } catch (error) {
        console.error('Error:', error);
      }
    }

    generateAndPrint();
  }, [context]);

  return <>{/* Render UI */}</>;
}

页边距

🌐 Page margins

在 iOS 上，你可以使用 margins 选项设置页面边距：

const { uri } = await Print.printToFileAsync({
  html: 'This page is printed with margins',
  margins: {
    left: 20,
    top: 50,
    right: 20,
    bottom: 100,
  },
});

如果将 useMarkupFormatter 设置为 true，设置页边距可能会导致打印输出的末尾出现空白页。为避免这种情况，请确保你的 HTML 字符串是一个格式良好的文档，包括在字符串开头添加 <!DOCTYPE html>。

🌐 If useMarkupFormatter is set to true, setting margins may cause a blank page to appear at the end of your printout. To prevent this, make sure your HTML string is a well-formed document, including <!DOCTYPE html> at the beginning of the string.

在 Android 上，如果你在 printAsync 或 printToFileAsync 中使用 html 选项，生成的打印可能会包含页面边距（这取决于 WebView 引擎）。它们是由 @page 样式块设置的，你可以在 HTML 代码中覆盖它们：

<style>
  @page {
    margin: 20px;
  }
</style>

有关更多详细信息，请参阅 @page 在 MDN 上的文档。

🌐 See @page documentation on MDN for more details.