IAccessible：：accNavigate 方法 (oleacc.h)

發行項
02/29/2024

IAccessible：：accNavigate 方法會周遊至容器內的另一個 UI 元素，並擷取物件。這個方法是一個選擇項目。

注意accNavigate 方法已被取代，不應使用。客戶端應該使用其他方法和屬性，例如 AccessibleChildren、 get_accChild、 get_accParent和 IEnumVARIANT。

語法

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

參數

[in] navDir

類型： long

指定要巡覽的方向。這個方向是空間順序，例如左或右，或邏輯順序，例如下一個或上一個。這個值是其中一個導覽常數。

[in] varStart

類型： VARIANT

指定巡覽的起始對像是物件本身還是其中一個物件的子系。此參數CHILDID_SELF (从对象) 或子標識碼 (從其中一個物件的子元素) 開始。如需初始化 VARIANT 的詳細資訊，請參閱如何在參數中使用子標識碼。

[out, retval] pvarEndUpAt

類型： VARIANT*

[out， retval]接收目的地對象相關信息的 VARIANT 結構位址。下表描述 pvarEnd 中傳回的資訊。

vt 成員	值成員
VT_EMPTY	無。指定的方向沒有UI元素。
VT_I4	lVal 包含 UI 元素的子標識碼。
VT_DISPATCH	pdispVal 包含 UI 元素 IDispatch 的位址。

傳回值

類型： HRESULT

如果成功，則傳回 S_OK。

如果未成功，則會傳回下表中的其中一個值，或另一個標準 COM 錯誤碼。伺服器會傳回這些值，但客戶端必須一律檢查輸出參數，以確保它們包含有效的值。如需詳細資訊，請參閱檢查 IAccessible 傳回值和傳回值。

錯誤	Description
S_FALSE	在指定的方向中找不到任何畫面元素。
DISP_E_MEMBERNOTFOUND	物件不支援這個方法。
E_INVALIDARG	引數無效。

備註

瀏覽和邏輯一律受限於容器內的UI元素。透過空間流覽，用戶端只會流覽至起始物件的同層級， (varStart) 。根據與邏輯導覽搭配使用的導覽旗標，用戶端會巡覽至子系或起始物件的同層級。

accNavigate 方法會擷取具有已定義螢幕位置的 UI 元素，以及沒有已定義螢幕位置的不可見物件。

這個方法不會變更選取範圍或焦點。若要變更焦點或選取物件，請使用 IAccessible：：accSelect。

若要避免在周遊螢幕元素時迴圈， accNavigate 會在您在最後一個專案上指定 NAVDIR_NEXT 或第一個元素上的 NAVDIR_PREVIOUS 時傳回S_FALSE VT_EMPTY。

如同其他 IAccessible 方法和函式，用戶端可能會因為用戶動作而收到 IAccessible 介面指標的錯誤。如需詳細資訊，請參閱接收 IAccessible 介面指標的錯誤。

某些系統定義的UI元素，例如功能表、功能表項和快捷功能表，允許流覽至不可見的物件。不過，其他系統定義的UI元素不支援此功能。伺服器可以選擇是否支援巡覽至不可見的物件，也可以略過或公開它們。

用戶端應用程式在使用 accNavigate 在對象之間巡覽時，必須傳回進程後傳回值。後續處理步驟的目標是要為用戶端提供 IAccessible 介面指標和子標識碼，讓他們可以使用 UI 元素的 IAccessible 方法和屬性。

下表根據下列準則描述 IAccessible：：accNavigate 的可能案例：

定義起點 (您從完整物件或簡單元素開始)
傳回的結果 (IDispatch 或VT_I4子標識碼)
用戶端應用程式必須執行的後置處理，才能有 IAccessible 介面指標和子標識碼

針對這些數據表，假設 startID 和 endID 是VT_I4子標識碼， (簡單元素) ，而 pStartAcc 和 pEndAcc 則VT_I4 CHILDID_SELF (完整对象) 。

下表描述下列NAVDIR_旗標：NEXT、PREVIOUS、LEFT、RIGHT、UP 和 DOWN。如需導覽旗標的詳細資訊，請參閱導覽常數。

起點	傳回的結果	傳回值的後續處理
pStartAcc， startID	VT_I4 endID	在 pStartAcc 上呼叫 get_accChild passing endID。遵循 get_accChild中所述的一般程式。
pStartAcc， startID	VT_DISPATCH pEndAcc	使用標準程式，將 IDispatch 介面指標轉換成 pEndAcc 的 IAccessible 介面指標。
pStartAcc，CHILDID_SELF	VT_I4 endID	在 pStartAcc 上呼叫 get_accParent，傳遞 CHILDID_SELF 以取得 endID 父代的 IAccessible 介面指標。然後，在該 IAccessible 介面指標上呼叫get_accChild，並傳遞 endID。遵循 get_accChild中所述的一般程式。
pStartAcc，CHILDID_SELF	VT_DISPATCH pEndAcc	使用標準程式，將 IDispatch 介面指標轉換成 pEndAcc 的 IAccessible 介面指標。

下表說明導覽旗標 NAVDIR_FIRSTCHILD 和 NAVDIR_LASTCHILD。當起點是簡單元素時，它不包含流覽至第一個或最後一個子系的專案，因為簡單元素不能有子系。

起點	傳回的結果	傳回值的後續處理
pStartAcc，CHILDID_SELF	VT_I4 endID	在 pStartAcc 上呼叫 get_accChild，並傳遞 endID。遵循 get_accChild中所述的一般程式。
pStartAcc，CHILDID_SELF	VT_DISPATCH pEndAcc	使用標準程式，將 IDispatch 介面指標轉換成 pEndAcc 的 IAccessible 介面指標。

如需詳細資訊，請參閱對象導覽屬性和方法。

伺服器範例

下列範例顯示自定義清單框方法的可能實作，其清單專案為子專案。


// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    return S_OK;
};

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	oleacc.h
程式庫	Oleacc.lib
Dll	Oleacc.dll
可轉散發套件	sp6 和更新版本和 Windows 95 Windows NT 4.0 上的 Active Accessibility 1.3 RDK