Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,19 @@ Repeated row reads return an existing sorted/frozen sibling order before consult
children or sort metadata. Cache misses retain the lazy scanner-order shortcut. Existing root,
layout/structure and archive-preview notifications invalidate orders, including empty live snapshots.

`QTreeView` lays out every row of every expanded folder on each expand, sort and live refresh, calling
the Python model about twice per row; that dispatch alone is about 1.3–2.5 s for 150,000 rows, against
43–86 ms for a C++ model (U-20261119-02). `FolderTreeModel` therefore shows a real folder with more than
`PAGE_ROWS` entries a page at a time: its rows (`_shown_rows`) are the first pages of the sorted/frozen
order plus one display-only `MoreRows` entry (a `VirtualEntry`, never actionable) counting the rest.
Clicking it or pressing Enter calls `show_more` through one relayout; `TreeFilter.reveal` calls
`show_rows_for` so a chart or list target past a page gets its row. Pages persist per folder across
sorts and refreshes, and the stable `MoreRows` instance keeps persistent indexes on it. Archive preview
groups are never paged. Row lookups, selection mapping, repaint ranges and `filesystem_rows` read the
shown rows; `hidden_rows` lets `ExpandedTreeProxy` keep `MoreRows` while a hidden entry matches. List
copy/export skips rows answering `list_transfer.PLACEHOLDER_ROLE`. The tree's selected entries are read
from whole selected ranges (`TreeFilter.selected_nodes`), not through Qt's per-row `selectedRows()`.

Unit/capacity changes instead emit column- and role-specific
[same-parent `dataChanged` ranges](https://doc.qt.io/qtforpython-6/PySide6/QtCore/QAbstractItemModel.html#PySide6.QtCore.QAbstractItemModel.dataChanged)
for the root row and previously queried nonempty sibling groups. The model records those parents
Expand Down
4 changes: 3 additions & 1 deletion docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -370,7 +370,9 @@ To give FileTree to someone without Python, compile it with Nuitka into a progra
says so in the status bar and next to the pointer instead of doing nothing. With many folders open the
tree refreshes less often, so the window stays responsive.
3. **Find what takes the space**: the biggest folders are at the top of the tree. Open a folder with the
arrow next to it, or explore the chart on the right.
arrow next to it, or explore the chart on the right. A folder with more than 2,000 entries shows them
2,000 at a time, so the window stays responsive: click its last row, or press Enter on it, for the next
ones. Picking an entry in the chart or a list shows the page it is on.

### Reading the results

Expand Down
2 changes: 1 addition & 1 deletion docs/guide_ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,7 +288,7 @@ FileTree を Python を持たない人に渡すには、Nuitka を使用して

## 使い方

1. **スキャン対象を選択**: クリック * フォルダーを選択します…* またはスタート ページのドライブの 1 つを選択し、フォルダーをウィンドウにドラッグするか、上部のボックスにパスを入力して Enter を押します。コマンド ライン `je-file-tree D:\Projects` (または `python start_file_tree.py D:\Projects`) からスキャンを開始することもできます。フォルダーをドロップすると、フォルダーがその場でスキャンされ、コピー アクションのみが受け入れられ、Shift キーが移動を要求した場合でもソースが保持されます。 2. **入力を見てください**: ツリーがすぐに表示され、FileTree が動作している間、最大のフォルダーが一番上に移動します。スキャンが終了すると、最大のファイルとファイルの種類が続きます。 *Stop* (または Esc) でいつでもスキャンを終了し、それまでに読み取った内容を保持し、不完全としてマークします。スキャン中は、スキャン結果を読み取ったり変更したりする操作(ごみ箱への移動、再スキャン、エクスポートなど)はスキャンの完了を待ちます。その間に使うと、何も起きないのではなく、ステータス バーとポインターの横に理由が表示されます。展開したフォルダーが多いときは、ウィンドウを操作できるようにフォルダー ツリーの更新間隔を広げます。 3. **スペースを占めるものを見つけます**: 最大のフォルダーがツリーの一番上にあります。横にある矢印のあるフォルダーを開くか、右側のグラフを調べてください。
1. **スキャン対象を選択**: クリック * フォルダーを選択します…* またはスタート ページのドライブの 1 つを選択し、フォルダーをウィンドウにドラッグするか、上部のボックスにパスを入力して Enter を押します。コマンド ライン `je-file-tree D:\Projects` (または `python start_file_tree.py D:\Projects`) からスキャンを開始することもできます。フォルダーをドロップすると、フォルダーがその場でスキャンされ、コピー アクションのみが受け入れられ、Shift キーが移動を要求した場合でもソースが保持されます。 2. **入力を見てください**: ツリーがすぐに表示され、FileTree が動作している間、最大のフォルダーが一番上に移動します。スキャンが終了すると、最大のファイルとファイルの種類が続きます。 *Stop* (または Esc) でいつでもスキャンを終了し、それまでに読み取った内容を保持し、不完全としてマークします。スキャン中は、スキャン結果を読み取ったり変更したりする操作(ごみ箱への移動、再スキャン、エクスポートなど)はスキャンの完了を待ちます。その間に使うと、何も起きないのではなく、ステータス バーとポインターの横に理由が表示されます。展開したフォルダーが多いときは、ウィンドウを操作できるようにフォルダー ツリーの更新間隔を広げます。 3. **スペースを占めるものを見つけます**: 最大のフォルダーがツリーの一番上にあります。横にある矢印のあるフォルダーを開くか、右側のグラフを調べてください。2,000 個を超える項目があるフォルダーは、ウィンドウの応答性を保つため 2,000 個ずつ表示します。最後の行をクリックするか、その行で Enter キーを押すと次の項目を表示します。グラフや一覧で選んだ項目は、その項目のページが自動的に表示されます。

### 結果の読み取り

Expand Down
2 changes: 1 addition & 1 deletion docs/guide_ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,7 +288,7 @@ Python이 없는 사람에게 FileTree를 제공하려면 Nuitka를 사용하여

## 사용방법

1. **검사 대상 선택**: *폴더 선택…* 또는 시작 페이지의 드라이브 중 하나를 클릭하거나 폴더를 창으로 드래그하거나 상단 상자에 경로를 입력하고 Enter 키를 누릅니다. `je-file-tree D:\Projects`(또는 `python start_file_tree.py D:\Projects`) 명령줄에서 스캔을 시작할 수도 있습니다. 폴더를 삭제하면 폴더가 제자리에 스캔되고 복사 작업만 허용되며 Shift가 이동을 요청하는 경우에도 소스가 유지됩니다. 2. **채워지는 것을 지켜보세요**: 트리가 즉시 나타나고 FileTree가 작동하는 동안 가장 큰 폴더가 맨 위로 이동합니다. 스캔이 끝나면 가장 큰 파일과 파일 형식이 따릅니다. *Stop*(또는 Esc)은 언제든지 스캔을 종료하고 지금까지 읽은 내용을 불완전으로 표시하여 유지합니다. 스캔 중에는 스캔 결과를 읽거나 바꾸는 작업(휴지통으로 이동, 다시 스캔, 내보내기 등)이 스캔이 끝날 때까지 기다립니다. 그동안 이런 작업을 누르면 아무 반응이 없는 대신 상태 표시줄과 포인터 옆에 이유가 표시됩니다. 펼친 폴더가 많으면 창이 계속 반응하도록 폴더 트리의 갱신 간격을 늘립니다. 3. **공간을 차지하는 항목 찾기**: 가장 큰 폴더가 트리 상단에 있습니다. 옆에 화살표가 있는 폴더를 열거나 오른쪽에 있는 차트를 탐색하세요.
1. **검사 대상 선택**: *폴더 선택…* 또는 시작 페이지의 드라이브 중 하나를 클릭하거나 폴더를 창으로 드래그하거나 상단 상자에 경로를 입력하고 Enter 키를 누릅니다. `je-file-tree D:\Projects`(또는 `python start_file_tree.py D:\Projects`) 명령줄에서 스캔을 시작할 수도 있습니다. 폴더를 삭제하면 폴더가 제자리에 스캔되고 복사 작업만 허용되며 Shift가 이동을 요청하는 경우에도 소스가 유지됩니다. 2. **채워지는 것을 지켜보세요**: 트리가 즉시 나타나고 FileTree가 작동하는 동안 가장 큰 폴더가 맨 위로 이동합니다. 스캔이 끝나면 가장 큰 파일과 파일 형식이 따릅니다. *Stop*(또는 Esc)은 언제든지 스캔을 종료하고 지금까지 읽은 내용을 불완전으로 표시하여 유지합니다. 스캔 중에는 스캔 결과를 읽거나 바꾸는 작업(휴지통으로 이동, 다시 스캔, 내보내기 등)이 스캔이 끝날 때까지 기다립니다. 그동안 이런 작업을 누르면 아무 반응이 없는 대신 상태 표시줄과 포인터 옆에 이유가 표시됩니다. 펼친 폴더가 많으면 창이 계속 반응하도록 폴더 트리의 갱신 간격을 늘립니다. 3. **공간을 차지하는 항목 찾기**: 가장 큰 폴더가 트리 상단에 있습니다. 옆에 화살표가 있는 폴더를 열거나 오른쪽에 있는 차트를 탐색하세요. 항목이 2,000개를 넘는 폴더는 창이 원활하게 반응하도록 2,000개씩 표시합니다. 마지막 행을 클릭하거나 그 행에서 Enter 키를 누르면 다음 항목을 표시합니다. 차트나 목록에서 선택한 항목은 해당 페이지가 자동으로 표시됩니다.

### 결과 읽기

Expand Down
2 changes: 1 addition & 1 deletion docs/guide_zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -291,7 +291,7 @@ python start_file_tree.py
1. **选择要扫描的地方**:在起始页点“选择文件夹…”或其中一个磁盘、把文件夹拖到窗口上,或在上方的输入框输入路径后按 Enter。也可以从命令行直接开始扫描:`je-file-tree D:\Projects`(或 `python start_file_tree.py D:\Projects`)。
拖动文件夹会在原位置扫描,且只接受复制操作;即使用 Shift 请求移动,也会保留来源。
2. **边扫边看**:文件夹树会立刻出现,FileTree 一边加总,最大的文件夹一边往上排;最大的文件与文件类型在扫描结束时补上。随时可以点“停止”(或按 Esc)结束扫描,已经读到的部分会留下来并标示为不完整。扫描进行中,会读取或更改扫描结果的操作(移到回收站、重新扫描、导出等)须等扫描完成;这时点击它们,状态栏与鼠标指针旁会说明原因,而不是没有反应。展开的文件夹很多时,文件夹树会放慢刷新频率,让窗口保持可操作。
3. **找出占空间的东西**:最大的文件夹排在最上面。点文件夹旁的箭头看里面的内容,或在右边的图表里浏览。
3. **找出占空间的东西**:最大的文件夹排在最上面。点文件夹旁的箭头看里面的内容,或在右边的图表里浏览。超过 2,000 个项目的文件夹每次显示 2,000 个,使窗口保持流畅:单击最后一行,或在该行按 Enter,即可显示接下来的项目。在图表或列表中选中的项目会自动显示其所在的页面。

### 看懂结果

Expand Down
2 changes: 1 addition & 1 deletion docs/guide_zh-TW.md
Original file line number Diff line number Diff line change
Expand Up @@ -291,7 +291,7 @@ python start_file_tree.py
1. **選擇要掃描的地方**:在起始頁按「選擇資料夾…」或其中一顆磁碟、把資料夾拖曳到視窗上,或在上方的方框輸入路徑後按 Enter。也可以從命令列直接開始掃描:`je-file-tree D:\Projects`(或 `python start_file_tree.py D:\Projects`)。
拖曳資料夾會在原位置掃描,且只接受複製動作;即使用 Shift 要求移動,也會保留來源。
2. **邊掃邊看**:資料夾樹會立刻出現,FileTree 一邊加總,最大的資料夾一邊往上排;最大的檔案與檔案類型在掃描結束時補上。隨時可以按「停止」(或 Esc)結束掃描,已經讀到的部分會留下來並標示為不完整。掃描進行中,會讀取或變更掃描結果的操作(移到資源回收筒、重新掃描、匯出等)須等掃描完成;這時按下它們,狀態列與滑鼠指標旁會說明原因,而不是沒有反應。展開的資料夾很多時,資料夾樹會放慢更新頻率,讓視窗保持可操作。
3. **找出佔空間的東西**:最大的資料夾排在最上面。按資料夾旁的箭頭看裡面的內容,或在右邊的圖表裡瀏覽。
3. **找出佔空間的東西**:最大的資料夾排在最上面。按資料夾旁的箭頭看裡面的內容,或在右邊的圖表裡瀏覽。超過 2,000 個項目的資料夾每次顯示 2,000 個,讓視窗保持流暢:按一下最後一列,或在該列按 Enter,就會顯示接下來的項目。在圖表或清單中選取的項目會自動顯示所在的頁面。

### 看懂結果

Expand Down
48 changes: 48 additions & 0 deletions docs/updates/2026-11.md
Original file line number Diff line number Diff line change
Expand Up @@ -549,3 +549,51 @@
- **驗證**:新增 `test/test_chart_focus.py`(2 個案例:從路徑框開始掃描後焦點在資料夾樹;焦點刻意留在路徑框時,使用圖表按鈕後按 Enter 與 Backspace 不會開始掃描,路徑框文字不變)。兩個案例在修正前都失敗。麵包屑、圖表、樹狀圖、起始頁、路徑框與開始掃描相關的測試檔:307 個通過(1 個已知的長路徑測試排除);`ruff check .`。
- **檔案**:`je_file_tree/gui/main_window.py`、`gui/results_view.py`;`test/test_chart_focus.py`;`architecture.md`;`progress.md`(刪除 #143)。
- **待辦**:無。

## U-20261119-02 · 2026-11-19 · 大型資料夾在檔案樹中分頁顯示,展開與更新不再卡頓 · #perf #gui #ux #i18n

- **原因**:使用者回報「檔案太多時,檔案樹的部分介面仍會卡頓」。
- **量測方法**:Windows 11、Python 3.14、PySide6,隱藏視窗(`WA_DontShowOnScreen`)在真實事件迴圈中操作,以 10 毫秒計時器量測停頓。測試資料在工作階段暫存資料夾自建:一個資料夾含 150,000 個檔案,另有 30 個資料夾各含 3,000 個檔案。量測只讀取自建資料,未刪除任何使用者資料。本機速度在不同時段相差約兩倍,因此前後比較都在同一時段量測。
- **找到的原因**:
- `QTreeView` 每次展開、排序或即時更新時,都會重新排版所有展開資料夾的每一列,每列由 C++ 呼叫 Python 模型兩次(`index`、`hasChildren`)。展開含 150,000 個檔案的資料夾需要 1.0 至 2.7 秒。
- 這是 PySide 由 C++ 呼叫 Python 的固有成本,無法只靠優化模型解決:同樣 150,000 列,一個什麼都不做的 Python 模型展開需要約 2.0 至 2.5 秒、重新排版約 1.3 秒;C++ 模型(`QStandardItemModel`)只要 86 與 43 毫秒。`FolderTreeModel` 約為這個下限的 1.5 倍。
- 掃描中展開這個資料夾時,每次有新檔案加入的即時更新都會重新排版全部的列:最長停頓約 1.0 至 1.1 秒,掃描結束時再停頓約 1.1 至 1.2 秒。
- 在檔案樹按 Ctrl+A 會停頓 41 秒:Qt 的 `selectedRows()` 每個選取列約呼叫 Python 9 次(約 18 秒),Qt 自己的 `selectAll` 每列約 6 次。
- **變更**:
- `FolderTreeModel` 對超過 `PAGE_ROWS`(2,000)個項目的資料夾分頁顯示:依目前的排序顯示第一頁,最後一列是只供顯示的 `MoreRows`(`VirtualEntry` 的子類別,不能執行任何檔案操作),寫出還有多少項目與其大小。按一下這一列或按 Enter,會再顯示一頁,並把目前列移到新出現的第一列。
- 從圖表或清單選取還沒顯示的項目時(`TreeFilter.reveal` 呼叫 `show_rows_for`),會一路擴展上層資料夾的頁數,直到顯示該項目。
- 排序、即時更新與移除項目後,保留已顯示的頁數;`MoreRows` 每個資料夾只有一個,因此停在這一列的持久索引會跟著移動。
- 篩選(`ExpandedTreeProxy`)時,只要有未顯示的項目符合條件,就保留 `MoreRows` 列;選取時不會把它當成項目,複製與匯出清單時也會略過(`list_transfer.PLACEHOLDER_ROLE`)。
- 檔案樹讀取選取項目時,改用 `TreeFilter.selected_nodes` 直接讀取整列選取範圍,不再經過 Qt 的 `selectedRows()`。
- 新增 `tree_more_rows`、`tree_more_rows_hint` 兩個字串(五種語言)。
- **結果**(同一組資料、同一時段):
- 展開含 150,000 個檔案的資料夾:1,031 至 2,688 毫秒降為 14 至 37 毫秒。
- Ctrl+A:17 至 41 秒降為 96 毫秒(只改選取讀取時是 17 秒)。
- 展開 30 個各含 3,000 個檔案的資料夾:663 至 1,621 毫秒降為 385 毫秒。
- 依名稱排序:316 至 642 毫秒降為 148 毫秒;剩下的是在 Python 中排序 150,000 個項目。
- 掃描中展開這個資料夾:最長停頓 1,046 至 1,138 毫秒降為 102 至 174 毫秒;掃描結束時 1,094 至 1,228 毫秒降為 22 至 113 毫秒。
- **驗證**:
- 新增 `test/test_tree_paging.py`(12 個案例,頁面大小設為 3):
- 分頁與最後一列,以及小資料夾不分頁。
- 再顯示一頁時保留選取,最後一列跟著移動。
- 從其他檢視選取時擴展上層頁數。
- 排序後保留頁數,即時掃描中的分頁。
- 篩選時保留或移除最後一列。
- 按一下與按 Enter 顯示下一頁,全選時不選入最後一列,複製時略過最後一列。
- 移除複製的略過條件後,複製案例會失敗。
- `test_tree_selection_cache.py` 的 4,000 列案例改為一頁大小;`test_tree_selection_capture.py` 改用公開的 `selected_nodes`。
- 所有 `test_tree*.py`、`test_gui.py`、清單複製與匯出、壓縮檔預覽、移除、圖表與其他引用結果檢視的測試檔,加上 `test_i18n.py`、`test_layers.py`:507 個通過,1 個略過(1 個已知的長路徑測試排除);`ruff check .`。
- **未驗證**:使用者實際的磁碟與畫面。同時展開許多資料夾時,排版成本仍與顯示的總列數成正比。
- **檔案**:
- 程式:`je_file_tree/gui/tree_model.py`、`gui/tree_projection.py`、`gui/tree_filter.py`、`gui/results_view.py`、`gui/list_transfer.py`、`gui/strings.py`。
- 測試:`test/test_tree_paging.py`、`test/test_tree_selection_cache.py`、`test/test_tree_selection_capture.py`。
- 文件:`architecture.md`、`docs/guide.md` 與四種語言的翻譯。
- **待辦**:無。

## U-20261119-03 · 2026-11-19 · macOS 上在「還有更多項目」列按 Enter 沒有反應 · #incident #fix #gui #macos

- **原因**:U-20261119-02 推送後,CI 的 macOS arm64 工作中 `test_tree_paging.py::test_clicking_the_last_row_shows_the_next_page_and_moves_to_it` 失敗,其他 17 個工作都通過。Qt 的項目檢視在 macOS 上按 Return 不會送出 `activated`(macOS 的開啟鍵是 Cmd+O),所以在大型資料夾的最後一列按 Enter 沒有反應;按一下仍然有效。
- **修正**:`ResultsView.eventFilter` 在檔案樹的目前列是 `MoreRows` 時,直接處理 Return 與 Enter 並顯示下一頁,不再依賴各平台的啟用按鍵;`activated` 的連線保留給連按兩下與 Cmd+O。
- **驗證**:測試在按 Enter 前移除 `activated` 的連線,模擬 macOS 的行為,因此在每個平台都會檢查這條路徑;未修正時本機也會失敗,修正後通過。`test_tree_paging.py`、`test_gui.py`、`test_chart_focus.py`、`test_tree_filter.py`、`test_list_transfer.py`:103 個通過(1 個已知的長路徑測試排除);`ruff check .`。
- **檔案**:`je_file_tree/gui/results_view.py`;`test/test_tree_paging.py`。
- **待辦**:無。
Loading
Loading