genanki からの移行

ライブラリを選んでいる段階なら、Anki Forge と genanki の比較を参照してください。

Anki Forge は安定したデータキー、検証済みの不変モデル、データを所有するメディアスナップショット、明示的なビルド・更新操作を使います。新しい作成モデルであり、genanki のオブジェクトや、削除済みの Anki Forge の Deck・lockfile インターフェースを模倣するものではありません。

genanki の概念	Anki Forge での対応
数値 ID を持つ Model	NoteType.builder(stable_key)...build()
識別子として使うフィールド名	安定した Field キーと、独立した表示名
フィールドの文字列を保持する Note	モデルを所有する model.note().field(key, content)
ノートをまとめる Deck	既定デッキを持つ Project。必要に応じてノート単位の .deck(name)
パッケージのメディアファイルパス	データを所有する Media.file(path) の値。型付きコンテンツを通して自動収集
パッケージの書き出し	project.build(BuildOptions.to(path))
フィールド由来の既定 GUID、または独自 GUID ルール	明示的で安定した名前空間とノートキー

from ankiforge import Project, NoteType, Field, Template, BuildOptions

model = (NoteType.builder('vocabulary').name('Vocabulary')
    .field(Field('word', name='Word', required=True))
    .field(Field('meaning', name='Meaning'))
    .template(Template('recognition', '{{word}}', '{{FrontSide}}<hr>{{meaning}}'))
    .build())
project = Project('vocabulary-course', default_deck='Languages::Vocabulary')
project.add('dictionary:cell', model.note().field('word', 'cell').field('meaning', '细胞'))
project.build(BuildOptions.to('vocabulary.apkg'))

キーには永続的な業務識別子を使います。表示名の変更や定義の本文の変更で、キーを変えないでください。インポーターの明示的な要件として内容に基づく識別情報が必要な場合を除き、現在のフィールド内容をハッシュにしないでください。キーのないソースデータには、SDK の外でキーを割り当てて永続保存します。

テンプレート式は Field キーを使います。表示名は独立して翻訳でき、ライブラリがキー参照を Anki のフィールド名へコンパイルします。宣言の欠落や競合は、ノートを追加する前のモデル完成時に拒否されます。ノート追加時にはモデルの依存関係を自動収集し、1つのモデルキーに競合する定義がある場合は拒否します。

文字列はプレーンテキストです。意図的な HTML は Content.html(...) で包んでください。media.image() / media.sound() と Content.sequence(...) で内容を組み合わせます。元のパスを削除・編集してもファイルのスナップショットは残ります。直接記述した HTML・CSS・スクリプトから参照する依存関係は、モデルビルダーの .asset(media) または project.add_asset(media) で明示的に宣言します。

後続リリースでは、同じ名前空間とデータキーで新しい Project を作成し、BuildOptions.to(next_path).update_from(previous_original_apkg) を呼び出します。オリジナル APKG が完全な識別情報の証拠を提供します。この手順は任意の古いパッケージから識別情報を復元したり、既存の genanki の数値 ID・GUID を自動変換したりするものではありません。別途検証済みのデータ移行で対応関係を確立しない限り、新モデルでの最初の配布物は、識別情報を引き継がない意図的な境界として扱ってください。

クイックスタート、API リファレンス、更新ポリシーを参照してください。