チュートリアル¶

Methods full documentation: fpdf.FPDF API doc

チュートリアル

Tuto 1 - 簡単な使用例¶

まずは、単純な使用例から始めましょう。

from fpdf import FPDF

pdf = FPDF()
pdf.add_page()
pdf.set_font("helvetica", style="B", size=16)
pdf.cell(40, 10, "Hello World!")
pdf.output("tuto1.pdf")

生成されるPDF

ライブラリをインポートした後、FPDF オブジェクトを作成します。上の例では、FPDF コンストラクタはデフォルト値を利用します(A4サイズ縦向きのページとミリメーター単位)。次のようにして、明示的に指定することも可能です。

pdf = FPDF(orientation="P", unit="mm", format="A4")

PDFを横向き(L)に設定したり、他のページサイズ(Letter, Legal など)や単位(pt, cm, in)を設定することも可能です。

（訳注）縦向き（portrait）、横向き（landscape）の頭文字で向きを指定します。

この時点ではPDFファイルにページが存在しないため、add_pageでページを追加します。原点は左上隅で、現在の位置はデフォルトでページ端から1cmの場所になります。余白はset_margins で変更可能です。

テキストを表示する前に、set_font でフォントを選択する必要があります。今回はHelvetica bold 16 を選択します。

pdf.set_font('Helvetica', style='B', size=16)

Iで斜体、Uで下線、空文字列で通常のフォント（または任意の組み合わせ）を指定することができます。フォントサイズはミリメートル（または他のユーザー単位）ではなくポイントで指定することに注意してください。他の内蔵フォントはTimes、Courier、Symbol、ZapfDingbatsです。

これでセルを cell で表示できるようになりました。セルとは、テキストを含む長方形の領域で、現在の位置に描画されます。寸法、テキスト（配置）、ボーダーの有無、そして現在の位置が次に移動する先（右、下、次の行頭）を指定します。ボーダー付きで描画するには次のようにします。

pdf.cell(40, 10, 'Hello World!', 1)

その隣に新しいセルを中央揃えのテキストで追加し、次の行に進むには、次のようにします。

pdf.cell(60, 10, 'Powered by FPDF.', new_x="LMARGIN", new_y="NEXT", align='C')

備考: 改行は ln でも可能です。ln メソッドは、改行時の高さを指定することができます。

最後に、output で、指定した場所にPDFを保存します。引数なしの output()は PDFの bytearrayを返します。

Tuto 2 - ヘッダー、フッターと改ページ、画像¶

ヘッダー、フッター、ロゴのある2ページのPDFを生成するサンプルです。

from fpdf import FPDF


class PDF(FPDF):
    def header(self):
        # Rendering logo:
        self.image("../docs/fpdf2-logo.png", 10, 8, 33)
        # Setting font: helvetica bold 15
        self.set_font("helvetica", style="B", size=15)
        # Moving cursor to the right:
        self.cell(80)
        # Printing title:
        self.cell(30, 10, "Title", border=1, align="C")
        # Performing a line break:
        self.ln(20)

    def footer(self):
        # Position cursor at 1.5 cm from bottom:
        self.set_y(-15)
        # Setting font: helvetica italic 8
        self.set_font("helvetica", style="I", size=8)
        # Printing page number:
        self.cell(0, 10, f"Page {self.page_no()}/{{nb}}", align="C")


# Instantiation of inherited class
pdf = PDF()
pdf.add_page()
pdf.set_font("Times", size=12)
for i in range(1, 41):
    pdf.cell(0, 10, f"Printing line number {i}", new_x="LMARGIN", new_y="NEXT")
pdf.output("new-tuto2.pdf")

生成されるPDF

この例では、header と footerメソッドを使用して、ページのヘッダーとフッターを処理しています。これらのメソッドは自動的に呼び出されます。 FPDFクラスはこれらのメソッドを持っていますが、何もしません。そのため、クラスを継承してメソッドをオーバーライドする必要があります。

ロゴは、左上隅の位置と幅を指定して、imageメソッドによって表示されます。高さは画像の縦横比から自動的に計算されます。

ページ番号を表示するには、セルの幅にnull valueを渡します。これによって、セルがページの右の余白まで広がります。これはテキストを中央寄せする場合に便利です。現在のページ番号は page_no メソッドで取得できます。総ページ数はドキュメント終了時に置換される特殊な値 {nb} によって取得できます（この特殊な値はalias_nb_pages() によって変更できます）。 set_y メソッドを使うことで、ページの上部もしくは下部からの絶対位置を指定できます。

ここで使用されているもう一つの興味深い機能は、自動改ページ機能です。セルがページの限界（デフォルトでは下から2cm）を超えると改行され、フォントが元に戻ります。ヘッダーとフッターは独自のフォント（helvetica）を使用しますが、本文はTimes を使用し続けます。この自動復帰の仕組みは、色と行幅にも適用されます。この改ページのトリガーとなるページの限界は set_auto_page_break で設定できます。

Tuto 3 - 改行と色¶

続いて、複数の段落を文字揃えして表示する例を見てみましょう。同時に、色の使い方についても学びます。

from fpdf import FPDF


class PDF(FPDF):
    def header(self):
        # Setting font: helvetica bold 15
        self.set_font("helvetica", style="B", size=15)
        # Calculating width of title and setting cursor position:
        width = self.get_string_width(self.title) + 6
        self.set_x((210 - width) / 2)
        # Setting colors for frame, background and text:
        self.set_draw_color(0, 80, 180)
        self.set_fill_color(230, 230, 0)
        self.set_text_color(220, 50, 50)
        # Setting thickness of the frame (1 mm)
        self.set_line_width(1)
        # Printing title:
        self.cell(
            width,
            9,
            self.title,
            border=1,
            new_x="LMARGIN",
            new_y="NEXT",
            align="C",
            fill=True,
        )
        # Performing a line break:
        self.ln(10)

    def footer(self):
        # Setting position at 1.5 cm from bottom:
        self.set_y(-15)
        # Setting font: helvetica italic 8
        self.set_font("helvetica", style="I", size=8)
        # Setting text color to gray:
        self.set_text_color(128)
        # Printing page number
        self.cell(0, 10, f"Page {self.page_no()}", align="C")

    def chapter_title(self, num, label):
        # Setting font: helvetica 12
        self.set_font("helvetica", size=12)
        # Setting background color
        self.set_fill_color(200, 220, 255)
        # Printing chapter name:
        self.cell(
            0,
            6,
            f"Chapter {num} : {label}",
            new_x="LMARGIN",
            new_y="NEXT",
            align="L",
            fill=True,
        )
        # Performing a line break:
        self.ln(4)

    def chapter_body(self, filepath):
        # Reading text file:
        with open(filepath, "rb") as fh:
            txt = fh.read().decode("latin-1")
        # Setting font: Times 12
        self.set_font("Times", size=12)
        # Printing justified text:
        self.multi_cell(0, 5, txt)
        # Performing a line break:
        self.ln()
        # Final mention in italics:
        self.set_font(style="I")
        self.cell(0, 5, "(end of excerpt)")

    def print_chapter(self, num, title, filepath):
        self.add_page()
        self.chapter_title(num, title)
        self.chapter_body(filepath)


pdf = PDF()
pdf.set_title("20000 Leagues Under the Seas")
pdf.set_author("Jules Verne")
pdf.print_chapter(1, "A RUNAWAY REEF", "20k_c1.txt")
pdf.print_chapter(2, "THE PROS AND CONS", "20k_c1.txt")
pdf.output("tuto3.pdf")

生成されるPDF

PDF中の本文（Jules Verne text）

get_string_width メソッドは現在のフォントでの文字列の幅を求めることができ、ここではタイトルを囲む枠の位置と幅を計算するために使われています。次に、色を指定し（set_draw_color、 set_fill_color、 set_text_color を利用）、線の太さをset_line_widthで1mmに設定します（デフォルトでは0.2）。最後に、セルを出力します（最後のパラメータをtrueにして、背景の塗りつぶしを有効にします。）。

段落を表示するためには multi_cell メソッドを利用します。テキストはデフォルトで両端揃えされます。行がセルの右端に届くか、改行文字（\n）のたびに改行され、現在のセルの下に新しいセルが自動的に作成されます。自動改行は、右端に最も近いスペースかソフトハイフン（\u00ad）の位置で行われます。ソフトハイフンは改行をトリガーする場合は通常のハイフンに置き換えられ、そうでない場合は無視されます。

この文書には、タイトル（set_title）と著者（set_author）の2つの文書プロパティがセットされています。プロパティは2つの方法で見ることができます。 1つ目は、Acrobat Readerで直接文書を開き、「ファイル」メニューから「プロパティ」オプションを選択する方法です。もう1つは、プラグインからも利用できますが、右クリックして「ドキュメントのプロパティ」を選択する方法です。

Tuto 4 - 段組み¶

この例では、前の例の派生版として、複数列に渡ってテキストを配置する（段組み）方法を紹介します。

from fpdf import FPDF


class PDF(FPDF):
    def header(self):
        self.set_font("helvetica", style="B", size=15)
        width = self.get_string_width(self.title) + 6
        self.set_x((210 - width) / 2)
        self.set_draw_color(0, 80, 180)
        self.set_fill_color(230, 230, 0)
        self.set_text_color(220, 50, 50)
        self.set_line_width(1)
        self.cell(
            width,
            9,
            self.title,
            border=1,
            new_x="LMARGIN",
            new_y="NEXT",
            align="C",
            fill=True,
        )
        self.ln(10)

    def footer(self):
        self.set_y(-15)
        self.set_font("helvetica", style="I", size=8)
        self.set_text_color(128)
        self.cell(0, 10, f"Page {self.page_no()}", align="C")

    def chapter_title(self, num, label):
        self.set_font("helvetica", size=12)
        self.set_fill_color(200, 220, 255)
        self.cell(
            0,
            6,
            f"Chapter {num} : {label}",
            new_x="LMARGIN",
            new_y="NEXT",
            border="L",
            fill=True,
        )
        self.ln(4)

    def chapter_body(self, fname):
        # Reading text file:
        with open(fname, "rb") as fh:
            txt = fh.read().decode("latin-1")
        with self.text_columns(
            ncols=3, gutter=5, text_align="J", line_height=1.19
        ) as cols:
            # Setting font: Times 12
            self.set_font("Times", size=12)
            cols.write(txt)
            cols.ln()
            # Final mention in italics:
            self.set_font(style="I")
            cols.write("(end of excerpt)")

    def print_chapter(self, num, title, fname):
        self.add_page()
        self.chapter_title(num, title)
        self.chapter_body(fname)


pdf = PDF()
pdf.set_title("20000 Leagues Under the Seas")
pdf.set_author("Jules Verne")
pdf.print_chapter(1, "A RUNAWAY REEF", "20k_c1.txt")
pdf.print_chapter(2, "THE PROS AND CONS", "20k_c1.txt")
pdf.output("tuto4.pdf")

生成されるPDF

PDF中の本文（Jules Verne text）

⚠️ This section has changed a lot and requires a new translation: https://github.com/py-pdf/fpdf2/issues/267

English versions:

Tuto 4 - Multi Columns
[Documentation on TextColumns](https://py-pdf.github.io/fpdf2/TextColumns.html

Tuto 5 - 表の作成¶

このチュートリアルでは、簡単な調整で何ができるのかを示すために、 2種類のテーブルの作成方法について解説します。

import csv
from fpdf import FPDF
from fpdf.fonts import FontFace
from fpdf.enums import TableCellFillMode


with open("countries.txt", encoding="utf8") as csv_file:
    data = list(csv.reader(csv_file, delimiter=","))

pdf = FPDF()
pdf.set_font("helvetica", size=14)

# Basic table:
pdf.add_page()
with pdf.table() as table:
    for data_row in data:
        row = table.row()
        for datum in data_row:
            row.cell(datum)

# Styled table:
pdf.add_page()
pdf.set_draw_color(255, 0, 0)
pdf.set_line_width(0.3)
headings_style = FontFace(emphasis="BOLD", color=255, fill_color=(255, 100, 0))
with pdf.table(
    borders_layout="NO_HORIZONTAL_LINES",
    cell_fill_color=(224, 235, 255),
    cell_fill_mode=TableCellFillMode.ROWS,
    col_widths=(42, 39, 35, 42),
    headings_style=headings_style,
    line_height=6,
    text_align=("LEFT", "CENTER", "RIGHT", "RIGHT"),
    width=160,
) as table:
    for data_row in data:
        row = table.row()
        for datum in data_row:
            row.cell(datum)

pdf.output("tuto5.pdf")

生成されるPDF - 国別CSVデータ

1つ目の例は最も基本的な方法で、FPDF.table() にデータを与えています。結果は単純なものですが、非常に短時間で作成できます。

2つ目の例ではいくつかの改善を加えています。色、テーブルの幅の制限、行の高さの縮小、中央寄せされたタイトル、列幅の指定、右寄せの数値などに加え、行を区切る横線を削除しています。これは、TableBordersLayout の borders_layout を指定することで行うことができます。

Tuto 6 - リンクの作成と、テキストスタイルの組み合わせ¶

このチュートリアルでは、PDF文書内にリンクを埋め込むいくつかの方法を紹介します。同様の方法で、外部リンクも作成可能です。

また、1つのテキスト内で複数のスタイリング（太字、斜体、下線）を使用する方法についても解説します。

from fpdf import FPDF


pdf = FPDF()

# First page:
pdf.add_page()
pdf.set_font("helvetica", size=20)
pdf.write(5, "To find out what's new in self tutorial, click ")
pdf.set_font(style="U")
link = pdf.add_link(page=2)
pdf.write(5, "here", link)
pdf.set_font()

# Second page:
pdf.add_page()
pdf.image(
    "../docs/fpdf2-logo.png", 10, 10, 50, 0, "", "https://py-pdf.github.io/fpdf2/"
)
pdf.set_left_margin(60)
pdf.set_font_size(18)
pdf.write_html(
    """You can print text mixing different styles using HTML tags: <b>bold</b>, <i>italic</i>,
<u>underlined</u>, or <b><i><u>all at once</u></i></b>!
<br><br>You can also insert links on text, such as <a href="https://py-pdf.github.io/fpdf2/">https://py-pdf.github.io/fpdf2/</a>,
or on an image: the logo is clickable!"""
)
pdf.output("tuto6.pdf")

生成されるPDF - fpdf2-logo

ここではテキストを表示するための新しい方法として、 write() を使っています。このメソッドは multi_cell() と非常によく似ており、重要な違いとしては次があります。

行末は右の余白、行頭は左の余白から始まる
現在の位置はテキストの終わりに移動する

したがって、このメソッドを用いてテキストのまとまりを書き込み、フォントスタイルを変更し、さらにその続きからテキストを書き込むことができます。一方でこの方法の欠点は、 multi_cell() メソッドで行ったようなテキストの字揃えが行えないことです。

この例の1ページ目では、write() をフォントスタイルの変更に使用しています。文章の始めには通常のスタイルのテキストですが、 set_font() メソッドを用いて下線を追加しています。

2ページ目への内部リンクを作成するには、 add_link() メソッドを使用します。このメソッドは「link」と名付けられたクリック可能なエリアを作成し、文書内の別のページに移動させます。

画像を利用した外部リンクを作成するために、ここでは image() メソッドを使っています。このメソッドは引数の1つとしてリンクを受け取ります。このリンクは内部リンクでも外部リンクでも問題ありません。

別の方法として、write_html() メソッドを使用してフォントスタイルの変更やリンクの作成を行うことも出来ます。このメソッドはHTMLパーサーであり、テキストの追加、フォントスタイルの変更、リンクの作成をHTMLを用いて行なえます。