Story (ストーリー)#

バージョン1.21.0で新規追加

メソッド / 属性	簡単な説明
`Story.reset()`	ストーリーの出力を先頭に巻き戻す
`Story.place()`	指定された長方形に収まるストーリーのコンテンツを計算
`Story.draw()`	計算されたコンテンツを現在のページに書き込む
`Story.element_positions()`	現在処理中のストーリーコンテンツを記録するコールバック関数
`Story.body`	ストーリーの基本となる body
`Story.write()`	ストーリーを DocumentWriter(ドキュメントライター) に配置して描画します
`Story.write_stabilized()`	HTMLコンテンツを DocumentWriter(ドキュメントライター) に反復的にレイアウトします
`Story.write_with_links()`	`write()` と同様ですが、PDFリンクも作成します
`Story.write_stabilized_with_links()`	`write_stabilized()` と同様ですが、PDFリンクも作成します
`Story.fit()`	Finds optimal rect that contains the story `self`.
`Story.fit_scale()`
`Story.fit_height()`
`Story.fit_width()`

クラスAPI

class Story#

__init__(self, html=None, user_css=None, em=12, archive=None)#

ストーリー を作成します。オプションでHTMLとCSSのソースを提供できます。HTMLは解析され、ストーリー内でDOM（ドキュメントオブジェクトモデル）として保持されます。

この構造は変更できます。テキスト、画像などのコンテンツは、Xml クラスのメソッドを使用して追加、コピー、変更、または削除できます。

完了したら、ストーリー を任意のデバイスに書き込むことができます。通常の使用法では、デバイスは新しいページを生成するために DocumentWriter(ドキュメントライター) によって提供されます。

以下は一般的な注意事項です：

Story (ストーリー) コンストラクタは提供されたHTMLを解析し、検証してDOMを作成します。
PyMuPDFは、基本的なDOMのノードへのアクセスを提供することでHTMLソースを操作する方法をいくつか提供しています。文書は完全にプログラム的に構築することも、既存のDOMをかなり任意に変更することもできます。このインターフェースの詳細については、Xml クラスをご覧ください。
DOMへの変更が必要ない（またはもう必要ない）場合、ストーリーはレイアウトが可能であり、新しいページを生成するために通常は DocumentWriter(ドキュメントライター) によって提供されるデバイスに供給する準備ができています。
次のステップは、ストーリーを配置して書き出すことです。これは、直接行うこともできます（place() と draw() を呼び出すことでループ処理することで）、または代替として write() または write_stabilised() メソッドを使用しても、ループ処理を自動化できます。どの方法を選択するかは主に好みの問題です。
- 最初のスタイルで作業するには、次のループを使用する必要があります：
  1. 適切なデバイスを取得します。通常、DocumentWriter(ドキュメントライター) から新しい空のページを要求することで取得します。
  2. ページ上に ストーリー データを受け取る必要がある1つまたは複数の長方形を決定します。すべてのページが同じ長方形セットを持つ必要はないことに注意してください。
  3. 各長方形を ストーリー に渡して配置し、その長方形のどの部分が埋まったか、また収まらなかったストーリーデータがあるかを学びます。このステップは、調整された長方形で何度も繰り返すことができ、呼び出し元が結果に満足するまで続けることができます。
  4. 任意で、この段階で element_positions() メソッドを呼び出して、興味深いアイテムが配置された場所の詳細をリクエストすることができます。アイテムは、整数の heading 属性がゼロでない場合（h1 - h6）、id属性がNoneでない場合（id に対応）、またはhref属性がNoneでない場合（href に対応）に興味深いと見なされます。これは、目次、画像の索引などの自動生成に便利に使用できます。
  5. 次に、draw() メソッドを使用してその長方形をデバイスに描画します。
  6. 最も最近の place() の呼び出しが、すべてのストーリーデータが収まったことを示した場合、ここで停止します。
  7. それ以外の場合、ループを戻すことができます。現在のデバイス（ページ）に配置するためにさらに長方形がある場合は、ステップ3に戻ります。長方形がない場合は、新しいデバイスを取得するためにステップ1に戻ります。
- 代わりに、DocumentWriter(ドキュメントライター) を使用している場合、write() または write_stabilized() メソッドを使用できます。これらは、動作を制御するコールバックが提供される代わりに、すべてのループ処理を処理します（特に使用する長方形/ページを列挙するコールバックが含まれます）。
ストーリー オブジェクトがどの部分がどの長方形/ページに配置されるかは、完全に Story (ストーリー) オブジェクトの制御下にあり、予測することはできません。
画像は ストーリー の一部となる可能性があります。画像は周囲のテキストと一緒に配置されます。
複数のストーリーは、互いに独立して同じページに書き込むことができます。たとえば、ページヘッダー、ページフッター、通常のテキスト、コメントボックスなどの異なるストーリーを持つことができます。

パラメータ:

html (str) -- HTMLソースコード。省略した場合、基本的な最小限のHTMLが生成されます（以下参照）。指定した場合、完全なHTML文書は必要ありません。組み込みのソースパーサは（多くの）HTML構文エラーを許容し、また "<b>Hello, <i>World!</i></b>" のようなHTMLフラグメントも受け入れます。
user_css (str) -- CSSソースコード。指定する場合、有効なCSS仕様を含む必要があります。
em (float) -- デフォルトのテキストフォントサイズ。
archive --
レンダリングのためのリソースをロードするための Archive (アーカイブ) 。現在サポートされているリソースタイプは画像とテキストフォントです。省略した場合、ストーリーはそのようなデータを検索しようとはせず、不完全な出力を生成する可能性があります。

注釈

アーカイブの代わりに、Archive (アーカイブ) を一時的に 構築する ための有効な引数も提供できます。したがって、story = pymupdf.Story(archive=pymupdf.Archive("myfolder")) の代わりに、story = pymupdf.Story(archive="myfolder") と短縮して記述することもできます。

place(where)#

ストーリーのコンテンツのうち、指定された長方形に収まる部分を計算します。このメソッドは、ストーリーのコンテンツのどの部分が既に書き込まれたかを示すポインタを維持し、次回の呼び出し時にそのポインタの位置から再開します。

パラメータ:: where (rect_like) -- 現在のコンテンツをこの長方形に収めるためのレイアウト。これはページの MediaBox のサブ長方形でなければなりません。
戻り値の型:: tuple[bool, rect_like]
戻り値:: bool (int) more と、実際に filled 長方形を返します。more == 0 の場合、ストーリーのすべてのコンテンツが書き込まれたことを意味し、それ以外の場合、more は次の長方形/ページに書き込むために待機しています。埋められた長方形は実際に埋められた where の一部です。

draw(dev, matrix=None)#

Story.place() によって準備されたコンテンツの一部をページに書き込みます。

パラメータ:

dev -- dev = writer.begin_page(mediabox) で作成された Device (デバイス)。このデバイスは、コンテンツを書き込むために必要なすべてのMuPDF関数を呼び出す方法を知っています。
matrix (matrix_like) -- ページに書き込む際にコンテンツを変形させるための行列。テキストを回転させるなどの例が考えられます。デフォルトでは変換は行われず（つまり Identity (アイデンティティ) 行列）、コンテンツはそのまま書き込まれます。

element_positions(function, args=None)#

ストーリーが現在のページ上で特定のHTML要素の配置情報を提供するようにします。つまり、Story.place() の 直後に このメソッドを呼び出します。

Story は位置情報を関数に渡します。この情報は、目次の生成などに便利に使用できます。

パラメータ:

function (callable) -- ElementPosition オブジェクトを受け入れるPython関数。この関数は、位置情報を処理するためにStoryオブジェクトによって呼び出されます。関数は正確に1つの引数を受け入れるcallableである必要があります。
args (dict) -- function に渡される ElementPosition インスタンスに追加情報を追加するためのオプションの辞書。たとえば、現在の出力ページ番号などが含まれることがあります。この辞書のすべてのキーは、有効なPython識別子の規則に従う文字列である必要があります。情報の完全なセットは以下で説明されています。

reset()#: ストーリーのドキュメントを最初に戻して、出力を再開します。

body#: ストーリーのDOMの body 部分。この属性には body の Xml ノードが含まれています。PDFの制作に関連するすべてのコンテンツは、「<body>」と「</body>」の間に含まれています。

write(writer, rectfn, positionfn=None, pagefn=None)#

Storyを DocumentWriter(ドキュメントライター) に配置し、描画します。これにより、Story.place() および Story.draw() などを呼び出すループの実装が不要になりますが、rectfn() コールバックを少なくとも提供する必要があります。

パラメータ:

writer -- DocumentWriter(ドキュメントライター) または None。
rectfn --
(rect_num: int, filled: Rect) を取り、(mediabox, rect, ctm) を返すcallable：
- mediabox: None or rect for new page.
- rect: The next rect into which content should be placed.
- ctm: None or a Matrix (マトリックス).
positionfn --
None, or a callable taking (position: ElementPosition):
- position:
  .page_num メンバーを持つ ElementPosition。
通常、見出しやIDを持つ要素を生成する際に複数回呼び出されます。
pagefn -- None または (page_num, mediabox, dev, after) を取り、各ページの開始(after=0)および終了（after=1）時に呼び出されます。

static write_stabilized(writer, contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)#

htmlコンテンツを DocumentWriter(ドキュメントライター) に対して反復的にレイアウトするための静的メソッド。

これにより、ページ番号が安定するまで目次セクションを追加したりすることができます。

(contentfn()、user_css、em、archive) から新しい Story (ストーリー) を繰り返し作成し、Story.write() への内部呼び出しでそれをレイアウトします。 None のライターを使用し、ElementPosition のリストを次回の contentfn() 呼び出しに渡します。

contentfn() からのhtmlが変更されなくなると、writer を使用して最終的な反復処理を行います。

パラメータ:

writer -- DocumentWriter(ドキュメントライター)。
contentfn -- ElementPositions のリストを取り、htmlを含む文字列を返す関数。返されるhtmlは、位置のリストに依存する場合があります。たとえば、最初の近くに目次がある場合です。
rectfn --
A callable taking (rect_num: int, filled: Rect) and returning (mediabox, rect, ctm):
- mediabox: None or rect for new page.
- rect: The next rect into which content should be placed.
- ctm: A Matrix (マトリックス).
pagefn -- None または (page_num、medibox、dev、after) を取り、各ページの開始（after=0）および終了（after=1）時に呼び出されます。
archive --
add_header_ids -- Trueの場合、idを持たないすべての見出しタグに一意のidを追加します。これは目次の自動生成に役立ちます

Returns:: None.

write_with_links(rectfn, positionfn=None, pagefn=None)#: write() に類似していますが、writer 引数がなく、内部のHTMLリンクごとにリンクが作成されたPDF Document (ドキュメント) が返されます。

static write_stabilized_with_links(contentfn, rectfn, user_css=None, em=12, positionfn=None, pagefn=None, archive=None, add_header_ids=True)#: write_stabilized() に類似していますが、writer 引数がなく、代わりに各内部のHTMLリンクにリンクが作成されたPDF Document (ドキュメント) が返されます。

class FitResult#

The result from a Story.fit*() method.

Members:

big_enough:: True if the fit succeeded.
filled:: From the last call to Story.place().
more:: False if the fit succeeded.
numcalls:: Number of calls made to self.place().
parameter:: The successful parameter value, or the largest failing value.
Rect (矩形):: The rect created from parameter.

fit(self, fn, pmin=None, pmax=None, delta=0.001, verbose=False)#

Finds optimal rect that contains the story self.

Returns a Story.FitResult instance.

On success, the last call to self.place() will have been with the returned rectangle, so self.draw() can be used directly.

パラメータ:

fn --
A callable taking a floating point parameter and returning a pymupdf.Rect(). If the rect is empty, we assume the story will not fit and do not call self.place().

Must guarantee that self.place() behaves monotonically when given rect fn(parameter) as parameter increases. This usually means that both width and height increase or stay unchanged as parameter increases.
pmin -- Minimum parameter to consider; None for -infinity.
pmax -- Maximum parameter to consider; None for +infinity.
delta -- Maximum error in returned parameter.
verbose -- If true we output diagnostics.

fit_scale(self, rect, scale_min=0, scale_max=None, delta=0.001, verbose=False)#

Finds smallest value scale in range scale_min..scale_max where scale * rect is large enough to contain the story self.

Returns a Story.FitResult instance.

パラメータ:

width -- width of rect.
height -- height of rect.
scale_min -- Minimum scale to consider; must be >= 0.
scale_max -- Maximum scale to consider, must be >= scale_min or None for infinite.
delta -- Maximum error in returned scale.
verbose -- If true we output diagnostics.

fit_height(self, width, height_min=0, height_max=None, origin=(0, 0), delta=0.001, verbose=False)#

Finds smallest height in range height_min..height_max where a rect with size (width, height) is large enough to contain the story self.

Returns a Story.FitResult instance.

パラメータ:

width -- width of rect.
height_min -- Minimum height to consider; must be >= 0.
height_max -- Maximum height to consider, must be >= height_min or None for infinite.
origin -- (x0, y0) of rect.
delta -- Maximum error in returned height.
verbose -- If true we output diagnostics.

fit_width(self, height, width_min=0, width_max=None, origin=(0, 0), delta=0.001, verbose=False)#

Finds smallest width in range width_min..width_max where a rect with size (width, height) is large enough to contain the story self.

Returns a Story.FitResult instance.

パラメータ:

height -- height of rect.
width_min -- Minimum width to consider; must be >= 0.
width_max -- Maximum width to consider, must be >= width_min or None for infinite.
origin -- (x0, y0) of rect.
delta -- Maximum error in returned width.
verbose -- If true we output diagnostics.

要素位置コールバック関数#

コールバック関数は、ストーリーの出力に関する情報を記録するために使用できます。この関数は情報への読み取り専用アクセスを持ち、ストーリーの出力に影響を与える方法はありません。

このメソッドを使用してストーリーを実行する典型的なループは次のようになります:

HTML = """
<html>
    <head></head>
    <body>
        <h1>Header level 1</h1>
        <h2>Header level 2</h2>
        <p>Hello MuPDF!</p>
    </body>
</html>
"""
MEDIABOX = pymupdf.paper_rect("letter")  # size of a page
WHERE = MEDIABOX + (36, 36, -36, -36)  # leave borders of 0.5 inches
story =  pymupdf.Story(html=HTML)  # make the story
writer = pymupdf.DocumentWriter("test.pdf")  # make the writer
pno = 0 # current page number
more = 1  # will be set to 0 when done
while more:  # loop until all story content is processed
    dev = writer.begin_page(MEDIABOX)  # make a device to write on the page
    more, filled = story.place(WHERE)  # compute content positions on page
    story.element_positions(recorder, {"page": pno})  # provide page number in addition
    story.draw(dev)
    writer.end_page()
    pno += 1  # increase page number
writer.close()  # close output file

def recorder(elpos):
    pass

ElementPosition クラスの属性#

Story.element_positions() で提供される関数に渡すパラメータは、次の属性を持つオブジェクトである必要があります。

recorder 関数に渡されるパラメータは、次の属性を持つオブジェクトです。

elpos.depth （int）– ボックス構造内でのこの要素の深さ。
elpos.heading （int）– ヘッダーレベル、ヘッダーがない場合は0、 h1 - h6 に対して1-6。
elpos.href (str) -- value of the href attribute, or None if not defined.
elpos.id （str）– id 属性の値、または未定義の場合は None。
elpos.rect （tuple）– ページ上の要素の位置。
elpos.text （str）– 要素の直接のテキスト。
elpos.open_close （int ビットフィールド）– ビット0がセットされている場合、要素を開く。ビット1がセットされている場合、要素を閉じる。他の要素を含む可能性がある要素に対して、即座に作成/開始された後にすぐに閉じられない要素に関連します。
elpos.rect_num （int）– これまでにストーリーで埋められた長方形の数。
elpos.page_num （int）– ページ番号。pymupdf.Story.write*() 関数を使用する場合にのみ存在します。

Do you have any feedback on this page?

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.