Tworzenie aplikacji dla workdocs z użyciem funkcji akcji dokumentu pozwala tworzyć nowe narzędzia do współpracy dla użytkowników monday, takie jak narzędzia do sprawdzania tekstu i generowania pomysłów.

W tym przewodniku utworzymy prostą aplikację z akcją dokumentu, która automatycznie zamienia zaznaczony fragment dokumentu na wielkie litery.

Zbuduj swoją pierwszą aplikację

Pobierz przykładowy kod

Pobierz przykładowy kod z repozytorium monday na GitHubie. Możesz pobrać plik ZIP z serwisu GitHub albo użyć polecenia git clone:

$ git clone https://github.com/mondaycom/welcome-apps.git

Zainstaluj ngrok

W tym przykładzie używamy usługi ngrok, która bezpiecznie łączy Twoje lokalne środowisko z internetem. Aby z niej skorzystać, utwórz bezpłatne konto i zainstaluj oprogramowanie.

Jeśli korzystasz już z ngrok, pomiń ten krok.

1. Pobierz i zainstaluj oprogramowanie ze strony ngrok
2. Utwórz konto ngrok
3. Pobierz swój token autoryzacyjny ze strony konta
4. Dodaj token autoryzacyjny do lokalnej instalacji, uruchamiając polecenie ngrok config add-authtoken <token>

Uruchom aplikację lokalnie

Gdy masz już przykładowy kod i skonfigurowany ngrok, możesz uruchomić aplikację.

Otwórz folder welcome apps w wybranym terminalu i przejdź do folderu apps/quickstart-workdocs.

$ cd apps/quickstart-workdocs

Zainstaluj zależności za pomocą npm.

$ npm install --loglevel error

Uruchom kod.

$ npm run start

Przejdź do panelu ngrok pod adresem localhost:4040 i skopiuj stamtąd adres URL tunelu. Użyj adresu zaczynającego się od https://.

Utwórz funkcję akcji dokumentu

Następnie dodaj funkcję akcji dokumentu do istniejącej aplikacji i połącz ją z adresem URL tunelu z poprzedniego kroku.

1. Kliknij przycisk Dodaj funkcję (Add feature) w menu po lewej stronie aplikacji.
2. W oknie modalnym wybierz Akcja dokumentu (Doc Action).
3. Na stronie Szczegóły funkcji (Feature Details) zaznacz pole Pasek narzędzi kontekstowy (Contextual Toolbar) w sekcji Obsługiwane lokalizacje (Supported Locations).
4. Kliknij Zapisz funkcję (Save Feature).
5. Po zapisaniu funkcji kliknij przycisk Nowa kompilacja (New Build) po prawej stronie ekranu.
6. W polu Niestandardowy URL (Custom URL) wklej adres URL tunelu z poprzedniego kroku.
7. Kliknij Utwórz kompilację (Create build), aby zapisać adres URL.

Użyj aplikacji w monday workdoc

Możesz teraz dodać aplikację do dokumentu i ją przetestować.

1. Utwórz nowy workdoc za pomocą menu Dodaj (Add) w lewym górnym rogu obszaru roboczego. Jeśli jeszcze nie tworzono przez Ciebie workdoca, przed przejściem dalej przeczytaj ten artykuł.
2. Wpisz tekst w dokumencie.
3. Zaznacz tekst. Pojawi się menu kontekstowe.
4. W menu kontekstowym wybierz ikonę puzzla Aplikacje (Apps).
5. Otworzy się menu rozwijane, w którym możesz wybrać funkcję aplikacji z listy. Pojawi się okno modalne z osadzoną aplikacją.
6. Kliknij przycisk Zamień na wielkie litery (Capitalize).
7. Zaznaczony tekst zostanie zamieniony na wielkie litery.

Dlaczego to działa

Po uruchomieniu przykładowego kodu możesz sprawdzić kod i konfigurację aplikacji, aby zrozumieć, dlaczego działa w ten sposób.

Poniżej omówiliśmy kilka podstawowych zasad, które wyjaśniają działanie aplikacji i pomogą Ci wykorzystać je we własnych aplikacjach.

Wybierz lokalizację aplikacji

Ponieważ nasza aplikacja edytuje istniejący tekst, wybraliśmy lokalizację paska narzędzi kontekstowego. Dzięki temu aplikacja pojawia się tylko wtedy, gdy ktoś zaznaczy treść w workdocu.

Jeśli aplikacja tworzy nową treść w workdocu, zamiast ją aktualizować, zalecamy umieszczenie jej w menu dodawania bloku. Jeśli aplikacja umożliwia oba te działania, możesz dodać ją w obu lokalizacjach.

Korzystanie z obiektu context

W przykładowej aplikacji korzystamy z obiektu context, który zawiera informacje o kontekście aplikacji. Możesz pobrać ten obiekt za pomocą metod SDK monday.get lub monday.listen.

W wierszu 20 używamy metody monday.get(), aby pobrać bieżący kontekst. Następnie korzystamy z atrybutów focusedBlocks i range, aby określić, którą treść zaktualizować.

W tym przykładzie używamy tylko dwóch pól z kontekstu. Pełny obiekt kontekstu zawiera znacznie więcej przydatnych informacji, takich jak identyfikator bieżącego dokumentu, aktualnie zaznaczone bloki oraz to, czy aplikację uruchomiono z paska narzędzi, czy z menu dodawania bloku. Pełną strukturę obiektu kontekstu możesz sprawdzić [tutaj].

Aktualizowanie treści dokumentu za pomocą monday.updateBlock()

Aktualizujemy treść dokumentu za pomocą metody SDK monday.updateBlock() bez konieczności uwierzytelniania ani tworzenia zapytania GraphQL. W aplikacjach po stronie klienta zalecamy korzystanie z metod addBlock, addMultiBlocks i updateBlock. Nasze API GraphQL umożliwia dodawanie bloków, ale metody SDK są znacznie prostsze w użyciu.

Korzystanie z biblioteki Delta

Treść każdego bloku jest określona w formacie Delta - specyfikacji opracowanej przez Quill. Aplikacja używa biblioteki quill-delta do modyfikowania treści bloków zamiast robić to ręcznie. Zalecamy używanie tej biblioteki, aby uniknąć błędów walidacji treści.

Format Delta to zwykła tablica obiektów, więc możesz chcieć modyfikować treść w tym formacie bez użycia biblioteki. Nie zalecamy tego, ponieważ nieprawidłowa struktura treści spowoduje błędy walidacji.

📘 Dołącz do naszej społeczności programistów!

Stworzyliśmy społeczność przeznaczoną dla naszych programistów. Możesz przeszukiwać wcześniejsze wątki, aby znaleźć rozwiązania, zadawać pytania, poznawać nowe funkcje i aktualizacje oraz korzystać ze wskazówek i porad innych programistów. Dołącz do nas! 😎