共用方式為

OPENFILENAMEW 結構 (commdlg.h)

  • 發行項

[從 Windows Vista 開始，通用項目對話框已取代 [開啟 ] 和 [另存 新 檔 ] 通用對話方塊。 建議您使用通用項目對話框 API，而不是來自通用對話框連結庫的這些對話方塊。

包含 GetOpenFileName 和 GetSaveFileName 函式用來初始化 [開啟 ] 或 [ 另存新 檔] 對話框的資訊。 使用者關閉對話框之後，系統會傳回此結構中用戶選取專案的相關信息。

語法

typedef struct tagOFNW {
  DWORD         lStructSize;
  HWND          hwndOwner;
  HINSTANCE     hInstance;
  LPCWSTR       lpstrFilter;
  LPWSTR        lpstrCustomFilter;
  DWORD         nMaxCustFilter;
  DWORD         nFilterIndex;
  LPWSTR        lpstrFile;
  DWORD         nMaxFile;
  LPWSTR        lpstrFileTitle;
  DWORD         nMaxFileTitle;
  LPCWSTR       lpstrInitialDir;
  LPCWSTR       lpstrTitle;
  DWORD         Flags;
  WORD          nFileOffset;
  WORD          nFileExtension;
  LPCWSTR       lpstrDefExt;
  LPARAM        lCustData;
  LPOFNHOOKPROC lpfnHook;
  LPCWSTR       lpTemplateName;
  LPEDITMENU    lpEditInfo;
  LPCSTR        lpstrPrompt;
  void          *pvReserved;
  DWORD         dwReserved;
  DWORD         FlagsEx;
} OPENFILENAMEW, *LPOPENFILENAMEW;

成員

lStructSize

類型： DWORD

結構的長度，以位元組為單位。 用於 sizeof (OPENFILENAME) 此參數。

hwndOwner

類型： HWND

擁有對話框之視窗的句柄。 此成員可以是任何有效的視窗句柄，如果對話框沒有擁有者，則為 NULL 。

hInstance

類型： HINSTANCE

如果在 Flags 成員中設定OFN_ENABLETEMPLATEHANDLE旗標，hInstance 是包含對話框範本的記憶體物件的句柄。 如果已設定 OFN_ENABLETEMPLATE 旗標， hInstance 是模組句柄，其中包含 由 lpTemplateName 成員命名的對話框範本。 如果未設定任何旗標，則會忽略此成員。 如果已設定 OFN_EXPLORER 旗標，系統會使用指定的範本來建立對話框，這是預設Explorer樣式對話框的子系。 如果未設定 OFN_EXPLORER 旗標，系統會使用範本來建立取代默認對話框的舊樣式對話方塊。

lpstrFilter

類型： LPCTSTR

緩衝區，包含以 Null 結束的篩選字串配對。 緩衝區中的最後一個字串必須以兩個 NULL 字元終止。

每個配對中的第一個字串是描述篩選 (的顯示字串，例如“Text Files”) ，而第二個字串會指定篩選模式 (例如“.TXT”) 。若要為單一顯示字串指定多個篩選模式，請使用分號分隔模式 (例如「.TXT;.DOC;。BAK“) 。 模式字串可以是有效檔名字符和星號 (*) 通配符的組合。 請勿在模式字串中包含空格。

系統不會變更篩選的順序。 它會以 lpstrFilter 中指定的順序，在 [文件類型] 下拉式方塊中顯示它們。

如果 lpstrFilter 為 NULL，對話框就不會顯示任何篩選。

在快捷方式的情況下，如果未設定任何篩選， GetOpenFileName 和 GetSaveFileName 會擷取.lnk檔案的名稱，而不是其目標。 此行為與在 Flags 成員中設定OFN_NODEREFERENCELINKS旗標相同。 若要在不篩選的情況下擷取快捷方式的目標，請使用字串 "All Files\0*.*\0\0"。

lpstrCustomFilter

類型： LPTSTR

靜態緩衝區，其中包含一對以 Null 終止的篩選字串，以保留使用者所選擇的篩選模式。 第一個字串是描述自定義篩選的顯示字串，而第二個字元串則是用戶選取的篩選模式。 第一次應用程式建立對話框時，您可以指定第一個字串，可以是任何空字串。 當使用者選取檔案時，對話框會將目前的篩選模式複製到第二個字元串。 保留的篩選模式可以是 lpstrFilter 緩衝區中指定的其中一個模式，也可以是使用者輸入的篩選模式。 系統會在下次建立對話框時，使用字串來初始化使用者定義檔案篩選。 如果 nFilterIndex 成員為零，對話方塊會使用自定義篩選。

如果這個成員是 NULL，對話框就不會保留使用者定義的篩選模式。

如果這個成員不是 NULL，nMaxCustFilter 成員的值必須指定 lpstrCustomFilter 緩衝區的大小，以字元為單位。

nMaxCustFilter

類型： DWORD

lpstrCustomFilter 所識別緩衝區的大小，以字元為單位。 此緩衝區長度至少應為 40 個字元。 如果 lpstrCustomFilter 為 NULL 或指向 NULL 字串，則會忽略此成員。

nFilterIndex

類型： DWORD

[ 檔案類型 ] 控制項中目前選取之篩選的索引。 lpstrFilter 指向的緩衝區包含定義篩選的字串組。 第一對字串的索引值為1、第二對2等等。 零的索引表示 lpstrCustomFilter 所指定的自定義篩選。 您可以在輸入上指定索引，以指出對話框的初始篩選描述和篩選模式。 當用戶選取檔案時， nFilterIndex 會傳回目前顯示之篩選的索引。 如果 nFilterIndex 為零，且 lpstrCustomFilter 為 NULL，則系統會使用 lpstrFilter 緩衝區中的第一個篩選。 如果這三個成員都是零或 NULL，則系統不會使用任何篩選，也不會在對話框的檔案清單控制件中顯示任何檔案。

lpstrFile

類型： LPTSTR

用來初始化 檔名編輯控制件 的檔名。 如果不需要初始化，則這個緩衝區的第一個字元必須是 NULL 。 當 GetOpenFileName 或 GetSaveFileName 函式成功傳回時，此緩衝區會包含所選檔案的磁碟驅動器指示項、路徑、檔名和擴展名。

如果已設定 OFN_ALLOWMULTISELECT 旗標，且用戶選取多個檔案，緩衝區會包含目前目錄，後面接著所選檔案的檔名。 對於 [總管樣式] 對話框，目錄和檔名字符串會以 NULL 分隔，並在姓氏後面加上額外的 NULL 字元。 對於舊樣式的對話框，字串會以空格分隔，而且函式會針對具有空格的檔名使用簡短檔名。 您可以使用 FindFirstFile 函式，在長和短檔名之間轉換。 如果使用者只選取一個檔案， 則 lpstrFile 字串在路徑和檔名之間沒有分隔符。

如果緩衝區太小，函式會傳回 FALSE ，而 CommDlgExtendedError 函 式會傳回 FNERR_BUFFERTOOSMALL。 在此情況下， lpstrFile 緩衝區的前兩個字節包含所需的大小，以位元組或字元為單位。

nMaxFile

類型： DWORD

lpstrFile 所指向緩衝區的大小，以字元為單位。 緩衝區必須夠大，才能儲存路徑和檔名字符串或字串，包括終止 的NULL 字元。 如果緩衝區太小而無法包含檔案資訊， GetOpenFileName 和 GetSaveFileName 函式會傳回 FALSE 。 緩衝區長度至少應為 256 個字元。

lpstrFileTitle

類型： LPTSTR

檔名和擴展名 (，不含所選檔案的路徑資訊) 。 此成員可以是 NULL。

nMaxFileTitle

類型： DWORD

lpstrFileTitle 所指向緩衝區的大小，以字元為單位。 如果 lpstrFileTitle 為 NULL，則會忽略此成員。

lpstrInitialDir

類型： LPCTSTR

初始目錄。 選取初始目錄的演算法會因不同平台而異。

Windows 7：

  1. 如果 lpstrInitialDir 第一次使用 [開啟] 或 [另存新檔] 對話框時傳遞的值相同，則使用者最近選取的路徑會當做初始目錄使用。
  2. 否則，如果 lpstrFile 包含路徑，該路徑就是初始目錄。
  3. 否則，如果 lpstrInitialDir 不是 NULL，則會指定初始目錄。
  4. 如果 lpstrInitialDir 為 NULL ，且目前目錄包含指定之篩選類型的任何檔案，則初始目錄為目前目錄。
  5. 否則，初始目錄是目前使用者的個人檔案目錄。
  6. 否則，初始目錄是 Desktop 資料夾。
Windows 2000/XP/Vista：
  1. 如果 lpstrFile 包含路徑，該路徑就是初始目錄。
  2. 否則， lpstrInitialDir 會指定初始目錄。
  3. 否則，如果應用程式過去使用了 [開啟] 或 [另存新檔] 對話框，則最近使用的路徑會選取為初始目錄。 不過，如果應用程式未長時間執行，則會捨棄其儲存的選取路徑。
  4. 如果 lpstrInitialDir 為 NULL ，且目前目錄包含指定之篩選類型的任何檔案，則初始目錄為目前目錄。
  5. 否則，初始目錄是目前使用者的個人檔案目錄。
  6. 否則，初始目錄是 Desktop 資料夾。

lpstrTitle

類型： LPCTSTR

要放在對話框標題列中的字串。 如果此成員為 NULL，系統會使用預設標題 (，也就是 [另存 新檔] 或 [ 開啟 ]) 。

Flags

類型： DWORD

一組可用來初始化對話框的位旗標。 當對話框傳回時，它會設定這些旗標來指出用戶的輸入。 這個成員可以是下列旗標的組合。

值 意義
OFN_ALLOWMULTISELECT
0x00000200
 [ 檔案名] 列表框允許多個選取專案。 如果您也設定 OFN_EXPLORER 旗標，對話框會使用Explorer樣式的使用者介面;否則，它會使用舊樣式的使用者介面。

如果用戶選取多個檔案， lpstrFile 緩衝區會傳回目前目錄的路徑，後面接著所選檔案的檔名。 nFileOffset 成員是第一個檔名的位移，以位元組或字元為單位，不會使用 nFileExtension 成員。 針對 [總管樣式] 對話框，目錄和檔名字符串會以 NULL 分隔，並在姓氏後面加上額外的 NULL 字元。 此格式可讓 [總管] 樣式對話框傳回包含空格的長檔名。 針對舊樣式對話框，目錄和檔名字符串會以空格分隔，而函式會針對具有空格的檔名使用簡短檔名。 您可以使用 FindFirstFile 函式，在 long 和 short 檔名之間轉換。

如果您指定舊樣式對話框的自定義範本，[ 檔案名 ] 清單框的定義必須包含 LBS_EXTENDEDSEL 值。
OFN_CREATEPROMPT
0x00002000
 如果使用者指定不存在的檔案，此旗標會導致對話框提示使用者建立檔案的許可權。 如果使用者選擇建立檔案，對話框會關閉，而且函式會傳回指定的名稱;否則，對話框會保持開啟狀態。 如果您使用此旗標搭配 OFN_ALLOWMULTISELECT 旗標，對話框可讓使用者只指定一個不存在的檔案。
OFN_DONTADDTORECENT
0x02000000
 防止系統將連結新增至包含使用者最近使用之檔的檔案系統目錄中選取的檔案。 若要擷取此目錄的位置，請使用 CSIDL_RECENT 旗標呼叫SHGetSpecialFolderLocation 函式。
OFN_ENABLEHOOK
0x00000020
 啟用 lpfnHook 成員中指定的攔截函式。
OFN_ENABLEINCLUDENOTIFY
0x00400000
 當使用者開啟資料夾時，會導致對話框將 CDN_INCLUDEITEM 通知訊息傳送至 OFNHookProc 攔截程式。 對話框會針對新開啟的資料夾中的每個項目傳送通知。 這些訊息可讓您控制對話框顯示在資料夾的專案清單中的專案。
OFN_ENABLESIZING
0x00800000
 讓 [總管] 樣式對話框能夠使用滑鼠或鍵盤來重設大小。 根據預設，[總管] 樣式的 [開啟 ] 和 [ 另存新 檔] 對話框允許調整對話框的大小，而不論是否已設定此旗標。 只有在您提供勾點程式或自定義範本時，才需要此旗標。 舊樣式對話框不允許重設大小。
OFN_ENABLETEMPLATE
0x00000040
 lpTemplateName 成員是 hInstance 成員所識別模組中對話框範本資源名稱的指標。 如果 已設定OFN_EXPLORER 旗標，系統會使用指定的範本來建立對話框，該對話框是預設 Explorer 樣式對話框的子系。 如果未設定 OFN_EXPLORER 旗標，系統會使用範本來建立取代默認對話框的舊樣式對話方塊。
OFN_ENABLETEMPLATEHANDLE
0x00000080
 hInstance 成員會識別包含預先載入對話框範本的數據區塊。 如果指定這個旗標，系統就會忽略 lpTemplateName 。 如果 已設定OFN_EXPLORER 旗標，系統會使用指定的範本來建立對話框，該對話框是預設 Explorer 樣式對話框的子系。 如果未設定 OFN_EXPLORER 旗標，系統會使用範本來建立取代默認對話框的舊樣式對話方塊。
OFN_EXPLORER
0x00080000
 指出對 [ 開啟 ] 或 [ 另存 新檔] 對話框所做的任何自定義，都使用 Explorer 樣式的自定義方法。 如需詳細資訊，請參閱 Explorer-Style 勾點程式和 Explorer樣式自定義範本。

根據預設，不論是否已設定此旗標， [開啟 ] 和 [ 另存新 檔] 對話框都會使用 Explorer 樣式的使用者介面。 只有在您提供勾點程式或自定義範本，或設定 OFN_ALLOWMULTISELECT 旗標時，才需要此旗標。

如果您想要舊樣式的使用者介面，請省略 OFN_EXPLORER 旗標，並提供取代的舊樣式範本或勾點程式。 如果您想要舊樣式，但不需要自定義範本或勾點程式，只要提供一律傳回 FALSE 的勾點程式即可。
OFN_EXTENSIONDIFFERENT
0x00000400
 使用者輸入的擴展名與 lpstrDefExt 指定的擴展名不同。 如果 lpstrDefExt 為 NULL，函式就不會使用此旗標。
OFN_FILEMUSTEXIST
0x00001000
 使用者只能在 [ 檔名 ] 專案字段中輸入現有檔案的名稱。 如果指定此旗標，且使用者輸入無效的名稱，對話框程式會在消息框中顯示警告。 如果指定這個旗標，也會使用 OFN_PATHMUSTEXIST 旗標。 此旗標可用於 [開啟 ] 對話框中。 它不能與 [ 另存新 檔] 對話框搭配使用。
OFN_FORCESHOWHIDDEN
0x10000000
 強制顯示系統和隱藏的檔案，因此覆寫使用者設定以顯示或未顯示隱藏的檔案。 不過，不會顯示標示為系統和隱藏的檔案。
OFN_HIDEREADONLY
0x00000004
 隱藏 [ 只讀] 複選框。
OFN_LONGNAMES
0x00200000
 針對舊樣式對話框，此旗標會讓對話框使用長檔名。 如果未指定此旗標，或設定 OFN_ALLOWMULTISELECT 旗標，舊樣式對話框會針對具有空格的檔名使用簡短檔名 (8.3 格式) 。 檔案總管樣式對話框會忽略此旗標，並一律顯示長檔名。
OFN_NOCHANGEDIR
0x00000008
 如果使用者在搜尋檔案時變更目錄，請將目前目錄還原為其原始值。

此旗標對 GetOpenFileName 無效。
OFN_NODEREFERENCELINKS
0x00100000
 指示對話框傳回所選快捷方式的路徑和檔名 (。LNK) 檔案。 如果未指定此值，對話框會傳回快捷方式所參考之檔案的路徑和檔名。
OFN_NOLONGNAMES
0x00040000
 對於舊樣式對話框，此旗標會使對話框使用簡短檔名 (8.3 格式) 。 檔案總管樣式對話框會忽略此旗標，並一律顯示長檔名。
OFN_NONETWORKBUTTON
0x00020000
 隱藏並停用 [網络 ] 按鈕。
OFN_NOREADONLYRETURN
0x00008000
 傳回的檔案未選取 [ 只讀 ] 複選框，而且不在受寫入保護的目錄中。
OFN_NOTESTFILECREATE
0x00010000
 在關閉對話方塊之前，不會建立檔案。 如果應用程式將檔案儲存在建立非修改的網路共用上，則應該指定此旗標。 當應用程式指定此旗標時，連結庫不會檢查寫入保護、完整磁碟、開啟的磁碟驅動器門或網路保護。 使用此旗標的應用程式必須仔細執行檔案作業，因為檔案一旦關閉，就無法重新開啟。
OFN_NOVALIDATE
0x00000100
 通用對話框允許傳回檔名中的無效字元。 一般而言，呼叫的應用程式會使用攔截程式來檢查檔名，方法是使用 FILEOKSTRING 訊息。 如果編輯控制項中的文字框是空的，或包含空格，則會更新檔案和目錄的清單。 如果編輯控件中的文本框包含任何其他專案， 則 nFileOffset 和 nFileExtension 會設定為剖析文字所產生的值。 不會將預設延伸模組新增至文字，也不會將文字複製到 lpstrFileTitle 所指定的緩衝區。 如果 nFileOffset 指定的值小於零，則檔名無效。 否則，檔名有效，且 nFileExtension 和 nFileOffset 可以使用，就像未指定 OFN_NOVALIDATE 旗標一樣。
OFN_OVERWRITEPROMPT
0x00000002
 如果選取的檔案已經存在，會導致 [ 另存新 檔] 對話框產生消息框。 用戶必須確認是否要覆寫檔案。
OFN_PATHMUSTEXIST
0x00000800
 使用者只能輸入有效的路徑和檔名。 如果使用此旗標，且使用者在 [ 檔名 ] 專案欄位中輸入無效的路徑和檔名，對話框函式會在消息框中顯示警告。
OFN_READONLY
0x00000001
 建立對話框時，一開始會選取 [ 只讀 ] 複選框。 此旗標表示關閉對話框時，[ 只讀 ] 複選框的狀態。
OFN_SHAREAWARE
0x00004000
 指定如果 OpenFile 函式的呼叫因為網路共用違規而失敗，則會忽略此錯誤，而且對話框會傳回選取的檔名。 如果未設定此旗標，對話框會在使用者指定的檔名發生網路共享違規時通知您的攔截程式。 如果您設定 OFN_EXPLORER 旗標，對話框會將 CDN_SHAREVIOLATION 訊息傳送至攔截程式。 如果您未設定 OFN_EXPLORER，對話框會將 SHAREVISTRING 已註冊的訊息傳送至攔截程式。
OFN_SHOWHELP
0x00000010
 導致對話框顯示 [ 說明 ] 按鈕。 hwndOwner 成員必須指定視窗，以接收當使用者按兩下 [說明] 按鈕時，對話框所傳送的 HELPMSGSTRING 已註冊訊息。 當使用者按兩下 [說明] 按鈕時，檔案總管樣式對話框會將CDN_HELP通知訊息傳送至您的攔截程式。

nFileOffset

類型： WORD

以零起始的位移，以字元為單位，從 lpstrFile 指向之字串中檔名的路徑開頭。 針對 ANSI 版本，這是位元元組數目;針對 Unicode 版本，這是字元數。 例如，如果 lpstrFile 指向下列字串 「c：\dir1\dir2\file.ext」，則此成員會包含值 13，表示 “file.ext” 字符串的位移。 如果用戶選取多個檔案， 則 nFileOffset 是第一個檔名的位移。

nFileExtension

類型： WORD

以零起始的位移，以字元為單位，從 lpstrFile 所指向之字串中擴展名的路徑開頭。 針對 ANSI 版本，這是位元元組數目;針對 Unicode 版本，這是字元數。 擴展名通常是子字串，後面接著最後一個出現的點 (“。”) 字元。 例如，txt 是檔名 readme.txt 的擴展名，html 是 readme.txt.html 的擴展名。 因此，如果 lpstrFile 指向字串 「c:\dir1\dir2\readme.txt」，則此成員會包含值 20。 如果 lpstrFile 指向字串 「c:\dir1\dir2\readme.txt.html」，則此成員會包含值 24。 如果 lpstrFile 指向字串 「c:\dir1\dir2\readme.txt.html.」，則此成員會包含值 29。 如果 lpstrFile 指向不包含任何 “.” 字元的字串，例如 “c：\dir1\dir2\readme”，則此成員包含零。

lpstrDefExt

類型： LPCTSTR

默認延伸模組。 如果使用者無法輸入擴展名，GetOpenFileName 和 GetSaveFileName 會將此擴展名附加至檔名。 此字串可以是任何長度，但只會附加前三個字元。 字串不應包含句點 (.) 。 如果此成員為 NULL ，且使用者無法輸入延伸模組，則不會附加任何延伸模組。

lCustData

類型： LPARAM

系統傳遞至 lpfnHook 成員所識別的攔截程式的應用程式定義數據。 當系統將 WM_INITDIALOG 訊息傳送至攔截程式時，訊息的 lParam 參數是建立對話框時所指定 之 OPENFILENAME 結構的指標。 攔截程式可以使用這個指標來取得 lCustData 值。

lpfnHook

類型： LPOFNHOOKPROC

勾點程式的指標。 除非 Flags 成員包含 OFN_ENABLEHOOK 旗標，否則會忽略這個成員。

如果未在 Flags 成員中設定OFN_EXPLORER旗標，lpfnHook 是 OFNHookProcOldStyle 攔截程式的指標，可接收用於對話框的訊息。 攔截程式會傳回 FALSE ，將訊息傳遞至預設對話框程式或 TRUE 以捨棄訊息。

如果已設定OFN_EXPLORER，lpfnHook 是 OFNHookProc 攔截程式的指標。 攔截程式會接收從對話框傳送的通知訊息。 攔截程式也會接收您藉由指定子對話框範本所定義之任何其他控件的訊息。 攔截程式不會接收適用於預設對話框之標準控件的訊息。

lpTemplateName

類型： LPCTSTR

hInstance 成員所識別模組中的對話框範本資源名稱。 針對編號對話框資源，這可以是 MAKEINTRESOURCE 宏所傳回的值。 除非在 Flags 成員中設定OFN_ENABLETEMPLATE旗標，否則會忽略這個成員。 如果 已設定OFN_EXPLORER 旗標，系統會使用指定的範本來建立對話框，該對話框是預設 Explorer 樣式對話框的子系。 如果未設定 OFN_EXPLORER 旗標，系統會使用範本來建立取代默認對話框的舊樣式對話方塊。

lpEditInfo

此成員會使用 #ifdef _MAC) 有條件地編譯 (，使其僅適用於Motorola 68K Macintosh計算機，不適用於Windows 用戶端操作系統。

lpstrPrompt

此成員會使用 #ifdef _MAC) 有條件地編譯 (，使其僅適用於Motorola 68K Macintosh計算機，不適用於Windows 用戶端操作系統。

pvReserved

類型： void*

此成員已保留。

dwReserved

類型： DWORD

此成員已保留。

FlagsEx

類型： DWORD

一組可用來初始化對話框的位旗標。 目前，此成員可以是零或下列旗標。

值 意義
OFN_EX_NOPLACESBAR
0x00000001
 如果設定此旗標，則不會顯示位置列。 如果未設定此旗標，Explorer 樣式對話框會包含包含常用資料夾圖示的放置列，例如 [我的最愛] 和 [桌面]。

備註

基於相容性考慮，如果 Flags 設定為 OFN_ENABLEHOOK 且 lStructSizeOPENFILENAME_SIZE_VERSION_400，則會隱藏 Places 列。

注意

commdlg.h 標頭會將 OPENFILENAME 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
標頭 commdlg.h (包含 Windows.h)

另請參閱

通用對話框連結庫

概念

GetOpenFileName

GetSaveFileName

其他資源

參考

SHGetSpecialFolderLocation