W części drugiej swojej serii „SharePoint Framework” przedstawię Ci zestaw porad i fragmentów kodu, które pomogą Ci zacząć przygodę z SPFx. Jeżeli jeszcze nie zaznajomiłeś/aś się z częścią pierwszą „SharePoint Framework – konfiguracja” serdecznie do tego zapraszam. Znajdziesz tam kluczowe informacje dotyczące konfiguracji oraz struktury projektu.
W celu ułatwienia pracy, użyjemy bibliotek mobx oraz mobx-react. Aby zainstalować paczki, w konsoli wpisujemy npm i mobx mox-react.
W pliku NavigationWebPart.ts odnajdujemy interfejs INavigationWebPartProps i uzupełniamy go takimi samymi zmiennymi jakie podaliśmy w pliku manifest.
export interface INavigationWebPartProps { items: IItemModel[]; }
Kolejnym krokiem, który może być bardzo łatwo pominięty, a jest niezwykle ważny, jest skonfigurowanie mobx’a. Nadpisujemy funkcję onInit():
public onInit(): Promise<void> {
return super.onInit().then(_ => {
configure({ isolateGlobalState: true})
});
}
Ponieważ nie wiemy jakich web partów w przyszłości użyjemy my lub inni użytkownicy, dobrze jest zabezpieczyć nasz web part przed interferencją z innymi rozwiązaniami używającymi mobx’a. Konfiguracja isolateGlobalState zapobiegnie problemom w przyszłości.
Przygotowanie nawigacji składać się będzie z następujących części:
- Stworzenie pliku store na potrzeby użycia mobx’a,
- Utworzenie komponentów potrzebnych do wyświetlenia nawigacji,
- Dodanie nowej kontrolki do PropertyPane,
- Dodanie styli do rozwiązania.
Plik store
Tutaj przechowywać będziemy dane, na których aktualnie pracujemy oraz których zmiana powodować będzie zmianę wyświetlanej zawartości. Umieścimy tutaj dane każdego kafelka nawigacji, aktualnie wybrany kafelek oraz informację, czy web part jest w trybie edycji. Całość zostanie wsparta kilkoma operacjami na elementach nawigacji:
import { observable } from "mobx";
import IItemModel from "../model/IItemModel";
export default class NavigationStore {
constructor(items: IItemModel[]) {
if (items) {
this.items = items;
} else {
this.items = [];
}
this.currentItem = -1;
}
@observable public items: IItemModel[];
@observable public editMode: boolean;
@observable public currentItem: number;
public addItem() {
this.currentItem = this.items.push({
Title: '',
ImageUrl: '',
Section: '',
Url: ''
}) - 1;
}
public deleteItem(index: number): void {
if (index === this.currentItem) {
this.currentItem = -1;
} else {
this.currentItem = this.currentItem - 1;
}
this.items.splice(index, 1);
}
}
W kodzie użyty został dekorator @observable. Wartość zmiennej tak oznaczonej będzie obserwowana przez mobx, a po jej zmianie wszystkie obserwujące ją komponenty ponownie wykonają funkcję render().
Komponenty nawigacji
Przygotujmy teraz komponenty nawigacji. Podstawowy plik Navigation.tsx został już wygenerowany. Wystarczy go tylko oczyścić z przykładowej implementacji i zastąpić naszą własną. Zacznijmy od pliku INavigationProps.ts. Jest to interfejs, w którym deklarujemy jakie dane mogą lub muszą zostać przekazane do komponentu. W naszym wypadku ograniczymy się do klasy store:
import NavigationStore from "../../../store/NavigationStore";
export interface INavigationProps {
store: NavigationStore;
}
W pliku Navigation.tsx wystarczy nam prosty render komponentu React. Zwróć uwagę na użyte dekoratory:
- @autobind – przypisują aktualną instancję web parta do this. Dzięki temu nasz this będzie obiektem klasy Navigation nawet jeśli odwołujemy się do niego z funkcji, które będą wywołane spoza klasy Navigation, np. funkcje przekazane do eventów, filtrów, mapowań,
- @observer – dekorator, który wykona za nas całą magię i sprawi, że obiekty tak oznaczonej klasy będą reagować na zmianę wartości obserwowanych w store zmiennych. 🙂
</pre>
import * as React from 'react';
import styles from './Navigation.module.scss';
import { INavigationProps } from './INavigationProps';
import { escape } from '@microsoft/sp-lodash-subset';
import IItemModel from '../../../model/IItemModel';
import Tile from './tile/Tile';
import { observer } from 'mobx-react';
import { DefaultButton } from 'office-ui-fabric-react/lib/Button';
import { autobind } from '@uifabric/utilities';
@observer export default class Navigation extends
React.Component<INavigationProps, {}> {
@autobind private addNewTile() {
this.props.store.addItem();
}
public render(): React.ReactElement<INavigationProps> {
return <div>
<div className={styles.navigation}>
{this.renderTiles()}
{this.renderEditMode()}
</div>
}
private renderEditMode() {
return this.props.store.editMode ? <DefaultButton
primary={true}
text="Add new tile"
onClick={this.addNewTile}
/> : null;
}
@autobind private renderTile(item: IItemModel, i: number): JSX.Element {
return <Tile id={i} store={this.props.store} />;
}
private renderTiles(): JSX.Element[] {
return this.props.store.items.map(this.renderTile);
}
}
<pre>
W przedostatniej funkcji zauważyłeś pewnie element JSX nazwany Tile. To jest nasz kolejny komponent. Przekazuje do niego store oraz id po którym komponent będzie się odwoływał do konkretnego kafelka. Implementację elementów nawigacji pozostawiam już Twojej inwencji. Przedstawię Ci tylko krótką koncepcję z jakiej ja korzystam:
- Zastosowałem dekorator @observer, który zadziała tak, jak ten opisany w klasie Navigation.tsx,
- Do danych kafelka odwołuję się w niżej przedstawiony sposób:
<span
className={styles.title}>{this.props.store.items[this.props.id].Title}</span>;
Kontrolka PropertyPane
Dodanie kontrolki PropertyPane pozwoli nam w łatwy sposób edytować i tworzyć nowe elementy nawigacji z poziomu ustawień web partu. Jeżeli chcesz dowiedzieć się w jaki sposób taką kontrolkę przygotować, zachęcam Cię do zapoznania się z artykułem na stronie Microsoftu.
Style CSS
Zatrzymajmy się teraz na chwilę przy stylach CSS. Warto tworzyć je osobno dla każdego z komponentów w odpowiadających im plikach SCSS. Każdy ma swój ulubiony sposób na przygotowanie styli. Chciałbym Ci tutaj jedynie zaproponować wykorzystanie gotowych zmiennych kolorów. Dzięki temu Twój web part będzie zmieniał kolory wraz ze zmianą motywu! Oto przykład, jak zastosować zmienną koloru:
background: linear-gradient(to right, "[theme: themePrimary, default: black]", rgba(0, 0, 0, 0));
Gdy nasz kod już jest gotowy, możemy podejrzeć efekt końcowy. W tym celu przy użyciu gulp serve w konsoli uruchamiamy proces budowania i startowania rozwiązania, do których mamy wgląd w workbenchu:
https://localhost:5432/workbench
<URL Twojego site>/_layouts/15/workbench.aspx
Wykorzystanie drugiego linka pozwoli przetestować web part na danych z SharePointa. Dla przykładu – mój web part pobrał zielony kolor z ustawionego motywu:
Podsumowanie
Przedstawiłem Ci zestaw porad i fragmentów kodu, które pomogą Ci zacząć przygodę z SPFx. Zachęcam do eksperymentowania! Jeżeli natomiast masz pomysł na projekt, który chcesz wdrożyć w swoim SharePoincie, zachęcam do kontaktu.
Na koniec zostawiam kilka porad, które mogą okazać się pomocne przy pracy:
- Uważaj przy importowaniu plików. Jeżeli w folderze projektu znajdują się już zbudowane pliki, VS Code często traktuje je jako domyślny import. Wywoła to później problemy przy ponownym budowaniu projektu lub przy próbie uruchomienia go na innym środowisku. Tak więc – importując, unikaj /lib/ w ścieżkach do twoich plików.
- Jeżeli masz problemy z pobraniem paczek do projektu przy pomocy npm install, skasuj folder node_modules oraz plik package-lock.json. Możliwe, że znajdują się tam elementy, które uniemożliwiają instalację.
- Zastanów się, czy instalowana paczka pochodzi z zaufanego źródła.
- Nie przesadzaj z dodatkowymi paczkami. Staraj się importować tylko te komponenty, które są niezbędne, a Twoje rozwiązanie nie rozrośnie się do dużych rozmiarów.
Zostaw komentarz