Método Items.Find (Outlook)

Localiza e retorna um objeto de item do Microsoft Outlook que satisfaz o filtro fornecido.

Sintaxe

expressão. Localizar (Filtro)

Expressão Uma expressão que retorna um objeto Items .

Parâmetros

Nome	Obrigatório/Opcional	Tipo de dados	Descrição
Filtro	Obrigatório	String	Uma sequência de caracteres que especifica os critérios aos quais o objeto retornado deve satisfazer.

Valor de retorno

Um valor de Object que representa um item do Outlook, se a chamada tiver êxito; Retorna Null (ou Nothing no Visual Basic) se ele falhar.

Comentários

Para usar a pesquisa de indexação de conteúdo na coleção Items, use o método Restrict. FindRow retornará um erro se Filter contiver palavras-chave de indexação de conteúdo. Para obter mais informações sobre palavras-chave de indexação de conteúdo, consulte Filtrando itens usando palavras-chave da consulta.

O método retornará um erro com as seguintes propriedades no Filtro :

Body	LastFirstNoSpaceCompany
Filhos	LastFirstSpaceOnlyCompany
Class	LastFirstNoSpaceAndSuffix
Companies	MemberCount
CompanyLastFirstNoSpace	NetMeetingAlias
CompanyLastFirstSpaceOnly	NetMeetingAutoStart
ContactNames	NetMeetingOrganizerAlias
Contatos	NetMeetingServer
ConversationIndex	NetMeetingType
DLName	RecurrenceState
Email1EntryID	ReplyRecipients
Email2EntryID	ReceivedByEntryID
Email3EntryID	ReceivedOnBehalfOfEntryID
EntryID	ResponseState
HTMLBody	Salvo
IsOnlineMeeting	Sent
LastFirstAndSuffix	submitted
LastFirstNoSpace	VotingOptions
AutoResolvedWinner	DownloadState
BodyFormat	IsConflict
InternetCodePage	MeetingWorkspaceURL
Permission

Criando filtros para os métodos Localizar e Restringir

A sintaxe do filtro varia dependendo do tipo de campo sendo filtrado.

Cadeia de Caracteres (para campos Texto)

Ao filtrar campos de texto, você pode usar apóstrofo (') ou aspas duplas ("") para delimitar os valores que fazem parte do filtro. Por exemplo, todas as linhas a seguir funcionam corretamente quando o campo é do tipo Cadeia de caracteres :

sFilter = "[CompanyName] = 'Microsoft'"  
sFilter = "[CompanyName] = ""Microsoft"""  
sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

In specifying a filter in a Jet or DASL query, if you use a pair of single quotes to delimit a string that is part of the filter, and the string contains another single quote or apostrophe, then add a single quote as an escape character before the single quote or apostrophe. Use a similar approach if you use a pair of double quotes to delimit a string. If the string contains a double quote, then add a double quote as an escape character before the double quote.

Por exemplo, na cadeia de caracteres de filtro DASL que filtra para a propriedade Subject ser igual à palavra can't, toda a cadeia de caracteres de filtro é delimitada por um par de aspas duplas e a cadeia de caracteres can't inserida é delimitada por um par de aspas individuais. Há três caracteres que você precisa escapar nesta cadeia de caracteres de filtro: a cotação dupla inicial e a cotação dupla final para a referência de propriedade de http://schemas.microsoft.com/mapi/proptag/0x0037001f, e o apóstrofo na condição de valor da palavra can't. A aplicação dos caracteres de escape apropriados permite expressar a cadeia de caracteres de filtro da seguinte forma:

filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'can''t'"

Como alternativa, você pode usar a chr(34) função para representar a cotação dupla (cujo valor de caractere ASCII é 34) que é usada como um caractere de escape. A substituição chr(34) usada como caractere de escape de aspas duplas permite expressar o último exemplo desta forma:

filter = "@SQL= " & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001f" _& Chr(34) & " = " & "'can''t'"

O uso de aspas simples e duplas como caracteres de escape também é obrigatório nas consultas DASL com o operador ci_startswith ou ci_phrasematch. Por exemplo, a consulta a seguir executa uma correspondência de frase para can't no assunto da mensagem:

filter = "@SQL=" & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001E" _& Chr(34) & " ci_phrasematch " & "'can''t'"

Outro exemplo é uma cadeia de caracteres de filtro DASL que filtra a propriedade Subject sendo igual às palavras the right stuff, em que a palavra stuff é fechada por aspas duplas. Nesse caso, você deve usar aspas duplas como escape da seguinte forma:

filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'the right ""stuff""'"

A different set of escaping rules apply to a property reference for named properties that contain the space, single quote, double quote, or percent character. For more information, see Referencing Properties by Namespace.

Date

Embora datas e horas geralmente são armazenadas com um formato Date, Find e Restrict métodos exigem que a data e hora ser convertido em uma representação de cadeia de caracteres. Para certificar-se de que a data está formatada como Outlook espera, use a função Format. O exemplo a seguir cria um filtro para localizar todos os contatos que foram modificados após 15 de janeiro de 1999 às 15:30.

sFilter = "[LastModificationTime] > '" & Format("1/15/99 3:30pm", "ddddd h:nn AMPM") & "'"

Operadores booleanos

operadores Boolean, TRUE/ FALSE, Sim/Não, DIANTE/OFF, e assim por diante, não devem ser convertidos em uma cadeia de caracteres. Por exemplo, para determinar se o registro no diário está habilitado para contatos, você pode usar esse filtro:

sFilter = "[Journal] = True" 

Observação

[!OBSERVAçãO] Se você usar aspas como delimitadores com campos Boolean, uma cadeia de caracteres vazia localizará itens cujos campos sejam False, e todas as cadeias de caracteres não-vazias localizarão os itens cujos campos sejam True.

Keywords (ou Categories)

O campo de categorias é do tipo palavras-chave, que foi projetada para armazenar vários valores. Ao acessar programaticamente, o campo categorias se comporta como um campo de texto e a cadeia de caracteres deve corresponder exatamente. Valores na cadeia de texto são separados por uma vírgula e um espaço. Geralmente, isso significa que você não pode usar os métodos Find e Restrict em um campo de palavras-chave se ele contiver mais de um valor. Por exemplo, se você tiver um contato na categoria Business e um contato nas categorias Social e corporativos, você não pode usar facilmente os métodos Find e Restrict para recuperar todos os itens que estão na categoria comercial. Em vez disso, você pode executar um loop em todos os contatos na pasta e use a função Instr para testar se a cadeia de caracteres "Business" está contida em todo o campo de palavras-chave.

Observação

[!OBSERVAçãO] Uma exceção possível seria se você limitasse o campo Categories a dois ou poucos valores. Então, seria possível usar os métodos Find e Restrict com o operador lógico OR para recuperar todos os contatos de Business. Por exemplo (em pseudocódigo): "Business" OU "Business, Personal" OU "Personal, Business". As cadeias de caracteres de categoria não são sensíveis a casos.

Integer

Você pode procurar por campos Integer com ou sem aspas como delimitadores. Os filtros a seguir localizarão contatos que foram criados com o Outlook 2000:

sFilter = "[OutlookInternalVersion] = 92711"  
sFilter = "[OutlookInternalVersion] = '92711'"

Usando variáveis como parte do filtro

Conforme ilustrado pelo exemplo do método Restrict, você pode usar valores de variáveis como parte do filtro. O exemplo de código do Microsoft Visual Basic Scripting Edition (VBScript) a seguir ilustra a sintaxe que utiliza variáveis como parte do filtro.

sFullName = "Dan Wilson" 

Essa abordagem usa Chr (34) para delimitar o valor:

sFilter = "[FullName] = " & Chr(34) & sFullName & Chr(34)

Essa abordagem usa aspas duplas para delimitar o valor:

sFilter = "[FullName] = """ & sFullName & """"

Usando operadores lógicos como parte do filtro

Os operadores lógicos permitidos são AND, OR e NOT. Veja a seguir variações da cláusula do método Restrict, para que você possa especificar vários critérios.

OR: o código a seguir retorna todos os itens de contato que têm como categoria Comercial ou Pessoal.

sFilter = "[Categories] = 'Personal' Or [Categories] = 'Business'" 

AND: o código a seguir recupera todos os contatos pessoais que trabalham na Microsoft.

sFilter = "[Categories] = 'Personal' And [CompanyName] = 'Microsoft'"

NOT: o código a seguir recupera todos os contatos pessoais que não trabalham na Microsoft.

sFilter = "[Categories] = 'Personal' And Not([CompanyName] = 'Microsoft')"

Observações adicionais

Se você está tentando usar os métodos Find ou Restrict com campos definidos pelo usuário, os campos devem ser definidos na pasta, caso contrário, ocorrerá um erro. Não é possível executar uma operação "contém". Por exemplo, você não pode usar Find ou Restrict para procurar itens que tenham uma determinada palavra no campo assunto. Em vez disso, você pode usar o método AdvancedSearch ou você pode executar um loop em todos os itens na pasta e use a função InStr para realizar uma pesquisa dentro de um campo. Use o método Restrict para pesquisar itens que começam dentro de um determinado intervalo de caracteres. Por exemplo, para procurar todos os contatos com o último nome começando com a letra M, use este filtro:

sFilter = "[LastName] > 'LZZZ' And [LastName] < 'N'"

Confira também

Objeto Items

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.