IAccessible：：accNavigate 方法 (oleacc.h)

项目
03/08/2023

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 (从对象) 开始，或者从某个对象的子元素) 开始的子 ID (。有关初始化 VARIANT 的详细信息，请参阅参数中使用子 ID 的方式。

[out, retval] pvarEndUpAt

类型： VARIANT*

[out， retval]接收有关目标对象的信息的 VARIANT 结构的地址。下表描述了 在 pvarEnd 中返回的信息。

vt 成员	值成员
VT_EMPTY	无。没有指定方向的 UI 元素。
VT_I4	lVal 包含 UI 元素的子 ID。
VT_DISPATCH	pdispVal 包含 UI 元素的 IDispatch 的地址。

返回值

类型： HRESULT

如果成功，则返回 S_OK。

如果未成功，则返回下表中的一个值，或者返回另一个标准 COM 错误代码。服务器返回这些值，但客户端必须始终检查输出参数以确保它们包含有效值。有关详细信息，请参阅检查 IAccessible 返回值和返回值。

错误	说明
S_FALSE	未按指定方向找到屏幕元素。
DISP_E_MEMBERNOTFOUND	该对象不支持此方法。
E_INVALIDARG	自变量无效。

注解

导航（包括空间和逻辑）始终仅限于容器中的 UI 元素。使用空间导航，客户端只能导航到 varStart (varStart) 的同级对象。根据与逻辑导航一起使用的导航标志，客户端导航到起始对象的子级或同级对象。

accNavigate 方法检索具有已定义屏幕位置的 UI 元素，以及没有定义的屏幕位置的不可见对象。

此方法不会更改所选内容或焦点。若要更改焦点或选择对象，请使用 IAccessible：：accSelect。

为了防止遍历屏幕元素时循环， accNavigate 在最后一个元素上指定 NAVDIR_NEXT或在第一个元素上指定NAVDIR_PREVIOUS时返回具有VT_EMPTY S_FALSE 。

与其他 IAccessible 方法和函数一样，客户端可能会因为用户操作而收到 IAccessible 接口指针的错误。有关详细信息，请参阅接收 IAccessible 接口指针的错误。

某些系统定义的 UI 元素（如菜单、菜单项和弹出菜单）允许导航到不可见的对象。但是，其他系统定义的 UI 元素不支持此功能。服务器可以选择是否支持导航到不可见对象，并且可以跳过或公开它们。

使用 accNavigate 在对象之间导航时，客户端应用程序必须返回进程后返回值。后期处理步骤的目标是为客户端提供 IAccessible 接口指针和子 ID，以便他们可以使用 UI 元素的 IAccessible 方法和属性。

下表根据以下条件描述了 IAccessible：：accNavigate 的可能方案：

定义起点 (是从完整对象还是简单元素开始)
结果 (IDispatch 或VT_I4子 ID) 返回
客户端应用程序需要执行的后处理才能具有 IAccessible 接口指针和子 ID

对于这些表，假设 startID 和 endID 是VT_I4子 ID (简单元素) ，pStartAcc 和 pEndAcc VT_I4 CHILDID_SELF (完整对象) 。

下表描述了以下NAVDIR_标志：NEXT、PREVIOUS、LEFT、RIGHT、UP 和 DOWN。有关导航标志的详细信息，请参阅导航常量。

起点	返回的结果	返回值的后处理
pStartAcc，startID	VT_I4 endID	在 pStartAcc 传递 endID 上调用get_accChild。按照 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 Professional [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	oleacc.h
Library	Oleacc.lib
DLL	Oleacc.dll
可再发行组件	使用 SP6 及更高版本和 Windows 95 Windows NT 4.0 上的活动辅助功能 1.3 RDK

请参阅

IAccessible

IAccessible：：accSelect

IDispatch

对象导航属性和方法

VARIANT

IAccessible：：accNavigate 方法 (oleacc.h)

语法

参数

返回值

注解

服务器示例

要求

请参阅

其他资源

其他资源