Skip to content

Latest commit

 

History

History
250 lines (163 loc) · 16.8 KB

api.md

File metadata and controls

250 lines (163 loc) · 16.8 KB

Справочник API

createRenderer([options])

Создаёт экземпляр Renderer с (опциональными) настройками.

const { createRenderer } = require('vue-server-renderer')
const renderer = createRenderer({ ... })

createBundleRenderer(bundle[, options])

Создаёт экземпляр BundleRenderer с сборкой сервера и (опциональными) настройками.

const { createBundleRenderer } = require('vue-server-renderer')
const renderer = createBundleRenderer(serverBundle, { ... })

Аргумент serverBundle может быть одним из следующих:

  • Абсолютный путь к созданному файлу сборки (.js или .json). Должен начинаться с /, чтобы трактоваться как путь к файлу.

  • Объект сборки, сгенерированный Webpack + vue-server-renderer/server-plugin.

  • Строка с кодом JavaScript (не рекомендуется).

См. также Представляем Bundle Renderer и Конфигурация сборки для подробностей.

Класс: Renderer

  • renderer.renderToString(vm[, context, callback]): ?Promise<string>

    Рендерит экземпляр Vue в строку. Объект контекста опционален. Коллбэк является обычным для Node.js коллбэком, где первый аргумент является ошибкой, а второй аргумент — отрендеренной строкой.

    С версии 2.5.0+ коллбэк является опциональным. Когда коллбэк не указан, метод возвращает Promise, который разрешается отрендеренным HTML.

  • renderer.renderToStream(vm[, context]): stream.Readable

    Рендерит экземпляр Vue в Node.js readable stream. Объект контекста опционален. См. также Стриминг для подробностей.

Класс: BundleRenderer

  • bundleRenderer.renderToString([context, callback]): ?Promise<string>

    Рендерит сборку в строку. Объект контекста опционален. Коллбэк является обычным для Node.js коллбэком, где первый аргумент является ошибкой, а второй аргумент — отрендеренной строкой.

    С версии 2.5.0+ коллбэк является опциональным. Когда коллбэк не указан, метод возвращает Promise, который разрешается отрендеренным HTML.

  • bundleRenderer.renderToStream([context]): stream.Readable

    Рендерит сборку в Node.js readable stream. Объект контекста опционален. См. также Стриминг для подробностей.

Настройки рендерера

  • template

    Предоставляет шаблон для всей HTML-страницы. Шаблон должен содержать комментарий <!--vue-ssr-outlet-->, который определяет место подстановки отрендеренного контента приложения.

    Шаблон также поддерживает базовые интерполяции с использованием контекста рендера:

    • Используйте двойные фигурные скобки для интерполяции экранированного HTML;
    • Используйте тройные фигурные скобки для интерполяции сырого HTML.

    Шаблон автоматически внедряет соответствующий контент, когда определённые свойства найден�� в контексте рендера:

    • context.head: (string) любая разметка для head, которая должна быть вставлена в заголовочный тег страницы.

    • context.styles: (string) любой встроенный CSS, который должен быть вставлен в заголовочный тег страницы. Обратите внимание, что это свойство будет автоматически заполнено при использовании vue-loader + vue-style-loader для CSS компонента.

    • context.state: (Object) начальное состояние хранилища Vuex, которое должно быть внедрено в страницу как window.__INITIAL_STATE__. Внедряемый JSON автоматически обрабатывается с помощью serialize-javascript для предотвращения XSS-уязвимостей.

    С версии 2.5.0+, встраиваемый скрипт также автоматически удаляется в режиме production.

    Кроме того, когда предоставлен clientManifest, шаблон автоматически внедряет следующее:

    • JavaScript и CSS ресурсы для клиентской части, необходимые для рендеринга (с асинхронными фрагментами добавляемыми автоматически);
    • Оптимальные ресурсы <link rel="preload/prefetch"> для отображаемой страницы.

    Вы можете отключить все автоматические внедрения передав inject: false в рендерер.

    См. также:

  • clientManifest

    • Добавлено в версии 2.3.0+

    Предоставляет объект манифеста клиентской сборки, сгенерированный vue-server-renderer/client-plugin. Клиентский манифест предоставляет для рендерера сборки необходимую информацию для автоматического внедрения ресурсов в шаблон HTML. Подробнее в разделе Генерация clientManifest.

  • inject

    • Добавлено в версии 2.3.0+

    Контролирует, выполнять ли автоматические внедрения при использовании template. По умолчанию true.

    См. также: Внедрение ресурсов вручную.

  • shouldPreload

    • Добавлено в версии 2.3.0+

    Функция, определяющая какие файлы должны иметь <link rel="preload"> в генерируемых ресурсах.

    По умолчанию, только JavaScript и CSS файлы будут предзагружаться, так как они абсолютно необходимы для загрузки приложения.

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

    const renderer = createBundleRenderer(bundle, {
  template,
  clientManifest,
  shouldPreload: (file, type) => {
    // тип определяется на основе расширения файла.
    // https://fetch.spec.whatwg.org/#concept-request-destination
    if (type === 'script' || type === 'style') {
      return true
    }
    if (type === 'font') {
      // предзагружать только woff2 шрифты
      return /\.woff2$/.test(file)
    }
    if (type === 'image') {
      // предзагружать только важные изображения
      return file === 'hero.jpg'
    }
  }
})

  • shouldPrefetch

    • Добавлено в версии 2.5.0+

    Функция для управления файлами, которые должны содержаться в генерируемых <link rel="prefetch">.

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

  • runInNewContext

    • Добавлено в версии 2.3.0+
    • Используется только в createBundleRenderer
    • Ожидается: boolean | 'once' ('once' поддерживается только с версии 2.3.1+)

    По умолчанию, рендерер сборки будет создавать новый контекст V8 для каждого рендеринга и повторно исполнять всю сборку. Это имеет некоторые преимущества — например, код приложения изолирован от процесса сервера и не нужно беспокоиться о проблеме «синглтона с состоянием», которая упоминалась ранее в руководстве. Однако этот режим требует значительных затрат производительности, поскольку повторное выполнение сборки обходится дорого, особенно когда приложение становится большим.

    По умолчанию эта опция имеет значение true для обеспечения обратной совместимости, но рекомендуется использовать runInNewContext: false или runInNewContext: 'once' всегда, когда это возможно.

    В версии 2.3.0 у этой опции есть ошибка, когда при runInNewContext: false сборка всё ещё исполнялась в отдельном глобальном контексте. Информация далее предполагает использование версии 2.3.1+.

    С опцией runInNewContext: false, код сборки будет выполняться в том же контексте global, что и серверный процесс, поэтому нужно быть осторожным с кодом, который изменяет global в вашем приложении.

    С опцией runInNewContext: 'once' (добавлено в версии 2.3.1+), сборка выполняется в отдельном контексте global, но только один раз при запуске. Это обеспечивает лучшую изоляцию кода приложения поскольку предотвращает случайно загрязнение объекта global серверного процесса. Предостережения заключаются в следующем:

    1. Зависимости, которые изменяют global (например, полифиллы) не должны быть объявлены внешними зависимостями в этом режиме;
    2. Значения, возвращаемые при выполнении сборки будут использовать разные глобальные конструкторы, например, ошибка внутри сборки не будет экземпляром Error в серверном процессе.

    См. также: Структура исходного кода

  • basedir

    • Добавлено в версии 2.2.0+
    • Используется только в createBundleRenderer

    Указание пути базового каталога для серверной сборки для разрешения зависимостей из node_modules в нём. Это необходимо только в том случае, если сгенерированный файл сборки располагается в другом месте, в отличии от используемых NPM-зависимостей, или когда ваш vue-server-renderer подключен NPM-ссылкой в вашем текущем проекте.

  • cache

    Реализация кэширования на уровне компонентов. Объект кэша должен реализовать следующий интерфейс (соответствуя нотациям Flow):

    type RenderCache = {
  get: (key: string, cb?: Function) => string | void;
  set: (key: string, val: string) => void;
  has?: (key: string, cb?: Function) => boolean | void;
};

    Для обычного использования достаточно передать lru-cache:

    const LRU = require('lru-cache')

const renderer = createRenderer({
  cache: LRU({
    max: 10000
  })
})

    Обратите внимание, что объект кэша по крайне мере должен реализовывать get и set. Кроме того, get и has опционально могут быть асинхронными, если они принимают второй аргумент как коллбэк. Это позволяет кэшу использовать асинхронные API, например для Redis:

    const renderer = createRenderer({
  cache: {
    get: (key, cb) => {
      redisClient.get(key, (err, res) => {
        // обработка ошибок, если таковые будут
        cb(res)
      })
    },
    set: (key, val) => {
      redisClient.set(key, val)
    }
  }
})

  • directives

    Позволяет предоставить серверную реализацию для ваших пользовательских директив:

    const renderer = createRenderer({
  directives: {
    example (vnode, directiveMeta) {
      // преобразуем vnode на основе метаданных привязанных к директиве
    }
  }
})

    Например, можете посмотреть серверную реализацию для директивы v-show.

Webpack плагины

Webpack плагины предоставляются как отдельные файлы, которые должны быть подключены напрямую:

const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')

По умолчанию генерируются файлы:

  • vue-ssr-server-bundle.json для серверной сборки;
  • vue-ssr-client-manifest.json для клиентской сборки.

Имена файлов могут быть изменены при создании экземпляров плагина:

const plugin = new VueSSRServerPlugin({
  filename: 'my-server-bundle.json'
})

См. также Конфигурация сборки для подробной информации.