跳到主要内容

Wiki.macro.uploadResource

Upload a file as a resource of the current macro's Wiki document and return its resource ID. Uploading is independent of configuration edit sessions.

Requirements​

ONES@ones-open/web-sdk
7.45.0+0.0.20+

Declare and enable a Wiki custom macro. Each method targets the calling entry's macro instance and does not accept another macro's ID. Public sharing, mobile and search do not load the macro runtime and cannot call these methods.

Signature​

interface MacroAPI {
  uploadResource(file: File): Promise<string>
}

Parameters​

Parameter or fieldTypeRequiredDescription
fileNative browser FileYesFrom a file input or new File(...); not a URL, path or plain object
file.namestringYesOriginal filename; nonempty, at most 255 UTF-8 bytes; no path separators, line breaks, null characters or double quotes
file.sizenumberBuilt into FileFile size in bytes, greater than 0 and at most 20 * 1024 * 1024
file.typestringBuilt into FileMIME type supplied by the browser or app; Wiki file-type, extension and quota checks still apply

There is no progress callback or extra options parameter. Track pending state in the app before and after the call.

Returns and behavior​

Promise<string> resolves to the Wiki document resource ID, not a download URL, file object or original filename. Read and store file.name yourself; do not infer names from resource IDs.

The user must be logged in and able to read the card, with the app and macro available. Page edit access and an edit lock are not required. Render and history entries may upload according to read permissions; this does not grant saveData access.

Uploading does not save the macro, update exportSpec or publish the page. Files belong to Wiki document resources, not app Hosted Object Storage. Publish references through the edit entry's saveData or an app backend static update.

Errors​

Error code or prefixMeaning and triggerRecommended handling
INVALID_RESOURCEThe file cannot be read; its name is empty, contains forbidden characters or exceeds 255 UTF-8 bytes; its size is zero or above 20 MiB; or bytes read differ from file.size.Select a file that meets the constraints above instead of retrying the same invalid file.
INVALID_MACRO_CONTEXTThe host cannot obtain the macro's team ID, document ID or card ID and cannot determine where the upload belongs.Call from a macro inserted in a Wiki document; reopen the page and contact an administrator if the problem persists.
READ_ONLYThe host has no current user's login credentials for uploading. This does not mean the page must be in edit mode.Restore login before uploading again.
MACRO_UNAVAILABLEThe runtime is missing or the entry does not match, or the macro has been destroyed or the app/macro is not enabled.Check availability and reload before retrying.
RESOURCE_UPLOAD_FAILED: <server error code>The upload API failed, for example because server validation, authentication, card read permission or Wiki file type, extension or quota checks failed. The suffix comes from the response code.Use the response code and upload request to identify the cause; correct the file or access before retrying.
RESOURCE_UPLOAD_FAILED: <HTTP status>The upload request failed without a usable business code, so the HTTP status is appended.Inspect the API response; fix authentication, permission or request issues, and retry temporary service failures.
RESOURCE_UPLOAD_FAILED: network errorNo usable response code or HTTP status was obtained, for example after a network interruption, timeout or a response without a valid resource ID. This suffix alone does not prove a network problem.Retain the selected file, inspect the network and response, and retry; do not treat the upload as successful.

Common upload API business errors are listed below. The SDK appends them after RESOURCE_UPLOAD_FAILED: :

Server error codeUpload failureRecommended handling
InvalidParameterInvalid upload payload, such as an invalid file name or macro context, file size outside the limits or a digest mismatch.Check the selected file and context; do not construct the upload request manually.
AuthFailureThe server cannot confirm the signed-in user's identity.Sign in again before uploading.
PermissionDeniedThe macro is unavailable on the server, or Wiki denies the user's access to the macro card or document resources.Check that the app is enabled and the user can read the current document.
ServerErrorThe platform-to-Wiki upload failed, Wiki rejected the upload or the returned resource ID is invalid. This includes Wiki file validation failures.Check file restrictions and server logs; retry after fixing the file or restoring the service.

These are common business codes; other authentication or service errors use the actual API response value.

File reading and browser cryptographic digest calculation can also throw native browser errors without these prefixes. Wrap the complete upload call in try / catch; see Catching errors for the error object contract.

Examples​

Install via package manager​

import { Wiki } from '@ones-open/web-sdk'

async function uploadAndSaveImage(file: File) {
  const resourceId = await Wiki.macro.uploadResource(file)
  await Wiki.macro.saveData({
    customData: { image: { resourceId, originalName: file.name } },
    exportSpec: [{ type: 'image', data: resourceId }],
    resources: [resourceId],
  })
  return resourceId
}

This example runs in the macro edit entry and replaces the complete content. Include any configuration and resources that must be retained. Viewing entries may only upload, without saving. Callers must handle upload and save failures.

Use via external script​

<script src="https://unpkg.com/@ones-open/web-sdk@0.0.20/dist/index.iife.js"></script>
<script>
  ;(async function () {
    const file = new File(['example'], 'example.txt', { type: 'text/plain' })
    const resourceId = await window.SDK.Wiki.macro.uploadResource(file)
    console.log(resourceId, file.name)
  })().catch(console.error)
</script>