Dashboard in được, xuất ảnh được, đọc được bằng trình đọc màn hình
Dashboard làm xong, demo trên màn hình rất đẹp. Rồi người dùng thật bắt đầu dùng nó theo những cách mình không nghĩ tới:
- Bấm Ctrl+P để in báo cáo tháng mang vào họp. Bản in có đủ nút "Thử lại", nút chuyển chế độ bảng, thanh lọc, và một bảng 40 dòng bị cắt mất nửa dưới.
- Bấm "Xuất ảnh" để dán biểu đồ vào slide. Ảnh có cả nút "i" và menu ba chấm ở góc.
- Một đồng nghiệp dùng trình đọc màn hình. Nó đọc "vùng phụ, trống", rồi đọc tên người dùng hai lần (một lần từ chữ, một lần từ avatar), rồi đọc "Địa điểm hai chấm" cho ô lọc.
Ba nhóm người dùng, ba kiểu "màn hình" khác nhau: giấy, ảnh và giọng đọc. Bài này là cách mình xử lý cả ba mà không phải viết ba phiên bản dashboard.
Đánh dấu một lần, dùng cho cả in và xuất ảnh
Thay vì viết CSS in dựa vào tên class (đổi class là hỏng), mình đánh dấu ý định trực tiếp trên phần tử:
| Thuộc tính | Nghĩa |
|---|---|
data-print="hide" |
Không in (nút, thanh lọc, menu) |
data-print="only" |
Chỉ hiện khi in (dòng "In lúc ... , bộ lọc: ...") |
data-print="whole" |
Không được cắt ngang giữa trang (một thẻ số liệu) |
data-export="skip" |
Không có trong ảnh xuất ra |
<Card data-print="whole">
<CardHeader title="Tỷ lệ sử dụng theo tuần" />
<div data-slot="controls" data-print="hide" data-export="skip">
<Button aria-pressed={showTable} onClick={toggleTable}>Bảng</Button>
<ImageButton target={cardRef} />
</div>
<TrendChart data={data} />
</Card>
Người viết component không cần biết CSS in viết ở đâu. Chỉ cần nói "cái này không in".
CSS in: ẩn đúng thứ, và cho bảng được ngắt trang
@media print {
[data-print="hide"] { display: none !important; }
[data-print="only"] { display: block !important; }
[data-print="whole"] { break-inside: avoid; }
/* Hộp có thanh cuộn in ra thành MỘT khối không ngắt được: bảng 40 dòng bị cắt mất nửa */
.table-scroll { overflow: visible !important; max-height: none !important; }
}
Dòng cuối là bug khó thấy nhất. Bảng nằm trong một hộp có overflow: auto để cuộn trên màn hình. Khi in, trình duyệt coi cả hộp là một khối, phần nào không vừa trang thì bị cắt, không sang trang mới. Bỏ giới hạn cuộn khi in thì bảng chảy tự nhiên qua nhiều trang.
Thêm hai quy tắc nữa. Khi in luôn dùng giao diện sáng, kể cả khi người dùng đang bật giao diện tối: nền đen in ra giấy vừa tốn mực vừa khó đọc. Và có một dòng data-print="only" ghi thời điểm in cùng bộ lọc đang áp dụng, vì tờ giấy rời khỏi màn hình là mất hết ngữ cảnh.
Xuất ảnh: lọc bỏ phần tử khi chụp
Nút "Xuất ảnh" chụp một thẻ thành PNG. Các thư viện chụp DOM thành ảnh như html-to-image cho truyền một hàm lọc:
import { toPng } from 'html-to-image';
async function exportCard(card: HTMLElement, fileName: string) {
const dataUrl = await toPng(card, {
filter: (node) => !(node instanceof HTMLElement && node.dataset.export === 'skip'),
backgroundColor: '#ffffff',
});
download(dataUrl, fileName + '.png');
}
Nhờ đã đánh dấu data-export="skip" từ đầu, ảnh xuất ra chỉ còn tiêu đề, biểu đồ và chú thích, dán thẳng vào slide được.
Test quy tắc in: jsdom không hiểu @media
Viết test cho chuyện "nút Thử lại không được in" thì vấp ngay: Vitest chạy trên jsdom, mà jsdom không áp dụng quy tắc @media nào. Trong test, getComputedStyle không bao giờ trả về display: none cho chế độ in.
Hai cách, tuỳ mức độ:
| Cách | Làm gì | Hợp khi |
|---|---|---|
| Đọc CSS trong test đơn vị | Lấy nội dung CSS đã được chèn vào trang, tìm quy tắc @media print khớp với phần tử, kiểm nó có display: none |
Muốn test nhanh, chạy cùng bộ test đơn vị |
| Giả lập in trong Playwright | await page.emulateMedia({ media: 'print' }) rồi kiểm phần tử không hiển thị, hoặc xuất PDF để xem |
Muốn chắc chắn trình duyệt thật in đúng |
Dashboard của mình dùng cả hai: test đơn vị đọc CSS cho từng quy tắc, và một test Playwright giả lập in cho cả trang. Cùng cách đọc CSS đó cũng dùng để test quy tắc "giảm chuyển động", vì prefers-reduced-motion cũng là một @media.
Trình đọc màn hình: ba lỗi nhỏ, ba cách sửa
Vùng trống không nên là một vùng. Layout có một khung bên phải (<aside>) để sau này chứa bảng hành động, hiện chưa có gì. Trình đọc màn hình vẫn liệt kê nó trong danh sách vùng của trang và đọc "vùng phụ, trống". Khi chưa có nội dung thì ẩn nó khỏi cây accessibility:
<aside aria-label="Bảng hành động" aria-hidden={actions.length === 0}>{actions}</aside>
Thứ đã có chữ thì không đọc lại. Avatar đặt cạnh tên người dùng. Tên đã được đọc, avatar thì đọc lại tên lần nữa. Ảnh chỉ để trang trí bên cạnh nội dung đã có chữ thì đánh dấu aria-hidden="true".
Tên dễ đọc không mang dấu câu của nhãn. Nhãn hiển thị là "Địa điểm:", và tên dễ đọc của ô lọc được lấy từ chính chuỗi đó, nên thành "Địa điểm hai chấm". Dùng chuỗi riêng cho aria-label, không có dấu hai chấm.
Và một quy tắc "ẩn khỏi mắt nhưng vẫn đọc được" dùng chung cho cả app, thay vì mỗi component tự viết một kiểu:
.sr-only {
position: absolute;
width: 1px;
height: 1px;
overflow: hidden;
white-space: nowrap;
clip-path: inset(50%);
}
Mình dùng nó cho các nhãn của thanh điều hướng khi thanh thu gọn chỉ còn icon trên màn hình hẹp: mắt thấy icon, trình đọc màn hình vẫn đọc được "Tổng quan", "Theo địa điểm".
Biểu đồ phải có bản dạng bảng
Người dùng trình đọc màn hình không "xem" được đường biểu đồ. Mỗi thẻ có nút "Bảng" bật tắt chế độ xem dạng bảng, dùng aria-pressed để báo trạng thái bật hay tắt. Bảng này còn có ích cho cả người nhìn được: ai cần số chính xác để dán vào Excel thì lấy ở đây, thay vì đọc nhẩm trên trục.
Checklist cho mọi dashboard
In
[ ] Nút, thanh lọc, menu không in ra
[ ] Bảng dài ngắt trang được, không bị cắt
[ ] Luôn in giao diện sáng, có dòng ghi thời điểm và bộ lọc
Xuất ảnh
[ ] Ảnh không có nút, menu, icon thông tin
Trình đọc màn hình
[ ] Không có vùng trống, không đọc trùng (avatar cạnh tên)
[ ] Tên dễ đọc của control không có dấu câu thừa
[ ] Một quy tắc .sr-only dùng chung
[ ] Mỗi biểu đồ có bản dạng bảng, nút bật tắt có aria-pressed
[ ] Tôn trọng prefers-reduced-motion
Thử ngay: mở dashboard của bạn, bấm Ctrl+P và xem bản xem trước khi in. Rồi bật trình đọc màn hình có sẵn của máy (Narrator trên Windows, VoiceOver trên Mac), bấm Tab qua thanh lọc. Hai phút là đủ thấy những gì người dùng của bạn đang gặp.
Bài sau trong series: hiệu năng UI mà không cần đoán: tải lười từng màn hình, danh sách ảo cho hàng nghìn dòng, và chuyện code khởi tạo chạy hai lần dưới StrictMode. Dashboard của bạn có ai từng in ra giấy chưa? Comment kể mình nghe với.
P.S. Checklist trình đọc màn hình ở trên mình không thuộc lòng được hết. Trước khi giao một màn hình, mình chạy skill ui-accessibility-auditor trong PrimeKit, bộ skill mình tự làm. Skill soát code giao diện theo hướng dẫn Web Interface Guidelines: tên dễ đọc, vùng trang, focus, tương phản, chuyển động. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:ui-accessibility-auditor kèm màn hình cần soát. Thử thật bằng trình đọc màn hình vẫn là bước không thay được.
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All rights reserved