Топаздокументация
Создание приложений

Data Lens

Соберите, проверьте, упакуйте и запустите поддерживаемое локальное веб-приложение для CSV и JSON.

Эта страница описывает Топаз v5.17. Прежде чем считать её актуальной, сверьте поле version в /version.json со значением 5.17.

Data Lens — поддерживаемый пример многомодульного веб-приложения. Оно открывает выбранный пользователем CSV или JSON, локально разбирает и фильтрует строки, показывает типизированную сводку, экспортирует текст и сохраняет только настройки представления. Импортированные документы и разобранные строки не отправляются на сервер и не записываются в долговременное состояние браузера.

Перед этим руководством завершите раздел Первое приложение. Нужно уже понимать модули, Result, тесты, topaz.lock и --locked. Для окончательной сборки браузерного продукта также нужен Rust с целью wasm32-unknown-unknown.

Почему это Web Application

Выбирайте web-app, когда Топаз владеет моделью, сообщениями, функцией обновления и представлением. Низкоуровневые цели web и web-worker нужны, только если существующая среда JavaScript владеет интерфейсом или протоколом Worker. Песочница предназначена для быстрых экспериментов с исходником, а не для развёртывания Data Lens.

Поддерживаемый исходный код разделён по обязанностям, а не собран в одном входном файле:

Вывод
data-lens/
  topaz.toml
  topaz.lock
  src/main.tpz
  src/model.tpz
  src/session.tpz
  src/view.tpz
  tests/application.tpz
  tests/exporting.tpz
  tests/parsing.tpz
  tests/transform.tpz
  styles/app.css
  registry/lens_labels/1.0.0/...
  vendor/lens_labels/1.0.0/...

data-lens-core/
  topaz.toml
  src/lib.tpz

data-lens-core отвечает за разбор CSV и JSON, фильтрацию, сортировку, сводку и экспорт. Веб-пакет отвечает за сообщения браузера, кодирование локального состояния и представление. lens_labels — зафиксированная зависимость из реестра, скопированная в vendor.

Сначала данные, затем интерфейс

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

TOPAZ
import data_lens_core { ФорматДанных, СтрокаДанных, РежимСортировки, Сводка }

export record Модель {
  источник: string,
  запрос: string,
  толькоАктивные: bool,
  формат: ФорматДанных,
  режимСортировки: РежимСортировки,
  строки: Array<СтрокаДанных>,
  сводка: Сводка,
  состояние: string,
  ошибка: Option<string>,
}

Разбор возвращает Result со стабильным местом ошибки, например JSON $[0].category: missing field. Функция обновления сохраняет сообщение в ошибка, а представление выводит его как текст. Исходное содержимое никогда не вставляется через innerHTML.

Жизненный цикл начинает с примера в памяти и запрашивает только сохранённые настройки представления:

TOPAZ
export function init() -> WebAppStep<Модель, Сообщение> {
  let основа = Модель {
    источник: ПРИМЕР_ДАННЫХ,
    запрос: "",
    толькоАктивные: false,
    формат: ФорматДанных.Табличный,
    режимСортировки: РежимСортировки.ПоИмени,
    строки: [],
    сводка: пустаяСводка(),
    состояние: "Ready",
    ошибка: None,
  }
  WebAppStep {
    model: применитьМодель(основа),
    commands: [загрузитьСостояние(
      "data-lens-session-load",
      "session",
      Сообщение.ЛокальнаяОперацияЗавершена,
    )],
  }
}

Открытие документа передаёт ограниченный текст UTF-8 только после явного выбора пользователя. Сеанс сохраняет лишь запрос, фильтр активных строк и режим сортировки. Отмена, неверный UTF-8, недоступное хранилище, исчерпание квоты и повреждённое состояние остаются типизированными исходами приложения.

Кратчайший поддерживаемый путь

Во время разработки подготовьте локальный источник реестра и соседний пакет ядра. Затем один раз скопируйте зависимость в проект командой vendor. Она проверяет и копирует зависимость реестра, а также записывает файл блокировки. Не запускайте lock раньше для зависимости реестра, которой ещё нет в vendor.

BASH
topaz vendor --root data-lens --from data-lens/registry
topaz fmt --check --root data-lens
topaz check --root data-lens --locked
topaz test data-lens/tests/parsing.tpz --root data-lens --locked
topaz test data-lens/tests/transform.tpz --root data-lens --locked
topaz test data-lens/tests/application.tpz --root data-lens --locked
topaz test data-lens/tests/exporting.tpz --root data-lens --locked
topaz dev --root data-lens --port 8000
topaz build --root data-lens --locked --release --out-dir data-lens-product

topaz run непосредственно запускает командный входной модуль с main. Data Lens использует жизненный цикл веб-приложения, поэтому наблюдаемая команда разработки для него — topaz dev.

В браузере проверьте CSV и JSON, метки и имена файлов Unicode, фильтрацию, оба режима сортировки, экспорт текста, сохранение, перезагрузку и удаление настроек, отмену, один неверный документ и восстановление после ошибочного изменения. Пока исходник снова не станет правильным, topaz dev продолжает раздавать последний успешный продукт.

Продукт и запуск без исходного пакета Топаза

Управляемый продукт содержит:

Вывод
data-lens-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── index.html
├── styles
│   └── app.css
├── topaz-app.js
├── topaz-artifact.json
├── topaz-web-capabilities.json
├── topaz-web.d.ts
├── topaz-web.js
└── topaz-web.wasm

Скопируйте весь каталог в новый статический корень и раздавайте его по HTTP. Продукту не нужны исходники пакета, CLI Топаза, реестр, среда npm, CDN или сервис данных. Если модули ES или WASM не загружаются через file://, используйте локальный статический HTTP-сервер. Если сборка отклоняет каталог из-за изменённого управляемого файла или другой цели, сохраните каталог нетронутым и выберите новый пустой --out-dir.

Связанная документация