Firefox75時点での内容
resource://gre/modules/PlacesTransactions.jsm
ファイル冒頭の説明文の翻訳
※機械翻訳を少し手直ししただけなので、意味が分かりにくい所がある。
概要
* Overview
* --------
* This modules serves as the transactions manager for Places (hereinafter PTM).
* It implements all the elementary transactions for its UI commands: creating
* items, editing their various properties, and so forth.
このモジュールは、
Placesのトランザクションマネージャー(以降、PTM)として機能します。
アイテムの作成、さまざまなプロパティの編集など、UIコマンドのすべての基本的なトランザクションを実装します。
* Note that since the effect of invoking a Places command is not limited to the
* window in which it was performed (e.g. a folder created in the Library may be
* the parent of a bookmark created in some browser window), PTM is a singleton.
* It's therefore unnecessary to initialize PTM in any way apart importing this
* module.
Placesコマンドの呼び出しの効果は、コマンドが実行されたウィンドウに限定されないため(たとえば、ライブラリで作成されたフォルダは、ブラウザウィンドウで作成されたブックマークの親である場合があります)、PTMはシングルトンです。
したがって、このモジュールのインポートとは別に、PTMを初期化する必要はありません。
* PTM shares most of its semantics with common command pattern implementations.
* However, the asynchronous design of contemporary and future APIs, combined
* with the commitment to serialize all UI operations, does make things a little
* bit different. For example, when |undo| is called in order to undo the top
* undo entry, the caller cannot tell for sure what entry would it be, because
* the execution of some transactions is either in process, or enqueued to be.
PTMは、その
セマンティクスのほとんどを一般的なコマンドパターン実装と共有しています。
ただし、現代と将来のAPIの非同期設計と、すべてのUI操作の
シリアル化への取り組みにより、状況は少し異なります。
たとえば、| undo | は「元に戻す」エントリのトップを元に戻すために呼ばれますが、呼び出し元はそのエントリが本当にそうであるかを確実には判断できません。一部のトランザクションの実行が処理中であるか、処理待ちになっているかもしれないためです。
* Also note that unlike the nsITransactionManager, for example, this API is by
* no means generic. That is, it cannot be used to execute anything but the
* elementary transactions implemented here (Please file a bug if you find
* anything uncovered). More-complex transactions (e.g. creating a folder and
* moving a bookmark into it) may be implemented as a batch (see below).
また、例えば nsITransactionManager とは異なり、このAPIは決して汎用なものではありません。
つまり、ここで実装された基本的なトランザクション以外の実行には使用できません(カバーされていないものを見つけたら、バグを報告してください)。
より複合的なトランザクション(例:フォルダーを作成してそこにブックマークを移動する)は、バッチとして実装できます(以下を参照)。
GUIDとアイテムIDに関する注意
* A note about GUIDs and item-ids
* -------------------------------
* There's an ongoing effort (see bug 1071511) to deprecate item-ids in Places
* in favor of GUIDs. Both because new APIs (e.g. Bookmark.jsm) expose them to
* the minimum necessary, and because GUIDs play much better with implementing
* |redo|, this API doesn't support item-ids at all, and only accepts bookmark
* GUIDs, both for input (e.g. for setting the parent folder for a new bookmark)
* and for output (when the GUID for such a bookmark is propagated).
GUIDを優先して
Placesのitem-idを廃止するための継続的な取り組みがあります(バグ1071511を参照)。
新しいAPI(たとえば、Bookmark.jsm)が必要最低限のAPIを公開していること、およびGUIDが| redo |の実装ではるかに優れているため、このAPIは入力(例えば、新しいブックマークの親フォルダ設定)および出力(作られたブックマークを伝える時)の両方でitem-idをまったくサポートせず、ブックマークGUIDのみを受け入れます。
* Should you need to convert GUIDs to item-ids, use PlacesUtils.promiseItemId.
GUIDをitem-idに変換する必要がある場合は、PlacesUtils.promiseItemIdを使用します。
トランザクションの構築
* Constructing transactions
* -------------------------
* At the bottom of this module you will find transactions for all Places UI
* commands. They are exposed as constructors set on the PlacesTransactions
* object (e.g. PlacesTransactions.NewFolder). The input for this constructors
* is taken in the form of a single argument, a plain object consisting of the
* properties for the transaction. Input properties may be either required or
* optional (for example, |keyword| is required for the EditKeyword transaction,
* but optional for the NewBookmark transaction).
このモジュールの下部には、全ての
PlacesUIコマンドのトランザクションがあります。
これらは、PlacesTransactionsオブジェクトに設定されたコンストラクター(例:PlacesTransactions.NewFolder)として公開されます。
このコンストラクタの入力は、トランザクションのプロパティで構成されるプレーンオブジェクトである単一の引数の形式で取得されます。
入力プロパティは必須またはオプションのいずれかです(たとえば、| keyword |はEditKeywordトランザクションでは必須ですが、NewBookmarkトランザクションではオプションです)。
new Object、または「{……}」の形式(オブジェクト・リテラルの形式)で作られたオブジェクト
* To make things simple, a given input property has the same basic meaning and
* valid values across all transactions which accept it in the input object.
* Here is a list of all supported input properties along with their expected
* values:
* - url: a URL object, an nsIURI object, or a href.
* - urls: an array of urls, as above.
* - tag - a string.
* - tags: an array of strings.
* - guid, parentGuid, newParentGuid: a valid Places GUID string.
* - guids: an array of valid Places GUID strings.
* - title: a string
* - index, newIndex: the position of an item in its containing folder,
* starting from 0.
* integer and PlacesUtils.bookmarks.DEFAULT_INDEX
物事を簡単にするために、特定の入力プロパティは、入力オブジェクトでそれを受け入れるすべてのトランザクションにわたって同じ基本的な意味と有効な値を持っています。
サポートされているすべての入力プロパティとその期待値のリストを次に示します。
- url:URLオブジェクト、nsIURIオブジェクト、またはhref。
- urls:上記のようなurlの配列。
- tag:文字列。
- tags:文字列の配列。
- guid、parentGuid、newParentGuid:有効なPlaces GUID文字列。
- guids:有効なPlaces GUID文字列の配列。
- title:文字列
- index、newIndex:0から始まる、それを含むフォルダー内のアイテムの位置。整数とPlacesUtils.bookmarks.DEFAULT_INDEX
* If a required property is missing in the input object (e.g. not specifying
* parentGuid for NewBookmark), or if the value for any of the input properties
* is invalid "on the surface" (e.g. a numeric value for GUID, or a string that
* isn't 12-characters long), the transaction constructor throws right way.
* More complex errors (e.g. passing a non-existent GUID for parentGuid) only
* reveal once the transaction is executed.
入力オブジェクトに必要なプロパティがない(例:NewBookmarkにparentGuidを指定していない)場合や、いずれかの入力プロパティの値が「表面上」で無効(例:GUIDが12文字長ではない)な場合、トランザクションコンストラクターは適切にスロー(例外エラー)します。
より複雑なエラー(たとえば、parentGuidに存在しないGUIDを渡すなど)は、トランザクションが実行されると明らかになります。
トランザクションの実行(トランザクションの | transact | メソッド)
* Executing Transactions (the |transact| method of transactions)
* --------------------------------------------------------------
* Once a transaction is created, you must call its |transact| method for it to
* be executed and take effect. |transact| is an asynchronous method that takes
* no arguments, and returns a promise that resolves once the transaction is
* executed. Executing one of the transactions for creating items (NewBookmark,
* NewFolder, NewSeparator) resolve to the new item's GUID.
* There's no resolution value for other transactions.
* If a transaction fails to execute, |transact| rejects and the transactions
* history is not affected.
トランザクションが作成されたら、実行して有効にするための関数 | transact | を呼び出す必要があります。
| transact | は引数を取らない非同期メソッドであり、トランザクションが実行されると解決する promise を返します。
アイテムを作成するためのトランザクション(NewBookmark、NewFolder、NewSeparator)の1つを実行すると、新しいアイテムのGUIDが resolve 値になります。
他のトランザクションに resolve 値はありません。
トランザクションの実行に失敗した場合、| transact | は reject され、トランザクション履歴は影響を受けません。
* |transact| throws if it's called more than once (successfully or not) on the
* same transaction object.
| transact | が同じトランザクションオブジェクトで2回以上呼び出された場合(成功したかどうかに関係なく)スロー(例外エラー)します。
バッチ
* Batches
* -------
* Sometimes it is useful to "batch" or "merge" transactions. For example,
* something like "Bookmark All Tabs" may be implemented as one NewFolder
* transaction followed by numerous NewBookmark transactions - all to be undone
* or redone in a single undo or redo command. Use |PlacesTransactions.batch|
* in such cases. It can take either an array of transactions which will be
* executed in the given order and later be treated a a single entry in the
* transactions history, or a generator function that is passed to Task.spawn,
* that is to "contain" the batch: once the generator function is called a batch
* starts, and it lasts until the asynchronous generator iteration is complete
* All transactions executed by |transact| during this time are to be treated as
* a single entry in the transactions history.
トランザクションを「バッチ」または「マージ」すると便利な場合があります。
たとえば、「すべてのタブをブックマークする」のようなものは、1つのNewFolderトランザクションとそれに続く多数のNewBookmarkトランザクションとして実装できます。すべてを1つの元に戻すまたはやり直しコマンドで元に戻したりやり直したりできます。
そのような場合、| PlacesTransactions.batch | を使用します。
それの引数には、指定された順序で実行され、後でトランザクション履歴の単一のエントリとして処理されるトランザクションの配列、またはバッチを「含む」ためにTask.spawnに渡されるジェネレーター関数を使用できます。ジェネレーター関数はバッチ開始時に呼ばれ、非同期ジェネレーターの反復が完了するまで続きます。この間 | transact | によって実行されるすべてのトランザクションがトランザクション履歴では単一のエントリとして扱われます。
* In both modes, |PlacesTransactions.batch| returns a promise that is to be
* resolved when the batch ends. In the array-input mode, there's no resolution
* value. In the generator mode, the resolution value is whatever the generator
* function returned (the semantics are the same as in Task.spawn, basically).
両方のモードで、| PlacesTransactions.batch | バッチの終了時に解決されるpromiseを返します。
配列入力モードでは、resolve 値はありません。
ジェネレーターモードでは、resolve 値はジェネレーター関数が返すものです(
セマンティクスは基本的にTask.spawnと同じです)。
* The array-input mode of |PlacesTransactions.batch| is useful for implementing
* a batch of mostly-independent transaction (for example, |paste| into a folder
* can be implemented as a batch of multiple NewBookmark transactions).
* The generator mode is useful when the resolution value of executing one
* transaction is the input of one more subsequent transaction.
| PlacesTransactions.batch | の配列入力モードは、ほとんど独立したトランザクションのバッチを実装するのに便利です(たとえば、フォルダー内への | paste | は複数のNewBookmarkトランザクションのバッチとして実装できます)。
ジェネレーターモードは、1つのトランザクションの実行の resolve 値が1つ以上の後続のトランザクションの入力である場合に役立ちます。
* In the array-input mode, if any transactions fails to execute, the batch
* continues (exceptions are logged). Only transactions that were executed
* successfully are added to the transactions history.
配列入力モードでは、トランザクションの実行に失敗した場合、バッチが続行されます(例外がログに記録されます)。
正常に実行されたトランザクションのみがトランザクション履歴に追加されます。
* WARNING: "nested" batches are not supported, if you call batch while another
* batch is still running, the new batch is enqueued with all other PTM work
* and thus not run until the running batch ends. The same goes for undo, redo
* and clearTransactionsHistory (note batches cannot be done partially, meaning
* undo and redo calls that during a batch are just enqueued).
警告:「ネストされた」バッチはサポートされていません。別のバッチの実行中にバッチを呼び出すと、新しいバッチは他のすべてのPTM作業と共にキューに入れられ、実行中のバッチが終了するまで実行されません。
同じことは、取り消し、やり直し、およびトランザクション履歴消去にも当てはまります(バッチは部分的に実行できないことに注意してください。つまり、バッチ中の取り消しややり直しの呼び出しは、ただキューに入れるだけということを意味します)。
* *****************************************************************************
* IT'S PARTICULARLY IMPORTANT NOT TO await ANY PROMISE RETURNED BY ANY OF
* THESE METHODS (undo, redo, clearTransactionsHistory) FROM A BATCH FUNCTION.
* UNTIL WE FIND A WAY TO THROW IN THAT CASE (SEE BUG 1091446) DOING SO WILL
* COMPLETELY BREAK PTM UNTIL SHUTDOWN, NOT ALLOWING THE EXECUTION OF ANY
* TRANSACTION!
* *****************************************************************************
特に重要なのが、バッチ関数からこれらのメソッド(元に戻す、やり直し、トランザクション履歴消去)から返される promise をまったく「待たない(NOT TO await)」ことです。
そのような場合に対処する方法を見つけるまで(バグ1091446を参照)、シャットダウンするまでPTMを完全に停止し、トランザクションの実行を許可しません。
シリアル化
* Serialization
* -------------
* All |PlacesTransaction| operations are serialized. That is, even though the
* implementation is asynchronous, the order in which PlacesTransactions methods
* is called does guarantee the order in which they are to be invoked.
全ての | PlacesTransaction | 操作はシリアル化されます。
つまり、実装が非同期であっても、PlacesTransactionsメソッドが呼び出される順序は、それらが実行される順序を保証します。
* The only exception to this rule is |transact| calls done during a batch (see
* above). |transact| calls are serialized with each other (and with undo, redo
* and clearTransactionsHistory), but they are, of course, not serialized with
* batches.
このルールの唯一の例外は、バッチ中の | transact | 呼び出しです。(上記を参照)。
| transact | 呼び出しは互いに(元に戻す、やり直し、およびトランザクション履歴消去も)シリアライズされますが、もちろん、バッチではシリアライズされません。
トランザクション履歴の構造
* The transactions-history structure
* ----------------------------------
* The transactions-history is a two-dimensional stack of transactions: the
* transactions are ordered in reverse to the order they were committed.
* It's two-dimensional because PTM allows batching transactions together for
* the purpose of undo or redo (see Batches above).
トランザクション履歴は、トランザクションの2次元スタックです。トランザクションは、コミットされた順序とは逆に順序付けられます。
2次元なのは、PTMでは、元に戻すまたはやり直しの為にトランザクションのバッチ処理を許可しているためです(上記のバッチを参照)。
* The undoPosition property is set to the index of the top entry. If there is
* no entry at that index, there is nothing to undo.
* Entries prior to undoPosition, if any, are redo entries, the first one being
* the top redo entry.
undoPositionプロパティは、トップエントリのインデックスに設定されます。
そのインデックスにエントリがない場合、元に戻すものは何もありません。
undoPositionより前のエントリは、もしあれば、それはredoエントリであり、最初のそれはトップredoエントリです。
* [ [2nd redo txn, 1st redo txn], <= 2nd redo entry
* [2nd redo txn, 1st redo txn], <= 1st redo entry
* [1st undo txn, 2nd undo txn], <= 1st undo entry
* [1st undo txn, 2nd undo txn] <= 2nd undo entry ]
* undoPostion: 2.
*
* Note that when a new entry is created, all redo entries are removed.
新しいエントリが作成されると、すべてのredoエントリが削除されることに注意してください。
メソッド / プロパティ
- PlacesTransactions.batch(transactionsToBatch)
- 引数:トランザクションの配列 or ジェネレーター関数
- 返り値:promise (resolve値:なし or ジェネレータ関数の返り値)
- PlacesTransactions.undo()
- 返り値:promise (resolve値:なし)
- PlacesTransactions.redo()
- 返り値:promise (resolve値:なし)
- PlacesTransactions.clearTransactionsHistory(undoEntries = true, redoEntries = true)
- 引数:undo,redo履歴を削除するかの真偽値
- 返り値:promise (resolve値:なし)
- PlacesTransactions.length
- 履歴のエントリー数
- PlacesTransactions.entry(index)
- 引数:履歴のindex(0以上length未満の整数)
- 返り値:トランザクションの配列(undo順、つまり実行順の逆順)
- PlacesTransactions.undoPosition
- undoのトップエントリーのindex
- PlacesTransactions.topUndoEntry
- undoのトップエントリー(トランザクションの配列)
- PlacesTransactions.topRedoEntry
- redoのトップエントリー(トランザクションの配列)
コンストラクター
コンストラクター |
必須プロパティ |
オプションプロパティ |
PlacesTransactions.NewBookmark(properties) |
url, parentGuid |
index, title, keyword, tags |
PlacesTransactions.NewFolder(properties) |
title, parentGuid |
index, children |
PlacesTransactions.NewSeparator(properties) |
parentGuid |
index |
PlacesTransactions.Move(properties) |
guid, newParentGuid |
newIndex |
PlacesTransactions.EditTitle(properties) |
guid, title |
|
PlacesTransactions.EditUrl(properties) |
guid, url |
|
PlacesTransactions.EditKeyword(properties) |
guid, keyword |
postData, oldKeyword |
PlacesTransactions.SortByName(properties) |
guid |
|
PlacesTransactions.Remove(properties) |
guids |
|
PlacesTransactions.Tag(properties) |
urls, tags |
|
PlacesTransactions.Untag(properties) |
urls |
tags |
PlacesTransactions.RenameTag(properties) |
oldTag, tag |
|
PlacesTransactions.Copy(properties) |
guid, newParentGuid |
newIndex |
- Untagはオプションのtagsを指定していない場合、urlsに設定されている全てのタグが削除される
最終更新:2020年04月19日 15:22