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

Понимание и настройка модели преобразования страниц публикации (начиная с версии за июнь 2019 г.)

  • Статья

Страницы публикации всегда основаны на макете страницы и главной странице. Эти две страницы в сочетании с полями, содержащими данные, составляют страницу, видимую пользователем в браузере. При преобразовании страниц публикации необходимо сопоставить используемые макеты страницы с моделью преобразования страницы публикации. Компонент преобразования страницы публикации будет иметь сопоставление макета страницы по умолчанию для всех стандартных макетов страниц, поэтому, если портал использует эти стандартные макеты страницы, которые вы охватываете. Реальность такова, что большинство порталов используют пользовательские макеты страниц (и пользовательские эталонные страницы), поэтому для этих пользовательских макетов страниц требуется сопоставление макетов страниц. Пользовательские макеты страниц можно обрабатывать двумя способами:

  • Предпочтительный вариант заключается в том, что вы сами предоставляете пользовательский файл сопоставления макета страницы. Это дает вам полный контроль над тем, какие поля переводятся в веб-части и где они находятся на современной странице, какие поля становятся метаданными и многое другое.
  • Если для преобразуемой страницы не найдено сопоставление макета страницы, мы создадим сопоставление на лету и используем его. Недостатком этого подхода является то, что все содержимое будет в конечном итоге в одном разделе и столбце современной страницы.

Создание файла сопоставления макета страницы

Если вы используете пользовательские макеты страниц, рекомендуется использовать файл сопоставления пользовательского макета страницы, чтобы получить более точные современные страницы. К счастью, вам не нужно вручную создавать эти пользовательские файлы макета, существует API .NET и поддержка PnP PowerShell для их создания.

С помощью PowerShell

С помощью командлета Export-PnPPageMapping можно:

  • Экспорт встроенного файла сопоставления (-BuiltInPageLayoutMapping параметр): этот файл будет использоваться для макетов страницы. Если вы укажете настраиваемое сопоставление для макета страницы в собственном файле сопоставления, то это сопоставление будет предпочтнее, чем сопоставление OOB
  • Проанализируйте макеты страниц на подключенном портале и экспортируйте их в виде файла сопоставления (-CustomPageLayoutMapping параметр). Все найденные пользовательские макеты страниц анализируются и экспортируются. Если вы также хотите проанализировать макеты страниц OOB, используйте -AnalyzeOOBPageLayouts параметр .
# Connect to your "classic" portal
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/classicportal -Interactive

# Analyze and export the page layout mapping files
Export-PnPPageMapping -BuiltInPageLayoutMapping -CustomPageLayoutMapping -Folder c:\temp

Использование .NET

В .NET необходимо использовать класс для PageLayoutAnalyser анализа макетов страниц. Ниже показано, как проанализировать все макеты страниц или макеты страниц, используемые определенными страницами публикации.

string siteUrl = "https://contoso.sharepoint.com/sites/classicportal";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    var analyzer = new PageLayoutAnalyser(cc);
    // Analyze all found page layouts
    analyzer.AnalyseAll();  
    analyzer.GenerateMappingFile("c:\\temp", "custompagelayoutmapping.xml");
}

string siteUrl = "https://contoso.sharepoint.com/sites/classicportal";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
    var analyzer = new PageLayoutAnalyser(cc);
    // Analyze all the unique page layouts for publishing pages starting with an "a"
    var pages = cc.Web.GetPagesFromList("Pages", "a");
    foreach (var page in pages)
    {
        analyzer.AnalysePageLayoutFromPublishingPage(page);
    }

    analyzer.GenerateMappingFile("c:\\temp", "custompagelayoutmapping.xml");
}

Описана модель сопоставления макетов страниц

При открытии файла сопоставления макета страницы отображаются следующие элементы верхнего уровня:

  • AddOns. Пользователю преобразования страницы может потребоваться применить пользовательскую логику для реализации своих потребностей, например преобразовать заданное свойство таким образом, чтобы оно могло работать с пользовательской веб-частью SPFX. Платформа поддерживает это, позволяя добавлять сборки с функциями... Просто определив их в разделе AddOn, а затем сослаться на пользовательские функции позже, установив для них префикс с заданным именем, преобразование страницы публикации будет использовать пользовательский код.

  • PageLayouts: этот элемент содержит сведения для каждого макета страницы, который вы планируете использовать. Для каждого макета страницы вы найдете определение заголовка, веб-части, метаданных, зон веб-частей и фиксированных веб-частей.

Дополнительные сведения смотрите в главах, которые вскоре появятся.

Определение PageLayout в модели макета страницы

Давайте проанализируем настройку сопоставления макета страницы в модели сопоставления макетов страниц, что лучше всего сделать на основе примера определения:

    <PageLayout Name="MyPageLayout" AlsoAppliesTo="MyOtherPageLayout;MyOtherPageLayout2" AssociatedContentType="CustomPage1" PageLayoutTemplate="AutoDetect" IncludeVerticalColumn="true" PageHeader="Custom">
      <SectionEmphasis VerticalColumnEmphasis="Soft">
        <Section Row="3" Emphasis="Neutral" />
      </SectionEmphasis>
      <Header Type="FullWidthImage" Alignment="Left" ShowPublishedDate="true">
        <Field Name="PublishingRollupImage;PublishingPageImage" HeaderProperty="ImageServerRelativeUrl" Functions="ToImageUrl({@name})" />
        <Field Name="ArticleByLine" HeaderProperty="TopicHeader" Functions=""/>
        <Field Name="PublishingContact" HeaderProperty="Authors" Functions="ToAuthors({PublishingContact})"/>
      </Header>
      <MetaData ShowPageProperties="true" PagePropertiesRow="1" PagePropertiesColumn="4" PagePropertiesOrder="1">
        <Field Name="PublishingContactName;PublishingContactEmail" TargetFieldName="MyPageContact" Functions="" />
        <Field Name="MyCategory" TargetFieldName="Category" Functions="" ShowInPageProperties="true" />
      </MetaData>
      <WebParts>
        <Field Name="PublishingPageImage" TargetWebPart="SharePointPnP.Modernization.WikiImagePart" Row="1" Column="1" Order="1">
          <Property Name="ImageUrl" Type="string" Functions="ToImageUrl({PublishingPageImage})"/>
          <Property Name="AlternativeText" Type="string" Functions="ToImageAltText({PublishingPageImage})" />
        </Field>
        <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2" Order="1">
          <Property Name="Text" Type="string" Functions="" />
        </Field>
      </WebParts>
      <WebPartZones>
        <WebPartZone Row="2" Column="1" Order="1" ZoneId="g_0C7F16935FAC4709915E2D77092A90DE" ZoneIndex="0">
          <!-- Optional element, only needed if you want to use custom position of the web parts coming from a web part zone -->
          <WebPartZoneLayout>
            <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="2"/>
            <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="2"/>
            <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="1"/>
          </WebPartZoneLayout>
        </WebPartZone>
      </WebPartZones>
      <FixedWebParts>
        <WebPart Row="1" Column="2" Order="1" Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">
          <Property Name="TITLE" Type="string" Value="Example Embedded Web Content Editor"/>
          <Property Name="CONTENT" Type="string" Value="PnP Rocks!"/>
        </WebPart>
      </FixedWebParts>
    </PageLayout>

Примечание.

Рекомендуется использовать схему pagelayoutmapping.xsd при редактировании этих файлов. Для файлов, которые вы предоставляете для преобразования страницы, будут проверены на соответствие этой схеме, и преобразование завершится ошибкой, если предоставленный файл сопоставления макета страницы недопустим.

Элемент PageLayout

В элементе PageLayout используются следующие свойства:

  • Имя: содержит имя макета страницы.
  • Также Применимо К. Если это сопоставление будет использоваться для нескольких макетов страниц, имена дополнительных макетов страниц можно указать в этом атрибуте в виде списка с разделителями с запятой. Свойство Name будет называться первым макетом страницы, а свойство AlsoAppliesTo содержит только дополнительные.
  • AssociatedContentType: имя современного типа контента страницы сайта, который вы хотите использовать. Оставьте это поле пустым, если вы хотите использовать тип контента страницы сайта по умолчанию.
  • PageLayoutTemplate: система макета для использования... значение по умолчанию AutoDetect , которое должно работать нормально во всех случаях, но при необходимости вы также можете выбрать определенный макет вики-сайта.
  • IncludeVerticalColumn: необязательный элемент для указания созданной целевой страницы должен иметь вертикальный столбец. При использовании вертикального столбца вы ориентируетесь на вертикальный столбец в качестве дополнительного столбца, поэтому, если перед добавлением вертикального столбца было 3 столбца, теперь будет 4 столбца, и поэтому вы можете задать значение столбца для содержимого страницы равным 4, чтобы поместить его в вертикальный столбец.
  • PageHeader: управляет типом заголовка страницы, который будет использоваться. По умолчанию используется значение Custom , что позволяет использовать хороший заголовок, но его можно переключить None на без заголовка или Default для современного заголовка страницы по умолчанию.

Элемент SectionEmphasis

В необязательном элементе SectionEmphasis используются следующие свойства:

  • VerticalColumnEmphasis: используйте это свойство, чтобы задать для вертикального столбца значение None, Neutral, Soft или Strong

Для каждого раздела при необходимости можно указать выделение раздела с помощью элемента Section:

  • Строка: указывает номер строки этого раздела. Первый раздел будет иметь номер 1.
  • Выделение: задает для раздела значение None, Neutral, Soft или Strong

Элемент Header

В элементе Header используются следующие свойства:

  • Тип: по умолчанию FullWidthImage позволяет отображать изображение заголовка в полной ширине. Альтернативные варианты: ColorBlockи CutInShapeNoImage. Обратите внимание, что этот атрибут актуален только в том случае, если для атрибута PageHeader задано значение Custom.
  • Выравнивание: управляет выравниванием содержимого заголовка страницы. Значение по умолчанию — Left, альтернативный параметр — Center.
  • ShowPublishedDate: определяет, отображается ли дата публикации страницы. Значение по умолчанию — true.

Для каждого поля, которое вы хотите использовать в современном заголовке, необходимо добавить элемент Field, указывающий:

  • Имя: имя полей на классической странице публикации. Например, добавление PublishingRollupImage;PublishingPageImage в качестве значения будет означать, что PublishingRollupImage будет приниматься , если он был заполнен, если не заполнено PublishingPageImage , будет опробован. Вы можете добавить любое необходимое количество переопределений
  • HeaderProperty: имя свойства заголовка, которое необходимо задать.
  • Функции. Если задано значение пустое, то значение поля на классической странице публикации принимается как есть, однако если здесь указана функция, используются выходные данные этой функции. Если вы указали несколько полей (поэтому используется параметр переопределения поля), необходимо указать поле для использования в функции как {@name}

При создании современного заголовка страницы есть 4 свойства заголовка страницы, которые можно заполнить данными, поступающими со страницы публикации:

  • ImageServerRelativeUrl: если в заголовке должно отображаться изображение, в этом поле необходимо определить путь к изображению, относительно сервера, для изображения, живущего в том же семействе веб-сайтов, что и страница. По умолчанию используется классическое поле страницы PublishingRollupImage публикации, но так как он содержит тег Img, содержимое поля очищается с помощью ToImageUrl функции .
  • TopicHeader: по умолчанию классическое поле страницы ArticleByLine публикации используется в качестве заголовка раздела для заголовка современной страницы.
  • Авторы. Установка авторов позволяет отобразить основной контакт для этой страницы в заголовке страницы. По умолчанию используется классическое поле страницы PublishingContact публикации, но так как это поле пользователя, содержимое поля преобразуется с помощью ToAuthors функции .
  • AlternativeText: не сопоставлено по умолчанию, но при необходимости можно добавить настраиваемое сопоставление для заполнения современного свойства замещающего текста заголовка.

Если вы, например, не хотите задавать заголовок раздела, можно просто удалить или закомментировать соответствующий элемент Field.

Параметры изображения заголовка страницы

Сопоставление по умолчанию принимает изображение, определенное в PublishingRollupImage поле в качестве заголовка страницы, но при необходимости можно выбрать другое поле изображения публикации или указать жестко закодированное значение изображения, живущего на исходном или целевом сайте. Ниже показан заголовок со статическим изображением:

<Header Type="FullWidthImage" Alignment="Left" ShowPublishedDate="true">
  <!-- Note that static values do require specifying them between '' -->
  <Field Name="PublishingRollupImage" HeaderProperty="ImageServerRelativeUrl" Functions="StaticString('/sites/classicportal/images/myimage.jpg')" />
  <Field Name="ArticleByLine" HeaderProperty="TopicHeader" Functions=""/>
  <Field Name="PublishingContact" HeaderProperty="Authors" Functions="ToAuthors({PublishingContact})"/>
</Header>

Элемент MetaData

Элемент метаданных определяет, какие из классических полей страницы публикации необходимо использовать в качестве метаданных для современной страницы. Как иногда требуется, чтобы метаданные также были представлены с помощью веб-части "Свойства страницы OOB", вы указываете, что с помощью следующих необязательных атрибутов:

  • ShowPageProperties: будет ли добавлена веб-часть свойств страницы на результирующей современной странице
  • PagePropertiesRow: строка, которая будет содержать веб-часть свойств страницы.
  • PagePropertiesColumn: столбец, который будет содержать веб-часть свойств страницы.
  • PagePropertiesOrder: порядок веб-части свойств страницы в определенной строке или столбце.

Для каждого поля, которое вы хотите взять на себя, необходимо добавить элемент Field, указывающий:

  • Имя: имя полей на классической странице публикации. Например, добавление PublishingContactName;PublishingContactEmail в качестве значения будет означать, что PublishingContactName будет приниматься , если он был заполнен, если не заполнено PublishingContactEmail , будет опробован. Вы можете добавить любое необходимое количество переопределений
  • TargetFieldName: имя поля на целевой современной странице.
  • Функции. Если задано значение пустое, то значение поля на классической странице публикации принимается как есть, однако если здесь указана функция, используются выходные данные этой функции. Если вы указали несколько полей (поэтому используется параметр переопределения поля), необходимо указать поле для использования в функции как {@name}
  • ShowInPageProperties: если задано значение true и если веб-часть свойств страницы включена, то это поле отображается в веб-части свойств страницы.

Примечание.

  • Поддержка функций недоступна для полей таксономии

Элемент WebParts

Каждое поле на классической странице публикации, которое должно стать визуальным элементом целевой страницы (например, веб-частью или текстом), должно быть определено в разделе веб-частей:

  • Имя: имя поля на классической странице публикации.
  • TargetWebPart: тип целевой веб-части, которая будет визуализировать это поле на современной странице. Поддерживаются целевые SharePointPnP.Modernization.WikiTextPartвеб-части , SharePointPnP.Modernization.WikiImagePart и Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c.
  • Строка: строка, в которую нужно поместить целевую веб-часть. Должно быть 1 или больше.
  • Столбец: столбец, в который нужно поместить целевую веб-часть. Должно быть 1, 2 или 3.
  • Order : порядок целевой веб-части в заданной строке или столбце.

В зависимости от выбранного TargetWebPart необходимо указать свойства веб-части, в которые содержатся данные, необходимые во время преобразования. Каждое свойство имеет следующие свойства:

  • Имя: имя свойства. Эти имена свойств должны соответствовать свойствам, используемым в модели преобразования страниц.
  • Тип: тип свойства. Эти типы свойств должны соответствовать свойствам, используемым в модели преобразования страниц.
  • Функции. Если задано значение пустое, значение свойства будет значением поля на исходной классической странице публикации. Функцию можно использовать для преобразования содержимого поля или для использования данных из другого поля классической страницы публикации.

Элемент WebPartZones

Если макет страницы содержит зоны веб-частей, их необходимо определить здесь. Это необходимо для правильного расположения преобразованных веб-частей на современной странице. Используются следующие свойства:

  • ZoneId: имя зоны.
  • ZoneIndex: индекс зоны (целое число)
  • Строка: строка, в которую нужно поместить веб-части, размещенные в этой зоне. Должно быть 1 или больше.
  • Столбец: столбец, в который нужно поместить веб-части, размещенные в этой зоне. Должно быть 1, 2 или 3.
  • Order: порядок в определенной строке или столбце для веб-частей, размещенных в этой зоне

Иногда страницы публикации имеют несколько веб-частей в зоне веб-частей, и вы хотите разместить каждую веб-часть по-разному на целевой странице. Это можно сделать с помощью необязательного элемента WebPartZoneLayout:

<WebPartZoneLayout>
  <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="2"/>
  <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="2"/>
  <WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="1"/>
</WebPartZoneLayout>

Приведенное выше определение приведет к тому, что первый элемент ContentEditorWebPart перейдет в строку 3, столбец 2. Второй элемент ContentEditorWebPart будет помещен в строку 3, столбец 1 с порядком 2, а первая веб-часть XSLTListView окажется в строке 3, столбец 1 с порядком 1. При необходимости можно определить как можно больше элементов WebPartOccurrence. Если в зоне веб-части нет соответствующей веб-части, элемент WebPartOccurrence будет игнорироваться. Если в зоне веб-части есть веб-часть, которая не указана как элемент WebPartOccurrence, то эта веб-часть получит сведения о строке, столбце и заказе из элемента WebPartZone.

Элемент FixedWebParts

Иногда макеты страниц содержат "фиксированные" веб-части. Это веб-части, жестко закодированные внутри макета страницы, поэтому они присутствуют на всех страницах, использующих макет страницы. Так как нет API для обнаружения этих "фиксированных" веб-частей, их необходимо определить как часть модели сопоставления макета страницы.

В "фиксированной" веб-части можно задать следующие свойства:

  • Тип: тип фиксированной веб-части. Список возможных типов см. здесь .
  • Строка: строка, в которую нужно поместить веб-часть "fixed". Должно быть 1 или больше.
  • Столбец: столбец, в который нужно поместить веб-часть "fixed". Должно быть 1, 2 или 3.
  • Order: порядок, соответствующий, если в одной строке и столбце помещалось несколько веб-частей.

Для каждой "фиксированной" веб-части необходимо определить соответствующие свойства. Как правило, вы берете на себя эти свойства, как они определены в классическом макете страницы. Для каждого свойства можно задать следующие атрибуты:

  • Свойство: имя свойства. Эти имена свойств должны соответствовать свойствам, используемым в модели преобразования страниц.
  • Тип: тип свойства. Эти типы свойств должны соответствовать свойствам, используемым в модели преобразования страниц.
  • Значение: значение, которое имеет это свойство. Не забудьте закодировать значение в ФОРМАТЕ XML.

Определение addOns в модели макета страницы

Надстройки позволяют вставить пользовательскую логику в модель сопоставления макета страницы, выполнив следующие 2 шага:

  • Создание пользовательской сборки, в котором размещаются пользовательские функции
  • объявив эту настраиваемую сборку в элементах AddOns.

Создание настраиваемой сборки с функциями и селекторами

Чтобы создать собственные функции, вам потребуется вставить ссылку на сборку SharePoint.Modernization.Framework в проект, а затем создать класс, наследующий класс SharePointPnP.Modernization.Framework.Functions.FunctionsBase:

using Microsoft.SharePoint.Client;
using SharePointPnP.Modernization.Framework.Functions;
using System;

namespace Contoso.Modernization
{
    public class MyCustomFunctions: FunctionsBase
    {
        public MyCustomFunctions(ClientContext clientContext) : base(clientContext)
        {
        }

        public string MyListAddServerRelativeUrl(Guid listId)
        {
            if (listId == Guid.Empty)
            {
                return "";
            }
            else
            {
                var list = this.clientContext.Web.GetListById(listId);
                list.EnsureProperties(p => p.RootFolder.ServerRelativeUrl);
                return list.RootFolder.ServerRelativeUrl;
            }
        }

    }
}

Объявление настраиваемой сборки

Прежде чем использовать настраиваемые функции, их необходимо объявить в модели, добавив одну ссылку на библиотеку или класс в элемент AddOns:

<AddOn Name="Custom" Type="Contoso.Modernization.MyCustomFunctions" Assembly="Contoso.Modernization.dll" />

Можно также добавить такой код (обратите внимание на полный путь):

<AddOn Name="Custom" Type="Contoso.Modernization.MyCustomFunctions" Assembly="c:\transform\Contoso.Modernization.dll" />

Обратите внимание, что в приведенном выше примере каждое объявление имеет имя Custom.

Использование настраиваемых функций или селекторов

После определения сборки вы можете использовать функции и селекторы, ссылаясь на них с помощью имени, похожего на префикс Custom в этом примере:

<Property Name="ListId" Type="guid" Functions="{ListServerRelativeUrl} = Custom.MyListAddServerRelativeUrl({ListId})"/>

Часто задаваемые вопросы о сопоставлении макетов страниц

Я хочу сохранить сведения о создании исходной страницы

При использовании подхода PowerShell PnP используйте -KeepPageCreationModificationInformation командлет в командлете ConvertTo-PnPPage . При использовании подхода .NET задайте KeepPageCreationModificationInformation для параметра значение true. При использовании этого параметра целевой странице будут заданы значения полей "Создано", "Изменено", "Автор" и "Редактор" исходной страницы.

Примечание.

Когда вы в рамках преобразования страницы повышаете уровень страницы как новости или публикуете страницу, в поле Редактор будет задано преобразование страницы, выполняемой учетной записью.

Я хочу продвигать созданные страницы как новости

Продвижение страниц, созданных на основе макета страницы, в качестве страниц новостей можно сделать с помощью -PostAsNews параметра -KeepPageCreationModificationInformation командлета (при использовании подхода PowerShell PnP) или с помощью параметра PostAsNews true (при использовании подхода .NET).

При использовании параметра в сочетании PostAsNews с параметром KeepPageCreationModificationInformationFirstPublishedDateField в поле будет задана дата изменения исходной страницы. Поле FirstPublishedDateField — это значение даты, отображаемое во время свертки новостей.

Я хочу вставить жестко заданный текст на созданную страницу

Иногда макет страницы содержит фрагменты текста, которые, так как они не являются содержимым на фактической странице, не преобразуются. Если это так, вы можете определить "поддельные" поля для сопоставления, как показано ниже:

<WebParts>
  ...
  <Field Name="ID" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="3">
    <Property Name="Text" Type="string" Functions="StaticString('&lt;H1&gt;This is some extra text&lt;/H1&gt;')" />
  </Field>
  ...
</WebParts>

Примечание.

HTML-код, предоставляемый в функции StaticString, должен быть закодирован в формате XML и должен быть отформатирован как HTML исходной страницы, так как этот HTML-код по-прежнему будет преобразован в HTML, который соответствует современному текстовому редактору

Я хочу префиксировать или суффикс содержимого из поля

Подход, используемый в предыдущей главе, позволяет добавить дополнительный текст на страницу, но имеет в качестве недостатка то, что дополнительный текст будет добавлен в его собственной текстовой части. Если вы хотите, чтобы дополнительный текст был интегрирован с фактическим преобразуемым текстом, то приведенный ниже подход позволяет сделать это. Можно либо префикс, либо суффикс существующего содержимого поля. При необходимости можно выполнить префикс или суффикс только в том случае, если поле содержит содержимое. Параметр bool в Prefixфункциях и определяет, SuffixPrefixAndSuffix должен ли префикс или суффикс происходить, когда содержимое поля пусто: "true" означает применение действия, даже если поле пусто.

Дополнительные сведения о приведенных ниже функциях см. в разделе Функции преобразования страниц и селекторы .

<WebParts>
...
  <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
    <Property Name="Text" Type="string" Functions="PrefixAndSuffix('&lt;H1&gt;Prefix some extra text&lt;/H1&gt;','&lt;H1&gt;Suffix some extra text&lt;/H1&gt;',{PublishingPageContent},'false')" />
  </Field>
  ...
  <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
    <Property Name="Text" Type="string" Functions="Prefix('&lt;H1&gt;Prefix some extra text&lt;/H1&gt;',{PublishingPageContent},'true')" />
  </Field>
  ...
  <Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
    <Property Name="Text" Type="string" Functions="Suffix('&lt;H1&gt;Suffix some extra text&lt;/H1&gt;',{PublishingPageContent},'false')" />
  </Field>
...
</WebParts>

Я хочу заполнить поле управляемых метаданных одним или несколькими терминами

Если в метаданных исходной страницы есть поле управляемых метаданных, может потребоваться аналогичное поле управляемых метаданных для целевой страницы. Данное преобразование страницы в настоящее время имеет функцию сопоставления управляемых метаданных, что создает проблему. Возможное решение заключается в заполнении целевого поля управляемых метаданных выбранным термином или набором терминов в случае поля управляемых метаданных с несколькими значениями. Это можно сделать с помощью функции, DefaultTaxonomyFieldValue как показано в следующем примере:

<MetaData ShowPageProperties="true" PagePropertiesRow="1" PagePropertiesColumn="4" PagePropertiesOrder="1">
...
  <Field Name="TaxField2" TargetFieldName="Metadata2" Functions="DefaultTaxonomyFieldValue({TaxField2},'a65537e8-aa27-4b3a-bad6-f0f61f84b9f7|69524923-a5a0-44d1-b5ec-7f7c6d0ec160','true')" ShowInPageProperties="true"/>
...
</MetaData>

Дополнительные сведения о функции см. в DefaultTaxonomyFieldValue разделе Функции преобразования страниц и селекторы.

Я хочу добавить дополнительную веб-часть на созданную страницу

При преобразовании классической страницы публикации в современную страницу иногда требуется добавить дополнительную современную веб-часть на созданной странице, без которой на классической странице публикации есть классическая версия этой веб-части. Это можно сделать, настроив файлы сопоставления webpartmapping.xml и макета страниц, как показано ниже.

Сначала определите пользовательскую веб-часть в файле webpartmapping.xml, добавив ей WebParts элемент в файл, как показано в этой стандартной веб-части SPFX Hello World:

<WebParts>
  ...
  <!-- Custom Hello world web part-->
  <WebPart Type="SharePointPnP.Demo.HelloWorld" CrossSiteTransformationSupported="true">
    <Properties>
      <Property Name="HelloWorld" Type="string" />
    </Properties>
   <Mappings>
    <Mapping Default="true" Name="default">
      <ClientSideWebPart Type="Custom" ControlId="157b22d0-8006-4ec7-bf4b-ed62383fea76" Order="10" JsonControlData="&#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;{HelloWorld}&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;"/>
    </Mapping>
  </Mappings>
</WebPart>
  ...
</WebParts>

Если вы не можете правильно определить пользовательскую веб-часть в приведенном выше элементе ClientSideWebPart , выполните следующие действия:

  • Перейдите к SharePoint Framework Workbench на сайте (например, https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx).
  • Добавление пользовательской веб-части в workbench и ее настройка при необходимости
  • Нажмите кнопку "Данные веб-части" на панели инструментов, а затем кнопку "Современные страницы"
  • Скопируйте структуру JSON WebPartData и используйте ее для выполнения следующих действий:
    • Значение guid ControlId — это значение свойства id json.
    • Удалите следующие свойства JSON из скопированного фрагмента: id, instanceIf, title и description. На этом этапе осталось следующее: {"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}
    • Xml кодирует эту строку, и вы получите следующее: &#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;HelloWorld from Bert&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;
    • При необходимости вставьте параметры веб-части в эту строку (например, {HelloWorld} в приведенном выше примере): &#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;{HelloWorld}&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;
    • Вставка результирующей строки в свойство JsonControlData

После этого необходимо обновить сопоставление макета страницы, добавив в раздел WebParts поле, которое будет преобразовано в эту настраиваемую веб-часть:

<WebParts>
  ...
  <!-- Add an extra web part on the page -->
  <Field Name="ID"  TargetWebPart="SharePointPnP.Demo.HelloWorld" Row="4" Column="1" Order="1">
    <Property Name="HelloWorld" Type="string" Functions="StaticString('PnP Rocks!')"/>
  </Field>
  ...
</WebParts>

Убедитесь, что в преобразовании укажите пользовательский файлwebpartmapping.xml (-WebPartMappingFile параметр командлета PowerShell, PublishingPageTransformator конструктор при использовании .NET).

Я использую много Add-In частей и хочу преобразовать их в пользовательские веб-части SPFX

По умолчанию преобразование страницы просто берет на себя часть надстройки на современной странице, так как надстройка выполняет работу на современных страницах. Однако если вы хотите выборочно преобразовать некоторые части надстройки в пользовательские веб-части на основе SPFX, удалить некоторые части надстройки и сохранить оставшиеся части надстройки, то сопоставления по умолчанию будет недостаточно. В приведенном ниже примере вы видите, что StaticString функция используется для отправки заголовка надстройки в качестве значения селектора сопоставления. Таким образом, в зависимости от названия веб-части будет выбрано сопоставление. Первая надстройка будет передана в качестве надстройки на современной странице, вторая будет преобразована в настраиваемую альтернативу на основе SPFX, а последняя будет просто удалена.

При сопоставлении с пользовательской веб-частью на основе SPFX можно использовать любое из свойств части надстройки для настройки альтернативы на основе SPFX (например, {HelloWorld} в приведенном ниже примере), даже если эти свойства не перечислены в узле Свойства в файле сопоставления. Дополнительные сведения о создании настраиваемого файла сопоставления см. также в предыдущей главе.

<WebPart Type="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" CrossSiteTransformationSupported="true">
  <!-- Note: the add-in can depend on assets that live in the source site, which is not something we can detect -->
  <Properties>
    <Property Name="FeatureId" Type="guid"/>
    <Property Name="ProductWebId" Type="guid"/>
    <Property Name="ProductId" Type="guid"/>
  </Properties>
  <Mappings Selector="StaticString({Title})">
    <Mapping Name="My Custom Report" Default="true">
      <!-- We keep this web part -->
      <ClientSideWebPart Type="ClientWebPart" Order="10" JsonControlData="{}"/>
    </Mapping>
    <Mapping Name="News Ticker" Default="false">
      <!--This web part will be transformed to a custom SPFX based web part -->
      <ClientSideWebPart Type="Custom" ControlId="157b22d0-8006-4ec7-bf4b-ed62383fea76" Order="10" JsonControlData="&#123;&quot;serverProcessedContent&quot;:&#123;&quot;htmlStrings&quot;:&#123;&#125;,&quot;searchablePlainTexts&quot;:&#123;&#125;,&quot;imageSources&quot;:&#123;&#125;,&quot;links&quot;:&#123;&#125;&#125;,&quot;dataVersion&quot;:&quot;1.0&quot;,&quot;properties&quot;:&#123;&quot;description&quot;:&quot;{HelloWorld}&quot;,&quot;test&quot;:&quot;Multi-line text field&quot;,&quot;test1&quot;:true,&quot;test2&quot;:&quot;2&quot;,&quot;test3&quot;:true&#125;&#125;"/>
    </Mapping>
    <Mapping Name="Some other add-in" Default="false">
      <!-- This add-in will not be taken over -->
    </Mapping>
  </Mappings>
</WebPart>

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

<WebPart Type="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" CrossSiteTransformationSupported="true">
  <!-- Note: the add-in can depend on assets that live in the source site, which is not something we can detect -->
  <Properties>
    <Property Name="FeatureId" Type="guid"/>
    <Property Name="ProductWebId" Type="guid"/>
    <Property Name="ProductId" Type="guid"/>
  </Properties>
  <Mappings Selector="ConcatenateWithPipeDelimiter({Title},{effect})">
    <Mapping Name="News Ticker|Slide" Default="true">
      <ClientSideText Text="***TEST.{Title} web part - Slide mapping chosen! Slider theme = {theme}***" Order="10" />
    </Mapping>
    <Mapping Name="News Ticker|Scroll" Default="false">
      <ClientSideText Text="***TEST.{Title} web part - Scroll mapping chosen! Slider theme = {theme}***" Order="10" />
    </Mapping>
  </Mappings>
</WebPart>

Можно ли управлять изображением предварительного просмотра страницы

Если на странице есть изображение заголовка страницы, это изображение также будет использоваться в качестве изображения предварительного просмотра страницы. Если вы хотите управлять изображением предварительного просмотра страницы, вы можете заполнить BannerImageUrl поле с помощью ToPreviewImageUrl функции или путем указания жестко закодированного значения, как показано в приведенных ниже примерах.

<!-- When you do have a publishing image field that will need to be set as preview image -->
<Field Name="PreviewImage" TargetFieldName="BannerImageUrl" Functions="ToPreviewImageUrl({PreviewImage})" />

<!-- When you do have a hard coded preview image already available on the target site. Note that the source field name (PublishingContactEmail in below sample) must exist, although it's not used here  -->
<Field Name="PublishingContactEmail" TargetFieldName="BannerImageUrl" Functions="StaticString('https://contoso.sharepoint.com/_layouts/15/getpreview.ashx?guidSite=88eebac1710b464cb6816639340fac55&amp;guidWeb=277fe40db9d24da5bbc6827714184958&amp;guidFile=91bf17fd54e849149a3ad6b4f006304e&amp;ext=jpg')" />

<!-- When you want to refer a static image living in the source site  -->
<Field Name="PreviewImage" TargetFieldName="BannerImageUrl" Functions="ToPreviewImageUrl('/sites/classicportal/images/myimage.jpg')" />

Когда преобразование приводит к современной веб-части QuickLinks (например, для преобразования SummaryLinkWebPart), платформа преобразования страниц будет использовать базовую конфигурацию по умолчанию для веб-части QuickLinks. Однако если вам нужна другая конфигурация, это можно сделать, указав свойство QuickLinksJsonProperties. Заключите закодированные свойства JSON в функцию StaticString, как показано в этом примере:

<WebParts>
  ...
  <Field Name="SummaryLinks" TargetWebPart="Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="1" Column="2">
    <!-- No function specified, means the content of the PublishingPageContent field will be assigned to the value of the first listed web part property -->
    <Property Name="SummaryLinkStore" Type="string" />
    <Property Name="Title" Type="string" Functions="EmptyString()"/>
    <Property Name="QuickLinksJsonProperties" Type="string" Functions="StaticString('{&quot;isMigrated&quot;: false, &quot;layoutId&quot;: &quot;Button&quot;, &quot;shouldShowThumbnail&quot;: true, &quot;buttonLayoutOptions&quot;: { &quot;showDescription&quot;: false, &quot;buttonTreatment&quot;: 1, &quot;iconPositionType&quot;: 2, &quot;textAlignmentVertical&quot;: 1, &quot;textAlignmentHorizontal&quot;: 2, &quot;linesOfText&quot;: 2}, &quot;listLayoutOptions&quot;: { &quot;showDescription&quot;: false, &quot;showIcon&quot;: true}, &quot;waffleLayoutOptions&quot;: { &quot;iconSize&quot;: 1, &quot;onlyShowThumbnail&quot;: false}, &quot;hideWebPartWhenEmpty&quot;: true}')" />
  </Field>
  ...
</WebParts>

Json в примере показывает все возможные параметры конфигурации, которые можно задать, но вы можете также просто определить нужные. До тех пор, пока json является допустимым и структура поддерживается, будет выбрана настраиваемая конфигурация QuickLinks.