chrome.windows

Mô tả

Dùng API chrome.windows để tương tác với các cửa sổ trình duyệt. Bạn có thể sử dụng API này để tạo, sửa đổi và sắp xếp lại các cửa sổ trong trình duyệt.

Quyền

Khi được yêu cầu, windows.Window sẽ chứa một mảng các đối tượng tabs.Tab. Bạn phải khai báo quyền "tabs" trong tệp kê khai nếu bạn cần quyền truy cập vào url, Thuộc tính pendingUrl, title hoặc favIconUrl của tabs.Tab. Ví dụ:

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

Khái niệm và cách sử dụng

Cửa sổ hiện tại

Nhiều hàm trong hệ thống tiện ích lấy đối số windowId không bắt buộc, mặc định là cửa sổ hiện tại.

Cửa sổ hiện tại là cửa sổ chứa mã hiện đang thực thi. Bây giờ bạn cần lưu ý rằng cửa sổ này có thể khác với cửa sổ trên cùng hoặc cửa sổ được lấy tiêu điểm.

Ví dụ: giả sử tiện ích tạo một vài thẻ hoặc cửa sổ từ một tệp HTML và Tệp HTML chứa lệnh gọi đến tabs.query(). Cửa sổ hiện tại là cửa sổ chứa đã thực hiện cuộc gọi, bất kể cửa sổ trên cùng là gì.

Trong trường hợp service worker, giá trị của cửa sổ hiện tại sẽ quay về giá trị hoạt động gần đây nhất cửa sổ. Trong một số trường hợp, có thể không có cửa sổ hiện tại cho các trang nền.

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API Windows trong chrome-extension-samples kho lưu trữ.

Hai cửa sổ, mỗi cửa sổ có một thẻ
Hai cửa sổ, mỗi cửa sổ có một thẻ.

Loại

CreateType

Chrome 44 trở lên

Chỉ định loại cửa sổ trình duyệt cần tạo. "panel" không được dùng nữa và chỉ được cung cấp cho các tiện ích hiện có trong danh sách cho phép trên Chrome OS.

Enum

"normal"
Chỉ định cửa sổ làm cửa sổ chuẩn.

"pop"
Chỉ định cửa sổ là cửa sổ bật lên.

"panel"
Chỉ định cửa sổ làm bảng điều khiển.

QueryOptions

Chrome 88 trở lên

Thuộc tính

  • điền sẵn

    boolean không bắt buộc

    Nếu đúng, đối tượng windows.Window sẽ có thuộc tính tabs chứa danh sách các đối tượng tabs.Tab. Các đối tượng Tab chỉ chứa các thuộc tính url, pendingUrl, title và favIconUrl nếu tệp kê khai của tiện ích bao gồm quyền "tabs".

  • windowTypes

    WindowType[] không bắt buộc

    Nếu được đặt, windows.Window được trả về sẽ được lọc dựa trên loại tương ứng. Nếu bạn không đặt chính sách này, bộ lọc mặc định sẽ được đặt thành ['normal', 'popup'].

Window

Thuộc tính

  • alwaysOnTop

    boolean

    Liệu cửa sổ có được đặt thành luôn ở trên cùng hay không.

  • tập trung

    boolean

    Liệu cửa sổ hiện có phải là cửa sổ được lấy tiêu điểm hay không.

  • độ cao

    số không bắt buộc

    Chiều cao của cửa sổ, bao gồm cả khung, tính bằng pixel. Trong một số trường hợp, bạn không thể chỉ định thuộc tính height cho một cửa sổ; ví dụ: khi truy vấn cửa sổ đã đóng từ API sessions.

  • id

    số không bắt buộc

    Mã nhận dạng của cửa sổ. Mã cửa sổ là duy nhất trong một phiên trình duyệt. Trong một số trường hợp, bạn không thể chỉ định thuộc tính ID cho một cửa sổ; ví dụ: khi truy vấn cửa sổ bằng API sessions, trong trường hợp này, mã phiên có thể xuất hiện.

  • ẩn danh

    boolean

    Liệu cửa sổ có ở chế độ ẩn danh hay không.

  • trái

    số không bắt buộc

    Độ lệch của cửa sổ từ cạnh trái màn hình tính bằng pixel. Trong một số trường hợp, bạn không thể chỉ định thuộc tính left cho một cửa sổ; ví dụ: khi truy vấn cửa sổ đã đóng từ API sessions.

  • sessionId

    chuỗi không bắt buộc

    Mã phiên được dùng để nhận dạng duy nhất một cửa sổ, lấy từ API sessions.

  • tiểu bang

    WindowState không bắt buộc

    Trạng thái của cửa sổ trình duyệt này.

  • thẻ

    Tab[] không bắt buộc

    Mảng các đối tượng tabs.Tab đại diện cho các thẻ hiện tại trong cửa sổ.

  • trên cùng

    số không bắt buộc

    Độ lệch của cửa sổ tính từ cạnh trên của màn hình, tính bằng pixel. Trong một số trường hợp, bạn không thể chỉ định thuộc tính top cho một cửa sổ; ví dụ: khi truy vấn cửa sổ đã đóng từ API sessions.

  • loại

    WindowType không bắt buộc

    Loại cửa sổ trình duyệt.

  • chiều rộng

    số không bắt buộc

    Chiều rộng của cửa sổ, bao gồm cả khung, tính bằng pixel. Trong một số trường hợp, bạn không thể chỉ định thuộc tính width cho một cửa sổ; ví dụ: khi truy vấn cửa sổ đã đóng từ API sessions.

WindowState

Chrome 44 trở lên

Trạng thái của cửa sổ trình duyệt này. Trong một số trường hợp, bạn không thể chỉ định thuộc tính state cho một cửa sổ; ví dụ: khi truy vấn cửa sổ đã đóng từ API sessions.

Enum

"normal"
Trạng thái của cửa sổ thông thường (không thu nhỏ, phóng to hoặc toàn màn hình).

"minimized"
Trạng thái cửa sổ đã thu nhỏ.

"Phóng to"
Trạng thái cửa sổ được phóng to.

"fullscreen"
Trạng thái cửa sổ toàn màn hình.

"lock-fullscreen"
Trạng thái của cửa sổ toàn màn hình bị khoá. Hành động của người dùng không thể thoát khỏi trạng thái toàn màn hình này. Trạng thái này chỉ có trên các tiện ích trong danh sách cho phép trên Chrome OS.

WindowType

Chrome 44 trở lên

Loại cửa sổ trình duyệt. Trong một số trường hợp, bạn không thể chỉ định thuộc tính type cho một cửa sổ; ví dụ: khi truy vấn cửa sổ đã đóng từ API sessions.

Enum

"normal"
Cửa sổ trình duyệt bình thường.

"pop"
Một cửa sổ bật lên của trình duyệt.

"panel"
Không dùng nữa trong API này. Cửa sổ kiểu bảng điều khiển trong Ứng dụng Chrome. Các tiện ích chỉ có thể thấy cửa sổ bảng điều khiển riêng của chúng.

"app"
Không dùng nữa trong API này. Cửa sổ Ứng dụng Chrome. Các tiện ích chỉ có thể xem cửa sổ của chính ứng dụng đang hoạt động.

"devtools"
Cửa sổ Công cụ cho nhà phát triển.

Thuộc tính

WINDOW_ID_CURRENT

Giá trị windowId đại diện cho cửa sổ hiện tại.

Giá trị

-2

WINDOW_ID_NONE

Giá trị windowId thể hiện việc không có cửa sổ trình duyệt Chrome.

Giá trị

-1

Phương thức

create()

Lời hứa 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

Tạo (mở) một cửa sổ trình duyệt mới kèm theo bất kỳ kích thước, vị trí hoặc URL mặc định nào được cung cấp sẵn.

Tham số

  • createData

    đối tượng không bắt buộc

    • tập trung

      boolean không bắt buộc

      Nếu true, mở một cửa sổ đang hoạt động. Nếu false, mở một cửa sổ không hoạt động.

    • độ cao

      số không bắt buộc

      Chiều cao tính bằng pixel của cửa sổ mới, bao gồm cả khung. Nếu không được chỉ định, giá trị mặc định sẽ là chiều cao tự nhiên.

    • ẩn danh

      boolean không bắt buộc

      Liệu cửa sổ mới có phải là cửa sổ ẩn danh hay không.

    • trái

      số không bắt buộc

      Số lượng pixel để định vị cửa sổ mới từ cạnh trái của màn hình. Nếu không được chỉ định, cửa sổ mới sẽ được bù trừ một cách tự nhiên từ cửa sổ được lấy tiêu điểm cuối cùng. Giá trị này sẽ bị bỏ qua đối với các bảng điều khiển.

    • setSelfAsOpener

      boolean không bắt buộc

      Chrome 64 trở lên

      Nếu là true, "window.opener" của cửa sổ mới tạo được đặt cho phương thức gọi và trong cùng đơn vị ngữ cảnh duyệt web có liên quan với phương thức gọi.

    • tiểu bang

      WindowState không bắt buộc

      Chrome 44 trở lên

      Trạng thái ban đầu của cửa sổ. Bạn không thể kết hợp các trạng thái minimized, maximized và fullscreen với left, top, width hoặc height.

    • tabId

      số không bắt buộc

      Mã của thẻ cần thêm vào cửa sổ mới.

    • trên cùng

      số không bắt buộc

      Số lượng pixel để định vị cửa sổ mới từ cạnh trên của màn hình. Nếu không được chỉ định, cửa sổ mới sẽ được bù trừ một cách tự nhiên từ cửa sổ được lấy tiêu điểm cuối cùng. Giá trị này sẽ bị bỏ qua đối với các bảng điều khiển.

    • loại

      CreateType không bắt buộc

      Chỉ định loại cửa sổ trình duyệt cần tạo.

    • url

      string | string[] không bắt buộc

      Một URL hoặc mảng URL để mở dưới dạng thẻ trong cửa sổ. Các URL đủ điều kiện phải chứa một lược đồ, ví dụ: "http://www.google.com", không phải "www.google.com". URL không đủ điều kiện được xem là tương đối trong tiện ích. Giá trị mặc định là trang Thẻ mới.

    • chiều rộng

      số không bắt buộc

      Chiều rộng tính bằng pixel của cửa sổ mới, bao gồm cả khung. Nếu không được chỉ định, giá trị mặc định sẽ là chiều rộng tự nhiên.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (window?: Window) => void

    • cửa sổ

      Cửa sổ không bắt buộc

      Chứa thông tin chi tiết về cửa sổ đã tạo.

Giá trị trả về

  • Promise<Window | không xác định>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

get()

Lời hứa 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

Lấy thông tin chi tiết về một cửa sổ.

Tham số

  • windowId

    số

  • queryOptions

    QueryOptions không bắt buộc

    Chrome 88 trở lên
  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (window: Window) => void

Giá trị trả về

  • Promise<Window>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getAll()

Lời hứa 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Truy xuất tất cả cửa sổ.

Tham số

  • queryOptions

    QueryOptions không bắt buộc

    Chrome 88 trở lên
  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (windows: Window[]) => void

Giá trị trả về

  • Promise<Window[]>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getCurrent()

Lời hứa 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

Lấy cửa sổ hiện tại.

Tham số

  • queryOptions

    QueryOptions không bắt buộc

    Chrome 88 trở lên
  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (window: Window) => void

Giá trị trả về

  • Promise<Window>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getLastFocused()

Lời hứa 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

Lấy cửa sổ được lấy tiêu điểm gần đây nhất — thường là cửa sổ "trên cùng".

Tham số

  • queryOptions

    QueryOptions không bắt buộc

    Chrome 88 trở lên
  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (window: Window) => void

Giá trị trả về

  • Promise<Window>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

remove()

Lời hứa 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

Xoá (đóng) một cửa sổ và tất cả thẻ bên trong cửa sổ đó.

Tham số

  • windowId

    số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

update()

Lời hứa 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

Cập nhật thuộc tính của một cửa sổ. Chỉ xác định các thuộc tính sẽ được thay đổi; các thuộc tính chưa xác định thì không thay đổi.

Tham số

  • windowId

    số

  • updateInfo

    đối tượng

    • drawAttention

      boolean không bắt buộc

      Nếu true, hãy làm cho cửa sổ hiện ra theo cách thu hút sự chú ý của người dùng đến cửa sổ đó mà không thay đổi cửa sổ được lấy tiêu điểm. Hiệu ứng này kéo dài cho đến khi người dùng thay đổi tiêu điểm sang cửa sổ. Tuỳ chọn này không có hiệu lực nếu cửa sổ đã có tiêu điểm. Đặt thành false để huỷ một yêu cầu drawAttention trước đó.

    • tập trung

      boolean không bắt buộc

      Nếu true, hãy đưa cửa sổ lên phía trước; Không thể kết hợp với trạng thái "giảm thiểu". Nếu false, đưa cửa sổ tiếp theo theo thứ tự z lên phía trước; không thể kết hợp với trạng thái 'toàn màn hình' hoặc 'Phóng to'.

    • độ cao

      số không bắt buộc

      Chiều cao để đổi kích thước cửa sổ thành pixel. Giá trị này sẽ bị bỏ qua đối với các bảng điều khiển.

    • trái

      số không bắt buộc

      Độ lệch từ cạnh trái của màn hình để di chuyển cửa sổ sang tính bằng pixel. Giá trị này sẽ bị bỏ qua đối với các bảng điều khiển.

    • tiểu bang

      WindowState không bắt buộc

      Trạng thái mới của cửa sổ. " thu nhỏ", "phóng to" và "toàn màn hình" không thể kết hợp các trạng thái với "left", "top", "width" hoặc "height".

    • trên cùng

      số không bắt buộc

      Độ lệch từ cạnh trên của màn hình để di chuyển cửa sổ sang tính bằng pixel. Giá trị này sẽ bị bỏ qua đối với các bảng điều khiển.

    • chiều rộng

      số không bắt buộc

      Chiều rộng để đổi kích thước cửa sổ thành tính bằng pixel. Giá trị này sẽ bị bỏ qua đối với các bảng điều khiển.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (window: Window) => void

Giá trị trả về

  • Promise&lt;Window&gt;

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

Sự kiện

onBoundsChanged

Chrome 86 trở lên 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Được kích hoạt khi cửa sổ đã được đổi kích thước; sự kiện này chỉ được gửi đi khi các giới hạn mới được cam kết chứ không phải khi các thay đổi đang diễn ra.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (window: Window) => void

onCreated

chrome.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi một cửa sổ được tạo.

Tham số

  • số gọi lại

    hàm

    Chrome 46 trở lên

    Tham số callback sẽ có dạng như sau: 

    (window: Window) => void

    • cửa sổ

      Cửa sổ

      Thông tin chi tiết về cửa sổ đã tạo.

  • bộ lọc

    đối tượng không bắt buộc

    • windowTypes

      WindowType[]

      Các điều kiện mà loại cửa sổ được tạo phải đáp ứng. Theo mặc định, mẫu này đáp ứng ['normal', 'popup'].

onFocusChanged

chrome.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi cửa sổ hiện được lấy tiêu điểm thay đổi. Trả về chrome.windows.WINDOW_ID_NONE nếu tất cả cửa sổ Chrome đều mất tiêu điểm. Lưu ý: Trên một số trình quản lý cửa sổ Linux, WINDOW_ID_NONE luôn được gửi ngay trước khi chuyển đổi từ cửa sổ Chrome này sang cửa sổ Chrome khác.

Tham số

  • số gọi lại

    hàm

    Chrome 46 trở lên

    Tham số callback sẽ có dạng như sau: 

    (windowId: number) => void

    • windowId

      số

      Mã của cửa sổ mới được lấy tiêu điểm.

  • bộ lọc

    đối tượng không bắt buộc

    • windowTypes

      WindowType[]

      Các điều kiện mà loại cửa sổ bị xoá phải đáp ứng. Theo mặc định, mẫu này đáp ứng ['normal', 'popup'].

onRemoved

chrome.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

Được kích hoạt khi một cửa sổ bị xóa (đóng).

Tham số

  • số gọi lại

    hàm

    Chrome 46 trở lên

    Tham số callback sẽ có dạng như sau: 

    (windowId: number) => void

    • windowId

      số

      Mã của cửa sổ bị xoá.

  • bộ lọc

    đối tượng không bắt buộc

    • windowTypes

      WindowType[]

      Các điều kiện mà loại cửa sổ bị xoá phải đáp ứng. Theo mặc định, mẫu này đáp ứng ['normal', 'popup'].