diff options
Diffstat (limited to 'files/ru/mozilla/add-ons/sdk/low-level_apis/places_bookmarks/index.html')
| -rw-r--r-- | files/ru/mozilla/add-ons/sdk/low-level_apis/places_bookmarks/index.html | 595 |
1 files changed, 0 insertions, 595 deletions
diff --git a/files/ru/mozilla/add-ons/sdk/low-level_apis/places_bookmarks/index.html b/files/ru/mozilla/add-ons/sdk/low-level_apis/places_bookmarks/index.html deleted file mode 100644 index 299e234fb2..0000000000 --- a/files/ru/mozilla/add-ons/sdk/low-level_apis/places_bookmarks/index.html +++ /dev/null @@ -1,595 +0,0 @@ ---- -title: places/bookmarks -slug: Mozilla/Add-ons/SDK/Low-Level_APIs/places_bookmarks -translation_of: Archive/Add-ons/Add-on_SDK/Low-Level_APIs/places_bookmarks ---- -<div class="note"> -<p>Unstable</p> -</div> - -<p><span class="seoSummary">Создание, изменение и удаление закладок.</span></p> - -<h2 id="Usage">Usage</h2> - -<p>Этот модуль экспортирует:</p> - -<ul> - <li>три конструктора: <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Bookmark(options)">Bookmark</a>, <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Group(options)">Group</a>, and <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Separator(options)">Separator</a>, corresponding to the types of objects, referred to as <strong>bookmark items</strong>, in the Bookmarks database in Firefox</li> - <li>две дополнительные функции, <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#save(bookmarkItems.2C_options)"><code>save()</code></a> для создания, обновения и удаления закладок, и <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#search(queries.2C_options)"><code>search()</code></a> для получения закладок соответствующих параметрам запроса.</li> -</ul> - -<p><code>save()</code> и <code>search()</code> асинхронные функции: they synchronously return a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#PlacesEmitter"><code>PlacesEmitter</code></a> object, which then asynchronously emits events as the operation progresses and completes.</p> - -<p>Each retrieved bookmark item represents only a snapshot of state at a specific time. The module does not automatically sync up a <code>Bookmark</code> instance with ongoing changes to that item in the database from the same add-on, other add-ons, or the user.</p> - -<h3 id="Примеры">Примеры</h3> - -<h4 id="Создание_новой_закладки">Создание новой закладки</h4> - -<pre class="brush: js">let { Bookmark, save } = require("sdk/places/bookmarks"); - -// Create a new bookmark instance, unsaved -let bookmark = Bookmark({ title: "Mozilla", url: "http://mozilla.org" }); - -// Attempt to save the bookmark instance to the Bookmarks database -// and store the emitter -let emitter = save(bookmark); - -// Listen for events -emitter.on("data", function (saved, inputItem) { - // on a "data" event, an item has been updated, passing in the - // latest snapshot from the server as `saved` (with properties - // such as `updated` and `id`), as well as the initial input - // item as `inputItem` - console.log(saved.title === inputItem.title); // true - console.log(saved !== inputItem); // true - console.log(inputItem === bookmark); // true -}).on("end", function (savedItems, inputItems) { - // Similar to "data" events, except "end" is an aggregate of - // all progress events, with ordered arrays as `savedItems` - // and `inputItems` -});</pre> - -<h4 id="Создание_нескольких_закладок_в_группе">Создание нескольких закладок в группе</h4> - -<pre class="brush: js">let { Bookmark, Group, save } = require("sdk/places/bookmarks"); - -let group = Group({ title: "Guitars" }); -let bookmarks = [ - Bookmark({ title: "Ran", url: "http://ranguitars.com", group: group }), - Bookmark({ title: "Ibanez", url: "http://ibanez.com", group: group }), - Bookmark({ title: "ESP", url: "http://espguitars.com", group: group }) -]; - -// Save `bookmarks` array -- notice we don't have `group` in the array, -// although it needs to be saved since all bookmarks are children -// of `group`. This will be saved implicitly. - -save(bookmarks).on("data", function (saved, input) { - // A data event is called once for each item saved, as well - // as implicit items, like `group` - console.log(input === group || ~bookmarks.indexOf(input)); // true -}).on("end", function (saves, inputs) { - // like the previous example, the "end" event returns an - // array of all of our updated saves. Only explicitly saved - // items are returned in this array -- the `group` won't be - // present here. - console.log(saves[0].title); // "Ran" - console.log(saves[2].group.title); // "Guitars" -});</pre> - -<h4 id="Поиск_закладок">Поиск закладок</h4> - -<p>Bookmarks can be queried with the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#search(queries.2C_options)"><code>search()</code></a> function, which accepts a query object or an array of query objects, as well as a query options object. Query properties are AND'd together within a single query object, but are OR'd together across multiple query objects.</p> - -<pre class="brush: js">let { search, UNSORTED } = require("sdk/places/bookmarks"); - -// Simple query with one object -search( - { query: "firefox" }, - { sort: "title" } -).on(end, function (results) { - // results matching any bookmark that has "firefox" - // in its URL, title or tag, sorted by title -}); - -// Multiple queries are OR'd together -search( - [{ query: "firefox" }, { group: UNSORTED, tags: ["mozilla"] }], - { sort: "title" } -).on("end", function (results) { - // Our first query is the same as the simple query above; - // all of those results are also returned here. Since multiple - // queries are OR'd together, we also get bookmarks that - // match the second query. The second query's properties - // are AND'd together, so results that are in the platform's unsorted - // bookmarks folder, AND are also tagged with 'mozilla', get returned - // as well in this query -});</pre> - -<h2 id="Globals">Globals</h2> - -<h3 id="Constructors">Constructors</h3> - -<h4 class="addon-sdk-api-name" id="Bookmark(options)"><code>Bookmark(options)</code></h4> - -<p>Creates an unsaved bookmark instance.</p> - -<h5 id="Parameters">Parameters</h5> - -<p><strong>options : object</strong><br> - Required options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>title</td> - <td>string</td> - <td> - <p>The title for the bookmark. Required.</p> - </td> - </tr> - <tr> - <td>url</td> - <td>string</td> - <td> - <p>The URL for the bookmark. Required.</p> - </td> - </tr> - </tbody> -</table> - -<p>Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>group</td> - <td>Group</td> - <td> - <p>The parent group that the bookmark lives under. Defaults to the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#UNSORTED">Bookmarks.UNSORTED</a> group.</p> - </td> - </tr> - <tr> - <td>index</td> - <td>number</td> - <td> - <p>The index of the bookmark within its group. Last item within the group by default.</p> - </td> - </tr> - <tr> - <td>tags</td> - <td>set</td> - <td> - <p>A set of tags to be applied to the bookmark.</p> - </td> - </tr> - </tbody> -</table> - -<h4 class="addon-sdk-api-name" id="Group(options)"><code>Group(options)</code></h4> - -<p>Creates an unsaved bookmark group instance.</p> - -<h5 id="Parameters_2">Parameters</h5> - -<p><strong>options : object</strong><br> - Required options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>title</td> - <td>string</td> - <td> - <p>The title for the group. Required.</p> - </td> - </tr> - </tbody> -</table> - -<p>Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>group</td> - <td>Group</td> - <td> - <p>The parent group that the bookmark group lives under. Defaults to the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#UNSORTED">Bookmarks.UNSORTED</a> group.</p> - </td> - </tr> - <tr> - <td>index</td> - <td>number</td> - <td> - <p>The index of the bookmark group within its parent group. Last item within the group by default.</p> - </td> - </tr> - </tbody> -</table> - -<h4 class="addon-sdk-api-name" id="Separator(options)"><code>Separator(options)</code></h4> - -<p>Creates an unsaved bookmark separator instance.</p> - -<h5 id="Parameters_3">Parameters</h5> - -<p><strong>options : object</strong><br> - Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>group</td> - <td>Group</td> - <td> - <p>The parent group that the bookmark group lives under. Defaults to the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#UNSORTED">Bookmarks.UNSORTED</a> group.</p> - </td> - </tr> - <tr> - <td>index</td> - <td>number</td> - <td> - <p>The index of the bookmark group within its parent group. Last item within the group by default.</p> - </td> - </tr> - </tbody> -</table> - -<h3 id="Functions">Functions</h3> - -<h4 class="addon-sdk-api-name" id="save(bookmarkItems_options)"><code>save(bookmarkItems, options)</code></h4> - -<p>Creating, saving, and deleting bookmarks are all done with the <code>save()</code> function. This function takes in any of:</p> - -<ul> - <li>a bookmark item (Bookmark, Group, Separator)</li> - <li>a duck-typed object (the relative properties for a bookmark item, in addition to a <code>type</code> property of <code>'bookmark'</code>, <code>'group'</code>, or <code>'separator'</code>)</li> - <li>an array of bookmark items.</li> -</ul> - -<p>All of the items passed in are pushed to the platform and are either created, updated or deleted.</p> - -<ul> - <li>adding items: if passing in freshly instantiated bookmark items or a duck-typed object, the item is created on the platform.</li> - <li>updating items: for an item referenced from a previous <code>save()</code> or from the result of a <code>search()</code> query, changing the properties and calling <code>save()</code> will update the item on the server.</li> - <li>deleting items: to delete a bookmark item, pass in a bookmark item with a property <code>remove</code> set to <code>true</code>.</li> -</ul> - -<p>The function returns a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#PlacesEmitter"><code>PlacesEmitter</code></a> that emits a <code>data</code> event for each item as it is saved, and an <code>end</code> event when all items have been saved.</p> - -<pre class="brush: js">let { Bookmark, Group } = require("sdk/places/bookmarks"); - -let myGroup = Group({ title: "My Group" }); -let myBookmark = Bookmark({ - title: "Moz", - url: "http://mozilla.com", - group: myGroup -}); - -save(myBookmark).on("data", function (item, inputItem) { - // The `data` event returns the latest snapshot from the - // host, so this is a new instance of the bookmark item, - // where `item !== myBookmark`. To match it with the input item, - // use the second argument, so `inputItem === myBookmark` - - // All explicitly saved items have data events called, as - // well as implicitly saved items. In this case, - // `myGroup` has to be saved before `myBookmark`, since - // `myBookmark` is a child of `myGroup`. `myGroup` will - // also have a `data` event called for it. -}).on("end", function (items, inputItems) { - // The `end` event returns all items that are explicitly - // saved. So `myGroup` will not be in this array, - // but `myBookmark` will be. - // `inputItems` matches the initial input as an array, - // so `inputItems[0] === myBookmark` -}); - -// Saving multiple bookmarks, as duck-types in this case - -let bookmarks = [ - { title: "mozilla", url: "http://mozilla.org", type: "bookmark" }, - { title: "firefox", url: "http://firefox.com", type: "bookmark" }, - { title: "twitter", url: "http://twitter.com", type: "bookmark" } -]; - -save(bookmarks).on("data", function (item, inputItem) { - // Each item in `bookmarks` has its own `data` event -}).on("end", function (results, inputResults) { - // `results` is an array of items saved in the same order - // as they were passed in. -});</pre> - -<h5 id="Parameters_4">Parameters</h5> - -<p><strong>bookmarkItems : bookmark|group|separator|array</strong><br> - A bookmark item (<a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Bookmark">Bookmark</a>, <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Group">Group</a>, <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Separator">Separator</a>), or an array of bookmark items to be saved.</p> - -<p><strong>options : object</strong><br> - Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>resolve</td> - <td>function</td> - <td> - <p>A resolution function that is invoked during an attempt to save a bookmark item that is not derived from the latest state from the platform. Invoked with two arguments, <code>mine</code> and <code>platform</code>, where <code>mine</code> is the item that is being saved, and <code>platform</code> is the current state of the item on the item. The object returned from this function is what is saved on the platform. By default, all changes on an outdated bookmark item overwrite the platform's bookmark item.</p> - </td> - </tr> - </tbody> -</table> - -<h5 id="Returns">Returns</h5> - -<p><strong>PlacesEmitter</strong> : Returns a <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#PlacesEmitter">PlacesEmitter</a>.</p> - -<h4 class="addon-sdk-api-name" id="remove(items)"><code>remove(items)</code></h4> - -<p>A helper function that takes in a bookmark item, or an <code>Array</code> of several bookmark items, and sets each item's <code>remove</code> property to true. This does not remove the bookmark item from the database: it must be subsequently saved.</p> - -<pre class="brush: js">let { search, save, remove } = require("sdk/places/bookmarks"); - -search({ tags: ["php"] }).on("end", function (results) { - // The search returns us all bookmark items that are - // tagged with `"php"`. - - // We then pass `results` into the remove function to mark - // all items to be removed, which returns the new modified `Array` - // of items, which is passed into save. - save(remove(results)).on("end", function (results) { - // items tagged with `"php"` are now removed! - }); -})</pre> - -<h5 id="Parameters_5">Parameters</h5> - -<p><strong>items : Bookmark|Group|Separator|array</strong><br> - A bookmark item, or <code>Array</code> of bookmark items to be transformed to set their <code>remove</code> property to <code>true</code>.</p> - -<h5 id="Returns_2">Returns</h5> - -<p><strong>array</strong> : An array of the transformed bookmark items.</p> - -<h4 class="addon-sdk-api-name" id="search(queries_options)"><code>search(queries, options)</code></h4> - -<p>Queries can be performed on bookmark items by passing in one or more query objects, each of which is given one or more properties.</p> - -<p>Within each query object, the properties are AND'd together: so only objects matching all properties are retrieved. Across query objects, the results are OR'd together, meaning that if an item matches any of the query objects, it will be retrieved.</p> - -<p>For example, suppose we called <code>search()</code> with two query objects:</p> - -<pre class="brush: js">[{ url: "mozilla.org", tags: ["mobile"]}, -{ tags: ["firefox-os"]}]</pre> - -<p>This will return:</p> - -<ul> - <li>all bookmark items from mozilla.org that are also tagged "mobile"</li> - <li>all bookmark items that are tagged "firefox-os"</li> -</ul> - -<p>An <code>options</code> object may be used to determine overall settings such as sort order and how many objects should be returned.</p> - -<h5 id="Parameters_6">Parameters</h5> - -<p><strong>queries : object|array</strong><br> - An <code>Object</code> representing a query, or an <code>Array</code> of <code>Objects</code> representing queries. Each query object can take several properties, which are queried against the bookmarks database. Each property is AND'd together, meaning that bookmarks must match each property within a query object. Multiple query objects are then OR'd together.</p> - -<p><strong>options : object</strong><br> - Optional options:</p> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">Name</th> - <th scope="col">Type</th> - <th scope="col"> </th> - </tr> - </thead> - <tbody> - <tr> - <td>count</td> - <td>number</td> - <td> - <p>The number of bookmark items to return. If left undefined, no limit is set.</p> - </td> - </tr> - <tr> - <td>sort</td> - <td>string</td> - <td> - <p>A string specifying how the results should be sorted. Possible options are <code>'title'</code>, <code>'date'</code>, <code>'url'</code>, <code>'visitCount'</code>, <code>'dateAdded'</code> and <code>'lastModified'</code>.</p> - </td> - </tr> - <tr> - <td>descending</td> - <td>boolean</td> - <td> - <p>A boolean specifying whether the results should be in descending order. By default, results are in ascending order.</p> - </td> - </tr> - </tbody> -</table> - -<h3 id="Properties">Properties</h3> - -<h4 class="addon-sdk-api-name" id="MENU"><code>MENU</code></h4> - -<p>This is a constant, default <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Group"><code>Group</code></a> on the Firefox platform, the <strong>Bookmarks Menu</strong>. It can be used in queries or specifying the parent of a bookmark item, but it cannot be modified.</p> - -<h4 class="addon-sdk-api-name" id="TOOLBAR"><code>TOOLBAR</code></h4> - -<p>This is a constant, default <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Group"><code>Group</code></a> on the Firefox platform, the <strong>Bookmarks Toolbar</strong>. It can be used in queries or specifying the parent of a bookmark item, but it cannot be modified.</p> - -<h4 class="addon-sdk-api-name" id="UNSORTED"><code>UNSORTED</code></h4> - -<p>This is a constant, default <a href="/en-US/Add-ons/SDK/Low-Level_APIs/places_bookmarks#Group"><code>Group</code></a> on the Firefox platform, the <strong>Unsorted Bookmarks</strong> group. It can be used in queries or specifying the parent of a bookmark item, but it cannot be modified.</p> - -<h2 id="Bookmark">Bookmark</h2> - -<h3 id="Properties_2">Properties</h3> - -<h4 class="addon-sdk-api-name" id="title"><code>title</code></h4> - -<p>The bookmark's title.</p> - -<h4 class="addon-sdk-api-name" id="url"><code>url</code></h4> - -<p>The bookmark's URL.</p> - -<h4 class="addon-sdk-api-name" id="group"><code>group</code></h4> - -<p>The group instance that the bookmark lives under.</p> - -<h4 class="addon-sdk-api-name" id="index"><code>index</code></h4> - -<p>The index of the bookmark within its group.</p> - -<h4 class="addon-sdk-api-name" id="updated"><code>updated</code></h4> - -<p>A Unix timestamp indicating when the bookmark was last updated on the platform.</p> - -<h4 class="addon-sdk-api-name" id="tags"><code>tags</code></h4> - -<p>A <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set">Set</a> of tags that the bookmark is tagged with.</p> - -<h2 id="Group">Group</h2> - -<h3 id="Properties_3">Properties</h3> - -<h4 class="addon-sdk-api-name" id="title_2"><code>title</code></h4> - -<p>The bookmark group's title.</p> - -<h4 class="addon-sdk-api-name" id="group_2"><code>group</code></h4> - -<p>The group instance that the bookmark group lives under.</p> - -<h4 class="addon-sdk-api-name" id="index_2"><code>index</code></h4> - -<p>The index of the bookmark group within its group.</p> - -<h4 class="addon-sdk-api-name" id="updated_2"><code>updated</code></h4> - -<p>A Unix timestamp indicating when the bookmark was last updated on the platform.</p> - -<h2 id="Separator">Separator</h2> - -<h3 id="Properties_4">Properties</h3> - -<h4 class="addon-sdk-api-name" id="group_3"><code>group</code></h4> - -<p>The group instance that the bookmark group lives under.</p> - -<h4 class="addon-sdk-api-name" id="index_3"><code>index</code></h4> - -<p>The index of the bookmark group within its group.</p> - -<h4 class="addon-sdk-api-name" id="updated_3"><code>updated</code></h4> - -<p>A Unix timestamp indicating when the bookmark was last updated on the platform.</p> - -<h2 id="PlacesEmitter">PlacesEmitter</h2> - -<p>The <code>PlacesEmitter</code> is not exported from the module, but returned from the <code>save</code> and <code>search</code> functions. The <code>PlacesEmitter</code> inherits from <a href="/en-US/Add-ons/SDK/Low-Level_APIs/event_target"><code>event/target</code></a>, and emits <code>data</code>, <code>error</code>, and <code>end</code>.</p> - -<p><code>data</code> events are emitted for every individual operation (such as: each item saved, or each item found by a search query), whereas <code>end</code> events are emitted as the aggregate of an operation, passing an array of objects into the handler.</p> - -<h3 id="Events">Events</h3> - -<h4 class="addon-sdk-api-name" id="data"><code>data</code></h4> - -<p>The <code>data</code> event is emitted when a bookmark item that was passed into the <code>save</code> method has been saved to the platform. This includes implicit saves that are dependencies of the explicit items saved. For example, when creating a new bookmark group with two bookmark items as its children, and explicitly saving the two bookmark children, the unsaved parent group will also emit a <code>data</code> event.</p> - -<pre class="brush: js">let { Bookmark, Group, save } = require("sdk/places/bookmarks"); - -let group = Group({ title: "my group" }); -let bookmarks = [ - Bookmark({ title: "mozilla", url: "http://mozilla.com", group: group }), - Bookmark({ title: "w3", url: "http://w3.org", group: group }) -]; - -save(bookmarks).on("data", function (item) { - // This function will be called three times: - // once for each bookmark saved - // once for the new group specified implicitly - // as the parent of the two items -});</pre> - -<p>The <code>data</code> event is also called for <code>search</code> requests, with each result being passed individually into its own <code>data</code> event.</p> - -<pre class="brush: js">let { search } = require("sdk/places/bookmarks"); - -search({ query: "firefox" }).on("data", function (item) { - // each bookmark item that matches the query will - // be called in this function -});</pre> - -<h5 id="Arguments">Arguments</h5> - -<p><strong>Bookmark|Group|Separator</strong> : For the <code>save</code> function, this is the saved, latest snapshot of the bookmark item. For <code>search</code>, this is a snapshot of a bookmark returned from the search query.</p> - -<p><strong>Bookmark|Group|Separator|object</strong> : Only in <code>save</code> data events. The initial instance of the item that was used for the save request.</p> - -<h4 class="addon-sdk-api-name" id="error"><code>error</code></h4> - -<p>The <code>error</code> event is emitted whenever a bookmark item's save could not be completed.</p> - -<h5 id="Arguments_2">Arguments</h5> - -<p><strong>string</strong> : A string indicating the error that occurred.</p> - -<p><strong>Bookmark|Group|Separator|object</strong> : Only in <code>save</code> error events. The initial instance of the item that was used for the save request.</p> - -<h4 class="addon-sdk-api-name" id="end"><code>end</code></h4> - -<p>The <code>end</code> event is called when all bookmark items and dependencies have been saved, or an aggregate of all items returned from a search query.</p> - -<h5 id="Arguments_3">Arguments</h5> - -<p><strong>array</strong> : The array is an ordered list of the input bookmark items, replaced with their updated, latest snapshot instances (the first argument in the <code>data</code> handler), or in the case of an error, the initial instance of the item that was used for the save request (the second argument in the <code>data</code> or <code>error</code> handler).</p> |