Utilisation de CSS pour personnaliser des pages SharePoint
Le langage CSS (« Cascading style sheet », « Feuilles de style en cascade ») joue un rôle important dans la personnalisation de SharePoint. Pour bien personnaliser la conception du site dans SharePoint et SharePoint Online, nous vous recommandons de comprendre la façon dont SharePoint utilise le CSS.
Importante
Cette option d’extensibilité est disponible uniquement pour des expériences SharePoint classiques. Vous ne pouvez pas l’utiliser avec des expériences modernes dans SharePoint Online, telles que des sites de communication. Notez également que vous ne devez pas prendre une dépendance sur la structure de la page html ou sur les noms de style CSS inhabituels comme ceux-ci peuvent être modifiés sans un avertissement.
Présentation de la personnalisation CSS
Lorsque vous créez une collection de sites SharePoint, SharePoint crée une galerie de pages maîtres (_catalogs/masterpage) où la plupart des éléments de personnalisation, notamment les fichiers .master, .css, image, HTML et JavaScript sont stockés.
SharePoint utilise la page seattle.master par défaut pour les sites d’équipe, les sites de publication et les sites d’équipe où l’option de publication est activée. Il utilise mysite15.master pour les sites OneDrive Entreprise. Chaque fichier .master fait référence au fichier corev15.css, qui est créé à partir d’une variété de fichiers .css livrés prêts à l’emploi avec SharePoint.
Toutes les pages maîtres par défaut utilisent corev15.css lors du traitement des styles et utilisent les fonctionnalités de cascade et de partage de fichier CSS pour déterminer les styles qui sont appliqués aux contrôles et éléments spécifiques dans les régions d’une page. Plusieurs fichiers CSS sont également combinés pour générer le fichier oslo.css, qui est utilisé avec la page maître oslo.master.
CSS dans les pages maîtres
L’espace réservé de contenu <SharePoint:CssRegistration>, qui correspond à la classe WebControls.CssRegistration dans le modèle objet côté serveur, définit le fichier CSS. Comme une référence pointant vers une page maître, SharePoint remplace les jetons de la page maître lors du traitement de la page. La classe WebControls.CssLink lit l’enregistrement à partir de la page maître et insère une balise <link> dans le fichier HTML généré.
Prenons l’exemple suivant.
<SharePoint:CssRegistration name="<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/contoso.css%>" runat="server"/>
Lors de l’exécution, ce code est rendu comme suit.
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/Core%20Styles/contoso.css">
La classe CSSLink restitue toutes les feuilles de style lors du rendu de la page. Si vous définissez des styles dans un fichier .css personnalisé qui sont également définis dans corev15.css, ils sont remplacés.
Fichier Corev15.CSS
De nombreuses feuilles CSS sont appliquées à SharePoint par défaut. Le fichier corev15.css est la principale source des styles dans SharePoint. Ce fichier est stocké dans le dossier SharePoint 15 du serveur, sur \TEMPLATE\LAYOUTS\1033\STYLES\Themable\COREV15.CSS et non pas dans la galerie de pages maîtres du site racine et de la page d’accueil.
Pour découvrir comment SharePoint utilise les feuilles CSS prêtes à l’emploi, recherchez le fichier corev15.css en utilisant les outils de développement dans votre navigateur web. Dans Internet Explorer, utilisez la barre d’outils développeur (en appuyant sur F12) et sélectionnez l’onglet CSS pour afficher corev15.css.
Les styles définis dans le fichier corev15.css utilisent les préfixes .ms- et .s4-, qui indiquent les styles créés par Microsoft. Le fichier corev15.css utilise également un grand nombre de sélecteurs enfants et descendants.
Lorsque vous visualisez le fichier, vous découvrez de nombreux commentaires au format suivant : /* [ReplaceFont ( themeFont:"body")] */. SharePoint lit ces commentaires lorsqu’une présentation composée est appliquée. Les commentaires indiquent à SharePoint de modifier l’attribut de la feuille de style CSS suivant immédiatement chaque commentaire. L’application d’une présentation composée peut modifier la plupart des couleurs, des polices et des images d’arrière-plan appliquées par défaut, et donc mettre à jour les paramètres de corev15.css.
Remarque
La sélection du fichier corev15.css de cette manière charge la feuille de style CSS rendue, plutôt que celle enregistrée. Parfois, des différences peuvent survenir entre les deux. Les agents utilisateurs tels que les navigateurs peuvent également modifier le rendu selon les actions de l’utilisateur.
Avertissement
Ne vous connectez pas au serveur pour modifier ou personnaliser les principaux fichiers CSS SharePoint dans la racine de SharePoint. Cela aura une incidence négative sur la prise en charge et la mise à niveau. Ne modifiez jamais corev15.css directement. Au lieu de cela, créez toujours une copie, renommez-la, puis modifiez le nouveau fichier. La modification de corev15.css appliquera la moindre personnalisation à toutes les applications web du serveur.
Procédure de création d’une feuille de style personnalisée pour SharePoint
Effectuez une copie de corev15.css et nommez-la contosov15.css.
Ouvrez la page de masque correspondante (dans cet exemple, contoso.masterpage) et modifiez la ligne CssRegistration de sorte qu’elle pointe vers contosov15.css à partir de corev15.css, comme illustré dans l’exemple suivant.
<SharePoint:CssRegistration Name="Themable/contoso.css" runat="server" />
- Sous la ligne CssRegistration, ajoutez les informations suivantes :
<SharePoint:CssRegistration name="/_catalogs/masterpage/contoso/contoso.css"
runat="server">
Présentations composées lors de la personnalisation
Vous pouvez utiliser des présentations composées lors de la personnalisation lorsque le fichier CSS est appelé à partir d’une page maître. Le fichier CSS est stocké dans l’un des emplacements suivants du système de fichiers SharePoint :
15\TEMPLATE\LAYOUTS\{LCID}\STYLES\Themable/Style Library/Themable//Style Library/{culture}/Themable/
Vous pouvez placer des fichiers de personnalisation personnalisés dans /Style Library/Themable/ et /Style Library/{culture}/Themable/, mais 15\TEMPLATE\LAYOUTS\{LCID}\STYLES\Themable n’est pas modifiable. Vous ne pouvez donc pas stocker de fichiers personnalisés à cet emplacement.
Remarque
Si ces emplacements n’existent pas par défaut, vous pouvez les créer manuellement et SharePoint détecte la possibilité de modifier leur thème.
Application de fichiers CSS personnalisés à une page SharePoint
Vous pouvez ajouter des fichiers CSS personnalisés aux champs de texte enrichis et aux zones de composant WebPart. Pour ajouter des fichiers CSS à un champ de texte enrichi, ouvrez la page en mode Édition, puis sélectionnez Insertion>Code incorporé à partir du ruban. Pour les zones de composant WebPart, utilisez le composant WebPart d’éditeur de scripts pour ajouter du code HTML, des scripts ou une feuille de style interne. Vous pouvez utiliser cette méthode pour masquer la barre de lancement rapide dans l’interface utilisateur par défaut de SharePoint. Si vous utilisez SharePoint Online et la fonction NoScript, NoScript désactive le composant WebPart d’éditeur de scripts.
Appliquez le fichier CSS à un site SharePoint en utilisant une feuille de style externe et en incluant une référence pointant vers la feuille de style dans la balise <link> dans les balises <head> de la page SharePoint.
L’exemple de code suivant illustre une méthode pour charger un fichier CSS personnalisé dans la bibliothèque de composants, appliquer une référence à l’URL CSS à l’aide d’une action personnalisée, puis créer une action personnalisée en vue de créer un lien menant vers le nouveau fichier CSS. Ce code fait partie de l’exemple Branding.AlternateCSSAndSiteLogo sur GitHub.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using Microsoft.SharePoint.Client;
using Microsoft.SharePoint.Client.EventReceivers;
namespace AlternateCSSAppAutohostedWeb.Services
{
public class AppEventReceiver : IRemoteEventService
{
public SPRemoteEventResult ProcessEvent(SPRemoteEventProperties properties)
{
SPRemoteEventResult result = new SPRemoteEventResult();
try
{
using (ClientContext clientContext = TokenHelper.CreateAppEventClientContext(properties, false))
{
if (clientContext != null)
{
Web hostWebObj = clientContext.Web;
List assetLibrary = hostWebObj.Lists.GetByTitle("Site Assets");
clientContext.Load(assetLibrary, l => l.RootFolder);
// First, upload the CSS files to the Asset library.
DirectoryInfo themeDir = new DirectoryInfo(System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath + "CSS");
foreach (var themeFile in themeDir.EnumerateFiles())
{
FileCreationInformation newFile = new FileCreationInformation();
newFile.Content = System.IO.File.ReadAllBytes(themeFile.FullName);
newFile.Url = themeFile.Name;
newFile.Overwrite = true;
Microsoft.SharePoint.Client.File uploadAsset = assetLibrary.RootFolder.Files.Add(newFile);
clientContext.Load(uploadAsset);
break;
}
string actionName = "SampleCSSLink";
// Now, apply a reference to the CSS URL via a custom action.
// Clean up existing actions that you might have deployed.
var existingActions = hostWebObj.UserCustomActions;
clientContext.Load(existingActions);
// Run uploads and initialize the existing Actions collection.
clientContext.ExecuteQuery();
// Clean up existing actions.
foreach (var existingAction in existingActions)
{
if(existingAction.Name.Equals(actionName, StringComparison.InvariantCultureIgnoreCase))
existingAction.DeleteObject();
}
clientContext.ExecuteQuery();
// Build a custom action to write a link to our new CSS file.
UserCustomAction cssAction = hostWebObj.UserCustomActions.Add();
cssAction.Location = "ScriptLink";
cssAction.Sequence = 100;
cssAction.ScriptBlock = @"document.write('<link rel=""stylesheet"" href=""" + assetLibrary.RootFolder.ServerRelativeUrl + @"/cs-style.css"" />');";
cssAction.Name = actionName;
// Apply.
cssAction.Update();
clientContext.ExecuteQuery();
}
result.Status = SPRemoteEventServiceStatus.Continue;
return result;
}
}
catch (Exception ex)
{
result.Status = SPRemoteEventServiceStatus.CancelWithError;
result.ErrorMessage = ex.Message;
return result;
}
}
public void ProcessOneWayEvent(SPRemoteEventProperties properties)
{
// This method is not used by app events.
}
}
}