chrome.bookmarks

توضیحات

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

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

مجوزها

bookmarks

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

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

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

اشیاء و خواص

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

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

نمونه ها

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

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

قطعه بعدی یک نشانک ایجاد می کند که به اسناد توسعه دهنده برای برنامه های افزودنی اشاره می کند. از آنجایی که اگر ایجاد نشانک ناموفق باشد، هیچ اتفاق بدی نمی‌افتد، این کد به خود زحمتی برای تعریف یک تابع برگشت نمی‌دهد.

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

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

انواع

BookmarkTreeNode

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

خواص

  • کودکان

    BookmarkTreeNode [] اختیاری است

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

  • dateAdded

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

    هنگامی که این گره ایجاد شد، در میلی ثانیه از دوران ( new Date(dateAdded) ).

  • dateGroupModified

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

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

  • dateLastUsed

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

    Chrome 114+

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

  • شناسه

    رشته

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

  • شاخص

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

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

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

    رشته اختیاری

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

  • عنوان

    رشته

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

  • غیر قابل تغییر

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

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

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

    رشته اختیاری

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

BookmarkTreeNodeUnmodifiable

Chrome 44+

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

ارزش

"مدیریت شده"

CreateDetails

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

خواص

  • شاخص

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

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

    رشته اختیاری

    به طور پیش فرض در پوشه سایر نشانک ها قرار می گیرد.

  • عنوان

    رشته اختیاری

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

    رشته اختیاری

خواص

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

منسوخ شده است

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

ارزش

1000000

MAX_WRITE_OPERATIONS_PER_HOUR

منسوخ شده است

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

ارزش

1000000

روش ها

create()

قول بده
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
)

یک نشانک یا پوشه تحت شناسه والدین مشخص شده ایجاد می کند. اگر آدرس اینترنتی NULL یا مفقود باشد، یک پوشه خواهد بود.

پارامترها

برمی گرداند

  • Promise< BookmarkTreeNode >

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

get()

قول بده
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
)

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

پارامترها

  • idOrIdList

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

    یک شناسه با مقدار رشته یا آرایه ای از شناسه های رشته ای

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: BookmarkTreeNode[]) => void

برمی گرداند

  • Promise< BookmarkTreeNode []>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getChildren()

قول بده
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
)

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

پارامترها

  • شناسه

    رشته

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: BookmarkTreeNode[]) => void

برمی گرداند

  • Promise< BookmarkTreeNode []>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getRecent()

قول بده
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
)

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

پارامترها

  • numberOfItems

    شماره

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: BookmarkTreeNode[]) => void

برمی گرداند

  • Promise< BookmarkTreeNode []>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getSubTree()

قول بده
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
)

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

پارامترها

  • شناسه

    رشته

    شناسه ریشه درخت فرعی برای بازیابی.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: BookmarkTreeNode[]) => void

برمی گرداند

  • Promise< BookmarkTreeNode []>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getTree()

قول بده
chrome.bookmarks.getTree(
  callback?: function,
)

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

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: BookmarkTreeNode[]) => void

برمی گرداند

  • Promise< BookmarkTreeNode []>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

move()

قول بده
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
)

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

پارامترها

  • شناسه

    رشته

  • مقصد

    شی

    • شاخص

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

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

      رشته اختیاری

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (result: BookmarkTreeNode) => void

برمی گرداند

  • Promise< BookmarkTreeNode >

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

remove()

قول بده
chrome.bookmarks.remove(
  id: string,
  callback?: function,
)

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

پارامترها

  • شناسه

    رشته

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

removeTree()

قول بده
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
)

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

پارامترها

  • شناسه

    رشته

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

قول بده
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
)

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

پارامترها

  • پرس و جو

    رشته | شی

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

    • پرس و جو

      رشته اختیاری

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

    • عنوان

      رشته اختیاری

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

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

      رشته اختیاری

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: BookmarkTreeNode[]) => void

برمی گرداند

  • Promise< BookmarkTreeNode []>

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

update()

قول بده
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
)

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

پارامترها

  • شناسه

    رشته

  • تغییر می کند

    شی

    • عنوان

      رشته اختیاری

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

      رشته اختیاری

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (result: BookmarkTreeNode) => void

برمی گرداند

  • Promise< BookmarkTreeNode >

    Chrome 90+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onChanged

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

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

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

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

    • شناسه

      رشته

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

      شی

      • عنوان

        رشته

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

        رشته اختیاری

onChildrenReordered

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

زمانی فعال می شود که فرزندان یک پوشه به دلیل مرتب شدن ترتیب در UI، ترتیب خود را تغییر داده باشند. این به عنوان یک نتیجه از یک 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

    • شناسه

      رشته

    • moveInfo

      شی

      • شاخص

        شماره

      • oldIndex

        شماره

      • oldParentId

        رشته

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

        رشته

onRemoved

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

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

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

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

    • شناسه

      رشته

    • removeInfo

      شی

      • شاخص

        شماره

      • Chrome 48+
      • شناسه والدین

        رشته