chrome.windows

Nội dung mô tả

Sử 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 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 cần quyền truy cập vào các thuộc tính url, 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 sẽ 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ã đang thực thi. Quan trọng là bạn phải nhận ra 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ử một tiện ích tạo một vài thẻ hoặc cửa sổ từ một tệp HTML duy nhất, 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 trang đã thực hiện lệnh 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 lại cửa sổ hoạt động gần đây nhất. Trong một số trường hợp, có thể không có cửa sổ hiện tại cho trang nền.

Ví dụ

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

Hai cửa sổ, mỗi cửa sổ có một thẻ
2 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. "Bảng điều khiển" không được dùng nữa và chỉ có sẵn cho các tiện ích hiện có trong danh sách cho phép trên Chrome OS.

Liệt kê

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

"pop"
Chỉ định cửa sổ làm 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 trả về sẽ được lọc dựa trên loại. Nếu bạn không đặt chính sách này, thì 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 ở chế độ 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 có thể không chỉ định được thuộc tính height cho một cửa sổ; ví dụ: khi truy vấn các cửa sổ đã đóng từ API sessions.

  • id

    số không bắt buộc

    Mã 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 có thể không chỉ định được 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 đó, mã phiên có thể xuất hiện.

  • ẩn danh

    boolean

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

  • trái

    số không bắt buộc

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

  • sessionId

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

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

  • state

    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 gồm các đối tượng tabs.Tab đại diện cho các thẻ hiện tại trong cửa sổ.

  • nửa đầu lượt đấu

    số không bắt buộc

    Độ lệch của cửa sổ so với 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 có thể không chỉ định được thuộc tính top cho một cửa sổ; ví dụ: khi truy vấn các cửa sổ đã đóng từ API sessions.

  • loại

    WindowType không bắt buộc

    Đây là 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 có thể không chỉ định được thuộc tính width cho một cửa sổ; ví dụ: khi truy vấn các 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 có thể không chỉ định được thuộc tính state cho một cửa sổ; ví dụ: khi truy vấn các cửa sổ đã đóng từ API sessions.

Liệt kê

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

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

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

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

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

WindowType

Chrome 44 trở lên

Đây là 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ác cửa sổ đã đóng từ API sessions.

Liệt kê

"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 Ứng dụng Chrome. Các tiện ích chỉ có thể xem cửa sổ bảng điều khiển của chính nó.

"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 đó.

"devtools"
Cửa sổ Công cụ dành 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 đại diện cho việc không có cửa sổ trình duyệt Chrome.

Giá trị

-1

Phương thức

create()

Cam kết 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

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

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, hãy mở một cửa sổ đang hoạt động. Nếu false, hãy 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, chiều cao mặc định sẽ là chiều cao tự nhiên.

    • ẩn danh

      boolean không bắt buộc

      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ính từ cạnh trái của màn hình. Nếu bạn không chỉ định, cửa sổ mới sẽ được bù trừ tự nhiên so với cửa sổ được lấy tiêu điểm gần đây nhất. Giá trị này sẽ bị bỏ qua đối với bảng điều khiển.

    • setSelfAsOpener

      boolean không bắt buộc

      Chrome 64 trở lên

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

    • state

      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.

    • nửa đầu lượt đấu

      số không bắt buộc

      Số pixel để định vị cửa sổ mới tính từ cạnh trên cùng của màn hình. Nếu bạn không chỉ định, cửa sổ mới sẽ được bù trừ tự nhiên so với cửa sổ được lấy tiêu điểm gần đây nhất. Giá trị này sẽ bị bỏ qua đối với 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[] optional

      URL hoặc mảng URL sẽ mở dưới dạng thẻ trong cửa sổ. URL đủ điều kiện phải bao gồm một lược đồ, ví dụ: "http://www.google.com", chứ không phải "www.google.com". Những URL không đủ điều kiện được xem là tương đối trong phần mở rộng. 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, chiều rộng 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ề

  • Hứa hẹn<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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

get()

Cam kết 
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

    number

  • 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ề

  • Lời hứa<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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAll()

Cam kết 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Lấy 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ề

  • Lời hứa<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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getCurrent()

Cam kết 
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ề

  • Lời hứa<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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getLastFocused()

Cam kết 
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ề

  • Lời hứa<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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

remove()

Cam kết 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

Tham số

  • windowId

    number

  • 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ề

  • Promise<void>

    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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

update()

Cam kết 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

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

Tham số

  • windowId

    number

  • updateInfo

    đối tượng

    • drawAttention

      boolean không bắt buộc

      Nếu là true, khiến cửa sổ hiển thị theo cách thu hút người dùng chú ý đế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ỷ yêu cầu drawAttention trước đó.

    • tập trung

      boolean không bắt buộc

      Nếu là 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 "thu nhỏ". Nếu false, hãy đư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 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 bảng điều khiển.

    • state

      WindowState không bắt buộc

      Trạng thái mới của cửa sổ. Không thể kết hợp các trạng thái "thu nhỏ", "tối đa" và "toàn màn hình" với "trái", "trên cùng", "chiều rộng" hoặc "chiều cao".

    • nửa đầu lượt đấu

      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 bảng điều khiển.

    • chiều rộng

      số không bắt buộc

      Chiều rộng cần đổ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 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ề

  • Lời hứa<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 để có 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. Lời hứa sẽ được phân giải bằng cùng một 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 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ổ đang được tạo phải đáp ứng. Theo mặc định, thuộc tính 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 làm 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 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

      number

      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, thuộc tính 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ị xoá (đó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

      number

      Mã của cửa sổ đã 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, thuộc tính này đáp ứng ['normal', 'popup'].