Hướng dẫn

Dấu trang

Nhập một lần tệp dấu trang xuất từ trình duyệt rồi đưa cùng bộ dấu trang vào nhiều hồ sơ — gộp hoặc thay thế, trong một thư mục hay toàn bộ — do chính trình duyệt của từng hồ sơ áp dụng.

Xem dạng Markdown

Cập nhật 28 tháng 10, 2026

Một bộ dấu trang là danh sách liên kết đọc từ tệp xuất dấu trang của trình duyệt. Bạn nhập tệp một lần vào thư viện của workspace, rồi xếp lượt cho bao nhiêu hồ sơ cũng được. Trình duyệt của mỗi hồ sơ áp dụng qua chính trình quản lý dấu trang của nó ở lần mở kế tiếp, trước khi phiên được báo sẵn sàng, và báo lại đúng những gì đã làm.

Nhập tệp

Xuất dấu trang từ bất kỳ trình duyệt nào (Chrome, Edge, Brave, Firefox…: Trình quản lý dấu trang → Xuất dấu trang). Kết quả là tệp bookmarks.html theo định dạng Netscape. Máy chủ Browlix đọc tệp bằng trình phân tích HTML thật và chỉ giữ phần an toàn:

chỉ liên kết http:// và https:// — bookmarklet (javascript:), data:, file:, chrome:, place: và mọi giao thức khác đều bị loại kèm lý do;
địa chỉ chứa tên đăng nhập hoặc mật khẩu (https://user:pass@…) bị từ chối và không bao giờ được lưu;
tiêu đề là chữ thuần; biểu tượng và mô tả trong tệp bị bỏ qua;
thanh dấu trang vẫn là thanh dấu trang, phần còn lại thành dấu trang khác, thư mục được giữ (tối đa 10 cấp);
tối đa 10 MB và 5.000 liên kết mỗi lần nhập; cùng một liên kết hai lần trong cùng thư mục chỉ giữ một.

import { readFile } from "node:fs/promises";

const imported = await bx.call("bookmarks.import", {
  body: { name: "Team links October", html: await readFile("./bookmarks.html", "utf8"), file_name: "bookmarks.html" },
});
const set = imported.data.set;
console.log(set.links, set.rejected_count); // what was kept, how many were refused

Nhập lại đúng danh sách đó sẽ trả về bộ đã có (created: false). bookmarks.get trả mọi liên kết (root bar/other, path thư mục, title, url) và tối đa 50 ví dụ liên kết bị loại kèm lý do: unsafe_scheme, invalid_url, credentials, too_long, too_deep hoặc over_limit.

Đưa vào hồ sơ

Việc đưa vào là so sánh-và-ghi theo từng hồ sơ: đọc revision dấu trang của từng hồ sơ trước, rồi gửi lại làm expected_rev. Hồ sơ nào đổi dấu trang trong lúc đó (có lượt nhập khác được xếp hoặc đã áp dụng) được báo conflict và không được xếp lượt — đọc lại rồi quyết định.

const set = (await bx.call("bookmarks.list", {})).data.find((s) => s.name === "Team links October");
const profileIds = ["…", "…"];
const preview = await bx.call("bookmarks.preview", { body: { profile_ids: profileIds } });

if (set) {
  const queued = await bx.call("bookmarks.apply", {
    path: { id: set.id },
    body: {
      mode: "merge",
      scope: "folder",
      folder: "Team links",
      targets: preview.data.map((p) => ({ profile_id: p.profile_id, expected_rev: p.rev })),
    },
  });
  console.log(queued.data.queued, queued.data.conflicts, queued.data.not_found);
}

Lựa chọn	Tác động trong mỗi hồ sơ
`mode: "merge"`	thêm liên kết chưa có trong thư mục đích; dấu trang hiện có giữ nguyên
`mode: "replace"`	xoá dấu trang trong vùng đích trước, rồi nhập danh sách
`scope: "folder"`	mọi liên kết vào một thư mục trên thanh dấu trang (`folder`, tạo mới nếu chưa có), giữ thư mục con của tệp
`scope: "all"`	thanh dấu trang và dấu trang khác đúng như trong tệp

replace với scope: "all" sẽ xoá mọi dấu trang hiện có của các hồ sơ đó trước — ứng dụng web yêu cầu xác nhận rõ ràng trước khi gửi.

Tối đa 500 hồ sơ mỗi lần gọi; hồ sơ ngoài nhóm của bạn là not_found. Lượt đã xếp có thể rút bằng bookmarks.cancel cho tới khi một trình duyệt nhận nó.

Máy chạy làm gì

Máy cần worker 0.16.0 trở lên. Worker cũ hơn không bao giờ nhận lượt nhập: chúng vẫn chờ (phiên hiển thị là đang chờ) cho tới khi hồ sơ mở trên máy đã cập nhật.

Khi hồ sơ mở, lệnh mở chỉ ghi từng lượt nhập đang chờ và số liên kết của nó; chỉ máy đang giữ đúng lệnh mở đó tải được danh sách liên kết. Trình duyệt mở trình quản lý dấu trang của chính nó ở nền, áp dụng các lượt theo thứ tự đã xếp (tối đa 8 lượt mỗi lần mở), đóng lại, rồi mới báo phiên sẵn sàng. profiles.bookmarks và sessions.get hiển thị số liệu do chính trình duyệt báo:

Trạng thái	Ý nghĩa
`pending`	chờ lần mở kế tiếp của hồ sơ
`applying`	một trình duyệt đã nhận và đang áp dụng
`applied`	xong: `added`, `duplicates` (đã có sẵn) và `removed` (do thay thế)
`failed`	trình duyệt không áp dụng được; lý do nói vì sao (thay đổi đã làm vẫn được đếm)
`cancelled`	đã rút trước khi trình duyệt nhận

Lượt nhập mà máy đã nhận nhưng không xác nhận — lệnh mở lỗi, hoặc máy dừng trước khi báo — quay lại pending và chạy ở lần mở sau. Gộp là idempotent: chạy lại không thêm gì đã có.

Lỗi bạn sẽ gặp

Mã	Khi nào
`FORBIDDEN`	nhập, đưa vào, rút hoặc xoá khi thiếu `bookmark.import`
`VALIDATION_FAILED`	không phải tệp xuất dấu trang, quá 10 MB, không còn liên kết http(s) nào, thiếu tên thư mục với `scope: "folder"`, hoặc quá 500 hồ sơ
`CONFLICT`	rút lượt mà trình duyệt đang áp dụng (hoặc đã kết thúc), hoặc xoá bộ mà hồ sơ vẫn đang chờ
`NOT_FOUND`	bộ dấu trang không có trong workspace này

Mọi quyết định đều có trong nhật ký kiểm toán: bookmark.import, bookmark.apply (theo từng hồ sơ, kèm cách nhập, vùng đích và revision), bookmark.cancel, bookmark.delete.