Thiết lập VKey theo cách bạn làm việc.

Bắt đầu nhanh

1. Tải VKey từ trang phát hành chính thức hoặc cài bằng WinGet.
2. Tắt các bộ gõ tiếng Việt khác để tránh hai chương trình cùng xử lý một phím.
3. Mở VKey, chọn Telex, VNI, Telex + VNI hoặc kiểu gõ tự định nghĩa.
4. Chọn chế độ V để gõ tiếng Việt và E để tạm dừng xử lý phím.

winget install PhatMT97.VKey

Nếu một ứng dụng gõ không đúng, đừng đổi thiết lập chung ngay. Hãy tạo cấu hình riêng cho ứng dụng đó và thử một cách gửi khác.

Kiểu gõ và bảng mã

VKey hỗ trợ các kiểu gõ sau:

• Telex: dùng chữ để đặt dấu và biến đổi nguyên âm.
• VNI: dùng phím số để đặt dấu.
• Telex + VNI: nhận cả hai cách gõ trong cùng một cấu hình.
• Simple Telex: giữ giá trị gốc của w, [ và ] trong nhiều tình huống hơn.
• Tự định nghĩa: cho phép gán lại các phím đặt dấu.

Các bảng mã gồm Unicode, TCVN3, VNI Windows, Unicode Compound và Vietnamese Locale. Với phần lớn ứng dụng hiện nay, nên giữ Unicode.

Cấu hình theo ứng dụng

Bạn có thể đặt kiểu gõ, bảng mã và cách gửi riêng cho từng file .exe. VKey áp dụng cấu hình khi cửa sổ tương ứng được chọn.

Khi dùng cách gửi Clipboard, dữ liệu clipboard không phải văn bản như hình ảnh có thể bị ảnh hưởng. Hãy sao lưu nội dung clipboard quan trọng trước khi thử.

Chuyển chế độ Việt và Anh

• Lưu chế độ theo ứng dụng: ghi nhớ trạng thái V hoặc E của từng ứng dụng.
• Khoá E: luôn dùng tiếng Anh và chặn phím tắt chuyển chế độ trong ứng dụng đã chọn.
• Khoá V: luôn bật tiếng Việt trong ứng dụng đã chọn.
• Tự tắt khi bàn phím CJK: chuyển sang E khi Windows dùng bố cục Trung, Nhật hoặc Hàn, sau đó bật lại khi trở về bố cục US.

Khoá chế độ theo ứng dụng áp dụng chủ yếu cho hook engine. Ứng dụng đang dùng TSF có thể có hành vi khác.

Đổi chế độ theo website bằng extension (thử nghiệm)

VKey Browser tự nhớ trạng thái V/E theo website trong phiên trình duyệt và cho phép đặt rule cố định. Extension chỉ trao đổi hostname, rule và kết quả V/E sau hotkey với VKeyBrowserHost trên máy; không đọc hoặc gửi nội dung bạn nhập.

Chuẩn bị

• Dùng bản VKey có VKeyBrowserHost.exe nằm cùng thư mục với VKey.exe hoặc VKeyClassic.exe.
• Chạy VKey ít nhất một lần để đăng ký Native Messaging Host cho trình duyệt.
• Tải hoặc clone repo VKey-Browser.

Cài trên Chrome, Edge hoặc Brave

1. Mở trang quản lý extension: chrome://extensions, edge://extensions hoặc brave://extensions.
2. Bật Developer mode.
3. Chọn Load unpacked và mở thư mục đã tải của VKey-Browser.
4. Ghim biểu tượng VKey Browser để đổi chế độ nhanh cho website hiện tại.

Cài tạm trên Firefox

1. Chạy npm run build:firefox trong thư mục VKey-Browser.
2. Mở about:debugging#/runtime/this-firefox.
3. Chọn Load Temporary Add-on.
4. Chọn file dist/firefox/manifest.json.

Thư mục gốc là gói Chromium; không chọn manifest.json ở đó cho Firefox.

Firefox sẽ gỡ extension tạm khi đóng trình duyệt; đây là cách thử nghiệm dành cho nhà phát triển.

Thiết lập và chuyển tab

Mở website, nhấn biểu tượng extension rồi chọn một chế độ cho hostname hiện tại:

• Tự nhớ V/E theo hotkey: khi bạn đổi V/E bằng hotkey VKey, extension nhớ kết quả cho hostname và tự khôi phục khi quay lại trong cùng phiên trình duyệt.
• Luôn gõ English (hard): luôn bỏ xử lý tiếng Việt trên hostname này và không cho hotkey ghi đè trạng thái.
• TSF tương thích (hard): luôn dùng TSF cho hostname này, phù hợp với editor hoặc forum gặp lỗi dính chữ; cần bật hỗ trợ ứng dụng TSF trong VKey.

Lựa chọn được áp dụng ngay, không cần bấm nút Lưu. Hai rule (hard) được lưu cục bộ và vẫn còn sau khi khởi động lại trình duyệt. Trạng thái V/E tự nhớ chỉ tồn tại trong phiên hiện tại và tự xóa khi đóng hoặc khởi động lại trình duyệt. Chọn lại Tự nhớ V/E theo hotkey sẽ bỏ rule hard của hostname đó.

Ví dụ: tại google.com, dùng hotkey chuyển sang V; tại github.com, dùng hotkey chuyển sang E. Trong phiên hiện tại, khi chuyển qua lại hai tab, extension sẽ tự khôi phục V hoặc E tương ứng. Nếu muốn một hostname luôn ở E sau cả khi khởi động lại trình duyệt, chọn Luôn gõ English (hard).

Công tắc Bật điều hướng theo website được bật mặc định. Tắt công tắc để tạm ngừng áp dụng mọi rule mà không xóa cấu hình; bật lại thì các rule đã lưu có hiệu lực ngay.

Popup hiển thị Đã kết nối VKey khi native host hoạt động. Nếu thấy Chưa kết nối VKeyBrowserHost, hãy kiểm tra bản VKey đang dùng có VKeyBrowserHost.exe, thoát/mở lại VKey để đăng ký host, sau đó khởi động lại trình duyệt và reload extension.

Đây là tính năng thử nghiệm. Thanh địa chỉ và các trang nội bộ như chrome:// hoặc about: không cung cấp hostname trang web cho extension nên tiếp tục dùng trạng thái hiện tại của VKey. Xem thêm tài liệu kỹ thuật và xử lý sự cố.

Chính tả, gõ tự do và khôi phục từ

• Kiểm tra chính tả: giảm việc đặt dấu nhầm vào chuỗi không giống âm tiết tiếng Việt.
• Gõ tự do: bỏ qua kiểm tra chính tả khi viết mã, tên riêng hoặc chuỗi đặc biệt.
• Khôi phục từ gốc: trả lại các phím ban đầu khi VKey nhận diện sai một từ.
• Danh sách loại trừ: giữ nguyên thuật ngữ, từ viết tắt hoặc chuỗi riêng của người dùng.
• Viết hoa đầu câu: hoạt động theo ngữ cảnh; TSF có thể cung cấp ngữ cảnh tốt hơn hook engine.

Engine C++20 có sẵn đáp ứng các chức năng gõ thông thường. Engine Rust cho kiểm tra chính tả nâng cao là tùy chọn và mặc định tắt.

Luôn giữ một từ riêng (Từ điển cá nhân)

Khi bật Kiểm tra chính tả nâng cao, engine chính tả có thể tự động sửa một số từ lạ, từ lóng hoặc từ ít gặp mà nó coi là gõ nhầm (ví dụ: soaf tự sửa thành sào, khuwm tự sửa thành khum). Bạn có thể thêm các từ này vào Từ điển cá nhân để bảo vệ chúng không bị tự động sửa.

Cách 1: Sử dụng giao diện trực quan (Khuyên dùng)

1. Nhấp chuột phải vào biểu tượng VKey ở khay hệ thống (System Tray) và chọn Từ điển & Loại trừ chính tả (hoặc mở từ cửa sổ Cài đặt).
2. Chọn tab Từ điển cá nhân:
   • Thêm từ: Nhập từ cần giữ nguyên vào ô văn bản (ví dụ soà, khưm, alo, tên riêng, thuật ngữ…), sau đó nhấn nút Thêm (hoặc nhấn phím Enter).
   • Sửa / Xóa: Nhấp chọn từ trong danh sách để chỉnh sửa hoặc nhấn Xóa để bỏ từ đó khỏi danh sách bảo vệ.
   • Nạp / Xuất file: Nhấn Nạp từ file… để nhập hàng loạt từ file văn bản .txt hoặc Xuất ra file… để sao lưu từ điển của bạn. Mỗi thay đổi (Thêm, Sửa, Xóa, Nạp file, bật/tắt Kiểm tra chính tả nâng cao) được áp dụng ngay lập tức — không cần nhấn thêm nút “Lưu”. VKey đồng bộ tức thì cho cả Hook Engine lẫn TSF mà không cần khởi động lại.

Cách 2: Chỉnh sửa thủ công file user_dictionary.txt

File user_dictionary.txt nằm cùng thư mục với config.toml (thường là thư mục cài đặt VKey). Nếu thư mục đó không có quyền ghi, hãy đặt file trong %APPDATA%\\VKey. File không được tạo tự động — bạn phải tự tạo bằng tay hoặc dùng giao diện Từ điển cá nhân ở Cách 1 để VKey tạo và quản lý giúp bạn.

1. Hãy báo lỗi tự sửa tại GitHub Issues trước khi thêm từ.
2. Mở user_dictionary.txt bằng Notepad hoặc trình soạn thảo văn bản.
3. Thêm mỗi từ cần giữ vào một dòng riêng biệt (ví dụ alo, khưm, soà).
4. Lưu file ở dạng mã hóa UTF-8.
5. Nhấn chuột phải vào Tray icon chọn Từ điển & Loại trừ chính tả → Nạp lại → Lưu & Áp dụng (hoặc chuyển chế độ Nâng cao → Cơ bản → Nâng cao) để nạp lại từ điển.

💡 Lưu ý định dạng file:

• Các dòng trống và dòng bắt đầu bằng ký tự # được tính là dòng chú thích và được bỏ qua (lưu ý: không dùng dấu ; vì engine Rust chỉ nhận diện dấu # làm chú thích).
• File trống hoặc chỉ có comment là hợp lệ và sẽ xóa danh sách bảo vệ.
• Nếu file có lỗi mã hóa UTF-8, dòng không hợp lệ hoặc file bị lỗi, VKey sẽ tự động giữ lại danh sách hợp lệ gần nhất để tránh gián đoạn trải nghiệm gõ. Danh sách từ điển chỉ được lưu trữ và xử lý hoàn toàn cục bộ trên máy tính của bạn.

Quản lý phím tắt

Trong mục quản lý phím tắt, bạn có thể gán tổ hợp cho các thao tác thường dùng:

• Chuyển giữa V và E.
• Khôi phục từ gốc.
• Tạm bỏ qua macro.
• Chuyển mã phần văn bản đang chọn.
• Bật hoặc tắt chế độ game cho ứng dụng đang mở.

Chế độ game không có phím tắt mặc định để tránh trùng với phím đã dùng trong game.

Sử dụng Windows TSF

VKey hỗ trợ Text Services Framework theo hai cách:

• Tăng cường ngữ cảnh: hook vẫn là cách nhập chính, TSF hỗ trợ đọc ngữ cảnh để xử lý dấu và viết hoa.
• TSF làm phương thức nhập chính: áp dụng cho các ứng dụng được thêm vào danh sách TSF. Cách này có thể phù hợp hơn với Office, ứng dụng Windows Store và một số ô nhập đặc thù.

Khi TSF là phương thức nhập chính, VKey yêu cầu Windows hiển thị phần chữ đang được soạn mà không gạch chân. Một số ứng dụng có thể tự vẽ kiểu composition riêng; nếu vẫn thấy gạch chân, hãy ghi rõ ứng dụng và phiên bản Windows khi báo lỗi.

Gõ tắt và macro

Macro thay một chuỗi ngắn bằng nội dung dài hơn. Nội dung có thể có xuống dòng và dài tới 20.000 ký tự.

• Chọn phím kích hoạt như Space, Enter hoặc Tab.
• Có thể dùng macro trong chế độ tiếng Anh nếu tùy chọn tương ứng được bật.
• Bật Tự động viết hoa theo phím tắt để kiểu viết hoa của kết quả đi theo cách viết của từ gõ tắt.

Ví dụ: cấu hình dc thành một địa chỉ đầy đủ, sau đó gõ dc và phím kích hoạt để chèn nội dung.

Viết hoa toàn bộ nội dung macro

1. Mở Bảng gõ tắt.
2. Nhập từ gõ tắt và nội dung đầy đủ bằng chữ thường. Ví dụ: đặt tp thành tp.hcm.
3. Bật Tự động viết hoa theo phím tắt trong phần thiết lập macro.
4. Gõ từ gõ tắt, rồi nhấn một phím kích hoạt đã chọn. Kết quả sẽ đi theo cách viết hoa của từ gõ tắt:

Không cần tạo macro riêng cho từng kiểu viết hoa.

Chuyển mã và biến đổi chữ

Công cụ chuyển mã làm việc trên phần văn bản đang chọn. Các thao tác gồm:

• Chuyển giữa Unicode, TCVN3, VNI Windows, Unicode Compound và Vietnamese Locale.
• Chuyển HOA, chuyển thường, viết hoa đầu câu hoặc bỏ dấu.
• Tự động dán kết quả và chọn lại phần văn bản vừa thay đổi.
• Chuyển tuần tự qua nhiều phép biến đổi bằng cùng một phím tắt.

Trước khi dùng trên tài liệu quan trọng, nên thử với một đoạn văn bản ngắn để kiểm tra ứng dụng đích có giữ nguyên lựa chọn hay không.

Cấu hình cho game

Chế độ game gửi lại phím gốc để game vẫn nhận W, A, S, D khi Telex xử lý dấu.

Bạn có thể bật theo hai cách:

1. Thêm file .exe của game trong Cấu hình từng ứng dụng và chọn Chế độ game.
2. Gán phím tắt Bật / tắt chế độ game cho app đang mở, sau đó nhấn ngay trong game.

Nếu game chạy bằng quyền Administrator, Windows có thể chặn VKey đang chạy với quyền thường. Chỉ chạy VKey bằng quyền Administrator khi ứng dụng đích thực sự yêu cầu.

Khởi động cùng Windows và watchdog

VKey đăng ký autostart theo một trong hai cơ chế:

• Chế độ thường dùng Registry của tài khoản hiện tại.
• Chế độ chạy với quyền Administrator dùng Task Scheduler.

Sau khi cập nhật hoặc di chuyển thư mục VKey, hãy tắt rồi bật lại Khởi động cùng Windows để ghi đường dẫn mới. Nếu autostart vẫn lỗi, tắt VKey và làm theo hướng dẫn gỡ cấu hình autostart cũ, sau đó mở VKey và bật lại.

Watchdog là tùy chọn riêng, mặc định tắt. Khi được bật, chương trình giám sát có thể khởi động lại VKey sau khi ứng dụng ngừng phản hồi hoặc thoát bất thường. Thoát VKey theo cách thông thường sẽ không kích hoạt khởi động lại.

Xử lý sự cố và bảo mật

VKey không đặt dấu trong một ứng dụng

1. Kiểm tra VKey đang ở chế độ V.
2. Tắt các bộ gõ khác.
3. Tạo cấu hình riêng cho ứng dụng và thử cách gửi phù hợp.
4. Nếu ứng dụng chạy bằng quyền Administrator, kiểm tra mức quyền của VKey.
5. Thử TSF nếu ô nhập không tương thích với hook engine.

ESET: không gõ được tiếng Việt trong trình duyệt

Nếu VKey vẫn gõ được trong Notepad/Word nhưng không đặt dấu trên Edge/Chrome, Browser protection / Safe Banking & Browsing của ESET có thể đang chặn bộ gõ. Trong issue #229, người dùng đã xác nhận thêm VKey vào Browser protection allowlist rồi khởi động lại trình duyệt giúp gõ tiếng Việt trở lại.

1. Kiểm tra tiện ích ESET và bảo vệ trình duyệt

• Edge: mở edge://extensions.
• Chrome: mở chrome://extensions.
• Firefox: mở about:addons → Extensions (Tiện ích mở rộng).

Tìm tiện ích có tên ESET, chẳng hạn ESET Browser Privacy & Security hoặc ESET Browser Security. Nếu có, mở ứng dụng ESET trên máy để kiểm tra Browser protection / Safe Banking & Browsing, đặc biệt là Secure all browsers (Bảo vệ tất cả trình duyệt) và Keyboard protection (Bảo vệ bàn phím). Tên và vị trí mục có thể khác tùy phiên bản ESET.

Không thấy tiện ích chưa có nghĩa là ESET không bảo vệ trình duyệt. Cửa sổ ẩn danh và việc chạy VKey bằng quyền Administrator cũng không bảo đảm tránh được lớp bảo vệ này.

2. Thêm VKey vào Browser protection allowlist

1. Xác định đúng thư mục VKey đang sử dụng. Có thể mở Task Manager, tìm tiến trình VKey.exe hoặc VKeyClassic.exe, nhấp chuột phải → Open file location (Mở vị trí tệp).

2. Trong ESET, mở Advanced setup (F5) → Protections → Browser protection → Browser protection allowlist → Edit.

3. Chọn Add và thêm từng file theo chế độ đang dùng:

   Chế độ VKey	File cần thêm bằng đường dẫn đầy đủ
   Hook (mặc định)	VKey.exe, hoặc VKeyClassic.exe nếu dùng Classic
   TSF	File .exe tương ứng ở trên và VKeyTSF.dll của bản đang dùng

   Chỉ thêm VKeyTSF.dll chưa đủ cho chế độ Hook. Nếu ESET ghi nhận DLL bị chặn ở đường dẫn khác, hãy dùng đúng đường dẫn trong log.

4. Nhấn OK / Apply để lưu tất cả hộp thoại. Thoát hoàn toàn trình duyệt, kể cả tiến trình chạy nền, rồi mở lại và thử gõ, ví dụ tieengs Vieetj → tiếng Việt với Telex.

Đây là ngoại lệ trong Browser protection allowlist của ESET; danh sách loại trừ quét virus thông thường hoặc mục Loại trừ ứng dụng của VKey không thay thế thiết lập này. Bạn có thể giữ Secure all browsers bật sau khi thêm ngoại lệ.

3. Nếu vẫn chưa gõ được

• Kiểm tra lại đường dẫn, nhất là khi vừa cập nhật hoặc di chuyển VKey, và chắc chắn đã đóng hết tiến trình trình duyệt trước khi mở lại.
• Mở Log files → Browser protection trong ESET để tìm file VKey bị chặn. Với file VKey đã xác minh, nhấp chuột phải vào bản ghi để thêm vào allowlist nếu phiên bản ESET hỗ trợ.
• Để kiểm tra nguyên nhân, có thể tạm tắt Secure all browsers trong Safe Banking & Browsing, khởi động lại trình duyệt rồi thử gõ. Thao tác này giảm bảo vệ trình duyệt; hãy bật lại sau khi kiểm tra và hoàn tất ngoại lệ.

Tham khảo tài liệu ESET: Browser protection allowlist và Safe Banking & Browsing.

Windows hoặc phần mềm diệt virus cảnh báo

Chỉ tải VKey từ GitHub Releases chính thức. Trước khi tạo ngoại lệ, hãy xác minh bản tải theo hướng dẫn antivirus và Sigstore. Trạng thái ký số có thể khác theo từng phiên bản.

Debug Log

Debug Log có thể ghi lại thao tác bàn phím để chẩn đoán lỗi. File log có thể chứa mật khẩu hoặc dữ liệu nhạy cảm.

Trước khi gửi log:

1. Mở file và đọc lại nội dung.
2. Xóa các dòng không liên quan.
3. Chỉ gửi đoạn cần thiết để tái hiện lỗi.

Đọc thêm tài liệu bảo mật và GUIDE.md gốc trên GitHub.