Jak wspominać użytkowników i kanały za pomocą PubNub Chat SDK
Tags: chatsdk, typescriptsdk, chatjavascript
Published: 2023-12-21 15:50:24

Wprowadzenie do PubNub Chat SDK
-------------------------------

PubNub Chat SDK, dostępny dla aplikacji TypeScript i JavaScript, udostępnia zestaw interfejsów API zaprojektowanych w celu ułatwienia dodawania potężnych i elastycznych funkcji czatu do aplikacji przy minimalnym rozwoju. Opcje czatu, takie jak [cytowanie](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/quotes), [wzmianki o użytkownikach](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions), [odniesienia do kanałów](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references), [wątki](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/threads), [potwierdzenia odczytu](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/read-receipts) i [wskaźniki pisania](https://www.pubnub.com/docs/chat/chat-sdk/build/features/typing-indicator) są natywnie obsługiwane przez SDK, co pozwala szybko zbudować pełnoprawną aplikację.

Zapoznaj się z naszą [dokumentacją](https://www.pubnub.com/docs/chat/chat-sdk/overview) i [przykładową aplikacją czatu](https://www.pubnub.com/docs/chat/chat-sdk/build/sample-chat), aby rozpocząć korzystanie z Chat SDK. Nasz [samouczek](https://www.pubnub.com/tutorials/chat-sdk/) przeprowadzi Cię przez podstawową funkcjonalność Chat SDK i dotknie niektórych bardziej zaawansowanych funkcji, podczas gdy nasze [hostowane demo](https://www.pubnub.com/demos/chat-sdk-mobile/) pokaże Chat SDK w akcji.

Ten poradnik jest częścią **serii postów** poświęconych niektórym z bardziej zaawansowanych funkcji PubNub Chat SDK. Serię można czytać w dowolnej kolejności, ale lista powiązanych artykułów znajduje się poniżej:

-   [Jak zarządzać członkostwem w kanałach użytkowników za pomocą Chat SDK](https://pubnub.com/how-to/chat-sdk-manage-user-channel-membership/)
-   [Jak dodawać reakcje i emotikony do wiadomości za pomocą zestawu Chat SDK](https://pubnub.com/how-to/chat-sdk-add-reactions-to-messages/)
-   [Jak tworzyć wątki i cytować wiadomości za pomocą Chat SDK](https://pubnub.com/how-to/chat-sdk-create-threads-and-quote-messges/)
-   [Jak wspominać użytkowników i kanały za pomocą Chat SDK](https://pubnub.com/how-to/chat-sdk-mention-users/)

Wspominanie użytkowników i kanałów
----------------------------------

Jedną z najpotężniejszych funkcji Chat SDK jest możliwość wspominania zarówno użytkowników, jak i kanałów, zapewniając odbiorcy wiadomości pełny kontekst o tym, kto i co zostało wspomniane (lub oznaczone) i umożliwiając mu podjęcie działań. Umożliwia to na przykład odbiorcy kliknięcie oznaczonego użytkownika w celu wyświetlenia jego strony profilowej lub kliknięcie oznaczonego kanału w celu wyświetlenia tego kanału. Te interaktywne funkcje są podstawą nowoczesnej aplikacji do czatu i wymagałyby dużego wysiłku programistycznego, aby wdrożyć je od podstaw, ale są one dostarczane jako standardowa część naszego zestawu Chat SDK.

Dokumentacja opisuje to jako [Wspominanie użytkowników](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions) i [odwoływanie się do kanałów](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references). Zawiera wszystkie niezbędne szczegóły, ale osobiście potrzebowałem zobaczyć działające demo tej funkcji, zanim zrozumiałem ją poprawnie.

Poniższe krótkie demo zostało zaprojektowane jako samodzielne i pokazuje tylko, jak działa wspominanie użytkowników i kanałów; żadne wiadomości nie są wysyłane przez PubNub, a "podgląd" jest renderowany lokalnie. Ma to na celu skupienie się na kluczowych funkcjach.

Spróbuj wpisać wiadomość i zauważ, że za każdym razem, gdy wpiszesz "@", a następnie pierwsze trzy litery jednego z testowych użytkowników, zostaniesz poproszony o "dodanie" tego użytkownika do wiadomości. Po dodaniu użytkownika, podgląd demo pokaże go jako hiperłącze (link nigdzie nie prowadzi i możesz renderować oznaczonego użytkownika w dowolny sposób we własnej aplikacji; nie jesteś ograniczony do hiperłączy). Użyj klawiszy strzałek, aby poruszać się po polu tekstowym; po wpisaniu karetki w oznaczonego użytkownika otrzymasz opcję "usunięcia" tego użytkownika z wiadomości.

Spróbuj również wpisać "#", a następnie pierwsze trzy litery jednego z kanałów testowych (wielkość liter nie ma znaczenia), co daje opcję "dodania" kanału do wiadomości. Dodane kanały są renderowane pogrubioną czcionką, ale podobnie jak użytkownicy, możesz renderować kanał w dowolny sposób.

Na koniec spróbuj wpisać hiperłącze i zauważ, że jest ono renderowane jako klikalny link u odbiorcy - podstawowa funkcjonalność tego została zapewniona automatycznie przez Chat SDK.

Interaktywne demo
-----------------

  
**Jeśli osadzona zawartość nie jest dostępna** na tej stronie, można ją również wyświetlić pod adresem [https://chat-sdk-how-to-mentions.netlify.app/](https://chat-sdk-how-to-mentions.netlify.app/).

Kod, który napędza to demo, jest dostępny na [GitHub](https://github.com/PubNubDevelopers/Chat-SDK-How-Tos/tree/main/mentions), ale w pozostałej części tego artykułu opiszemy, jak zostało ono zbudowane.

### Wymagania wstępne

Upewnij się, że masz instancję [obiektu Chat](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/chat) w swojej aplikacji

```js
const chat = await Chat.init({
  publishKey: "YOUR_PUBLISH_KEY",
  subscribeKey: "YOUR_SUBSCRIBE_KEY",
  userId: "YOUR_USER_ID",
})
```

Istnieje wiele możliwych parametrów, które można przekazać do Chat SDK, ale aby wspomnieć o użytkownikach i kanałach, nie potrzebujesz niczego więcej niż standardowy klucz publikowania, klucz subskrypcji i identyfikator użytkownika. Jeśli wszystko to jest dla ciebie nowe i nie wiesz, od czego zacząć, zapoznaj się z sekcją [wstępnej konfiguracji](https://www.pubnub.com/docs/chat/chat-sdk/build/configuration) w naszej dokumentacji.

### Wspominanie użytkowników

Dokumentacja dotycząca wspominania [użytkowników](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions) odwołuje się do [MessageDraft](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message-draft) w prawie każdym przykładzie i metodzie, dlatego ważne jest, aby zrozumieć cel MessageDraft. MessageDraft jest podstawowym typem w Chat SDK, który umożliwia dostarczanie kontekstu do wiadomości - przykłady kontekstu obejmują wszelkie pliki zawarte w wiadomościach, wszelkie inne wiadomości, które zostały [zacytowane](https://pubnub.com/how-to/chat-sdk-create-threads-and-quote-messges/), oraz wszelkich użytkowników lub kanałów oznaczonych w wiadomości. Dostarczanie kontekstu do wiadomości pozwala na bogate w funkcje doświadczenie dla użytkowników, a mechanizm MessageDraft pozwala Chat SDK na dostarczenie wszystkich informacji potrzebnych aplikacji do zbudowania angażującego doświadczenia użytkownika.

Po pierwsze, za każdym razem, gdy tworzysz nową wiadomość, tj. podczas inicjalizacji aplikacji i po wysłaniu dowolnej wiadomości, musisz utworzyć nowy obiekt MessageDraft. Możesz wybrać, czy użytkownicy będą sugerowani "globalnie", czy tylko od tych użytkowników, którzy są [członkami](https://pubnub.com/how-to/chat-sdk-manage-user-channel-membership/) "kanału

```js
setNewMessageDraft(channel.createMessageDraft({ userSuggestionSource: "channel"}))
```

Po utworzeniu obiektu MessageDraft musimy dostarczyć mu wszelkie znaki, które użytkownik wpisze w swojej wiadomości; odbywa się to poprzez wywołanie funkcji [MessageDraft.onChange()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#track-mentions) za każdym razem, gdy zmieni się wpisany tekst. Poniższy kod jest przykładem funkcji onChange() dla pola <input>

```js
async function handleInput(event: React.FormEvent<HTMLInputElement>)
{
  if (!newMessageDraft) return
  const response = await newMessageDraft.onChange(event.currentTarget.value)
  if (response.users.suggestedUsers?.length > 0)
  {
    setSuggestedUsers(response.users.suggestedUsers)
    setNameOccurrenceIndex(response.users.nameOccurrenceIndex)
  }
  else
  {
    setSuggestedUsers([])
    setNameOccurrenceIndex(-1)
  }
  … //  Also handle channels (omitted for brevity)
  setRenderedMessage(newMessageDraft.getMessagePreview())
}
```

W tym programie obsługi zmian wiele się dzieje, więc podzielmy go na części:

Linia:

```js
const response = await newMessageDraft.onChange(event.currentTarget.value)
```

Zostanie wywołana za każdym razem, gdy zmieni się tekst wejściowy i zwróci tablicę sugerowanych [użytkowników](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user), jeśli istnieją odpowiednie sugestie (tj. jeśli wpisałeś "@Mar", zasugeruje "Marian", "Mary" itp.) Jeśli istnieją sugerowani [użytkownicy](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user), chcemy pokazać je użytkownikowi aplikacji i śledzić "nameOccurrenceIndex" powiązany z tymi sugestiami. "nameOccurrenceIndex" będzie zwiększany za każdym razem, gdy użytkownik wpisze znak "@" i jest używany przez Chat SDK do określenia, które sugestie są tworzone.

Gdy użytkownik aplikacji wybierze sugerowanego użytkownika, wywoływany jest następujący kod:

```js
async function pickSuggestedUser(user:User) 
{
  if (!newMessageDraft) return

  newMessageDraft.addMentionedUser(
    user,
    nameOccurrenceIndex
  )

  setText(newMessageDraft.value)
  setRenderedMessage(newMessageDraft.getMessagePreview())
  setSuggestedUsers([])
  setNameOccurrenceIndex(-1)
  inputRef.current?.focus()
}
```

Ważne jest tutaj wywołanie [messageDraft.addMentionedUser()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#add-mentioned-user), które poinformuje Chat SDK, który [użytkownik](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user) jest reprezentowany przez określony symbol "@

Należy również zwrócić uwagę na wywołanie setText(newMessageDraft.value); spowoduje to aktualizację pola wejściowego w celu odzwierciedlenia wybranego użytkownika i jest wymagane, aby wszystko działało niezawodnie i było intuicyjne dla użytkownika.

A co z usuwaniem użytkownika? Aplikacja demonstracyjna będzie śledzić, gdzie znajduje się kursor w polu wejściowym i korzystać z interfejsu API Chat SDK [getHighlightedMention()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#show-user-details-on-highlighting), aby zwrócić, które dane użytkownika są obecnie podświetlone. Jeśli użytkownik jest podświetlony, użytkownik aplikacji ma możliwość usunięcia tego użytkownika, co odbywa się poprzez wywołanie funkcji API [removeMentionedUser()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#show-user-details-on-highlighting)

Chociaż to demo renderuje tylko podgląd wiadomości za pomocą [getMessagePreview()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#show-linked-mention-preview), w produkcji należy również wywołać [send()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#send-message-with-mentions) na obiekcie MessageDraft, aby przekazać go odbiorcy.

### Odwoływanie się do kanałów

Podczas odwoływania się do kanałów stosowane są dokładnie te same zasady, co w przypadku odwoływania się do użytkowników, przy czym zmieniają się tylko nazwy metod i parametry. Powinieneś użyć tej samej instancji obiektu MessageDraft, aby wspomnieć zarówno o [kanałach](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/channel), jak i [użytkownikach](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user).

Aby powrócić do obsługi onChange() pola <input>, kod będzie wyglądał następująco:

```js
async function handleInput(event: React.FormEvent<HTMLInputElement>)
{
  if (!newMessageDraft) return
  const response = await newMessageDraft.onChange(event.currentTarget.value)
  … //  Also handle users (omitted for brevity)
  if (response.channels.suggestedChannels?.length > 0)
  {
    setSuggestedChannels(response.channels.suggestedChannels)
    setLastAffectedChannelOccurrenceIndex(response.channels.channelOccurrenceIndex)
  }
  else
  {
    setSuggestedChannels([])
    setLastAffectedChannelOccurrenceIndex(-1)
  }
  setRenderedMessage(newMessageDraft.getMessagePreview())
}
```

Gdy użytkownik aplikacji wybierze sugerowany kanał, wywoływany jest następujący kod:

```js
async function pickSuggestedChannel(channel:Channel)
{
  if (!newMessageDraft) return
  newMessageDraft.addReferencedChannel(channel, lastAffectedChannelOccurrenceIndex)
  setText(newMessageDraft.value)
  setRenderedMessage(newMessageDraft.getMessagePreview())
  setSuggestedChannels([])
  setLastAffectedChannelOccurrenceIndex(-1)
  inputRef.current?.focus()
}
```

Ważne jest tutaj wywołanie [messageDraft.addReferencedChannel()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references#add-referenced-channel), które powie Chat SDK, który [kanał](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/channel) jest reprezentowany przez określony symbol "#".

Podobnie jak w przypadku wybierania użytkowników, wywołanie setText(newMessageDraft.value) zaktualizuje pole wejściowe, aby odzwierciedlić wybrany kanał i jest wymagane, aby wszystko działało niezawodnie i było intuicyjne dla użytkownika.

Chociaż to demo tego nie obsługuje, Chat SDK obsługuje również usuwanie odniesień do kanałów i inne możliwości. Pełna lista funkcji znajduje się w [dokumentacji Channel](https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/references) References.

### Renderowanie wspomnianych użytkowników i kanałów

[Dokumentacja](https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/mentions#show-mention-as-link) opisuje pewną logikę renderowania wiadomości, ale znalazłem najbardziej elegancki przykład dostarczony przez [aplikację startową Chat SDK](https://github.com/pubnub/js-chat/blob/master/samples/getting-started/src/App.tsx), więc zasadniczo skopiowałem ją do tego demo. Chat SDK umożliwia dostęp do różnych "części" wiadomości, które są dostępne jako typy "[MixedTextTypedElement](https://github.com/pubnub/js-chat/blob/71eac822097d798e6eccfe896760ce230bbe076f/lib/src/types.ts#L165)" i dostępne za pośrednictwem metody [message.getLinkedText()](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/links#render-urls).

Demo określa React useCallback, aby określić sposób renderowania każdej z tych "części":

```js
const renderMessagePart = useCallback((messagePart: MixedTextTypedElement) => {
  if (messagePart.type === "text") {
    return messagePart.content.text
  }
  if (messagePart.type === "plainLink") {
    return <a href={messagePart.content.link}>{messagePart.content.link}</a>
  }
  if (messagePart.type === "textLink") {
    return <a href={messagePart.content.link}>{messagePart.content.text}</a>
  }
  if (messagePart.type === "mention") {
    return <span><a href={`https://pubnub.com/users/${messagePart.content.id}`}>{messagePart.content.name}</a> </span>
  }
  if (messagePart.type === "channelReference") {
    return <b>#{messagePart.content.name} </b>
  }
  return ""
}, [])
```

Renderowanie demo jest uproszczone: hiperłącza są konwertowane na klikalne linki, wzmianki użytkownika są również przekształcane w klikalne linki (choć nie wskazują one na rzeczywiste adresy URL), a odniesienia do kanałów są pogrubione.

Demo: Wzmianki o użytkownikach i kanałach w naszym demo React Native na urządzenia mobilne
------------------------------------------------------------------------------------------

Możesz grać z tymi funkcjami za pomocą naszego Chat SDK Demo for Mobile, dostępnego jako [hostowane demo](https://www.pubnub.com/demos/chat-sdk-mobile/) z pełnym kodem źródłowym na [GitHub](https://github.com/pubnub/js-chat/tree/master/samples/react-native-group-chat). **Powinieneś także zobaczyć demo renderowane w iFrame na dole tej sekcji**.

![Two smartphones displaying chat application interfaces with user messages and mentions within a testing group.](https://images.ctfassets.net/3prze68gbwl1/5p6UMdZQNzoyPvIbioQa21/66a58f4e10ae33d3d19a9b3e6d3d1b3e/mentions.png)

-   Zaloguj się do aplikacji, wybierając losowy identyfikator użytkownika dla każdego urządzenia. Zanotuj w pamięci identyfikatory użytkowników
-   Rozpocznij rozmowę z drugiego urządzenia, wybierając użytkownika zalogowanego na pierwszym urządzeniu.
-   Wpisz "@", a następnie pierwsze trzy znaki jednego z identyfikatorów użytkowników, jako których się zalogowałeś. Wybierz użytkownika z prezentowanej listy rozwijanej.

![Smartphone messaging interface with a composed message addressing a user by their username.](https://images.ctfassets.net/3prze68gbwl1/2uPEzYJ9TmzC6VXtOcWIG2/6626f33acdb69a5a24872a7cb8a75b6a/mentions1.png)

-   Zauważ, że otrzymana wiadomość wyświetli nazwę użytkownika jako hiperłącze.
-   Przejdź do zakładki "Wzmianki" dla wspomnianego użytkownika i zwróć uwagę, jak wyświetlana jest wiadomość, która wspomina o tym użytkowniku.

![Smartphone displaying a welcome message in the mentions tab on a social media app.](https://images.ctfassets.net/3prze68gbwl1/3upUA7IAUUlnV5J9LheP6/09d54150d4963e3b8a03367e25da70ea/mentions2.png)

-   Możesz również wpisać adres URL w wiadomości w aplikacji demonstracyjnej, aby wyświetlić go jako hiperłącze, np. [http://www.pubnub.com](http://www.pubnub.com).

  
**Jeśli osadzona zawartość nie jest dostępna** na tej stronie, można ją również wyświetlić pod adresem [https://pubnubdevelopers.github.io/Chat-SDK-Demo/mobile/](https://pubnubdevelopers.github.io/Chat-SDK-Demo/mobile/).

Jak PubNub może ci pomóc?
=========================

Ten artykuł został pierwotnie opublikowany na [PubNub.com](https://pubnub.com/how-to/chat-sdk-mention-users/)

Nasza platforma pomaga programistom tworzyć, dostarczać i zarządzać interaktywnością w czasie rzeczywistym dla aplikacji internetowych, aplikacji mobilnych i urządzeń IoT.

Podstawą naszej platformy jest największa w branży i najbardziej skalowalna sieć komunikacyjna w czasie rzeczywistym. Dzięki ponad 15 punktom obecności na całym świecie obsługującym 800 milionów aktywnych użytkowników miesięcznie i niezawodności na poziomie 99,999%, nigdy nie będziesz musiał martwić się o przestoje, limity współbieżności lub jakiekolwiek opóźnienia spowodowane skokami ruchu.

Poznaj PubNub
-------------

Sprawdź [Live Tour](https://www.pubnub.com/tour/introduction/), aby zrozumieć podstawowe koncepcje każdej aplikacji opartej na PubNub w mniej niż 5 minut.

Rozpocznij konfigurację
-----------------------

Załóż [konto](https://admin.pubnub.com/signup/) PubNub, aby uzyskać natychmiastowy i bezpłatny dostęp do kluczy PubNub.

Rozpocznij
----------

[Dokumenty](https://www.pubnub.com/docs) PubNub pozwolą Ci rozpocząć pracę, niezależnie od przypadku użycia lub [zestawu SDK](https://www.pubnub.com/docs).