1.0.0-insiders.20260717-1e84621 • Published 4d ago

@univerjs-pro/resources

Licence

—

Version

1.0.0-insiders.20260717-1e84621

Deps

Size

124 kB

Vulns

Weekly

Stars

13.8K

Summary Dependency Versions

@univerjs-pro/resources

@univerjs-pro/resources is part of Univer Pro. It provides a product-independent static resource registry.

Package Overview

Package	UMD global	CSS	Locales	Facade entry
`@univerjs-pro/resources`	`UniverProResources`	No	No	No

Installation

pnpm add @univerjs-pro/resources
# or
npm install @univerjs-pro/resources

Keep all @univerjs/* and @univerjs-pro/* packages on the same version.

Usage

Runtime registration

import { ResourceRegistryService } from '@univerjs-pro/resources';

const resources = new ResourceRegistryService();
resources.register({
    registryId: 'acme',
    resources: [{
        id: 'logo',
        name: 'Logo',
        payload: {
            type: 'image',
            source: { type: 'url', value: 'https://assets.example/logo.svg' },
            intrinsicSize: { width: 240, height: 80 },
        },
    }],
});

Manifest registration

Store static registrations in a JSON manifest:

{
    "registrations": [{
        "input": {
            "registryId": "acme",
            "groups": [{ "id": "brand", "label": "Brand" }],
            "tags": [{ "id": "logo", "label": "Logo" }],
            "defaults": { "storagePolicy": "reference" },
            "resources": [{
                "id": "primary-logo",
                "name": "Primary logo",
                "groupId": "brand",
                "tagIds": ["logo"],
                "payload": {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "value": "https://assets.example/logo.svg"
                    },
                    "intrinsicSize": { "width": 240, "height": 80 }
                }
            }]
        }
    }]
}

Import the manifest and pass it to the plugin:

import { UniverResourcesPlugin } from '@univerjs-pro/resources';
import resourcesManifest from './resources-manifest.json';

univer.registerPlugin(UniverResourcesPlugin, resourcesManifest);

The plugin owns these registrations and disposes them with its lifecycle.

Manifest fields

The following tables describe the generic manifest fields supported by the resources package.

Manifest and registration

Field	Required	Description
`registrations`	No	Registration entries to load when the plugin starts. Defaults to an empty array.
`registrations[].input`	Yes	The resource collection passed to the registry.
`registrations[].options`	No	Registration behavior. See Registration options.

Registration input

Field	Required	Description
`registryId`	Yes	Namespace for the resources. It must match `[A-Za-z0-9][A-Za-z0-9._:-]*`.
`defaultLocale`	No	Fallback locale for localized text when the requested locale is absent.
`groups`	No	Groups available to resources in this registration. Group IDs must be unique within the array.
`tags`	No	Tags available to resources in this registration. Tag IDs must be unique within the array.
`resources`	Yes	Resource descriptors to register.
`defaults.storagePolicy`	No	Default image storage policy: `reference` or `managed`. Defaults to `reference`.

Groups and tags contain an id and a label. Labels, resource names, and descriptions accept strings or locale maps. For example: { "en-US": "Logo", "zh-CN": "标志" }.

Resource descriptor

Field	Required	Description
`id`	Yes	Resource ID within the registry. It must match `[A-Za-z0-9][A-Za-z0-9._:-]*`.
`name`	Yes	Display name as a string or locale map.
`description`	No	Description as a string or locale map.
`groupId`	No	ID from `input.groups`. Unknown groups reject the resource.
`tagIds`	No	IDs from `input.tags`. An unknown tag rejects the resource.
`keywords`	No	Additional search terms.
`order`	No	Sort order used by consumers.
`preview`	No	Image source used for previews. It follows the same source rules as `payload.source`.
`payload`	Yes	Product payload. The built-in image payload is described below.

Resource identity combines registryId and resource id. A duplicate identity keeps the first registered resource.

Image payload

Field	Required	Description
`type`	Yes	Use `image` for the built-in image payload.
`source`	Yes	Image source. See Image sources.
`intrinsicSize`	No	`{ width, height }` in pixels. Both values must be finite positive numbers. Consumers can preserve the aspect ratio without loading the image.
`storagePolicy`	No	`reference` or `managed`. Overrides `defaults.storagePolicy`.
`colorEditable`	No	Whether consumers may recolor the image. Defaults to `false`.
`initialColor`	No	Initial color string for color-editable resources.

Image sources

Every source has a type and string value.

Type	Accepted value
`url`	Absolute `http:`, `https:`, or `blob:` URL. Relative URLs are rejected.
`dataUrl`	Image data URL such as `data:image/png;base64,iVBORw0KGgo=`.
`svgText`	Raw SVG markup.

The registry sanitizes SVG data URLs and raw SVG markup by default. It does not download URL sources during registration.

Registration options

Field	Required	Description
`trusted`	No	Set to `true` only for trusted manifests that may bypass SVG sanitization. Defaults to `false`.

Resources

Keywords

univer univer-pro resources