chrome.bookmarks

refresh date: 2026-09-25 robots: noindex

این اجازه هشداری را فعال می‌کند.

شرح

از chrome.bookmarks API برای ایجاد، سازمان‌دهی، و دستکاری نشانک‌ها استفاده کنید. همچنین صفحه‌های لغو را ببینید که می‌توانید از آن برای ایجاد صفحه سفارشی «مدیر نشانک» استفاده کنید.

اجازه‌ها

bookmarks

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

مانیفست

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

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

اشیاء و خصوصیت‌ها

نشانک‌ها به‌صورت درختی سازمان‌دهی می‌شوند، که در آن هر گره در درخت یا نشانک است یا پوشه (گاهی‌اوقات گروه نامیده می‌شود). هر گره در درخت با یک شیء 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',
});

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

انواع

BookmarkTreeNode

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

مشخصات

  • کودکان

    BookmarkTreeNode[] اختیاری

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

  • dateAdded

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

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

  • dateGroupModified

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

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

  • dateLastUsed

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

    Chrome نسخه ۱۱۴ و بالاتر

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

  • folderType

    FolderType اختیاری

    Chrome نسخه ۱۳۴ و بالاتر

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

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

  • id

    رشته

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

  • شاخص

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

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

  • parentId

    رشته اختیاری

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

  • درحال همگام‌سازی

    بولی

    Chrome نسخه ۱۳۴ و بالاتر

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

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

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

  • عنوان

    رشته

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

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

    "managed"
     اختیاری

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

  • نشانی وب

    رشته اختیاری

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

BookmarkTreeNodeUnmodifiable

Chrome نسخه ۴۴ به بالا

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

مقدار

"managed"

CreateDetails

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

مشخصات

  • شاخص

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

  • parentId

    رشته اختیاری

    به‌طور پیش‌فرض به پوشه «نشانک‌های دیگر» می‌رود.

  • عنوان

    رشته اختیاری

  • نشانی وب

    رشته اختیاری

FolderType

Chrome نسخه ۱۳۴ و بالاتر

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

شمارشی

«bookmarks-bar»
پوشه‌ای که محتوای آن در بالای پنجره مرورگر نمایش داده می‌شود.

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

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

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

مشخصات

MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

منسوخ‌شده

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

مقدار

۱۰۰۰۰۰۰

MAX_WRITE_OPERATIONS_PER_HOUR

منسوخ‌شده

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

مقدار

۱۰۰۰۰۰۰

ROOT_NODE_ID

Chrome نسخه ۱۴۵ و بالاتر

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

مقدار

«0»

روش‌ها

create()

قول 
chrome.bookmarks.create(
  bookmark: CreateDetails,
  callback?: function,
): Promise<BookmarkTreeNode>

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

پارامترها

بازگشتی‌ها

  • Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

get()

قول 
chrome.bookmarks.get(
  idOrIdList: string | [string, ...string[]],
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

پارامترها

  • idOrIdList

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

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: BookmarkTreeNode[]) => void

بازگشتی‌ها

  • Promise<BookmarkTreeNode[]>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getChildren()

قول 
chrome.bookmarks.getChildren(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

پارامترها

  • id

    رشته

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: BookmarkTreeNode[]) => void

بازگشتی‌ها

  • Promise<BookmarkTreeNode[]>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getRecent()

قول 
chrome.bookmarks.getRecent(
  numberOfItems: number,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

پارامترها

  • numberOfItems

    شماره

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: BookmarkTreeNode[]) => void

بازگشتی‌ها

  • Promise<BookmarkTreeNode[]>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getSubTree()

قول 
chrome.bookmarks.getSubTree(
  id: string,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

پارامترها

  • id

    رشته

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: BookmarkTreeNode[]) => void

بازگشتی‌ها

  • Promise<BookmarkTreeNode[]>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getTree()

قول 
chrome.bookmarks.getTree(
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: BookmarkTreeNode[]) => void

بازگشتی‌ها

  • Promise<BookmarkTreeNode[]>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

move()

قول 
chrome.bookmarks.move(
  id: string,
  destination: object,
  callback?: function,
): Promise<BookmarkTreeNode>

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

پارامترها

  • id

    رشته

  • مقصد

    شیء

    • شاخص

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

    • parentId

      رشته اختیاری

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: BookmarkTreeNode) => void

بازگشتی‌ها

  • Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

remove()

قول 
chrome.bookmarks.remove(
  id: string,
  callback?: function,
): Promise<void>

نشانک یا پوشه نشانک خالی را برمی‌دارد.

پارامترها

  • id

    رشته

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

removeTree()

قول 
chrome.bookmarks.removeTree(
  id: string,
  callback?: function,
): Promise<void>

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

پارامترها

  • id

    رشته

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

قول 
chrome.bookmarks.search(
  query: string | object,
  callback?: function,
): Promise<BookmarkTreeNode[]>

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

پارامترها

  • پُرسمان

    رشته | شیء

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

    • پُرسمان

      رشته اختیاری

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

    • عنوان

      رشته اختیاری

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

    • نشانی وب

      رشته اختیاری

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: BookmarkTreeNode[]) => void

بازگشتی‌ها

  • Promise<BookmarkTreeNode[]>

    Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

update()

قول 
chrome.bookmarks.update(
  id: string,
  changes: object,
  callback?: function,
): Promise<BookmarkTreeNode>

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

پارامترها

  • id

    رشته

  • تغییرات

    شیء

    • عنوان

      رشته اختیاری

    • نشانی وب

      رشته اختیاری

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: BookmarkTreeNode) => void

بازگشتی‌ها

  • Chrome نسخه ۹۰ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onChanged

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • id

      رشته

    • changeInfo

      شیء

      • عنوان

        رشته

      • نشانی وب

        رشته اختیاری

onChildrenReordered

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • id

      رشته

    • reorderInfo

      شیء

      • childIds

        string[]

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

    • id

      رشته

    • moveInfo

      شیء

      • شاخص

        شماره

      • oldIndex

        شماره

      • oldParentId

        رشته

      • parentId

        رشته

onRemoved

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

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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

    • id

      رشته

    • removeInfo

      شیء

      • شاخص

        شماره

      • Chrome نسخه ۴۸ به بالا
      • parentId

        رشته