Поделиться через

Переход с JSLink на расширения SharePoint Framework

  • Статья

Начиная с Microsoft SharePoint 2013, в большинстве корпоративных решений, основанных на Microsoft 365 и SharePoint Online, для настройки полей использовалось свойство JSLink полей и представлений списков.

В "современном" пользовательском интерфейсе SharePoint Online и SharePoint Server 2019 большинство таких настроек больше не доступно. Расширения SharePoint Framework позволяют предоставлять аналогичные функции в "современном" пользовательском интерфейсе.

Из данного руководства вы узнаете, как перейти со старых ("классических") настроек на новую модель на основе расширений SharePoint Framework.

Примечание.

Дополнительные сведения о создании расширений SharePoint Framework см. в статье Обзор расширений SharePoint Framework.

Сначала рассмотрим доступные разработчикам варианты для создания расширений SharePoint Framework.

  • Настройщик приложений. Расширьте встроенный "современный" пользовательский интерфейс SharePoint, добавив пользовательские элементы HTML и клиентский код в заранее определенные заполнители на "современных" страницах. Дополнительные сведения о настройщиках приложений см. в разделе Создание первого расширения SharePoint Framework (Hello World, часть 1)
  • Набор команд. добавляет пользовательские пункты меню ECB и настраиваемые кнопки на панель команд или в представление списка или библиотеки. С этими командами можно связать любое действие на стороне клиента. Дополнительные сведения о наборах команд см. в разделе Создание первого расширения набора команд ListView.
  • Настройщик полей. Настройте отображение поля в представлении списка, используя настраиваемые элементы HTML и клиентский код. Дополнительные сведения о настройщиках полей см. в разделе Создание первого расширения настройщика полей.

Наиболее полезное в нашем контексте расширение — настройщик заполнителей.

Предположим, используется среда SharePoint Online, в которой есть настраиваемый список с настраиваемым полем Color, относящимся к типу Choice и принимающим следующие значения: Red, Green, Blue, Yellow. Допустим, что у вас есть собственное значение для свойства JSLink веб-части представления списка.

Ниже представлен фрагмент кода JavaScript, на который ссылается свойство JSLink (customColorRendering.js).

// Define a namespace for the custom rendering code
var customJSLinkRendering = customJSLinkRendering || {};

// Define a function that declare the custom rendering rules for the target list view
customJSLinkRendering.CustomizeFieldRendering = function () {

  // Define a custom object to configure the rendering template overrides
  var customRenderingOverride = {};
  customRenderingOverride.Templates = {};
  customRenderingOverride.Templates.Fields =
  {
    // Declare the custom rendering function for the 'View' of field 'Color'
    'Color':
    {
      'View': customJSLinkRendering.RenderColorField
    }
  };

  // Register the custom rendering template
  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
};

// Declare the custom rendering function for the 'View' of field 'Color'
customJSLinkRendering.RenderColorField = function (context)
{
  var colorField = context.CurrentItem.Color;

  // Declare a local variable to hold the output color
  var color = '';

  // Evaluate the values of the 'Color' field and render it accordingly
  switch (colorField)
  {
    case 'Red':
      color = 'red';
      break;
    case 'Green':
      color = 'green';
      break;
    case 'Blue':
      color = 'blue';
      break;
    case 'Yellow':
      color = 'yellow';
      break;
    default:
      color = 'white';
      break;
  }

  // Render the output for the 'Color' field
  return "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
};

// Invoke the custom rendering function
customJSLinkRendering.CustomizeFieldRendering();

На приведенном ниже снимке экрана показано, как настраивается свойство JSLink в веб-части представления списка.

Настройка свойства JSLink в веб-части представления списка

Если вы отправили файл JavaScript в библиотеку Активы сайта, то для свойства JSLink может быть задано значение "~site/SiteAssets/customColorRendering.js".

Ниже показано, как теперь отрисовывается список.

Особая отрисовка поля Color настраиваемого списка

Как видите, в полях Color отображается квадрат, заполненный цветом, выбранным на уровне элемента.

Примечание.

Чтобы подготовить такое решение на "классическом" сайте, можно воспользоваться шаблоном подготовки PnP, который может одновременно подготовить список с настраиваемым полем и свойством JSLink.

Ниже описано, как перенести старое решение в SharePoint Framework.

Создание решения SharePoint Framework

  1. С помощью консоли создайте папку для проекта:

    md spfx-custom-field-extension

  2. Перейдите в папку проекта:

    cd spfx-custom-field-extension

  3. В папке проекта запустите генератор Yeoman для SharePoint Framework, чтобы сформировать шаблон проекта на платформе SharePoint Framework:

    yo @microsoft/sharepoint

  4. При появлении запроса введите следующие значения (выберите вариант по умолчанию для всех запросов, не перечисленных ниже).

    • Как называется ваше решение?: spfx-custom-field-extension
    • Какой тип клиентского компонента нужно создать?: Расширение
    • Какой тип клиентского расширения нужно создать? Настройщик полей
    • Как называется настройщик полей? CustomColorField
    • Какой шаблон вы хотите использовать?: Платформа JavaScript отсутствует

  5. Запустите Visual Studio Code (или другой редактор кода) и начните разработку решения. Чтобы запустить Visual Studio Code, можно выполнить приведенный ниже оператор.

    code .

Определение нового настройщика полей с помощью JavaScript

Чтобы воспроизвести отрисовку настраиваемого поля JSLink, необходимо реализовать ту же логику с помощью клиентского кода в новом решении SharePoint Framework. Чтобы выполнить эту задачу, сделайте следующее:

  1. Откройте файл в папке ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.manifest.json. Скопируйте значение свойства id и сохраните его в надежном месте, так как оно понадобится вам позже.

  2. Откройте файл ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.ts и измените его содержимое в соответствии со следующим фрагментом кода:

    import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

import * as strings from 'CustomColorFieldFieldCustomizerStrings';
import styles from './CustomColorFieldFieldCustomizer.module.scss';

/**
* If your field customizer uses the ClientSideComponentProperties JSON input,
* it will be deserialized into the BaseExtension.properties object.
* You can define an interface to describe it.
*/
export interface ICustomColorFieldFieldCustomizerProperties {
  // This is an example; replace with your own property
  sampleText?: string;
}

const LOG_SOURCE: string = 'CustomColorFieldFieldCustomizer';

export default class CustomColorFieldFieldCustomizer
extends BaseFieldCustomizer<ICustomColorFieldFieldCustomizerProperties> {

  @override
  public onInit(): Promise<void> {
    // Add your custom initialization to this method.  The framework will wait
    // for the returned promise to resolve before firing any BaseFieldCustomizer events.
    Log.info(LOG_SOURCE, 'Activated CustomColorFieldFieldCustomizer with properties:');
    Log.info(LOG_SOURCE, JSON.stringify(this.properties, undefined, 2));
    Log.info(LOG_SOURCE, `The following string should be equal: "CustomColorFieldFieldCustomizer" and "${strings.Title}"`);
    return Promise.resolve();
  }

  @override
  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {

    var colorField = event.fieldValue;

    // Declare a local variable to hold the output color
    var color = '';

    // Evaluate the values of the 'Color' field and render it accordingly
    switch (colorField)
    {
      case 'Red':
        color = 'red';
        break;
      case 'Green':
        color = 'green';
        break;
      case 'Blue':
        color = 'blue';
        break;
      case 'Yellow':
        color = 'yellow';
        break;
      default:
        color = 'white';
        break;
    }

    // Render the output for the 'Color' field
    event.domElement.innerHTML = "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
  }

  @override
  public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
    // This method should be used to free any resources that were allocated during rendering.
    // For example, if your onRenderCell() called ReactDOM.render(), then you should
    // call ReactDOM.unmountComponentAtNode() here.
    super.onDisposeCell(event);
  }
}

    Как видите, содержимое метода onRenderCell() практически такое же, как у метода RenderColorField() в реализации JSLink. Единственные отличия:

    • Чтобы получить текущее значение поля, необходимо считать свойство event.fieldValue входного аргумента метода onRenderCell().
    • Чтобы вернуть настраиваемый HTML-код для отрисовки поля, необходимо назначить значение свойству innerHTML объекта event.domElement, представляющему выходной контейнер HTML для отрисовки поля.

    Если не считать этих незначительных изменений, вы можете использовать практически такой же код JavaScript, как прежде.

    На приведенном ниже рисунке показан результат.

    Настройщик полей в

Тестирование решения в режиме отладки

  1. Вернитесь в окно консоли и выполните приведенную ниже команду, чтобы выполнить сборку и запустить локальный сервер Node.js для размещения решения.

    gulp serve --nobrowser

  2. Откройте любой браузер и перейдите к "современному" списку, содержащему настраиваемое поле с именем Color и типом Choice с теми же значениями, что и раньше (Red, Green, Blue, Yellow). Вы можете использовать список, созданный на "классическом" сайте, просто просматривая его в "современном" интерфейсе. Теперь добавьте приведенные ниже параметры строки запроса к URL-адресу страницы AllItems.aspx.

    ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Color":{"id":"c3070978-d85e-4298-8758-70b5b5933076"}}

    В приведенной ниже строке запроса замените GUID сохраненным значением id из файла CustomColorFieldFieldCustomizer.manifest.json. Имя свойства Color указывает на поле, которое нужно настроить. При желании вы также можете передать настраиваемый объект конфигурации, сериализованный в формате JSON, в качестве дополнительного параметра при конструировании настройщика полей.

    При выполнении запроса страницы появится запрос разрешения на запуск кода с домена localhost (окно с заголовком "Разрешить скрипты отладки?"). Если вы хотите отладить и протестировать решение локально, необходимо разрешить загрузку скриптов отладки.

    Примечание.

    Либо можно создавать записи конфигурации службы в файле config/serve.json проекта для автоматизации создания параметров строки запроса отладки, как описано в этом документе: Отладка решений SharePoint Framework на современных страницах SharePoint

Определение нового настройщика полей с помощью TypeScript

Теперь вы можете заменить код JavaScript на TypeScript, чтобы воспользоваться преимуществами полностью типизированного подхода TypeScript.

  1. Откройте файл ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.module.scss. В этом SCSS-файле представлен стиль пользовательского интерфейса настройщика полей. Замените содержимое SCSS-файла приведенным ниже кодом.

    .CustomColorField {
  .cell {
    float: left;
    width: 20px;
    height: 20px;
    margin: 5px;
    border: 1px solid rgba(0,0,0,.2);
  }

  .cellRed {
    background: red;
  }

  .cellGreen {
    background: green;
  }

  .cellBlue {
    background: blue;
  }

  .cellYellow {
    background: yellow;
  }

  .cellWhite {
    background: white;
  }
}

  2. Замените реализацию метода onRenderCell() приведенным ниже фрагментом кода.

    @override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Read the current field value
  let colorField: String = event.fieldValue;

  // Add the main style to the field container element
  event.domElement.classList.add(styles.CustomColorField);

  // Get a reference to the output HTML
  let fieldHtml: HTMLDivElement = event.domElement.firstChild as HTMLDivElement;

  // Add the standard style
  fieldHtml.classList.add(styles.cell);

  // Add the colored style
  switch(colorField)
  {
    case "Red":
      fieldHtml.classList.add(styles.cellRed);
      break;
    case "Green":
      fieldHtml.classList.add(styles.cellGreen);
      break;
    case "Blue":
      fieldHtml.classList.add(styles.cellBlue);
      break;
    case "Yellow":
      fieldHtml.classList.add(styles.cellYellow);
      break;
    default:
      fieldHtml.classList.add(styles.cellWhite);
      break;
  }
}

    Обратите внимание, что в новой реализации метода используется полностью типизированный подход, а класс CSS cell назначается дочернему элементу DIV текущего элемента поля вместе с другим пользовательским классом CSS, чтобы определить целевой цвет элемента DIV в соответствии с выбранным значением поля.

  3. Еще раз запустите настройщик полей в режиме отладки и просмотрите результаты.

Упаковка и размещение решения

Если вы довольны результатом, упакуйте решение и разместите его в настоящей инфраструктуре. Прежде чем собирать пакет, необходимо объявить XML-файл Feature Framework для подготовки расширения.

Обзор элементов Feature Framework

  1. В редакторе кода откройте файл /sharepoint/assets/elements.xml. В приведенном ниже фрагменте кода показано, как должен выглядеть файл.

    <?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{40475661-efaf-447a-a220-c992b20ec1c3}"
           Name="SPFxColor"
           DisplayName="Color"
           Title="Color"
           Type="Choice"
           Required="FALSE"
           Group="SPFx Columns"
           ClientSideComponentId="c3070978-d85e-4298-8758-70b5b5933076">
    </Field>
</Elements>

    Как видите, он напоминает файл SharePoint Feature Framework, но содержит пользовательский элемент Field с типом поля Choice, который ссылается на свойство id настройщика полей, используя атрибут ClientSideComponentId. Кроме того, в нем может быть атрибут ClientSideComponentProperties для настройки свойств конфигурации, необходимых расширению.

  2. Откройте файл ./config/package-solution.json. В файле вы увидите ссылку на файл elements.xml в разделе assets.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-custom-field-extension-client-side-solution",
    "id": "ab0fbbf8-01ba-4633-8498-46cfd5652619",
    "version": "1.0.0.0",
    "features": [{
      "title": "Application Extension - Deployment of custom action.",
      "description": "Deploys a custom action with ClientSideComponentId association",
      "id": "090dc976-878d-44fe-8f8e-ac603d094aa1",
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ]
      }
    }]
  },
  "paths": {
    "zippedPackage": "solution/spfx-custom-field-extension.sppkg"
  }
}

Объединение в пакет, упаковка и развертывание решения

Затем необходимо объединить в пакет и упаковать пакет решения в каталог приложений. Для этого выполните указанные ниже действия.

Подготовьте и разверните решение для клиента SharePoint Online:

  1. Выполните приведенную ниже задачу, чтобы создать пакет решения. При этом создается сборка выпуска проекта:

    gulp bundle --ship

  2. Выполните приведенную ниже задачу, чтобы упаковать решение. Эта команда создает пакет *.sppkg в папке sharepoint/solution .

    gulp package-solution --ship

  3. Добавьте или перетащите новый пакет клиентского решения в каталог приложений в клиенте и нажмите кнопку Развернуть.

Установка и запуск решения

  1. Откройте браузер и перейдите на любой "современный" сайт.

  2. Перейдите на страницу Содержимое сайта и добавьте новое приложение.

  3. Выберите Из вашей организации, чтобы просмотреть решения, доступные в каталоге приложений.

  4. Выберите решение spfx-custom-field-extension-client-side-solution и установите его на целевом сайте.

    Добавление решения на сайт

  5. После завершения установки приложения создайте настраиваемый список, измените его свойства и добавьте новый столбец на основе уже имеющихся. Выберите группу столбцов под названием Столбцы SPFx и добавьте поле Color.

    Добавление поля в список

  6. Измените добавленное поле и настройте значения цветов (Red, Green, Blue, Yellow), а затем сохраните параметры поля.

  7. Добавьте в список элементы и просмотрите результат в представлении списка. Они должны выглядеть так, как на приведенном ниже снимке экрана.

    Настройщик полей в действии

Поздравляем! Вы создали настройщик полей, используя расширения SharePoint Framework.

См. также