chrome.bookmarks

توضیحات

از API chrome.bookmarks برای ایجاد، سازماندهی و دستکاری بوکمارک‌ها استفاده کنید. همچنین به بخش Override Pages مراجعه کنید که می‌توانید از آن برای ایجاد یک صفحه مدیریت بوکمارک سفارشی استفاده کنید.

کلیک روی ستاره، یک نشانک اضافه می‌کند
با کلیک روی ستاره، یک نشانک اضافه می‌شود.

مجوزها

bookmarks

برای استفاده از API بوکمارک‌ها، باید مجوز "bookmarks" را در مانیفست افزونه اعلام کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "bookmarks"
  ],
  ...
}

مفاهیم و کاربردها

اشیاء و ویژگی‌ها

بوک‌مارک‌ها در یک درخت سازماندهی می‌شوند، که در آن هر گره در درخت یا یک بوک‌مارک است یا یک پوشه (که گاهی اوقات گروه نامیده می‌شود). هر گره در درخت توسط یک شیء bookmarks.BookmarkTreeNode نمایش داده می‌شود.

ویژگی‌های BookmarkTreeNode در سراسر API chrome.bookmarks استفاده می‌شوند. برای مثال، وقتی bookmarks.create را فراخوانی می‌کنید، والد گره جدید ( parentId ) و به صورت اختیاری، ویژگی‌های index ، title و url گره را ارسال می‌کنید. برای اطلاعات بیشتر در مورد ویژگی‌هایی که یک گره می‌تواند داشته باشد، به bookmarks.BookmarkTreeNode مراجعه کنید.

مثال‌ها

کد زیر پوشه‌ای با عنوان "Extension bookmarks" ایجاد می‌کند. اولین آرگومان تابع create() ویژگی‌های پوشه جدید را مشخص می‌کند. آرگومان دوم تابعی را تعریف می‌کند که پس از ایجاد پوشه اجرا می‌شود.

chrome.bookmarks.create(
  {'parentId': bookmarkBar.id, 'title': 'Extension bookmarks'},
  function(newFolder) {
    console.log("added folder: " + newFolder.title);
  },
);

قطعه کد بعدی یک نشانه‌گذاری (bookmark) ایجاد می‌کند که به مستندات توسعه‌دهنده برای افزونه‌ها اشاره می‌کند. از آنجایی که در صورت عدم موفقیت در ایجاد نشانه‌گذاری، اتفاق بدی رخ نخواهد داد، این کد نیازی به تعریف یک تابع فراخوانی (callback function) ندارد.

chrome.bookmarks.create({
  'parentId': extensionsFolderId,
  'title': 'Extensions doc',
  'url': 'https://developer.chrome.com/docs/extensions',
});

برای امتحان کردن این API، نمونه API نشانک‌ها را از مخزن chrome-extension-samples نصب کنید.

انواع

BookmarkTreeNode

یک گره (یا یک نشانه‌گر یا یک پوشه) در درخت نشانه‌گر. گره‌های فرزند در پوشه والد خود مرتب شده‌اند.

خواص

  • کودکان

    BookmarkTreeNode [] اختیاری

    یک لیست مرتب از فرزندان این گره.

  • تاریخ اضافه شد

    شماره اختیاری

    وقتی این گره ایجاد شد، بر حسب میلی‌ثانیه از زمان شروع ( new Date(dateAdded) ).

  • تاریخ گروه اصلاح‌شده

    شماره اختیاری

    آخرین باری که محتویات این پوشه تغییر کرده است، بر حسب میلی‌ثانیه از زمان شروع.

  • تاریخآخرین استفاده

    شماره اختیاری

    کروم ۱۱۴+

    آخرین باری که این گره باز شده است، بر حسب میلی‌ثانیه از زمان شروع. برای پوشه‌ها تنظیم نشده است.

  • نوع پوشه

    نوع پوشه اختیاری

    کروم ۱۳۴+

    در صورت وجود، این پوشه‌ای است که توسط مرورگر اضافه می‌شود و توسط کاربر یا افزونه قابل تغییر نیست. گره‌های فرزند را می‌توان تغییر داد، اگر این گره ویژگی unmodifiable نداشته باشد. اگر گره توسط کاربر و افزونه قابل تغییر باشد، حذف می‌شود (پیش‌فرض).

    ممکن است صفر، یک یا چندین گره از هر نوع پوشه وجود داشته باشد. یک پوشه می‌تواند توسط مرورگر اضافه یا حذف شود، اما نه از طریق API افزونه‌ها.

  • شناسه

    رشته

    شناسه منحصر به فرد برای گره. شناسه‌ها در پروفایل فعلی منحصر به فرد هستند و حتی پس از راه‌اندازی مجدد مرورگر نیز معتبر باقی می‌مانند.

  • شاخص

    شماره اختیاری

    موقعیت مبتنی بر ۰ این گره در پوشه والدش.

  • شناسه والدین

    رشته اختیاری

    id پوشه والد. برای گره ریشه حذف می‌شود.

  • همگام‌سازی

    بولی

    کروم ۱۳۴+

    اینکه آیا این گره توسط مرورگر با حافظه حساب کاربری از راه دور کاربر همگام‌سازی شده است یا خیر. این می‌تواند برای تمایز بین نسخه‌های حساب کاربری و فقط محلی از یک FolderType یکسان استفاده شود. مقدار این ویژگی ممکن است برای یک گره موجود تغییر کند، به عنوان مثال در نتیجه اقدام کاربر.

    توجه: این نشان می‌دهد که آیا گره در ارائه‌دهنده حساب داخلی مرورگر ذخیره شده است یا خیر. این امکان وجود دارد که یک گره از طریق شخص ثالث همگام‌سازی شود، حتی اگر این مقدار نادرست باشد.

    برای گره‌های مدیریت‌شده (گره‌هایی که unmodifiable در آنها روی true تنظیم شده است)، این ویژگی همیشه false خواهد بود.

  • عنوان

    رشته

    متنی که برای گره نمایش داده می‌شود.

  • غیرقابل اصلاح

    "مدیریت شده"
    اختیاری

    دلیل غیرقابل تغییر بودن این گره را نشان می‌دهد. مقدار managed نشان می‌دهد که این گره توسط مدیر سیستم یا توسط متولی یک کاربر تحت نظارت پیکربندی شده است. در صورتی که گره توسط کاربر و افزونه قابل تغییر باشد، حذف می‌شود (پیش‌فرض).

  • آدرس اینترنتی

    رشته اختیاری

    آدرس اینترنتی (URL) که کاربر هنگام کلیک روی نشانک به آن هدایت می‌شود. برای پوشه‌ها حذف شده است.

BookmarkTreeNodeUnmodifiable

کروم ۴۴+

دلیل غیرقابل تغییر بودن این گره را نشان می‌دهد. مقدار managed نشان می‌دهد که این گره توسط مدیر سیستم پیکربندی شده است. در صورتی که گره توسط کاربر و افزونه قابل تغییر باشد، حذف می‌شود (پیش‌فرض).

ارزش

"مدیریت شده"

CreateDetails

شیء ارسال شده به تابع ()create.

خواص

  • شاخص

    شماره اختیاری

  • شناسه والدین

    رشته اختیاری

    به طور پیش‌فرض در پوشه‌ی Other Bookmarks قرار دارد.

  • عنوان

    رشته اختیاری

  • آدرس اینترنتی

    رشته اختیاری

FolderType

کروم ۱۳۴+

نوع پوشه را نشان می‌دهد.

شمارشی

"نوار نشانک‌ها"
پوشه‌ای که محتویات آن در بالای پنجره مرورگر نمایش داده می‌شود.

«دیگر»
نشانک‌هایی که در فهرست کامل نشانک‌ها در همه پلتفرم‌ها نمایش داده می‌شوند.

«موبایل»
نشانک‌ها عموماً در دستگاه‌های تلفن همراه کاربر موجود هستند، اما از طریق افزونه یا در مدیریت نشانک‌ها قابل تغییر هستند.

"مدیریت شده"
یک پوشه سطح بالا که ممکن است در صورتی وجود داشته باشد که مدیر سیستم یا متولی یک کاربر تحت نظارت، بوک‌مارک‌ها را پیکربندی کرده باشد.

خواص

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

منسوخ شده

عملیات نوشتن بوکمارک دیگر توسط کروم محدود نمی‌شود.

ارزش

۱۰۰۰۰۰۰

MAX_WRITE_OPERATIONS_PER_HOUR

منسوخ شده

عملیات نوشتن بوکمارک دیگر توسط کروم محدود نمی‌شود.

ارزش

۱۰۰۰۰۰۰

ROOT_NODE_ID

در حال بررسی

id مرتبط با گره سطح ریشه.

ارزش

«0»

روش‌ها

create()

chrome.bookmarks.create(
  bookmark: CreateDetails,
): Promise<BookmarkTreeNode>

یک بوکمارک یا پوشه تحت parentId مشخص شده ایجاد می‌کند. اگر url برابر با NULL باشد یا وجود نداشته باشد، یک پوشه خواهد بود.

پارامترها

بازگشت‌ها

get()

chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
): Promise<BookmarkTreeNode[]>

BookmarkTreeNode(s) مشخص شده را بازیابی می‌کند.

پارامترها

  • idOrIdList

    رشته | [رشته، ...رشته[]]

    یک شناسه رشته‌ای واحد، یا آرایه‌ای از شناسه‌های رشته‌ای

بازگشت‌ها

getChildren()

chrome.bookmarks.getChildren(
  id: string,
): Promise<BookmarkTreeNode[]>

فرزندان شناسه‌ی BookmarkTreeNode مشخص شده را بازیابی می‌کند.

پارامترها

  • شناسه

    رشته

بازگشت‌ها

getRecent()

chrome.bookmarks.getRecent(
  numberOfItems: number,
): Promise<BookmarkTreeNode[]>

نشانک‌های اخیراً اضافه شده را بازیابی می‌کند.

پارامترها

  • تعداد اقلام

    شماره

    حداکثر تعداد اقلامی که باید بازگردانده شوند.

بازگشت‌ها

getSubTree()

chrome.bookmarks.getSubTree(
  id: string,
): Promise<BookmarkTreeNode[]>

بخشی از سلسله مراتب نشانک‌ها را با شروع از گره مشخص شده بازیابی می‌کند.

پارامترها

  • شناسه

    رشته

    شناسه‌ی ریشه‌ی زیردرختی که قرار است بازیابی شود.

بازگشت‌ها

getTree()

chrome.bookmarks.getTree(): Promise<BookmarkTreeNode[]>

کل سلسله مراتب نشانک‌ها را بازیابی می‌کند.

بازگشت‌ها

move()

chrome.bookmarks.move(
  id: string,
  destination: object,
): Promise<BookmarkTreeNode>

BookmarkTreeNode مشخص شده را به مکان ارائه شده منتقل می‌کند.

پارامترها

  • شناسه

    رشته

  • مقصد

    شیء

    • شاخص

      شماره اختیاری

    • شناسه والدین

      رشته اختیاری

بازگشت‌ها

remove()

chrome.bookmarks.remove(
  id: string,
): Promise<void>

یک نشانک یا یک پوشه نشانک خالی را حذف می‌کند.

پارامترها

  • شناسه

    رشته

بازگشت‌ها

  • قول<void>

    کروم ۹۰+

removeTree()

chrome.bookmarks.removeTree(
  id: string,
): Promise<void>

به صورت بازگشتی یک پوشه بوکمارک را حذف می‌کند.

پارامترها

  • شناسه

    رشته

بازگشت‌ها

  • قول<void>

    کروم ۹۰+
chrome.bookmarks.search(
  query: string | object,
): Promise<BookmarkTreeNode[]>

جستجو برای BookmarkTreeNodes مطابق با پرس و جوی داده شده. پرس و جوهای مشخص شده با یک شیء، BookmarkTreeNodes مطابق با تمام ویژگی‌های مشخص شده را تولید می‌کنند.

پارامترها

  • پرس و جو

    رشته | شیء

    یا رشته‌ای از کلمات و عبارات نقل قول شده که با URLها و عناوین بوکمارک مطابقت دارند، یا یک شیء. اگر یک شیء باشد، می‌توان ویژگی‌های query ، url و title را مشخص کرد و بوکمارک‌هایی که با تمام ویژگی‌های مشخص شده مطابقت دارند، تولید می‌شوند.

    • پرس و جو

      رشته اختیاری

      رشته‌ای از کلمات و عبارات نقل قول شده که با URLها و عناوین بوکمارک‌ها مطابقت دارند.

    • عنوان

      رشته اختیاری

      عنوان نشانک؛ کلمه به کلمه مطابقت دارد.

    • آدرس اینترنتی

      رشته اختیاری

      آدرس اینترنتی نشانک؛ کلمه به کلمه مطابقت دارد. توجه داشته باشید که پوشه‌ها آدرس اینترنتی ندارند.

بازگشت‌ها

update()

chrome.bookmarks.update(
  id: string,
  changes: object,
): Promise<BookmarkTreeNode>

ویژگی‌های یک نشانه‌گذاری یا پوشه را به‌روزرسانی می‌کند. فقط ویژگی‌هایی را که می‌خواهید تغییر دهید مشخص کنید؛ ویژگی‌های نامشخص بدون تغییر باقی می‌مانند. توجه: در حال حاضر، فقط «عنوان» و «آدرس اینترنتی» پشتیبانی می‌شوند.

پارامترها

  • شناسه

    رشته

  • تغییرات

    شیء

    • عنوان

      رشته اختیاری

    • آدرس اینترنتی

      رشته اختیاری

بازگشت‌ها

رویدادها

onChanged

chrome.bookmarks.onChanged.addListener(
  callback: function,
)

وقتی یک نشانک یا پوشه تغییر می‌کند، فعال می‌شود. توجه: در حال حاضر، فقط تغییرات عنوان و آدرس اینترنتی این را فعال می‌کنند.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (id: string, changeInfo: object) => void

    • شناسه

      رشته

    • تغییراطلاعات

      شیء

      • عنوان

        رشته

      • آدرس اینترنتی

        رشته اختیاری

onChildrenReordered

chrome.bookmarks.onChildrenReordered.addListener(
  callback: function,
)

زمانی اجرا می‌شود که فرزندان یک پوشه به دلیل ترتیب مرتب‌سازی در رابط کاربری، ترتیب خود را تغییر داده باشند. این تابع در نتیجه‌ی تابع ()move فراخوانی نمی‌شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (id: string, reorderInfo: object) => void

    • شناسه

      رشته

    • اطلاعات سفارش مجدد

      شیء

      • شناسه‌های فرزند

        رشته[]

onCreated

chrome.bookmarks.onCreated.addListener(
  callback: function,
)

هنگام ایجاد یک بوکمارک یا پوشه، فعال می‌شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (id: string, bookmark: BookmarkTreeNode) => void

onImportBegan

chrome.bookmarks.onImportBegan.addListener(
  callback: function,
)

زمانی که یک جلسه‌ی وارد کردن بوک‌مارک آغاز می‌شود، اجرا می‌شود. ناظران گران‌قیمت باید به‌روزرسانی‌های onCreated را تا زمانی که onImportEnded اجرا شود، نادیده بگیرند. ناظران همچنان باید سایر اعلان‌ها را فوراً مدیریت کنند.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    () => void

onImportEnded

chrome.bookmarks.onImportEnded.addListener(
  callback: function,
)

هنگامی که جلسه وارد کردن نشانک پایان می‌یابد، اجرا می‌شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    () => void

onMoved

chrome.bookmarks.onMoved.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک بوک‌مارک یا پوشه به پوشه والد دیگری منتقل شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (id: string, moveInfo: object) => void

    • شناسه

      رشته

    • اطلاعات حرکت

      شیء

      • شاخص

        شماره

      • oldIndex

        شماره

      • شناسه والدین قدیمی

        رشته

      • شناسه والدین

        رشته

onRemoved

chrome.bookmarks.onRemoved.addListener(
  callback: function,
)

وقتی یک بوک‌مارک یا پوشه حذف می‌شود، فعال می‌شود. وقتی یک پوشه به صورت بازگشتی حذف می‌شود، یک اعلان برای پوشه فعال می‌شود و هیچ اعلانی برای محتویات آن فعال نمی‌شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (id: string, removeInfo: object) => void

    • شناسه

      رشته

    • حذف اطلاعات

      شیء

      • شاخص

        شماره

      • کروم ۴۸+
      • شناسه والدین

        رشته