IAccessible：：get_accName 方法 (oleacc.h)

發行項
03/05/2024

IAccessible：：get_accName 方法會擷取指定對象的名稱。所有物件都支援這個屬性。

語法

HRESULT get_accName(
  [in]          VARIANT varChild,
  [out, retval] BSTR    *pszName
);

參數

[in] varChild

類型： VARIANT

指定擷取的名稱是否屬於物件或其中一個物件的子專案。這個參數CHILDID_SELF (取得对象) 或子標識碼 (，以取得對象子專案的相關信息) 。如需初始化 VARIANT 結構的詳細資訊，請參閱參數中使用子標識碼的方式。

[out, retval] pszName

類型： BSTR*

BSTR 的位址，接收包含指定之物件名稱的字串。

傳回值

類型： HRESULT

如果成功，則傳回 S_OK。

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

錯誤	Description
S_FALSE	指定的物件沒有名稱。
E_INVALIDARG	引數無效。

備註

許多物件，例如圖示、功能表、複選框、下拉式方塊和其他控件，都會向使用者顯示標籤。向用戶顯示的任何標籤都會用於物件的名稱屬性。如需詳細資訊，請參閱 Name 屬性。

伺服器開發人員的注意事項： 如果您使用 Name 屬性的選單或按鈕文字，請移除任何連字元 (&) 標示鍵盤存取鍵。提供用戶端的存取金鑰，以回應 IAccessible：：get_accKeyboardShortcut。

將此屬性傳回的字串本地化。

伺服器範例

下列範例顯示這個方法的可能實作，用於管理自己的子專案之自定義清單框控件。


// m_pStdAccessibleObject is the standard object returned by CreateStdAccessibleObject. 
// m_pControl is the control object that provides this accessibility object. It maintains
// a zero-based collection of child items. 

HRESULT STDMETHODCALLTYPE AccServer::get_accName( 
    VARIANT varChild,
    BSTR *pszName)
{
    if (varChild.vt != VT_I4)
    {
        *pszName = NULL;
        return E_INVALIDARG;
    }
    // For the control itself, let the standard accessible object return the name 
    // assigned by the application. This is either the "caption" property or, if 
    // there is no caption, the text of any label. 
    if (varChild.lVal == CHILDID_SELF)
    {
        return m_pStdAccessibleObject->get_accName(varChild, pszName);                  
    }
    
    // Else return the name of the item in the list. 
    else
    {
        CustomListControlItem* pItem = m_pControl->GetItemAt(varChild.lVal - 1);
        if (pItem)
        {
            *pszName = SysAllocString(pItem->GetName());        
       
        }
    }
    return S_OK;
};

用戶端範例

下列範例函式會顯示控件的可存取名稱。


HRESULT PrintName(IAccessible* pAcc, long childId)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    BSTR bstrName;
    VARIANT varChild;
    varChild.vt = VT_I4;
    varChild.lVal = childId;
    HRESULT hr = pAcc->get_accName(varChild, &bstrName);
    printf("Name: %S ", bstrName);
    SysFreeString(bstrName);
    return hr;
}

規格需求

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